SCSCP C Library

Table of Contents


Next: , Up: (dir)

SCSCP C Library


Next: , Previous: Top, Up: Top

1 SCSCP C Library Copying conditions

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.


Next: , Previous: SCSCP C Library Copying conditions, Up: Top

2 Introduction to SCSCP C Library

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.


Next: , Previous: Introduction to SCSCP C Library, Up: Top

3 Installing SCSCP C Library

3.1 Installation on a Unix-like system (Linux, Mac OS X, BSD, cygwin, ...)

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:

  1. `tar xzf scscp-1.0.3.tar.gz'
  2. `cd scscp-1.0.3'
  3. `./configure'

    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.

    --help
    -h
    Print a summary of all of the options to configure, and exit.
    --prefix=dir
    Use dir as the installation prefix. See the command make install for the installation names.
  4. `make'

    This compiles SCSCP C Library in the working directory.

  5. `make check'

    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).

  6. `make install'

    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.

3.1.1 Other `make' Targets

There are some other useful make targets:

3.2 Installation on Windows system

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:

  1. Expand the file `scscp-1.0.3.tar.gz'
  2. Execute the command `cmd.exe' from the menu `Start' / `Execute...'

    This will open a console window

  3. `cd 'dir`\scscp-1.0.3'

    Go to the directory dir where SCSCP C Library has been expanded.

  4. `nmake /f makefile.vc XMLDIR=dir'

    This compiles SCSCP C Library in the working directory. Use dir as the installation directory of the libxml2 library.

  5. `nmake /f makefile.vc XMLDIR=dir check'

    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).

  6. `nmake /f makefile.vc install DESTDIR=dir'

    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.


Next: , Previous: Installing SCSCP C Library, Up: Top

4 Reporting bugs


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.


Next: , Previous: Reporting bugs, Up: Top

5 SCSCP C Library Basics

5.1 Headers and Libraries

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>

5.1.1 Compilation on a Unix-like system

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.

5.1.2 Compilation on a Windows system

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.

5.2 Thread safe

SCSCP C Library is reentrant and thread-safe wit some exceptions:

  1. It's safe for two threads to read from the same SCSCP variable simultaneously, but it's not safe for one to read while the another might be writing, nor for two threads to write simultaneously.
  2. If the standard I/O functions such as send are not reentrant then the SCSCP I/O functions using them will not be reentrant either.


Next: , Previous: SCSCP C Library Basics, Up: Top

6 C Interface


Next: , Up: C Interface

6.1 Constants

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.


Next: , Previous: Constants, Up: C Interface

6.2 Types


Next: , Up: Types

6.2.1 SCSCP_socketserver

— Data type: SCSCP_socketserver

This type contains all information of the SCSCP server.

Before using any object of this type, the function SCSCP_ss_init must be called.


Next: , Previous: SCSCP_socketserver, Up: Types

6.2.2 SCSCP_socketclient

— Data type: SCSCP_socketclient

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_init must be called.


Next: , Previous: SCSCP_socketclient, Up: Types

6.2.3 SCSCP_incomingclient

— Data type: SCSCP_incomingclient

This type contains all information of an incoming connection accepted by a server.


Next: , Previous: SCSCP_incomingclient, Up: Types

6.2.4 SCSCP_status

— Data type: SCSCP_status

This type contains all information about errors. Before using any object of this type, the SCSCP_STATUS_INITIALIZER must 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_IGNORE could 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.


Next: , Previous: SCSCP_status, Up: Types

6.2.5 SCSCP_calloptions

— Data type: SCSCP_calloptions

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 functions SCSCP_co_get_xxx.

The value SCSCP_CALLOPTIONS_DEFAULT could be used in order to use the default procedure call options. In this case, a unique call identifier will be generated using the prefix libSCSCP: and the procedure call will return no value (SCSCP_option_return_nothing will be used).

Before using any object of this type, the function SCSCP_co_init must be called.


Next: , Previous: SCSCP_calloptions, Up: Types

6.2.6 SCSCP_returnoptions

— Data type: SCSCP_returnoptions

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 functions SCSCP_ro_get_xxx.

The value SCSCP_RETURNOPTIONS_IGNORE could be used in order to ignore the returned value by the function SCSCP_sc_callrecvheader, SCSCP_sc_callrecvstr.

Before using any object of this type, the function SCSCP_ro_init must be called.


Next: , Previous: SCSCP_returnoptions, Up: Types

6.2.7 SCSCP_msgtype

— Data type: SCSCP_msgtype

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_terminated of the OpenMath Content Dictionary scscp1.
`SCSCP_msgtype_ProcedureCompleted'
The message is a "Procedure completed". It is defined by the symbol procedure_completed of the OpenMath Content Dictionary scscp1.
`SCSCP_msgtype_ProcedureCall'
The message is a "Procedure call". It is defined by the symbol procedure_call of the OpenMath Content Dictionary scscp1.
`SCSCP_msgtype_Interrupt'
The message is a "Interrupt" signal. It is defined by the processing instruction "<? scscp terminate ?>".


Next: , Previous: SCSCP_msgtype, Up: Types

6.2.8 SCSCP_encodingtype

— Data type: SCSCP_encodingtype

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.


Next: , Previous: SCSCP_encodingtype, Up: Types

6.2.9 SCSCP_xmlnodeptr

— Data type: SCSCP_xmlnodeptr

This type defines a pointer to a node of a XML tree.


Next: , Previous: SCSCP_xmlnodeptr, Up: Types

6.2.10 SCSCP_xmlattrptr

— Data type: SCSCP_xmlattrptr

This type defines a pointer to an attribute of a node of type SCSCP_xmlnodeptr (noode of a XML tree).


Previous: SCSCP_xmlattrptr, Up: Types

6.2.11 SCSCP_io

— Data type: SCSCP_io

This type defines a pointer to a low-level Input/output stream.


Next: , Previous: Types, Up: C Interface

6.3 Server functions

The following functions manage all operations on the SCSCP_socketserver and SCSCP_incomingclient objects.

6.3.1 SCSCP_ss_init

— Library Function: int SCSCP_ss_init

( 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);
 

6.3.2 SCSCP_ss_clear

— Library Function: int SCSCP_ss_clear ( SCSCP_socketserver* server, SCSCP_status* status )

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.

6.3.3 SCSCP_ss_listen

— Library Function: int SCSCP_ss_listen ( SCSCP_socketserver* server, int port, int firstavailable, SCSCP_status* status )

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.

6.3.4 SCSCP_ss_getport

— Library Function: int SCSCP_ss_getport (SCSCP_socketserver* server)
It returns the port from the server is listening. If the function listen failed or is not called before, then this function returns -1.

6.3.5 SCSCP_ss_close

— Library Function: int SCSCP_ss_close ( SCSCP_socketserver* server, SCSCP_status* status )

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.

6.3.6 SCSCP_ss_acceptclient

— Library Function: int SCSCP_ss_acceptclient ( SCSCP_socketserver* server, SCSCP_incomingclient* incomingclient, SCSCP_status* status )

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);
     

6.3.7 SCSCP_ss_closeincoming

— Library Function: int SCSCP_ss_closeincoming ( SCSCP_incomingclient* incomingclient, SCSCP_status* 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.

6.3.8 SCSCP_ss_callrecvstr

— Library Function: int SCSCP_ss_callrecvstr ( SCSCP_incomingclient* incomingclient, SCSCP_calloptions* options, SCSCP_msgtype* msgtype, char** openmathbuffer, SCSCP_status* status)

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.

6.3.9 SCSCP_ss_callrecvheader

— Library Function: int SCSCP_ss_callrecvheader ( SCSCP_incomingclient* incomingclient, SCSCP_calloptions* options, SCSCP_msgtype* msgtype, SCSCP_status* status)

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.

6.3.10 SCSCP_ss_getxmlnode

— Library Function: SCSCP_xmlnodeptr SCSCP_ss_getxmlnode ( SCSCP_incomingclient* incomingclient, SCSCP_status* status)
This function returns a pointer to the current XML tree received from the client. This function could be used to start parsing the message sent by the client. This pointer is valid until the next call to the functions 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.

6.3.11 SCSCP_ss_getxmlnoderawstring

— Library Function: char * SCSCP_ss_getxmlnoderawstring ( SCSCP_incomingclient* incomingclient, SCSCP_xmlnodeptr curnode, SCSCP_status* status)
This function returns the content of the current node curnode and its children as a string. This string must be freed by the system call 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.

6.3.12 SCSCP_ss_sendterminatedstr

— Library Function: int SCSCP_ss_sendterminatedstr ( SCSCP_incomingclient* incomingclient, SCSCP_returnoptions* options, const char * cdname, const char * symbolname, const char * message, SCSCP_status* status )

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);

6.3.13 SCSCP_ss_sendcompletedstr

— Library Function: int SCSCP_ss_sendcompletedstr ( SCSCP_incomingclient* incomingclient, SCSCP_returnoptions* options, const char * openmathbuffer, SCSCP_status* 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.

6.3.14 SCSCP_ss_sendcompletedhook

— Library Function: int SCSCP_ss_sendcompletedhook ( SCSCP_incomingclient* incomingclient, SCSCP_returnoptions* options, int (*callbackwriteargs)(SCSCP_io* stream, void *param, SCSCP_status* status), void* param, SCSCP_status* status)

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.

6.3.15 SCSCP_ss_infomessagesend

— Library Function: int SCSCP_ss_infomessagesend ( SCSCP_incomingclient* incomingclient, const char* messagebuffer, SCSCP_status* status )

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.

6.3.16 SCSCP_ss_set_encodingtype

— Library Function: int SCSCP_ss_set_encodingtype ( SCSCP_incomingclient* incomingclient, SCSCP_encodingtype encodingtype, SCSCP_status* status )
This function sets the current encoding of the OpenMath objects used by the SCSCP server to send an answer. The provided Openmath buffers, such as for the call 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.

6.3.17 SCSCP_ss_get_encodingtype

— Library Function: int SCSCP_ss_set_encodingtype ( SCSCP_incomingclient* incomingclient, SCSCP_encodingtype* encodingtype, SCSCP_status* status )
This function returns, in the argument encodingtype, the current encoding for the OpenMath objects when the SCSCP server sends an answer.

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.


Next: , Previous: Server functions, Up: C Interface

6.4 Client functions

The following functions manage all operations on the SCSCP_socketclient object.

6.4.1 SCSCP_sc_init

— Library Function: int SCSCP_sc_init

( SCSCP_socketclient* client, SCSCP_status* status, ... )

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);

6.4.2 SCSCP_sc_clear

— Library Function: int SCSCP_sc_clear ( SCSCP_socketclient* client, SCSCP_status* status )

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.

6.4.3 SCSCP_sc_connect

— Library Function: int SCSCP_sc_connect

( 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.

6.4.4 SCSCP_sc_close

— Library Function: int SCSCP_sc_close ( SCSCP_socketclient* client, SCSCP_status* status )
It closes a connection previously opened by a SCSCP client with the function 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.

6.4.5 SCSCP_sc_set_encodingtype

— Library Function: int SCSCP_sc_set_encodingtype ( SCSCP_socketclient* client, SCSCP_encodingtype encodingtype, SCSCP_status* status )
This function sets the current encoding of the OpenMath objects used by the SCSCP client to send a "procedure call" message. The provided Openmath buffers, such as for the call 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.

6.4.6 SCSCP_sc_get_encodingtype

— Library Function: int SCSCP_sc_set_encodingtype ( SCSCP_socketclient* client, SCSCP_encodingtype* encodingtype, SCSCP_status* status )
This function returns, in the argument encodingtype, the current encoding for the OpenMath objects when the SCSCP client sends a "procedure call" message.

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.

6.4.7 SCSCP_sc_callsendstr

— Library Function: int SCSCP_sc_callsendstr ( SCSCP_socketclient* client, SCSCP_calloptions* options, const char * openmathbuffer, SCSCP_status* status )

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.

6.4.8 SCSCP_sc_callrecvstr

— Library Function: int SCSCP_sc_callrecvstr ( SCSCP_socketclient* client, SCSCP_returnoptions* options, SCSCP_msgtype* msgtype, char** openmathbuffer, SCSCP_status* status)

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.

6.4.9 SCSCP_sc_callsendhook

— Library Function: int SCSCP_sc_callsendhook ( SCSCP_socketclient* client, SCSCP_calloptions* options, int (*callbackwriteappli)(SCSCP_io* stream, void *param, SCSCP_status* status), void* param, SCSCP_status* status)

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.

6.4.10 SCSCP_sc_callrecvheader

— Library Function: int SCSCP_sc_callrecvheader ( SCSCP_socketclient* client, SCSCP_returnoptions* options, SCSCP_msgtype* msgtype, SCSCP_status* status)

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.

6.4.11 SCSCP_sc_callrecvterminated

— Library Function: int SCSCP_sc_callrecvterminated ( SCSCP_socketclient* client, char ** cdname, char ** symbolname, char** messagebuffer, SCSCP_status* status)

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.

6.4.12 SCSCP_sc_callrecvcompleted

— Library Function: int SCSCP_sc_callrecvcompleted ( SCSCP_socketclient* client, char** openmathbuffer, SCSCP_status* status)
The client reads the content of the messages if the server replies with a "procedure completed" message. This function must be called only if 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.

6.4.13 SCSCP_sc_callsendinterrupt

— Library Function: int SCSCP_sc_callsendinterrupt ( SCSCP_socketclient* client, const char* call_id, SCSCP_status* status )

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.

6.4.14 SCSCP_sc_executehookxmlnode

— Library Function: int SCSCP_sc_executehookxmlnode ( SCSCP_socketclient* client, SCSCP_option_return returntype, const char * cdname, const char* symbolname, int (*callbackwriteargs)(SCSCP_io* stream, void *param, SCSCP_status* status), void* param, SCSCP_xmlnodeptr* node, SCSCP_status* status)

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.

6.4.15 SCSCP_sc_executehookstr

— Library Function: int SCSCP_sc_executehookstr ( SCSCP_socketclient* client, SCSCP_option_return returntype, const char * cdname, const char* symbolname, int (*callbackwriteargs)(SCSCP_io* stream, void *param, SCSCP_status* status), void* param, char ** openmathbuffer, SCSCP_status* status)

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.

6.4.16 SCSCP_sc_infomessagesend

— Library Function: int SCSCP_sc_infomessagesend ( SCSCP_socketclient* client, const char* messagebuffer, SCSCP_status* status )

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.

6.4.17 SCSCP_sc_getxmlnode

— Library Function: SCSCP_xmlnodeptr SCSCP_sc_getxmlnode ( SCSCP_socketclient* client, SCSCP_status* status)
The client returns a pointer to the current XML tree. This function could be used to start parsing the message sent by the server. This pointer is valid until the next call to the functions 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.

6.4.18 SCSCP_sc_getxmlnoderawstring

— Library Function: char * SCSCP_sc_getxmlnoderawstring ( SCSCP_socketclient* client, SCSCP_xmlnodeptr curnode, SCSCP_status* status)
This function returns the content of the current node curnode and its children as a string. This string must be freed by the system call 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.


Next: , Previous: Client functions, Up: C Interface

6.5 I/O functions

6.5.1 SCSCP_io_write

— Library Function: int SCSCP_io_write ( SCSCP_io* stream, const char *buffer, SCSCP_status* status )

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.

6.5.2 SCSCP_io_writeOMSTR

— Library Function: int SCSCP_io_writeOMSTR ( SCSCP_io* stream, const char *buffer, const char *id, SCSCP_status* status )

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.

6.5.3 SCSCP_io_writeOMFdouble

— Library Function: int SCSCP_io_writeOMFdouble ( SCSCP_io* stream, double x, const char *id, SCSCP_status* status )

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.

6.5.4 SCSCP_io_writeOMFstr

— Library Function: int SCSCP_io_writeOMFstr ( SCSCP_io* stream, const char* buffer, const char *id, SCSCP_status* status )

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.

6.5.5 SCSCP_io_writeOMIint

— Library Function: int SCSCP_io_writeOMIint ( SCSCP_io* stream, int x, const char *id, SCSCP_status* status )

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.

6.5.6 SCSCP_io_writeOMIlonglong

— Library Function: int SCSCP_io_writeOMIlonglong ( SCSCP_io* stream, long long x, const char *id, SCSCP_status* status )

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.

6.5.7 SCSCP_io_writeOMIstr

— Library Function: int SCSCP_io_writeOMIstr ( SCSCP_io* stream, const char* buffer, const char *id, SCSCP_status* status )

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.

6.5.8 SCSCP_io_writeOMS

— Library Function: int SCSCP_io_writeOMS ( SCSCP_io* stream, const char* cdname, const char* symbolname, const char *id, SCSCP_status* status )

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.

6.5.9 SCSCP_io_writeOMV

— Library Function: int SCSCP_io_writeOMV ( SCSCP_io* stream, const char* buffer, const char *id, SCSCP_status* status )

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.

6.5.10 SCSCP_io_writeOMR

— Library Function: int SCSCP_io_writeOMR ( SCSCP_io* stream, const char* buffer, SCSCP_status* status )

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.

6.5.11 SCSCP_io_writeOMB

— Library Function: int SCSCP_io_writeOMB ( SCSCP_io* stream, const void* buffer, size_t lenbuffer SCSCP_status* status )

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.

6.5.12 SCSCP_io_writebeginOMA

— Library Function: int SCSCP_io_writebeginOMA ( SCSCP_io* stream, const char *id, SCSCP_status* status )

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.

6.5.13 SCSCP_io_writeendOMA

— Library Function: int SCSCP_io_writeendOMA ( SCSCP_io* stream, SCSCP_status* status )

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.

6.5.14 SCSCP_io_writebeginOMATP

— Library Function: int SCSCP_io_writebeginOMATP ( SCSCP_io* stream, const char *id, SCSCP_status* status )

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.

6.5.15 SCSCP_io_writeendOMATP

— Library Function: int SCSCP_io_writeendOMATP ( SCSCP_io* stream, SCSCP_status* status )

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.

6.5.16 SCSCP_io_writebeginOMATTR

— Library Function: int SCSCP_io_writebeginOMATTR ( SCSCP_io* stream, const char *id, SCSCP_status* status )

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.

6.5.17 SCSCP_io_writeendOMATTR

— Library Function: int SCSCP_io_writeendOMATTR ( SCSCP_io* stream, SCSCP_status* status )

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.

6.5.18 SCSCP_io_writebeginOMBIND

— Library Function: int SCSCP_io_writebeginOMBIND ( SCSCP_io* stream, const char *id, SCSCP_status* status )

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.

6.5.19 SCSCP_io_writeendOMBIND

— Library Function: int SCSCP_io_writeendOMBIND ( SCSCP_io* stream, SCSCP_status* status )

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.

6.5.20 SCSCP_io_writebeginOME

— Library Function: int SCSCP_io_writebeginOME ( SCSCP_io* stream, const char *id, SCSCP_status* status )

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.

6.5.21 SCSCP_io_writeendOME

— Library Function: int SCSCP_io_writeendOME ( SCSCP_io* stream, SCSCP_status* status )

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.

6.5.22 SCSCP_io_writebeginOMFOREIGN

— Library Function: int SCSCP_io_writebeginOMFOREIGN ( SCSCP_io* stream, const char *id, SCSCP_status* status )

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.

6.5.23 SCSCP_io_writeendOMFOREIGN

— Library Function: int SCSCP_io_writeendOMFOREIGN ( SCSCP_io* stream, SCSCP_status* status )

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.

6.5.24 SCSCP_io_writebeginOMOBJ

— Library Function: int SCSCP_io_writebeginOMOBJ ( SCSCP_io* stream, SCSCP_status* status )

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.

6.5.25 SCSCP_io_writeendOMOBJ

— Library Function: int SCSCP_io_writeendOMOBJ ( SCSCP_io* stream, SCSCP_status* status )

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.


Next: , Previous: I/O functions, Up: C Interface

6.6 Status functions

6.6.1 SCSCP_status_clear

— Library Function: void SCSCP_status_clear (SCSCP_status* status )

It clears the internal structure of the object status and frees allocated memory for this object by any error of the library.

6.6.2 SCSCP_status_is

— Library Function: int SCSCP_status_is ( SCSCP_status* status )

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");
      }

6.6.3 SCSCP_status_strerror

— Library Function: const char* SCSCP_status_strerror (const SCSCP_status* status )

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));
      }


Next: , Previous: Status functions, Up: C Interface

6.7 Procedure call options functions

6.7.1 SCSCP_co_init

— Library Function: int SCSCP_co_init ( SCSCP_calloptions* options, SCSCP_status* 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.

6.7.2 SCSCP_co_clear

— Library Function: int SCSCP_co_clear ( SCSCP_calloptions* options, SCSCP_status* status )

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.

6.7.3 SCSCP_co_set_callid

— Library Function: int SCSCP_co_set_callid ( SCSCP_calloptions* options, const char *buffer, SCSCP_status* status )

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.

6.7.4 SCSCP_co_get_callid

— Library Function: int SCSCP_co_get_callid ( SCSCP_calloptions* options, const char **buffer, SCSCP_status* status )

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.

6.7.5 SCSCP_co_set_runtimelimit

— Library Function: int SCSCP_co_set_runtimelimit ( SCSCP_calloptions* options, size_t time, SCSCP_status* status )

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.

6.7.6 SCSCP_co_get_runtimelimit

— Library Function: int SCSCP_co_get_runtimelimit ( SCSCP_calloptions* options, size_t* time, SCSCP_status* status )

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.

6.7.7 SCSCP_co_set_minmemory

— Library Function: int SCSCP_co_set_minmemory ( SCSCP_calloptions* options, size_t memsize, SCSCP_status* status )

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.

6.7.8 SCSCP_co_get_minmemory

— Library Function: int SCSCP_co_get_minmemory ( SCSCP_calloptions* options, size_t* memsize, SCSCP_status* status )

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.

6.7.9 SCSCP_co_set_maxmemory

— Library Function: int SCSCP_co_set_maxmemory ( SCSCP_calloptions* options, size_t memsize, SCSCP_status* status )

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.

6.7.10 SCSCP_co_get_maxmemory

— Library Function: int SCSCP_co_get_maxmemory ( SCSCP_calloptions* options, size_t* memsize, SCSCP_status* status )

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.

6.7.11 SCSCP_co_set_debuglevel

— Library Function: int SCSCP_co_set_debuglevel ( SCSCP_calloptions* options, int debuglevel, SCSCP_status* status )

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.

6.7.12 SCSCP_co_get_debuglevel

— Library Function: int SCSCP_co_get_debuglevel ( SCSCP_calloptions* options, int* debuglevel, SCSCP_status* status )

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.

6.7.13 SCSCP_co_set_returntype

— Library Function: int SCSCP_co_set_returntype ( SCSCP_calloptions* options, SCSCP_option_return returntype, SCSCP_status* status )

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

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.

6.7.14 SCSCP_co_get_returntype

— Library Function: int SCSCP_co_get_returntype ( SCSCP_calloptions* options, SCSCP_option_return* returntype, SCSCP_status* status )

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.

6.7.15 SCSCP_co_get_encodingtype

— Library Function: int SCSCP_co_get_encodingtype ( SCSCP_calloptions* options, SCSCP_encodingtype* encodingtype, SCSCP_status* status )
This function returns, in the argument encodingtype, the current encoding for the OpenMath objects associated with this "procedure call" message.

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.


Next: , Previous: Procedure call options functions, Up: C Interface

6.8 Procedure return options functions

6.8.1 SCSCP_ro_init

— Library Function: int SCSCP_ro_init ( SCSCP_returnoptions* options, SCSCP_status* status )

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.

6.8.2 SCSCP_ro_clear

— Library Function: int SCSCP_ro_clear ( SCSCP_returnoptions* options, SCSCP_status* status )

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.

6.8.3 SCSCP_ro_set_callid

— Library Function: int SCSCP_ro_set_callid ( SCSCP_returnoptions* options, const char *buffer, SCSCP_status* status )

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.

6.8.4 SCSCP_ro_get_callid

— Library Function: int SCSCP_ro_get_callid ( SCSCP_returnoptions* options, const char **buffer, SCSCP_status* status )

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.

6.8.5 SCSCP_ro_set_runtime

— Library Function: int SCSCP_ro_set_runtime ( SCSCP_returnoptions* options, size_t time, SCSCP_status* status )

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.

6.8.6 SCSCP_ro_get_runtime

— Library Function: int SCSCP_ro_get_runtime ( SCSCP_returnoptions* options, size_t* time, SCSCP_status* status )

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.

6.8.7 SCSCP_ro_set_memory

— Library Function: int SCSCP_ro_set_memory ( SCSCP_returnoptions* options, size_t memsize, SCSCP_status* status )

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.

6.8.8 SCSCP_ro_get_memory

— Library Function: int SCSCP_ro_get_memory ( SCSCP_returnoptions* options, size_t* memsize, SCSCP_status* status )

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.

6.8.9 SCSCP_ro_set_message

— Library Function: int SCSCP_ro_set_message ( SCSCP_returnoptions* options, const char *buffer, SCSCP_status* status )

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.

6.8.10 SCSCP_ro_get_message

— Library Function: int SCSCP_ro_get_message ( SCSCP_returnoptions* options, const char **buffer, SCSCP_status* status )

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.


Next: , Previous: Procedure return options functions, Up: C Interface

6.9 XML parsing functions

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);
        }
     }

6.9.1 SCSCP_xmlnode_getnext

— Library Function: SCSCP_xmlnodeptr SCSCP_xmlnode_getnext ( SCSCP_xmlnodeptr curnode )
This function returns a pointer to the next node. If curnode is the last element, this function returns NULL.

6.9.2 SCSCP_xmlnode_getname

— Library Function: const char* SCSCP_xmlnode_getname ( SCSCP_xmlnodeptr curnode )
This function returns the name of the node curnode.

6.9.3 SCSCP_xmlnode_getid

— Library Function: const char* SCSCP_xmlnode_getid ( SCSCP_xmlnodeptr curnode )
This function returns the reference id (<OM... id="...">) of the node curnode. The function returns NULL if the reference id isn't available.

6.9.4 SCSCP_xmlnode_getchild

— Library Function: SCSCP_xmlnodeptr SCSCP_xmlnode_getchild ( SCSCP_xmlnodeptr curnode )
This function returns the first child of the node curnode. The function returns NULL if it has no child.

6.9.5 SCSCP_xmlnode_getcontent

— Library Function: const char * SCSCP_xmlnode_getcontent ( SCSCP_xmlnodeptr curnode )
This function returns as a string the content of the node curnode.

6.9.6 SCSCP_xmlnode_getattr

— Library Function: SCSCP_xmlattrptr SCSCP_xmlnode_getattr ( SCSCP_xmlnodeptr curnode )
This function returns the first attribute of the node curnode.

6.9.7 SCSCP_xmlattr_getnext

— Library Function: SCSCP_xmlattrptr SCSCP_xmlattr_getnext ( SCSCP_xmlattrptr attr )
This function returns a pointer to the next attribute. If attr is the last attribute, this function returns NULL.

6.9.8 SCSCP_xmlattr_getvalue

— Library Function: int SCSCP_xmlattr_getvalue ( SCSCP_xmlattrptr attr, const char ** name, const char ** value )
This function returns, in the argument name, a pointer to the name of the attribute attr and returns, in the argument value, a pointer to the value of the attribute attr.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

6.9.9 SCSCP_xmlnode_readOMS

— Library Function: int SCSCP_xmlnode_readOMS ( SCSCP_xmlnodeptr* node, const char ** cdname, const char ** symbolname )
This function reads an OpenMath symbol and the cd name to cdname and the name to symbolname. symbolname and cdname mustn't be NULL.

On exit, it returns 0 if node doesn't contain an OpenMath symbol , otherwise the return value is a non-zero value.

6.9.10 SCSCP_xmlnode_readOMIstr

— Library Function: int SCSCP_xmlnode_readOMIstr ( SCSCP_xmlnodeptr* node, const char ** value)
This function reads an OpenMath integer and stores it to value. value mustn't be NULL.

On exit, it returns 0 if node doesn't contain an OpenMath integer , otherwise the return value is a non-zero value.

6.9.11 SCSCP_xmlnode_readOMIint

— Library Function: int SCSCP_xmlnode_readOMIint ( SCSCP_xmlnodeptr* node, int* value)
This function reads an OpenMath integer and store it to value.

On exit, it returns 0 if node doesn't contain an OpenMath integer , otherwise the return value is a non-zero value.

6.9.12 SCSCP_xmlnode_readOMFstr

— Library Function: int SCSCP_xmlnode_readOMFstr ( SCSCP_xmlnodeptr* node, const char ** value, int * base)
This function reads an OpenMath floating-point number and stores it to value. It stores to base the base used to represent the floating-point number (16 for "hex", 10 for "dec"). value and base mustn't be NULL.

On exit, it returns 0 if node doesn't contain an OpenMath floating-point , otherwise the return value is a non-zero value.

6.9.13 SCSCP_xmlnode_readOMFdouble

— Library Function: int SCSCP_xmlnode_readOMFdouble ( SCSCP_xmlnodeptr* node, double* value)
This function reads an OpenMath floating-point number and stores it to value. value mustn't be NULL.

On exit, it returns 0 if node doesn't contain an OpenMath floating-point , otherwise the return value is a non-zero value.

6.9.14 SCSCP_xmlnode_readOMSTR

— Library Function: int SCSCP_xmlnode_readOMSTR ( SCSCP_xmlnodeptr* node, const char ** value)
This function reads an OpenMath string and store it to value. value mustn't be NULL.

On exit, it returns 0 if node doesn't contain an OpenMath string , otherwise the return value is a non-zero value.

6.9.15 SCSCP_xmlnode_readOMR

— Library Function: int SCSCP_xmlnode_readOMR ( SCSCP_xmlnodeptr* node, const char ** value)
This function reads an OpenMath reference and stores it to value. value mustn't be NULL.

On exit, it returns 0 if node doesn't contain an OpenMath reference , otherwise the return value is a non-zero value.

6.9.16 SCSCP_xmlnode_readOMV

— Library Function: int SCSCP_xmlnode_readOMV ( SCSCP_xmlnodeptr* node, const char ** value)
This function reads an OpenMath variable and stores it to value. value mustn't be NULL.

On exit, it returns 0 if node doesn't contain an OpenMath variable , otherwise the return value is a non-zero value.

6.9.17 SCSCP_xmlnode_readpairOMSOMSTR

— Library Function: int SCSCP_xmlnode_readpairOMSOMSTR ( SCSCP_xmlnodeptr* node, const char *cdname, const char *symbolname, const char **buffer)
This function reads an OpenMath symbol and an OpenMath string. It checks that the symbol has the same symbol name and cd name as the arguments symbolname and cdname. It stores the OpenMath string to value. cdname, symbolname and value mustn't be NULL.

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.


Next: , Previous: XML parsing functions, Up: C Interface

6.10 Remote objects functions

6.10.1 SCSCP_sc_remoteobjectstoresessionhook

— Library Function: int SCSCP_sc_remoteobjectstoresessionhook ( SCSCP_socketclient* client, int (*callbackwriteargs)(SCSCP_io* stream, void *param, SCSCP_status* status), void* param, char ** cookiename, SCSCP_status* status)

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.

6.10.2 SCSCP_sc_remoteobjectstorepersistenthook

— Library Function: int SCSCP_sc_remoteobjectstorepersistenthook ( SCSCP_socketclient* client, int (*callbackwriteargs)(SCSCP_io* stream, void *param, SCSCP_status* status), void* param, char ** cookiename, SCSCP_status* status)

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.

6.10.3 SCSCP_sc_remoteobjectretrievexmlnode

— Library Function: int SCSCP_sc_remoteobjectretrievexmlnode ( SCSCP_socketclient* client, const char *cookiename, SCSCP_xmlnodeptr* node, SCSCP_status* status)

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.

6.10.4 SCSCP_sc_remoteobjectretrievestr

— Library Function: int SCSCP_sc_remoteobjectretrievestr ( SCSCP_socketclient* client, const char *cookiename, char** openmathbuffer, SCSCP_status* status)

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.

6.10.5 SCSCP_sc_remoteobjectunbind

— Library Function: int SCSCP_sc_remoteobjectunbind ( SCSCP_socketclient* client, const char *cookiename, SCSCP_status* status)

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.


Previous: Remote objects functions, Up: C Interface

6.11 Miscellaneous functions

6.11.1 SCSCP_get_libversionstr

— Library Function: const char* SCSCP_get_libversionstr (void)

Return the SCSCP C Library version, as a null-terminated string.

6.11.2 SCSCP_get_libversionnum

— Library Function: void SCSCP_get_libversionnum (unsigned int *major, unsigned int *minor, unsigned int *patch)

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.

6.11.3 SCSCP_CHECK_LIBVERSION

— Library Function: int SCSCP_CHECK_LIBVERSION ()

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


Next: , Previous: C Interface, Up: Top

7 Design a SCSCP C server

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".


Next: , Previous: Design a SCSCP C server, Up: Top

8 Design a SCSCP C client

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.


Next: , Previous: Design a SCSCP C client, Up: Top

9 C++ Interface

All C++ functions and class are grouped in the namespace SCSCP.


Next: , Up: C++ Interface

9.1 Server

9.1.1 Constructor

— Constructor: Server (const char* servicename, const char* serviceversion, const char* serviceid) throw(Exception)

It initializes the SCSCP server with the default versions (SCSCP_PROTOCOL_VERSION_1_3 and SCSCP_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_version and service_id of the Connection Initiation Message.

— Destructor: ~Server (void)

If the server was listening on a port, the method Server::close is called before clearing the object. It destroys the SCSCP server.

9.1.2 listen

— Method on Server: int listen (int port=SCSCP_PROTOCOL_DEFAULTPORT) throw(Exception)

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.

9.1.3 getport

— Method on Server: int getport () const

It returns the port from the server is listening. If the function listen failed or is not called before, then this function returns -1.

9.1.4 close

— Method on Server: int close () throw(Exception)

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.

9.1.5 eof

— Method on Server: bool eof () const

It returns true if the connection is closed.

9.1.6 acceptclient

— Method on Server: IncomingClient* acceptclient () throw ()

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();


Next: , Previous: Server, Up: C++ Interface

9.2 IncomingClient

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.

9.2.1 Destructor

— Destructor: ~IncomingClient (void)

If a connection with a client was already opened, the connection is closed with the client.

9.2.2 eof

— Method on Client: bool eof () const

It returns true if the connection is closed.


Next: , Previous: IncomingClient, Up: C++ Interface

9.3 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).

9.3.1 Constructor

— Constructor: Client (void) throw(Exception)

It initializes the SCSCP client with the default version (SCSCP_PROTOCOL_VERSION_1_3 and SCSCP_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, and SCSCP_PROTOCOL_VERSION_1_2.

— Destructor: ~Client (void)

If a connection was already opened, the method Client::close is called before clearing the object. It destroys the SCSCP client.

9.3.2 connect

— Method on Client: int connect (const char *machine, int port=SCSCP_PROTOCOL_DEFAULTPORT) throw(Exception)

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.

9.3.3 close

— Method on Client: int close () throw(Exception)

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.

9.3.4 eof

— Method on Client: bool eof () const

It returns true if the connection is closed.


Next: , Previous: Client, Up: C++ Interface

9.4 Procedure call

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.

9.4.1 ProcedureCall

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.

9.4.1.1 ProcedureCall Constructor
— Constructor: ProcedureCall (Client& session)

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_id of the OpenMath Content Dictionary scscp1. The call identifier is prefixed by libSCSCP:.

— Destructor: ~ProcedureCall (void)

It destroys the procedure call.

9.4.1.2 set_runtimelimit
— Method on ProcedureCall: int set_runtimelimit (size_t time)

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.

9.4.1.3 get_runtimelimit
— Method on ProcedureCall: int get_runtimelimit (size_t& time)

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.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

9.4.1.4 set_minmemory
— Method on ProcedureCall: int set_minmemory (size_t memsize)

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.

9.4.1.5 get_minmemory
— Method on ProcedureCall: int get_minmemory (size_t& memsize)

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.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

9.4.1.6 set_maxmemory
— Method on ProcedureCall: int set_maxmemory (size_t memsize)

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.

9.4.1.7 get_maxmemory
— Method on ProcedureCall: int get_maxmemory (size_t& memsize)

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.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

9.4.1.8 set_debuglevel
— Method on ProcedureCall: int set_debuglevel (int debuglevel)

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.

9.4.1.9 get_debuglevel
— Method on ProcedureCall: int get_debuglevel (int& debuglevel)

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 returns 0.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

9.4.1.10 set_runtime
— Method on ProcedureCall: int set_runtime (size_t time)

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.

9.4.1.11 get_runtime
— Method on ProcedureCall: int get_runtime (size_t& time)

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.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

9.4.1.12 set_memory
— Method on ProcedureCall: int set_memory (size_t memsize)

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.

9.4.1.13 get_memory
— Method on ProcedureCall: int get_memory (size_t& memsize)

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.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

9.4.1.14 set_message
— Method on ProcedureCall: int set_message ( const char *buffer)

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 instance of the object is destroyed.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

9.4.1.15 get_message
— Method on ProcedureCall: int get_message (const char *&buffer)

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 returned string mustn't be modified.

On exit, it returns 0 if an error occurs, otherwise the return value is a non-zero value.

9.4.1.16 set_encodingtype
— Method on ProcedureCall: int set_encodingtype (SCSCP_encodingtype encodingtype)

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.

9.4.1.17 get_encodingtype
— Method on ProcedureCall: int get_encodingtype (SCSCP_encodingtype& encodingtype)

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.

9.4.1.18 get_returntype
— Method on ProcedureCall: int get_returntype (SCSCP_option_return& returntype)

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.

9.4.1.19 get_callid
— Method on ProcedureCall: int get_callid (const char*& callid)

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.

9.4.2 Client::Computation

9.4.2.1 Client::Computation Constructor
— Constructor: Client::Computation (Client& session) : public ProcedureCall

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_id of the OpenMath Content Dictionary scscp1. The call identifier is prefixed by libSCSCP:.

— Destructor: ~Client::Computation (void)

It destroys the procedure call on the client side.

9.4.2.2 send
— Method on Client::Computation: int send (const char *openmathbuffer, size_t lenbuffer, SCSCP_option_return returntype)

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.

— Method on Client::Computation: int send (SCSCP_option_return returntype, std::ostream *& outstream) throw (Exception)

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 to discard(). 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();
     
— Method on Client::Computation: int send (SCSCP_option_return returntype, Ounfstream*& outstream) throw (Exception)

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 with endOMA().

The "procedure call" message must be completed with a call to finish() or discarded with a call to discard(). 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();
     
9.4.2.3 recv
— Method on Client::Computation: int recv (SCSCP_msgtype& msgtype, char*& openmathbuffer, size_t& lenbuffer)

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.

— Method on Client::Computation: int recv (SCSCP_msgtype& msgtype, Iunfstream* &stream) throw (Exception)

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 recv or send.

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.

9.4.2.4 discard
— Method on Client::Computation: int discard (void) throw (Exception)

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.

9.4.2.5 finish
— Method on Client::Computation: int finish (void) throw (Exception)

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.

9.4.3 Server::Computation

9.4.3.1 Server::Computation Constructor
— Constructor: Server::Computation (IncomingClient& session) : public ProcedureCall

It initializes the instance to handle the procedure call on the server side.

— Destructor: ~Server::Computation (void)

It destroys the instance to handle the procedure call on the server side.

9.4.3.2 recv
— Method on Client::Computation: int recv (SCSCP_msgtype& msgtype, char*& openmathbuffer, size_t& lenbuffer) throw (Exception)

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_ProcedureCall or SCSCP_msgtype_Interrupt. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument msgtype is SCSCP_msgtype_Interrupt, the call identifier of the interrupted procedure call could be retrieved with a call to get_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.

— Method on Client::Computation: int recv (SCSCP_msgtype& msgtype, Iunfstream*& stream) throw (Exception)

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_ProcedureCall or SCSCP_msgtype_Interrupt. The client sends only "Procedure Call" or "Interrupt" message. On exit, if the argument msgtype is SCSCP_msgtype_Interrupt, the call identifier of the interrupted procedure call could be retrieved with a call to get_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 recv or send.

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.

9.4.3.3 sendcompleted

These methods allow to send a "procedure completed" message to the client.

— Method on Client::Computation: int sendcompleted (const char* openmathbuffer=NULL, size_t lenbuffer=0) throw (Exception)

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.

— Method on Client::Computation: int sendcompleted (std::ostream *& outstream) throw (Exception)

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.

— Method on Server::Computation: int sendcompleted (Ounfstream*& outstream) throw (Exception)

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.

9.4.3.4 sendterminated

That method allows to send a "procedure terminated" message to the client.

— Method on Client::Computation: int sendterminated (const char * cdname, const char * symbolname, const char * message) throw (Exception)

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.

9.4.3.5 finish
— Method on Server::Computation: int finish (void) throw (Exception)

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.


Next: , Previous: Procedure call, Up: C++ Interface

9.5 Stream

9.5.1 Ounfstream

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;
9.5.1.1 beginOMA
— Method on Ounfstream&: beginOMA (Ounfstream&) throw (Exception)

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.

9.5.1.2 endOMA
— Method on Ounfstream&: beginOMA (Ounfstream&) throw (Exception)

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.

9.5.1.3 beginOMATP
— Method on Ounfstream&: beginOMATP (Ounfstream&) throw (Exception)

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.

9.5.1.4 endOMATP
— Method on Ounfstream&: endOMATP (Ounfstream&) throw (Exception)

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.

9.5.1.5 beginOMATTR
— Method on Ounfstream&: beginOMATTR (Ounfstream&) throw (Exception)

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.

9.5.1.6 endOMATTR
— Method on Ounfstream&: endOMATTR (Ounfstream&) throw (Exception)

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.

9.5.1.7 beginOME
— Method on Ounfstream&: beginOME (Ounfstream&) throw (Exception)

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.

9.5.1.8 endOME
— Method on Ounfstream&: endOME (Ounfstream&) throw (Exception)

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.

9.5.1.9 beginOMOBJ
— Method on Ounfstream&: beginOMOBJ (Ounfstream&) throw (Exception)

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.

9.5.1.10 endOMOBJ
— Method on Ounfstream&: endOMOBJ (Ounfstream&) throw (Exception)

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.

9.5.1.11 operator<<
— operator<< on Ounfstream: Ounfstream& operator << (Ounfstream& out, int x) throw (Exception)

It writes x to the stream out as 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.

— operator<< on Ounfstream: Ounfstream& operator << (Ounfstream& out, double x) throw (Exception)

It writes x to the stream out as 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.

— operator<< on Ounfstream: Ounfstream& operator << (Ounfstream& out, const char * str) throw (Exception)

It writes the C-style string str to the stream out as 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.

— operator<< on Ounfstream: Ounfstream& operator << (Ounfstream& out, OMF x) throw (Exception)

It writes the OpenMath float x to the stream out according to the current encoding.

On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.

— operator<< on Ounfstream: Ounfstream& operator << (Ounfstream& out, OMI x) throw (Exception)

It writes the OpenMath integer x to the stream out according to the current encoding.

On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.

— operator<< on Ounfstream: Ounfstream& operator << (Ounfstream& out, OMR x) throw (Exception)

It writes the OpenMath reference x to the stream out according to the current encoding.

On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.

— operator<< on Ounfstream: Ounfstream& operator << (Ounfstream& out, OMS x) throw (Exception)

It writes the OpenMath symbol x to the stream out according to the current encoding.

On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.

— operator<< on Ounfstream: Ounfstream& operator << (Ounfstream& out, OMV x) throw (Exception)

It writes the OpenMath variable x to the stream out according to the current encoding.

On exit, if an error occurs, then an exception is raised if the exception mechanism is enabled.

9.5.2 Iunfstream

9.5.2.1 omtype

This type is an enumeration of the possible values of the node.

The possible values are

`SCSCP_omtype_OMI'
OpenMath integer.
`SCSCP_omtype_OMF'
OpenMath IEEE floating point number.
`SCSCP_omtype_OMV'
OpenMath variable.
`SCSCP_omtype_OMS'
OpenMath symbol.
`SCSCP_omtype_OMSTR'
OpenMath string.
`SCSCP_omtype_OMB'
OpenMath byte array.
`SCSCP_omtype_OMFOREIGN'
OpenMath foreign.
`SCSCP_omtype_OMA'
OpenMath application.
`SCSCP_omtype_OMBIND'
OpenMath binding.
`SCSCP_omtype_OMATTR'
OpenMath attribution.
`SCSCP_omtype_OME'
OpenMath error.
`SCSCP_omtype_OMATP'
OpenMath attribute pair.
`SCSCP_omtype_OMOBJ'
OpenMath object.
`SCSCP_omtype_OMBVAR'
OpenMath variables used in binding.
`SCSCP_omtype_OMR'
OpenMath reference.
`SCSCP_omtype_CONTENT'
content node.
9.5.2.2 iterator_attr

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.

— Method on Iunfstream::iterator_attr: bool end () const

It returns true if no more attributes are available, otherwise it returns false.

— Method on Iunfstream::iterator_attr: void operator++ ()

It goes to the next attributes.

— Method on Iunfstream::iterator_attr: const char *get_name () const

It returns the name of the current attribute.

— Method on Iunfstream::iterator_attr: const char *get_value () const

It returns the value of the current attribute.

9.5.2.3 eof
— Method on Iunfstream: bool eof () const

It returns true if no more nodes are available in the stream.

9.5.2.4 get_attr
— Method on Iunfstream: Iunfstream::iterator_attr get_attr ()

It returns an iterator on the attributes of the nodes.

9.5.2.5 get_type
— Method on Iunfstream: Iunfstream::omtype get_type () const

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.

9.5.2.6 get_typename
— Method on Iunfstream: const char* get_typename () const

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.

9.5.2.7 get_content
— Method on Iunfstream: const char* get_content () const

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.

9.5.2.8 beginOM
— Method on Iunfstream: Iunfstream beginOM ()

It returns a stream to parse the children nodes of the derived OpenMath objects.

9.5.2.9 operator>>
— operator>> on Iunfstream: Iunfstream& operator >> (int& x) throw (Exception)

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.

— operator>> on Iunfstream: Iunfstream& operator >> (double& x) throw (Exception)

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.

— operator>> on Iunfstream: Iunfstream& operator >> (const char*& x) throw (Exception)

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.

— operator>> on Iunfstream: Iunfstream& operator >> (OMF x) throw (Exception)

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.

— operator>> on Iunfstream: Iunfstream& operator >> (OMI x) throw (Exception)

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.

— operator>> on Iunfstream: Iunfstream& operator >> (OMR x) throw (Exception)

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.

— operator>> on Iunfstream: Iunfstream& operator >> (OMS x) throw (Exception)

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.

— operator>> on Iunfstream: Iunfstream& operator >> (OMV x) throw (Exception)

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.


Next: , Previous: Stream, Up: C++ Interface

9.6 Exception

On errors, the C++ functions raise an exception of type Exception which derivates from the STL std::exception.

9.6.1 Constructor

— Constructor: Exception (const SCSCP_status* status) : public std::exception

It initializes the SCSCP exception wit the specified status information.

— Destructor: ~Exception (void)

It destroys the exception.

9.6.2 what

— Method on Exception: const char * what () const throw()

It returns a C-style character string describing the general cause of the current error.


Previous: Exception, Up: C++ Interface

9.7 OpenMath objects

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, ....

9.7.1 OMBase

— Method on OMBase: const char * get_id () const

It returns the reference id (<OM .... id="...">) of the Openmath object. It may return NULL if the reference id of the object is unset.

9.7.2 OMA

— Constructor: OMA (const char *id=NULL)

It creates the OpenMath application with the reference id. paramid

— Method on OMA: Iunfstream beginOM ()

It returns a stream to parse the children nodes of the derived OpenMath objects.

9.7.3 OMBIND

— Constructor: OMBIND (const char *id=NULL)

It creates the OpenMath binding with the reference id. paramid

— Method on OMBIND: Iunfstream beginOM ()

It returns a stream to parse the children nodes of the derived OpenMath objects.

9.7.4 OME

— Constructor: OME (const char *id=NULL)

It creates the OpenMath error with the reference id. paramid

— Method on OME: Iunfstream beginOM ()

It returns a stream to parse the children nodes of the derived OpenMath objects.

9.7.5 OMF

— Constructor: OMF (const char* value, const char *id=NULL)

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.

— Method on OMF: const char * get_value () const

This function returns the value of the Openmath float.

— Method on OMF: int get_base () const

This function returns the base number of the Openmath float.

9.7.6 OMI

— Constructor: OMI (const char* value, const char *id=NULL)

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.

— Method on OMI: const char * get_value () const

This function returns the value of the Openmath integer.

9.7.7 OMR

— Constructor: OMR (const char* href)

It creates the OpenMath reference href. The C-style string href isn't duplicated.

— Method on OMR: const char * get_reference () const

This function returns the value of the Openmath reference.

9.7.8 OMS

— Constructor: OMS (const char* cdname, const char* symbolname, const char *id=NULL)

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.

— Method on OMS: const char * get_cdname () const

This function returns the cd name of the Openmath symbol.

— Method on OMS: const char * get_symbolname () const

This function returns the symbol name of the Openmath symbol.

9.7.9 OMV

— Constructor: OMV (const char* name, const char *id=NULL)

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.

— Method on OMS: const char * get_name () const

This function returns the name of the Openmath variable.


Next: , Previous: C++ Interface, Up: Top

10 Design a SCSCP C++ server

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".


Next: , Previous: Design a SCSCP C++ server, Up: Top

11 Design a SCSCP C++ client

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.


Previous: Design a SCSCP C++ client, Up: Top

12 References