Copyright © 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 M. Gastineau, Astronomie et Systèmes Dynamiques, IMCCE, CNRS, Observatoire de Paris
gastineau@imcce.fr
This library is governed by the CeCILL-C or CeCILL license under French law and abiding by the rules of distribution of free software. You can use, modify and/ or redistribute the software under the terms of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following URL "http://www.cecill.info".
As a counterpart to the access to the source code and rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors have only limited liability.
In this respect, the user's attention is drawn to the risks associated with loading, using, modifying and/or developing or reproducing the software by the user in light of its specific status of free software, that may mean that it is complicated to manipulate, and that also therefore means that it is reserved for developers and experienced professionals having in-depth computer knowledge. Users are therefore encouraged to load and test the software's suitability as regards their requirements in conditions enabling the security of their systems and/or data to be ensured and, more generally, to use and operate it in the same conditions as regards security.
The fact that you are presently reading this means that you have had knowledge of the CeCILL-C or CeCILL license and that you accept its terms.
This library is an implementation of the Symbolic Computation Software Composibility Protocol (SCSCP). The current implementation is based on the specification version 1.3 (see References).
This library provides API to develop client applications to access Computer Algebra Systems which support that protocol. So these client applications will be refered as `SCSCP client' in this documentation.
Computer Algebra Systems could use the API to provide services to other applications using this protocol. So these Computer Algebra Systems will be refered as `SCSCP server' in this documentation.
This library provides a C and C++ API to allow to be used in C or C++ programs.
To build SCSCP C Library, you first have to install Libxml2 version 2.6 or later (see http://xmlsoft.org/) on your computer. You need C and C++ compilers, such as gcc and g++. And you need a standard Unix `make' program, plus some other standard Unix utility programs.
Here are the steps needed to install the library on Unix systems:
Running configure might take a while. While running, it prints some messages telling which features it is checking for.
configure recognizes the following options to control how it operates.
This compiles SCSCP C Library in the working directory.
This will make sure SCSCP C Library was built correctly.
If you get error messages, please report them to gastineau@imcce.fr (See Reporting bugs, for information on what to include in useful bug reports).
This will copy the files scscp.h, scscpxx.h and scscptypes.h to the directory /usr/local/include, the files libscscp.a and libscscpxx.a to the directory /usr/local/lib, and the file scscp.info to the directory /usr/local/share/info (or if you passed the `--prefix' option to configure, using the prefix directory given as argument to `--prefix' instead of /usr/local). Note: you need write permissions on these directories.
There are some other useful make targets:
Create an info version of the manual, in scscp.info.
Create a PDF version of the manual, in scscp.pdf.
Create a DVI version of the manual, in scscp.dvi.
Create a Postscript version of the manual, in scscp.ps.
Create an HTML version of the manual, in several pages in the directory scscp.html; if you want only one output HTML file, then type `makeinfo --html --no-split scscp.texi' instead.
Delete all object files and archive files, but not the configuration files.
Delete all files not included in the distribution.
Delete all files copied by `make install'.
To build SCSCP C Library, you first have to install Libxml2 version 2.6 or later (see http://xmlsoft.org/) on your computer. You need C and C++ compilers and a Windows SDK. It has been successfully compiled with the Windows Server 2003 R2 Platform SDK, the Windows SDK of Vista, and the Windows Server 2008 Platform SDK.
Here are the steps needed to install the library on Windows systems:
This will open a console window
Go to the directory dir where SCSCP C Library has been expanded.
This compiles SCSCP C Library in the working directory. Use dir as the installation directory of the libxml2 library.
This will make sure SCSCP C Library was built correctly.
If you get error messages, please report them to gastineau@imcce.fr (See Reporting bugs, for information on what to include in useful bug reports).
This will copy the files scscp.h, scscpxx.h and scscptypes.h to the directory dir\include, the files scscp.lib and scscpxx.lib to the directory dir\lib, the file scscp.info and scscp.pdf to the directory dir\doc. Note: you need write permissions on these directories.
If you think you have found a bug in the SCSCP C Library, first have a look on the SCSCP C Library web page http://www.imcce.fr/trip/scscp/ , in which case you may find there a workaround for it. Otherwise, please investigate and report it. We have made this library available to you, and it is not to ask too much from you, to ask you to report the bugs that you find.
There are a few things you should think about when you put your bug report together. You have to send us a test case that makes it possible for us to reproduce the bug. Include instructions on how to run the test case.
You also have to explain what is wrong; if you get a crash, or if the results printed are incorrect and in that case, in what way.
Please include compiler version information in your bug report. This can be extracted using `cc -V' on some machines, or, if you're using gcc, `gcc -v'. Also, include the output from `uname -a' and the SCSCP version.
Send your bug report to: gastineau@imcce.fr. If you think something in this manual is unclear, or downright incorrect, or if the language needs to be improved, please send a note to the same address.
All C declarations needed to use C interface are collected in the include file scscp.h. It is designed to work with both C and C++ compilers. All C++ declarations needed to use C++ interface are collected in the include file scscpxx.h.
You should include that file in any C program using the SCSCP C Library :
#include <scscp.h>
You should include that file in any C++ program using the SCSCP C Library :
#include <scscpxx.h>
Note however that the SCSCP constants use NULL, the header file stdio.h must be included before.
#include <stdio.h>
#include <scscp.h>
All C programs using SCSCP must link against the libscscp library and the Libxml2 library. On Unix-like system this can be done with -lscscp `xml2-config --libs`, for example
gcc myprogram.c -o myprogram -lscscp `xml2-config --libs`
All C++ programs using SCSCP must link against the libscscpxx and libscscp libraries and the Libxml2 library. On Unix-like system this can be done with -lscscpxx -lscscp `xml2-config --libs`, for example
g++ myprogram.cpp -o myprogram -lscscpxx -lscscp `xml2-config --libs`
If SCSCP C Library has been installed to a non-standard location then it may be necessary to use -I and -L compiler options to point to the right directories, and some sort of run-time path for a shared library.
All C programs using SCSCP must link against the scscp.lib library and the Libxml2 library. On Windows system this can be done with scscp.lib libxml2_a.lib iconv.lib wsock32.lib ws2_32.lib, for example
cl.exe /out:myprogram myprogram.c scscp.lib libxml2_a.lib iconv.lib \
wsock32.lib ws2_32.lib
All C++ programs using SCSCP must link against the scscpxx.lib and scscp.lib libraries and the Libxml2 library.
On Windows system this can be done with scscpxx.lib scscp.lib libxml2_a.lib iconv.lib wsock32.lib ws2_32.lib, for example
cl.exe /out:myprogram myprogram.cpp scscpxx.lib scscp.lib \
libxml2_a.lib iconv.lib wsock32.lib ws2_32.lib
If SCSCP C Library has been installed to a non-standard location then it may be necessary to use /I and /LIBPATH: compiler options to point to the right directories.
SCSCP C Library is reentrant and thread-safe wit some exceptions:
send are not reentrant
then the SCSCP I/O functions using them will not be reentrant either.
SCSCP_VERSION_MAJOR
This integer constant defines the major revision of this library. It can be used to distinguish different releases of this library.
SCSCP_VERSION_MINOR
This integer constant defines the minor revision of this library. It can be used to distinguish different releases of this library.
SCSCP_VERSION_PATCH
This integer constant defines the patch level revision of this library. It can be used to distinguish different releases of this library.
#if (SCSCP_VERSION_MAJOR>=2)
|| (SCSCP_VERSION_MAJOR>=1 && SCSCP_VERSION_MINOR>=3)
...
#endif
|
SCSCP_PROTOCOL_VERSION_1_3
This string defines the version string for the SCSCP specification version 1.3 .
SCSCP_PROTOCOL_VERSION_1_2
This string defines the version string for the SCSCP specification version 1.2 .
SCSCP_PROTOCOL_DEFAULTPORT
This integer is the default value on which port should listen the SCSCP server. The value 26133 for this port has been assigned to SCSCP by the Internet Assigned Numbers Authority (IANA) in November 2007, see http://www.iana.org/assignments/port-numbers.
This type contains all information of the SCSCP server.
Before using any object of this type, the function
SCSCP_ss_initmust be called.
This type contains all information of the SCSCP client about the connection through a socket to a SCSCP server.
Before using any object of this type, the function
SCSCP_sc_initmust be called.
This type contains all information of an incoming connection accepted by a server.
This type contains all information about errors. Before using any object of this type, the
SCSCP_STATUS_INITIALIZERmust be used to initialize the status object.
SCSCP_status status = SCSCP_STATUS_INITIALIZER; ...Each function of the library updates an object of this type if an error occurs during the processing. The value
SCSCP_STATUS_IGNOREcould be used in order to ignore the returned value by these functions.The possible values are
- `SCSCP_STATUS_OK'
- No error occurs.
- `SCSCP_STATUS_ERRNO'
- The variable errno is set to a system error. The value of errno specifies the error.
- `SCSCP_STATUS_EXECFAILED'
- The remote execution fails.
- `SCSCP_STATUS_NOMEM'
- Not enough memory
- `SCSCP_STATUS_OPENMATHNOTVALID'
- The OpenMath expression isn't valid.
- `SCSCP_STATUS_RECVCANCEL'
- The interrupt message "<? scscp cancel ?>" was received.
- `SCSCP_STATUS_RECVQUIT'
- The quit message "<? scscp quit ?>" was received or the socket is closed before receiving this message.
- `SCSCP_STATUS_USAGEUNKNOWNDEBUGLEVEL'
- The debug level isn't available in the procedure call message.
- `SCSCP_STATUS_USAGEUNKNOWNMEM'
- The memory usage isn't available in the procedure return message.
- `SCSCP_STATUS_USAGEUNKNOWNMESSAGE'
- The information message isn't available in the procedure return message.
- `SCSCP_STATUS_USAGEUNKNOWNMINMEMORY'
- The minimal memory isn't available in the procedure call message.
- `SCSCP_STATUS_USAGEUNKNOWNMAXMEMORY'
- The maximal memory isn't available in the procedure call message.
- `SCSCP_STATUS_USAGEUNKNOWNRETURNTYPE'
- The return type isn't available in the procedure call message
- `SCSCP_STATUS_USAGEUNKNOWNRUNTIME'
- The runtime usage isn't available in the procedure return message.
- `SCSCP_STATUS_USAGEUNKNOWNRUNTIMELIMIT'
- The runtime limit usage isn't available in the procedure call message.
- `SCSCP_STATUS_VERSIONNEGOTIATIONFAILED'
- The version negotiation fails.
The following values indicate an invalid usage of the library
- `SCSCP_STATUS_CALLIDISNOTSET'
- The call identifier isn't defined in the options.
- `SCSCP_STATUS_CALLOPTIONSOBJECTNULL'
- The object call options passed to the function is NULL.
- `SCSCP_STATUS_CLIENTOBJECTNULL'
- The object client passed to the function is NULL.
- `SCSCP_STATUS_RETURNOPTIONSOBJECTNULL'
- The object return options passed to the function is NULL.
- `SCSCP_STATUS_RETURNTYPEISNOTSET'
- The return type isn't defined in the options.
- `SCSCP_STATUS_SERVEROBJECTNULL'
- The object server passed to the function is NULL.
- `SCSCP_STATUS_STREAMOBJECTNULL'
- The object stream passed to the function is NULL.
This type contains all information about the options for a procedure call. The attribute of the procedure call could be set using the functions
SCSCP_co_set_xxx. The attribute of the procedure call could be get using the functionsSCSCP_co_get_xxx.The value
SCSCP_CALLOPTIONS_DEFAULTcould be used in order to use the default procedure call options. In this case, a unique call identifier will be generated using the prefixlibSCSCP:and the procedure call will return no value (SCSCP_option_return_nothingwill be used).Before using any object of this type, the function
SCSCP_co_initmust be called.
This type contains all information about the options for a procedure return. The attribute of the procedure return could be set using the functions
SCSCP_ro_set_xxx. The attribute of the procedure return could be get using the functionsSCSCP_ro_get_xxx.The value
SCSCP_RETURNOPTIONS_IGNOREcould be used in order to ignore the returned value by the functionSCSCP_sc_callrecvheader,SCSCP_sc_callrecvstr.Before using any object of this type, the function
SCSCP_ro_initmust be called.
This type defines the type of sent messages between the client and the server.
The available values are
- `SCSCP_msgtype_ProcedureTerminated'
- The message is a "Procedure terminated". It is defined by the symbol
procedure_terminatedof the OpenMath Content Dictionaryscscp1.- `SCSCP_msgtype_ProcedureCompleted'
- The message is a "Procedure completed". It is defined by the symbol
procedure_completedof the OpenMath Content Dictionaryscscp1.- `SCSCP_msgtype_ProcedureCall'
- The message is a "Procedure call". It is defined by the symbol
procedure_callof the OpenMath Content Dictionaryscscp1.- `SCSCP_msgtype_Interrupt'
- The message is a "Interrupt" signal. It is defined by the processing instruction "<? scscp terminate ?>".
This type defines the encoding type of the sent OpenMath Objects between the client and the server.
The available values are
- `SCSCP_encodingtype_XML'
- The OpenMath objects are encoded using the XML encoding. It is the default encoding for all connections.
- `SCSCP_encodingtype_Binary'
- The OpenMath objects are encoded using the Binary encoding.
This type defines a pointer to an attribute of a node of type SCSCP_xmlnodeptr (noode of a XML tree).
The following functions manage all operations on the SCSCP_socketserver and SCSCP_incomingclient objects.
( SCSCP_socketserver* server, SCSCP_status* status , const char* servicename, const char* serviceversion, const char* serviceid, ...)
It initializes the internal structure of the object server. The variadic arguments should be of the type const char* and the last argument must be NULL. The variadic parameters define the allowed version of SCSCP protocol that could be negotiated with the SCSCP server.
The arguments servicename, serviceversion and serviceid are used as the value of the attribute service_name, service_version and service_id of the Connection Initiation Message.
The constants SCSCP_PROTOCOL_VERSION_x_x could be used for the variadic parameters.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_init fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The following example shows how to initialize the server supporting the scscp versions "1.3" and "1.001" .
SCSCP_status status;
SCSCP_server server;
int res;
res = SCSCP_ss_init(&server, &status, "MYCAS","1","myid",
SCSCP_PROTOCOL_VERSION_1_3,
"1.001", NULL);
|
It clears the internal structure of the object server and frees allocated memory for this object by the function SCSCP_ss_init.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_clear fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
server creates an internal queue for the incoming connections and starts to listen on the port of "localhost". If the port isn't available and firstavailable = 0, it fails. If the port isn't available and firstavailable = 1, it retries with the next port until it finds an available port. If port is 0, an available random port is chosen.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_listen fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
server terminates to listen for the incoming connections.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_close fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
server extracts the first connection request on the queue of pending connections. If no pending connections are present on the queue, it blocks the caller until a connection is present.
After the Connection Initiation, the server returns, in the argument incomingclient, an object to manage future exchanged messages.
After the transactions, incomingclient must be closed and cleared with the function SCSCP_ss_closeincoming.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_acceptclient fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The following example shows how to implement the main loop of the SCSCP server.
SCSCP_status status;
SCSCP_incomingclient incomingclient;
SCSCP_server server;
/*initialization of the server */
SCSCP_ss_init(&server, &status, "MYCAS","1","myid",
SCSCP_PROTOCOL_VERSION_1_3,
"1.001", NULL);
SCSCP_ss_listen(&server, SCSCP_PROTOCOL_DEFAULTPORT, &status);
while (SCSCP_ss_acceptclient(&server, &incomingclient, &status))
{
... process incoming message ...
SCSCP_ss_closeincoming(&incomingclient, &status);
}
/* destroy the server */
SCSCP_ss_close(& server, &status);
SCSCP_ss_clear(&server, &status);
|
It closes the connection with the client and clears the object incomingclient.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_closeincoming fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It waits for an incoming message. When a new message is available, then it reads the attribute, the type and the content of the message sent by the client incomingclient.
The call options options could be get using the functions SCSCP_co_get_xxx. options must be initialized before with the function SCSCP_co_init.
On exit, the argument msgtype must be SCSCP_msgtype_ProcedureCall or SCSCP_msgtype_Interrupt. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument msgtype is SCSCP_msgtype_Interrupt, options contains the call identifier of the interrupted procedure call.
On exit, the argument openmathbuffer contains the content of the message sent by the client. This string must be freed by the system call free.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_callrecvstr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It reads the attribute and type of the message sent by the client incomingclient.
The call options options could be get using the functions SCSCP_co_get_xxx. options must be initialized before with the function SCSCP_co_init.
On exit, the argument msgtype must be SCSCP_msgtype_ProcedureCall or SCSCP_msgtype_Interrupt. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument msgtype is SCSCP_msgtype_Interrupt, options contains the call identifier of the interrupted procedure call.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_callrecvheader fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
SCSCP_ss_callrecv....
On exit, it returns NULL if an error occurs, otherwise the return value is a valid address. If SCSCP_ss_getxmlnode fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
free.
On exit, it returns NULL if an error occurs, otherwise the return value is a valid address. If SCSCP_ss_getxmlnoderawstring fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It sends a "procedure terminated" message to the SCSCP client with the options. The symbol of the OpenMath Error is defined by its name symbolname and its CD cdname. message is the message that will be inserted in a OMSTR OpenMath object.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_sendterminatedstr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
SCSCP_ss_sendterminatedstr(&incomingclient, &options,
"scscp1","error_system_specific",
"can't store a remote object", &status);
|
It sends a "procedure completed" message to the SCSCP client with the options. The string openmathbuffer is the argument of the "procedure completed".
The string openmathbuffer must be a valid OpenMath command or NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_sendcompletedstr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It sends a "procedure completed" message to the client with the options. The arguments of the "procedure completed" message must be written by the callback function callbackwriteargs. The function callbackwriteargs must use the I/O functions SCSCP_io_writexxx, such as SCSCP_io_writeOMSTR, to write data which are sent to the SCSCP client.
The argument param is a pointer which is provided to the callbackwriteargs to exchange information. This pointer and its content isn't modified by SCSCP_ss_sendcompletedhook.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_sendcompletedhook fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It sends an information message to the SCSCP client for a debugging purpose. The string messagebuffer must be a valid string.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_infomessagesend fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
SCSCP_ss_sendcompletedstr, must use the same encoding.
The default encoding for the SCSCP server is the SCSCP_encodingtype_XML.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_set_encodingtype fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ss_get_encodingtype fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The following functions manage all operations on the SCSCP_socketclient object.
It initializes the internal structure of the object client. The variadic arguments should be of the type const char* and the last argument must be NULL. The variadic parameters define the allowed version of SCSCP protocol that could be negotiated with the SCSCP server.
During the negotiation with the server, the client will choose the first version in the variadic parameters that the server supports too. So the variadic parameters should start by from the highest level of the SCSCP version to the lowest version.
The constants SCSCP_PROTOCOL_VERSION_x_x could be used for the variadic parameters.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_init fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
res = SCSCP_sc_init(&client, &status, SCSCP_PROTOCOL_VERSION_1_3,
"1.0beta", NULL);
|
It clears the internal structure of the object client and frees allocated memory for this object by the function SCSCP_sc_init.
If a connection was already opened, the function SCSCP_sc_close is called before clearing the object.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_clear fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
( SCSCP_socketclient* client, const char *machine, int port, SCSCP_status* status )
It tries to connect to the SCSCP server which is running on the computer machine and is listening on the port port.
client must be initialized with the function SCSCP_sc_init before calling this function. If the connection achieves, client is updated on exit.
machine could be any string but it must resolved as an IP address. Its value could be "localhost" if the SCSCP server runs on the same computer.
In most of the case, the default value SCSCP_PROTOCOL_DEFAULTPORT should be used for the port number.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_connect fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
SCSCP_sc_connect.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_close fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
SCSCP_sc_callsendstr, must use the same encoding.
The default encoding for the SCSCP client is the SCSCP_encodingtype_XML.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_set_encodingtype fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_get_encodingtype fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client sends a "procedure call" message to the SCSCP server with the options. The string openmathbuffer is the argument of the procedure call.
A connection must be previously opened with SCSCP_sc_connect before preforming this procedure call.
The string openmathbuffer must be an OpenMath Application object.
The value SCSCP_CALLOPTIONS_DEFAULT could be used for the parameter options in order to use the default procedure call options. The procedure call options could be set using the functions SCSCP_co_set_xxx.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_callsendstr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client reads the attribute, the type and the content of the message returned by the server in response of a procedure call.
On exit, the argument msgtype contains the message type returned by the server.
On exit, the argument openmathbuffer contains the content of the message returned by the server. This string must be freed by the system call free.
The value SCSCP_RETURNOPTIONS_IGNORE could be used for the parameter options in order to ignore the returned value. The return options could be get using the functions SCSCP_ro_get_xxx. If options isn't SCSCP_RETURNOPTIONS_IGNORE, it must be initialized before with the function SCSCP_ro_init.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_callrecvstr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client sends a "procedure call" message to the server with the options. The arguments of the procedure call must be written by the callback function callbackwriteappli. The function callbackwriteappli must use the functions SCSCP_io_writexxx, such as SCSCP_io_writeOMSTR, to write data which are sent to the SCSCP server.
The function callbackwriteappli must write an OpenMath Application object.
A connection must be previously opened with SCSCP_sc_connect before preforming this procedure call.
The argument param is a pointer which is provided to the callbackwriteargs to exchange information. This pointer and its content isn't modified by SCSCP_sc_callsendhook.
The value SCSCP_CALLOPTIONS_DEFAULT could be used for the parameter options in order to use the default procedure call options. The procedure call options could be set using the functions SCSCP_co_set_xxx.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_callsendhook fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client reads the attribute and type of the message returned by the server in response of a procedure call.
The value SCSCP_RETURNOPTIONS_IGNORE could be used for the parameter options in order to ignore the returned value. The return options could be get using the functions SCSCP_ro_get_xxx. If options isn't SCSCP_RETURNOPTIONS_IGNORE, it must be initialized before with the function SCSCP_ro_init.
On exit, the argument msgtype contains the message type returned by the server.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_callrecvheader fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client reads the content of the OpenMath error if the server replies with a "procedure terminated" message. This function must be called only if SCSCP_sc_callrecvheader returns msgtype=SCSCP_msgtype_ProcedureTerminated.
On exit, the argument symbolname contains the name of the OpenMath symbol from the OpenMath content dictionnary cdname. These strings must be freed by the system call free.
On exit, the argument messagebuffer contains the full content of the error (including the head symbol of the OpenMath error) returned by the server. This string must be freed by the system call free.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_callrecvterminated fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
SCSCP_sc_callrecvheader returns msgtype=SCSCP_msgtype_ProcedureCompleted.
On exit, the argument openmathbuffer contains the content of the message returned by the server. This string must be freed by the system call free.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_callrecvcompleted fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It sends an interrupt signal to the SCSCP server with the call ID call_id. The server need not to complete the computation but the server will always reply to the procedure call. The argument call_id can't be NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_callsendinterrupt fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client sends a "procedure call" message to the server with an OpenMath symbol symbolname from the content dictionary cdname as first argument. The other arguments of the procedure call must be written by the callback function callbackwriteargs. The function callbackwriteargs must use the functions SCSCP_io_writexxx, such as SCSCP_io_writeOMSTR, to write data which are sent to the SCSCP server.
A connection must be previously opened with SCSCP_sc_connect before preforming this procedure call.
The argument param is a pointer which is provided to the callbackwriteargs to exchange information. This pointer and its content isn't modified by SCSCP_sc_executehookxmlnode.
The server returns a result (object, cookie, nothing) depending on the value returntype. On exit, the argument node contains a pointer to the OpenMath object by the server.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_executehookxmlnode fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client sends a "procedure call" message to the server with an OpenMath symbol symbolname from the content dictionary cdname as first argument. The other arguments of the procedure call must be written by the callback function callbackwriteargs. The function callbackwriteargs must use the functions SCSCP_io_writexxx, such as SCSCP_io_writeOMSTR, to write data which are sent to the SCSCP server.
A connection must be previously opened with SCSCP_sc_connect before preforming this procedure call.
The argument param is a pointer which is provided to the callbackwriteargs to exchange information. This pointer and its content isn't modified by SCSCP_sc_callsendhookstr.
The server returns a result (object, cookie, nothing) depending on the value returntype. On exit, the argument openmathbuffer contains a string representing the OpenMath object by the server.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_callsendhookstr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It sends an information message to the SCSCP server for a debugging purpose. The string messagebuffer must be a valid string.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_infomessagesend fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
SCSCP_sc_callrecv....
On exit, it returns NULL if an error occurs, otherwise the return value is a valid address. If SCSCP_sc_getxmlnode fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
free.
On exit, it returns NULL if an error occurs, otherwise the return value is a valid address. If SCSCP_sc_getxmlnoderawstring fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the data buffer directly to the stream. The argument buffer can't be NULL.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_write fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the data buffer as an OpenMath string <OMSTR>...</OMSTR> to the stream.
If the argument buffer is NULL, the OpenMath string is encoding with only one space.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMSTR fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the floating-point number x as an OpenMath float <OMF dec="..." /> to the stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMFdouble fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the floating-point number buffer as an OpenMath float <OMF dec="..." /> to the stream.
The argument buffer can't be NULL.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMFstr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the integer x as an OpenMath integer <OMI>...</OMI> to the stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMIint fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the integer x as an OpenMath integer <OMI>...</OMI> to the stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMIlonglong fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the integer buffer as an OpenMath integer <OMI>...</OMI> to the stream.
The argument buffer can't be NULL.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMIstr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the symbol symbolname of the Content Dictionary cdname as an OpenMath symbol <OMS cd="..." name="..." /> to the stream.
The argument cdname and symbolname can't be NULL.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMS fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the variable buffer as an OpenMath variable <OMV name="..." /> to the stream.
The argument buffer can't be NULL.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMV fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the reference buffer as an OpenMath reference <OMR href="..."/> to the stream.
The argument buffer can't be NULL.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMR fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the array buffer of lenbuffer bytes as an OpenMath byte array <OMB/>...</OMB> to the stream.
The argument buffer can't be NULL.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeOMB fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the beginning of the structured Open Math object <OMA> to the stream stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writebeginOMA fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the end of the structured Open Math object </OMA> to the stream.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeendOMA fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the beginning of the structured Open Math attribute pair <OMATP> to the stream stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writebeginOMATP fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the end of the structured Open Math attribute pair </OMATP> to the stream.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeendOMATP fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the beginning of the structured Open Math attribution <OMATTR> to the stream stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writebeginOMATTR fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the end of the structured Open Math attribution </OMATTR> to the stream.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeendOMATTR fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the beginning of the structured Open Math binding object <OMBIND> to the stream stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writebeginOMBIND fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the end of the structured Open Math binding object </OMBIND> to the stream.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeendOMBIND fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the beginning of the structured Open Math error <OME> to the stream stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writebeginOME fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the end of the structured Open Math error </OME> to the stream.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeendOME fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the beginning of the structured Open Math foreign object <OMFOREIGN> to the stream stream.
id is the id of this object for the future reference (see OMR). id could be NULL if unset.
Currently, the binary encoding isn't supported, the function always fails.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writebeginOMFOREIGN fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the end of the structured Open Math foreign object </OMFOREIGN> to the stream
Currently, the binary encoding isn't supported, the function always fails.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeendOMFOREIGN fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the beginning of the structured Open Math object <OMOBJ> to the stream stream.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writebeginOMOBJ fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It writes the end of the structured Open Math object </OMOBJ> to the stream.
This function must only be called by the callback function callbackwritearg provided to the hook functions SCSCP_ss_sendcompletedhook, SCSCP_sc_callsendhook, ....
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_io_writeendOMOBJ fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It clears the internal structure of the object status and frees allocated memory for this object by any error of the library.
This function returns the integer value of the status object. The returned value are defined in See SCSCP_status. status mustn't be SCSCP_STATUS_IGNORE.
This function could be defined as a macro in the header file scscp.h.
int res = SCSCP_co_get_maxmemory(&options, &memsize, status);
if (res)
{
printf("maximum memory = %lld\n", (long long)memsize);
}
else if (SCSCP_status_is(status)==SCSCP_STATUS_USAGEUNKNOWNMAXMEMORY)
{
printf("maximum memory not available\n");
}
|
This function accepts an argument status and returns a pointer to the corresponding message string.
int res = SCSCP_co_get_maxmemory(&options, &memsize, status);
if (res)
{
printf("maximum memory = %lld\n", (long long)memsize);
}
else
{
printf("error message ='%s'\n", SCSCP_status_strerror(status));
}
|
It initializes the internal structure of the object options.
It generates and sets the call identifier of the options of the procedure call. This call identifier is defined as the symbol call_id of the OpenMath Content Dictionary scscp1. The call identifier is prefixed by libSCSCP:. It sets the return type to the value SCSCP_option_return_object.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_init fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It clears the internal structure of the object options and frees allocated memory for this object by the function SCSCP_co_init.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_clear fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the call identifier of the options of the procedure call. It overwrites the default call identifier, generated by SCSCP_co_init. This call identifier is defined as the symbol call_id of the OpenMath Content Dictionary scscp1.
The argument buffer can't be NULL and won't be duplicated by these functions. So buffer mustn't be destroyed until the function SCSCP_co_clear is called on the object options. The argument buffer shouldn't be use any string beginning with libSCSCP: because SCSCP_co_init generates unique call identifier with this prefix. The caller of this function is resposible of the unicity of the content of buffer during th connection.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_set_callid fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument buffer, the call id of the options of the procedure call. This call id is defined as the symbol call_id of the OpenMath Content Dictionary scscp1. The argument buffer can't be NULL. The returned string mustn't be modified.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_get_callid fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the amount of time in milliseconds, with the value time, that the SCSCP server should spend on this call. This runtime limit is defined by the symbol option_runtime of the OpenMath Content Dictionary scscp1.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_set_runtimelimit fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument time, the amount of time in milliseconds that the server should spend on this call. This amount of time is defined as the symbol option_runtime of the OpenMath Content Dictionary scscp1. If the amount of time isn't available (not supplied by the server), the function fails and status is set to SCSCP_STATUS_USAGEUNKNOWNRUNTIMELIMIT.
The argument time can't be NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_get_runtimelimit fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the minimum amount of memory in bytes, with the value memsize, that the server should use on this call. This memory limit is defined by the symbol option_min_memory of the OpenMath Content Dictionary scscp1.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_set_minmemory fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument memsize, the minimum amount of memory in bytes that the server should use on this call. This amount of memory is defined as the symbol option_min_memory of the OpenMath Content Dictionary scscp1. If the amount of memory isn't available (not supplied by the server), the function fails and status is set to SCSCP_STATUS_USAGEUNKNOWNMINMEMORY.
The argument memsize can't be NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_get_minmemory fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the maximum amount of memory in bytes, with the value memsize, that the SCSCP server should use on this call. This memory limit is defined by the symbol option_max_memory of the OpenMath Content Dictionary scscp1.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_set_maxmemory fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument memsize, the maximum amount of memory in bytes that the server should use on this call. This amount of memory is defined as the symbol option_max_memory of the OpenMath Content Dictionary scscp1. If the amount of memory isn't available (not supplied by the server), the function fails and status is set to SCSCP_STATUS_USAGEUNKNOWNMAXMEMORY.
The argument memsize can't be NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_get_maxmemory fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the debug level, with the value debuglevel, that the client is interested. This debug level is defined by the symbol option_debuglevel of the OpenMath Content Dictionary scscp1.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_set_debuglevel fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument debuglevel, the debug level that the client is interested. This debug level is defined as the symbol option_max_memory of the OpenMath Content Dictionary scscp1. If the debug level isn't available (not supplied by the server), the function fails and status is set to SCSCP_STATUS_USAGEUNKNOWNDEBUGLEVEL.
The argument debuglevel can't be NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_get_debuglevel fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the return type, with the value returntype, of the procedure call that the server should send. The available value for returntype are
SCSCP_option_return_object. The return value is an OpenMath object. It's defined by the symbol option_return_object of the OpenMath Content Dictionary scscp1.
SCSCP_option_return_cookie. The return value is a cookie (a reference to an OpenMath object). It's defined by the symbol option_return_cookie of the OpenMath Content Dictionary scscp1.
SCSCP_option_return_nothing. The procedure call returns no value. It's defined by the symbol option_return_nothing of the OpenMath Content Dictionary scscp1.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_set_returntype fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument returntype, the return type of the "procedure call" message that the server should send. The possible value of returntype are described in the function SCSCP_co_set_returntype.
If the return type isn't available (not supplied by the server), the function fails and status is set to SCSCP_STATUS_USAGEUNKNOWNRETURNTYPE.
The argument returntype can't be NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_get_returntype fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_co_get_encodingtype fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It initializes the internal structure of the object options.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_init fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
It clears the internal structure of the object options and frees allocated memory for this object by the function SCSCP_ro_init.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_clear fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the call id, with the value buffer, of the options of the procedure return. This call id is defined as the symbol call_id of the OpenMath Content Dictionary scscp1. The argument buffer can't be NULL and won't be duplicated by this function. So buffer can't be destroyed until the function SCSCP_ro_clear is called on the object options.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_set_callid fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument buffer, the call id of the options of the procedure return. This call id is defined as the symbol call_id of the OpenMath Content Dictionary scscp1. The argument buffer mustn't be NULL. The returned string mustn't be modified.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_get_callid fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the amount of time in milliseconds, with the value time, that the server spent on this call. This amount of time is defined as the symbol info_runtime of the OpenMath Content Dictionary scscp1.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_set_runtime fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument time, the amount of time in milliseconds that the server spent on this call. This amount of time is defined as the symbol info_runtime of the OpenMath Content Dictionary scscp1. If the amount of time isn't available (not supplied by the server), the function fails and status is set to SCSCP_STATUS_USAGEUNKNOWNRUNTIME.
The argument time can't be NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_get_runtime fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the amount of memory in bytes, with the value memsize, that the server used on this call. This amount of memory is defined as the symbol info_memory of the OpenMath Content Dictionary scscp1.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_set_memory fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument memsize, the amount of memory in bytes that the server used for this call. This amount of memory is defined as the symbol info_memory of the OpenMath Content Dictionary scscp1. If the amount of memory isn't available (not supplied by the server), the function fails and status is set to SCSCP_STATUS_USAGEUNKNOWNMEM.
The argument memsize can't be NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_get_runtime fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function sets the information message, with the value buffer, of the options of the procedure return. This information message is defined as the symbol info_message of the OpenMath Content Dictionary scscp1. The argument buffer can't be NULL and won't be duplicated by this function. So buffer can't be destroyed until the function SCSCP_ro_clear is called on the object options.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_set_message fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
This function returns, in the argument buffer, the information message of the options of the procedure return. This information message is defined as the symbol info_message of the OpenMath Content Dictionary scscp1. The argument buffer mustn't be NULL. The returned string mustn't be modified.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_ro_get_message fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The following functions are useful to parse incoming messages after reading the header of the message with the functions SCSCP_sc_callrecvheader or SCSCP_ss_callrecvheader. The following example prints each node and attribute of a XML tree.
void printelements(SCSCP_xmlnodeptr node, int tab)
{
SCSCP_xmlattrptr attr;
const char *name;
const char *value;
int j;
while (node!=NULL)
{
for(j=0; j<tab; j++) putchar(' ');
printf ("node : '%s'\n",SCSCP_xmlnode_getname(node));
for (attr = SCSCP_xmlnode_getattr(node);
attr!=NULL;
attr = SCSCP_xmlattr_getnext(attr))
{
SCSCP_xmlattr_getvalue(attr, &name, &value);
for(j=0; j<tab+1; j++) putchar(' ');
printf ("attribute : '%s ' = '%s'\n",name, value);
}
printelements(SCSCP_xmlnode_getchild(node),tab+4);
node = SCSCP_xmlnode_getnext(node);
}
}
|
NULL.
NULL.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain an OpenMath symbol , otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain an OpenMath integer , otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain an OpenMath integer , otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain an OpenMath floating-point , otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain an OpenMath floating-point , otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain an OpenMath string , otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain an OpenMath reference , otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain an OpenMath variable , otherwise the return value is a non-zero value.
On exit, it returns 0 if node doesn't contain OpenMath symbol and an OpenMath string , otherwise the return value is a non-zero value.
The client sends a "procedure call" message to store an object on the server. This object will be usable in the remainder of the current SCSCP session. The object is written by the callback function callbackwriteargs. The function callbackwriteargs must use the functions SCSCP_io_writexxx, such as SCSCP_io_writeOMSTR, to write data which are sent to the SCSCP server.
A connection must be previously opened with SCSCP_sc_connect before preforming this call.
The argument param is a pointer which is provided to the callbackwriteargs to exchange information. This pointer and its content isn't modified by SCSCP_sc_remoteobjectstoresessionhook.
On exit, the argument cookiename contains the name of the Openmath reference returned by the server. This string must be freed by the system call free.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_remoteobjectstoresessionhook fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client sends a "procedure call" message to store an object on the server. This object will be usable from different SCSCP session. The object is written by the callback function callbackwriteargs. The function callbackwriteargs must use the functions SCSCP_io_writexxx, such as SCSCP_io_writeOMSTR, to write data which are sent to the SCSCP server.
A connection must be previously opened with SCSCP_sc_connect before preforming this call.
The argument param is a pointer which is provided to the callbackwriteargs to exchange information. This pointer and its content isn't modified by SCSCP_sc_remoteobjectstorepersistenthook.
On exit, the argument cookiename contains the name of the Openmath reference returned by the server. This string must be freed by the system call free.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_remoteobjectstorepersistenthook fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client sends a "procedure call" message to retrieve the value of an remote object cookiename from the server. A connection must be previously opened with SCSCP_sc_connect before preforming this call.
This function returns, in the argument node, a pointer to this OpenMath object.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_remoteobjectretrievexmlnode fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client sends a "procedure call" message to retrieve the value of an remote object cookiename from the server. A connection must be previously opened with SCSCP_sc_connect before preforming this call.
This function returns, in the argument openmathbuffer, a string of this OpenMath object. This string must be freed by the system call free.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_remoteobjectretrievestr fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
The client sends a "procedure call" message to remove the remote object cookiename from the server. A connection must be previously opened with SCSCP_sc_connect before preforming this call.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value. If SCSCP_sc_remoteobjectunbind fails, the value of status is set to the corresponding error value. SCSCP_STATUS_IGNORE could be used for status in order to ignore the returned value.
Return the SCSCP C Library version, as a null-terminated string.
Return the SCSCP C Library version as unsigned values. On exit, major contains the major revision, minor contains the minor revision and patch the patch level revision.
Verify that the SCSCP C Library versions are consistent.
It verifies that the version of the SCSCP C Library with which an application was compiled matches the version of the SCSCP C Library against which the application is currently linked.
This function is defined as a macro and returns an integer of type int.
On exit, it returns
The file examples/decodeserver.c shows the server which decodes each node of the OpenMath expression received from the client. It sends an answer to the client depending on the call options.
A simple SCSCP server could be done with the following operations. This server supports the scscp versions "1.3" and "1.5beta".
SCSCP_socketserver server;
SCSCP_status status = SCSCP_STATUS_INITIALIZER;
SCSCP_ss_init(&server, &status, "MYCAS", "1.0", "myid",
SCSCP_PROTOCOL_VERSION_1_3,
"1.5beta",
NULL);
SCSCP_ss_listen(&client, SCSCP_PROTOCOL_DEFAULTPORT, 0, &status);
SCSCP_incomingclient incomingclient;
while (SCSCP_ss_acceptclient(&server, &incomingclient, &status))
{
SCSCP_calloptions calloptions;
SCSCP_returnoptions returnoptions;
SCSCP_msgtype msgtype;
SCSCP_co_init(&calloptions, status);
SCSCP_ro_init(&returnopt, status);
SCSCP_ss_callrecvheader(&incomingclient, &calloptions,
&msgtype, &status);
SCSCP_xmlnodeptr ptrnode;
ptrnode = SCSCP_ss_getxmlnode(&incomingclient, &status);
char *openmathbuffer;
SCSCP_ss_callrecvstr(&incomingclient, &calloptions, &msgtype,
&openmathbuffer, &status);
const char *openmathanswer="<OM...>";
SCSCP_ss_sendcompletedstr(&incomingclient, &returnopt,
openmathanswer, &status);
const char *messageerror="can't store an object";
SCSCP_ss_sendterminatedstr(&incomingclient, &returnopt,
"sccsp1", "error_system_specific",
messageerror, &status);
SCSCP_co_clear(&options, status);
SCSCP_ro_clear(&returnopt, status);
SCSCP_ss_closeincoming(&incomingclient, &status);
}
SCSCP_ss_close(&server, &status);
SCSCP_ss_clear(&server, &status);
The file examples/simplestclient.c shows the simplest client which stores the value 6177887 on the server and prints the answer of the server.
The file examples/decodeclient.c shows the client which decodes each node of the OpenMath expression received from the server.
A simple SCSCP client could be done with the following operations. This simple client will connect with the SCSCP server located on "localhost" and listening on port 26133.
SCSCP_socketclient client;
SCSCP_status status = SCSCP_STATUS_INITIALIZER;
SCSCP_sc_init(&client, &status, SCSCP_PROTOCOL_VERSION_1_3, NULL);
SCSCP_sc_connect(&client, "localhost",
SCSCP_PROTOCOL_DEFAULTPORT, &status);
SCSCP_calloptions calloptions;
SCSCP_co_init(&calloptions, status);
SCSCP_sc_callsendstr(&client, &calloptions,
"<OMA><OMS cd=\"scscp2\" name=\"get_allowed_heads\" /></OMA>",
&status);
SCSCP_msgtype msgtype;
SCSCP_returnoptions options;
SCSCP_ro_init(&options, status);
SCSCP_sc_callrecvheader(client, &options, &msgtype,
&status);
if (msgtype==SCSCP_msgtype_ProcedureTerminated)
{
char *messagebuffer;
char *cdname;
char *symbolname;
SCSCP_sc_callrecvterminated(client, &cdname, &symbolname,
&messagebuffer, status);
}
SCSCP_msgtype msgtype;
SCSCP_returnoptions options;
char *buffer;
SCSCP_ro_init(&options, status);
SCSCP_sc_callrecvstr(client, &options, &msgtype,
&buffer, &status);
SCSCP_sc_close(&client,&status);
SCSCP_sc_clear(&client,&status);
All C++ functions and class are grouped in the namespace SCSCP.
It initializes the SCSCP server with the default versions (
SCSCP_PROTOCOL_VERSION_1_3andSCSCP_PROTOCOL_VERSION_1_2) of SCSCP protocol that could be negotiated.The arguments servicename, serviceversion and serviceid are used as the value of the attribute
service_name,service_versionandservice_idof the Connection Initiation Message.
If the server was listening on a port, the method
Server::closeis called before clearing the object. It destroys the SCSCP server.
It creates an internal queue for the incoming connections and starts to listen on the port of "localhost". If the port isn't available, it retries with the next port until it finds an available port. If port is 0, an available random port is chosen.
On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
It returns the port from the server is listening. If the function listen failed or is not called before, then this function returns -1.
It terminates to listen for the incoming connections.
On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
It extracts the first connection request on the queue of pending connections. If no pending connections are present on the queue, it blocks the caller until a connection is present.
After the Connection Initiation, the server returns an object to manage future exchanged messages.
After the transactions, the returned pointer must be deleted to close the connection and release the memory.
On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
The following example shows how to implement the main loop of the SCSCP C++ server.
SCSCP::Server server("MYCAS","1","myid");
SCSCP::IncomingClient *incomingclient;
/*listen on the default port */
server.listen();
while ((incomingclient=server.acceptclient())!=NULL)
{
... process incoming messages ...
delete incomingclient;
}
/* stop the server */
server.close();
|
The class IncomingClient handles a connection on the SCSCP server side. So on the server side, several instances of that class could exist at the same time to handle connection from different clients. That class is only instanciated by the function Server::acceptclient().
On the server side, the "Procedure Call" request are handled by an instance of Server::Computation.
If a connection with a client was already opened, the connection is closed with the client.
The class Client handles the connection on the SCSCP client side.
After a connection is initialized, the procedure call could be performed using an instance of the class Client::Computation (see Procedure call).
It initializes the SCSCP client with the default version (
SCSCP_PROTOCOL_VERSION_1_3andSCSCP_PROTOCOL_VERSION_1_2) of SCSCP protocol that could be negotiated.During the negotiation with the server, the client will choose the first version, that the server supports too, in the following order :
SCSCP_PROTOCOL_VERSION_1_3, andSCSCP_PROTOCOL_VERSION_1_2.
If a connection was already opened, the method
Client::closeis called before clearing the object. It destroys the SCSCP client.
It tries to connect to the SCSCP server which is running on the computer machine and is listening on the port port.
machine could be any string but it must resolved as an IP address. Its value could be "localhost" if the SCSCP server runs on the same computer.
In most of the case, the default value SCSCP_PROTOCOL_DEFAULTPORT should be used for the port number.
On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
It closes a connection previously opened by the client with the method
Client::connect. On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
The procedure calls are managed on the client side by a instance of the class Client::Computation.
The procedure calls are managed on the server side by a instance of the class Server::Computation.
The class Client::Computation and Server::Computation derivate from ProcedureCall and inherit of all public methods of that class.
This class should not be instantiated by the application. Only the Client::Computation and Server::Computation should be instantiated. This class provides methods to access the call options or return options of a procedure call.
It initializes the procedure call. It generates and sets the call identifier of the options of the procedure call. This call identifier is defined as the symbol
call_idof the OpenMath Content Dictionaryscscp1. The call identifier is prefixed bylibSCSCP:.
This function sets the amount of time in milliseconds, with the value time, that the SCSCP server should spend on this call. This runtime limit is defined by the symbol
option_runtimeof the OpenMath Content Dictionaryscscp1.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument time, the amount of time in milliseconds that the server should spend on this call. This amount of time is defined as the symbol
option_runtimeof the OpenMath Content Dictionaryscscp1. If the amount of time isn't available (not supplied by the server), the function fails.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function sets the minimum amount of memory in bytes, with the value memsize, that the server should use on this call. This memory limit is defined by the symbol
option_min_memoryof the OpenMath Content Dictionaryscscp1.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument memsize, the minimum amount of memory in bytes that the server should use on this call. This amount of memory is defined as the symbol
option_min_memoryof the OpenMath Content Dictionaryscscp1. If the amount of memory isn't available (not supplied by the server), the function fails.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function sets the maximum amount of memory in bytes, with the value memsize, that the SCSCP server should use on this call. This memory limit is defined by the symbol
option_max_memoryof the OpenMath Content Dictionaryscscp1.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument memsize, the maximum amount of memory in bytes that the server should use on this call. This amount of memory is defined as the symbol
option_max_memoryof the OpenMath Content Dictionaryscscp1. If the amount of memory isn't available (not supplied by the server), the function fails.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function sets the debug level, with the value debuglevel, that the client is interested. This debug level is defined by the symbol
option_debuglevelof the OpenMath Content Dictionaryscscp1.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument debuglevel, the debug level that the client is interested. This debug level is defined as the symbol
option_max_memoryof the OpenMath Content Dictionaryscscp1. If the debug level isn't available (not supplied by the server), the function fails and returns 0.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function sets the amount of time in milliseconds, with the value time, that the server spent on this call. This amount of time is defined as the symbol
info_runtimeof the OpenMath Content Dictionaryscscp1.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument time, the amount of time in milliseconds that the server spent on this call. This amount of time is defined as the symbol
info_runtimeof the OpenMath Content Dictionaryscscp1. If the amount of time isn't available (not supplied by the server), the function fails.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function sets the amount of memory in bytes, with the value memsize, that the server used on this call. This amount of memory is defined as the symbol
info_memoryof the OpenMath Content Dictionaryscscp1.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument memsize, the amount of memory in bytes that the server used for this call. This amount of memory is defined as the symbol
info_memoryof the OpenMath Content Dictionaryscscp1. If the amount of memory isn't available (not supplied by the server), the function fails.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function sets the information message, with the value buffer, of the options of the procedure return. This information message is defined as the symbol
info_messageof the OpenMath Content Dictionaryscscp1. The argument buffer can't be NULL and won't be duplicated by this function. So buffer can't be destroyed until the instance of the object is destroyed.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument buffer, the information message of the options of the procedure return. This information message is defined as the symbol
info_messageof the OpenMath Content Dictionaryscscp1. The returned string mustn't be modified.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function sets the current encoding of the OpenMath objects used by the SCSCP server or the client, to send the data. The provided Openmath buffers, such as for the call
sendstr, and the streams operations must use the same encoding.The default encoding for the SCSCP client and server is the
SCSCP_encodingtype_XML.On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument encodingtype, the current encoding of the OpenMath objects used by the SCSCP server or the client to send the data.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument returntype, the return type of the "procedure call" message that the server should send. The possible value of returntype are described in the function
SCSCP_co_set_returntype.If the return type isn't available (not supplied by the client), the function fails.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
This function returns, in the argument callid, the call id of the procedure call. The returned string mustn't be modified.
On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.
It initializes the procedure call on the client side. It generates and sets the call identifier of the options of the procedure call. This call identifier is defined as the symbol
call_idof the OpenMath Content Dictionaryscscp1. The call identifier is prefixed bylibSCSCP:.
The client sends a "procedure call" message to the SCSCP server with the options specified before. The server will return a result (object, cookie, nothing) depending on the value returntype. The array openmathbuffer is the argument of the procedure call and must be a valid OpenMath Application object with the same encoding as the instance. lenbuffer specifies the number of valid bytes in the array openmathbuffer.
On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
The client prepares a "procedure call" message to the SCSCP server with the options specified before. The server will return a result (object, cookie, nothing) depending on the value returntype.
The OpenMath data must be written to the returned stream outstream. This stream only accepts data already encoded in the OpenMath format. The application is responsible to encode data in the same encoding as specified by
get_encodingtype.The written data must be an OpenMath Application object. So it must start with
<OMA>and finish with</OMA>if the XML encoding is used.The "procedure call" message must be completed with a call to
finish()or discarded with a call todiscard(). These functions will delete the pointer outstream.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
The following example sends the "Procedure Call" message in order to compute 10! .
Client::Computation mytask(client); std::ostream* mypstream; mytask.send(SCSCP_option_return_object, mystream); *mystream << "<OMA>"; *mystream << "<OMS cd=\"integer1\" name=\"factorial\" />"; *mystream << "<OMI>10</OMI>"; *mystream << "</OMA>"; mytask.finish();
The client prepares a "procedure call" message to the SCSCP server with the options specified before. The server will return a result (object, cookie, nothing) depending on the value returntype.
The data must be written to the returned stream outstream. The data will be converted to the OpenMath encoding using the encoding specified by
get_encodingtype.The written data must be an OpenMath Application object. So it must start with
beginOMA()and finish withendOMA().The "procedure call" message must be completed with a call to
finish()or discarded with a call todiscard(). These functions will delete the pointer outstream.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
The following example sends the "Procedure Call" message in order to compute 10! .
Client::Computation mytask(client); Ounfstream *mystream; mytask.send(SCSCP_option_return_object, mystream); *mystream << beginOMA; *mystream << OMS("integer1", "factorial") << 10; *mystream << endOMA; mytask.finish();
The client waits for the answer of a "procedure call" message from the server. It reads the attribute, the type and the content of the message returned by the server in response of a procedure call.
On exit, the argument msgtype contains the message type returned by the server.
On exit, the argument openmathbuffer contains the content of the message returned by the server. This array must be freed by the system call
free. lenbuffer contains the number of valid bytes in the array openmathbuffer.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
The client waits for the answer of a "procedure call" message from the server. It reads the attribute, the type and the content of the message returned by the server in response of a procedure call.
On exit, the argument msgtype contains the message type returned by the server.
On exit, the argument stream contains a pointer to a stream. It allows to parse the input stream. This pointer is valid until to the next call to
recvorsend.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
It discards the "Procedure call" message previously created with
send. The end of the message isn't sent to the server. So the server won't process this procedure call.The stream, returned by the function
send, must not be longer used after that call.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
It completes the "Procedure call" message previously created with
send. The end of the message is sent to the server. So the server will process it.The stream, returned by the function
send, must not be longer used after that call.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
It initializes the instance to handle the procedure call on the server side.
It destroys the instance to handle the procedure call on the server side.
It waits for an incoming message. When a new message is available, then it reads the attribute, the type and the content of the message sent by the client incomingclient.
On exit, the argument msgtype must be
SCSCP_msgtype_ProcedureCallorSCSCP_msgtype_Interrupt. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument msgtype isSCSCP_msgtype_Interrupt, the call identifier of the interrupted procedure call could be retrieved with a call toget_callid().On exit, the argument openmathbuffer contains the content of the message sent by the client. This string must be freed by the system call
free.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
It waits for an incoming message. When a new message is available, then it reads the attribute, the type and the content of the message sent by the client incomingclient.
On exit, the argument msgtype must be
SCSCP_msgtype_ProcedureCallorSCSCP_msgtype_Interrupt. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument msgtype isSCSCP_msgtype_Interrupt, the call identifier of the interrupted procedure call could be retrieved with a call toget_callid().On exit, the argument stream contains a pointer to a stream. It allows to parse the input stream. This pointer is valid until to the next call to
recvorsend.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
These methods allow to send a "procedure completed" message to the client.
It sends a "procedure completed" message using an openmath buffer to the client with the options specified before. The array openmathbuffer is the argument of the procedure call and must be a valid OpenMath object with the same encoding as the instance. If the anwser is empty, openmathbuffer could be NULL. lenbuffer specifies the number of valid bytes in the array openmathbuffer.
On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
The server prepares to send a "procedure completed" message using an openmath buffer to the client with the options specified before.
The OpenMath data must be written to the returned stream outstream. This stream only accepts data already encoded in the OpenMath format. The application is responsible to encode data in the same encoding as specified by
get_encodingtype.The written data must be an OpenMath object.
The answer must be completed with a call to
finish(). That function will delete the pointer outstream.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
The server prepares to send a "procedure completed" message using an openmath buffer to the client with the options specified before.
The data must be written to the returned stream outstream. The data will be converted to the OpenMath encoding using the encoding specified by
get_encodingtype.The written data must be an OpenMath object.
The answer must be completed with a call to
finish(). That function will delete the pointer outstream.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
That method allows to send a "procedure terminated" message to the client.
It sends a "procedure terminated" message to the SCSCP client with the options specified before. The symbol of the OpenMath Error is defined by its name symbolname and its CD cdname. message is the message that will be inserted in a OMSTR OpenMath object.
On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
It completes the answer previously created with
sendcompleted. The end of the message is sent to the client. So the client will process it.The stream, returned by the function
sendcompleted, must not be longer used after that call.On exit, if an error occurs, then it returns 0 and an exception is raised if the exception mechanism is enabled. Otherwise the return value is a non-zero value.
This output stream handles the writing of the basic C data-types, such as int, double, .... It supports also the manipulators to build complex OpenMath objects. It encodes in binary or XML the OpenMath objects according to the current encoding of the stream. The following example buids the OpenMath Object, corresponding to 1+n^2 :
Ounfstream& stream =...
stream<< beginOMA << OMS("arith1","plus")
stream<< 1
stream<< beginOMA <<OMS("arith1","power") << OMV("n") << 2 << endOMA
stream<<endOMA;
It writes the beginning of the structured Open Math object
<OMA>to the stream stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the end of the structured Open Math object
</OMA>to the stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the beginning of the structured Open Math object
<OMATP>to the stream stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the end of the structured Open Math object
</OMATP>to the stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the beginning of the structured Open Math object
<OMATTR>to the stream stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the end of the structured Open Math object
</OMATTR>to the stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the beginning of the structured Open Math object
<OME>to the stream stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the end of the structured Open Math object
</OME>to the stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the beginning of the structured Open Math object
<OMOBJ>to the stream stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the end of the structured Open Math object
</OMOBJ>to the stream.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes x to the stream
outas the basic OpenMath object<OMI>...</OMI>according to the current encoding.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes x to the stream
outas the basic OpenMath object<OMF dec="..."/>according to the current encoding.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the C-style string str to the stream
outas the basic OpenMath object<OMSTR>...</OMSTR>according to the current encoding.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the OpenMath float x to the stream
outaccording to the current encoding.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the OpenMath integer x to the stream
outaccording to the current encoding.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the OpenMath reference x to the stream
outaccording to the current encoding.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the OpenMath symbol x to the stream
outaccording to the current encoding.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It writes the OpenMath variable x to the stream
outaccording to the current encoding.On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
This type is an enumeration of the possible values of the node.
The possible values are
This type in an iterator on the attributes of the Openmath elements. it could be used in a similar as iteraor of the STL.
Iunfstream& stream = .... ;
for (Iunfstream::iterator_attr attr = stream.get_attr();
attr.end() ;
++attr)
{
PRINTAB(tab+1);
cout <<"attribute : '" << attr.get_name() <<"' = '"
<< attr.get_value() <<"'"<<endl;
}
|
This type defines the following methods.
It returns true if no more attributes are available, otherwise it returns false.
It returns the name of the current attribute.
It returns the value of the current attribute.
It returns true if no more nodes are available in the stream.
It returns an iterator on the attributes of the nodes.
It returns as an enumeration the current node, .e.g, SCSCP_omtype_OMA for an OpenMath Application. It could return SCSCP_omtype_CONTENT if the node contains only a content.
It returns as a C-style string the name of the current node, .e.g, "OMA" for an OpenMath Application. It could return NULL if the node contains only a content.
It returns as a C-style string the content of the current node. It returns NULL if the content of the OpenMath object is empty.
It returns a stream to parse the children nodes of the derived OpenMath objects.
It reads an OpenMath object from the stream and converts it to the integer x. If this OpenMath object can't be converted to a floating-point, an exception is raised.
On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It reads an OpenMath object from the stream and converts it to the floating-point x. If this OpenMath object can't be converted to a floating-point, an exception is raised.
On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It reads an OpenMath string from the stream and store it to x. If this OpenMath object can't be converted to a string, an exception is raised.
On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It reads the OpenMath float x from the stream.
On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It reads the OpenMath integer x from the stream.
On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It reads the OpenMath reference x from the stream.
On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It reads the OpenMath symbol x from the stream.
On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
It reads the OpenMath variable x from the stream.
On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.
On errors, the C++ functions raise an exception of type Exception which derivates from the STL std::exception.
It initializes the SCSCP exception wit the specified status information.
It returns a C-style character string describing the general cause of the current error.
These OpenMath objects are usefull to perform the input or output from/to the stream. All these OpenMath objects derivate from the base class OMBase.
The C-style string accepted by their constructor aren't duplicated and must exist during the life of the instance of the object.
The method beginOM is a common method for derived OpenMath object, such as OMA, OME, ....
It returns the reference id (<OM .... id="...">) of the Openmath object. It may return NULL if the reference id of the object is unset.
It creates the OpenMath application with the reference id. paramid
It returns a stream to parse the children nodes of the derived OpenMath objects.
It creates the OpenMath binding with the reference id. paramid
It returns a stream to parse the children nodes of the derived OpenMath objects.
It creates the OpenMath error with the reference id. paramid
It returns a stream to parse the children nodes of the derived OpenMath objects.
It creates the OpenMath float with the value and the reference id. paramid The C-style string href isn't duplicated. value must be in base 10.
This function returns the value of the Openmath float.
It creates the OpenMath integer with the value and the reference id. paramid The C-style string href isn't duplicated. value must be in base 10.
This function returns the value of the Openmath integer.
It creates the OpenMath reference href. The C-style string href isn't duplicated.
This function returns the value of the Openmath reference.
It creates the OpenMath symbol symbolname of the Content Dictionary cdname. The C-style strings cdname and symbolname aren't duplicated. id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function returns the cd name of the Openmath symbol.
This function returns the symbol name of the Openmath symbol.
It creates the OpenMath variable name. The C-style string name isn't duplicated. id is the id of this object for the future reference (see OMR). id could be NULL if unset.
This function returns the name of the Openmath variable.
The file examples/decodeserverxx.cpp shows the server which decodes each node of the OpenMath expression received from the client. It sends an answer to the client depending on the call options.
A simple SCSCP C++ server could be done with the following operations. This server supports the scscp versions "1.3".
Server server("MYCAS", "1.0", "myid");
server.listen();
IncomingClient *incomingclient;
while ((incomingclient=server.acceptclient())!=NULL)
{
Server::Computation mytask(incomingclient);
Iunfstream *mystream;
mytask.recv(msgtype, mystream);
...
char *openmathbuffer;
mytask.recv(msgtype, openmathbuffer, lenbuffer);
....
free(openmathbuffer);
const char *answer="<OMI>10</OMI>";
mytask.sendcompleted(answer, ::strlen(answer));
std::ostream*& stream;
mytask.sendcompleted(stream);
*stream << "<OMI>10</OMI>";
mytask.finish();
Ounfstream* stream;
mytask.sendcompleted(stream);
*stream << 10;
mytask.finish();
const char *messageerror="can't store an object";
mytask.sendterminated("sccsp1", "error_system_specific",
messageerror);
delete incomingclient;
}
server.close();
The file examples/simplestclientxx.cpp shows the simplest client which stores the value 6177887 on the server using the C-byte array and prints the answer of the server.
The file examples/simplestclientstreamfmtxx.cpp shows the simplest client which stores the value 6177887 on the server using the STL ostream and prints the answer of the server.
The file examples/simplestclientstreamunfxx.cpp shows the simplest client which stores the value 435 on the server using the unformatted stream and prints the answer of the server.
A simple SCSCP client could be done with the following operations. This simple client will connect with the SCSCP server located on "localhost" and listening on port 26133.
SCSCP::Client client;
client.connect("localhost");
const char *cmd = "<OMA><OMS cd=\"scscp2\"
name=\"get_allowed_heads\"/></OMA>";
mytask.send(cmd, ::strlen(cmd), SCSCP_option_return_object);
std::ostream*& stream;
mytask.send(SCSCP_option_return_object, stream);
*stream << "<OMA>";
*stream << "<OMS cd=\"scscp2\" name=\"get_allowed_heads\"/>
*stream << </OMA>";
mytask.finish();
Ounfstream* stream;
mytask.send(SCSCP_option_return_object, stream);
*stream << beginOMA;
*stream << OMS("scscp2","get_allowed_heads");
*stream << endOMA;
mytask.finish();
Iunfstream *mystream;
mytask.recv(msgtype, mystream);
...
char *buffer;
size_t lenbuffer;
SCSCP_msgtype msgtype;
mytask.recv(msgtype, buffer,lenbuffer);
client.close();
Version 1.3, 2009
S.Freundt, P.Horn, A.Konovalov, S.Linton, D.Roozemond.
D. Roozemond
D. Roozemond