GAP (scscp) - Chapter 4: Message exchange by SCSCP

To ensure the message exchange as required by SCSCP specification, the SCSCP package extends the global record OMsymRecord from the OpenMath package with new entries to support scscp1 and scscp2 content dictionaries ([FHK+a], [FHK+c]), and also service-dependent transient private content dictionaries (see Chapter 5 for details about transient content dictionaries). It also overwrites some OpenMath functions by their extended (but backwards compatible) versions, and adds some new OpenMath-related functions to send and receive SCSCP messages, documented below.

Note that functions documented in this chapter belong to the middle-level interface, and the user may find it more convenient to use functions developed on top of them and explained in next chapters.

4.1 Communication with the SCSCP server

4.1-1 StartSCSCPsession

Initialises SCSCP session and negotiates with the server about the version of the protocol. Returns the string with the service_id (which may be used later as a part of the call identifier) or causes an error message if can not perform these tasks.


gap> s := InputOutputTCPStream("localhost",26133);
< input/output TCP stream to localhost:26133 >
gap> StartSCSCPsession(s);
"localhost:26133:5541"
gap> CloseStream( s );

After the call to StartSCSCPsession the SCSCP server is ready to accept procedure calls.

4.1-2 OMPutProcedureCall

Takes a stream stream, the string proc_name and a record objrec, and writes to stream an OpenMath object procedure_call for the procedure proc_name with arguments given by the list objrec.object and procedure call options (which should be encoded as OpenMath attributes) given in the list objrec.attributes.

cd:="cdname" may be used to specify the name of the content dictionary if the procedure is actually a standard OpenMath symbol. Note that the server may reject such a call if it accepts only calls of procedures from the transient content dictionary, see InstallSCSCPprocedure (5.1-1) for explanation). If the cdname is not specified, scscp_transient_1 content dictionary will be assumed by default. The value of the debuglevel option is an integer. If it is non-zero, the procedure_completed message will carry on also some additional information about the call, for example, runtime and memory used.


gap> t:="";; stream:=OutputTextString(t,true);;
gap> OMPutProcedureCall( stream, "WS_Factorial", rec( object:= [ 5 ], 
>      attributes:=[ [ "call_id", "user007" ], 
>                    ["option_runtime",1000],
>                    ["option_min_memory",1024], 
>                    ["option_max_memory",2048],
>                    ["option_debuglevel",1], 
>                    ["option_return_object"] ] ) );;
gap> Print(t);
<?scscp start ?>
<OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
	<OMATTR>
		<OMATP>
			<OMS cd="scscp1" name="call_id"/>
			<OMSTR>user007</OMSTR>
			<OMS cd="scscp1" name="option_runtime"/>
			<OMI>1000</OMI>
			<OMS cd="scscp1" name="option_min_memory"/>
			<OMI>1024</OMI>
			<OMS cd="scscp1" name="option_max_memory"/>
			<OMI>2048</OMI>
			<OMS cd="scscp1" name="option_debuglevel"/>
			<OMI>1</OMI>
			<OMS cd="scscp1" name="option_return_object"/>
			<OMSTR></OMSTR>
		</OMATP>
		<OMA>
			<OMS cd="scscp1" name="procedure_call"/>
			<OMA>
				<OMS cd="scscp_transient_1" name="WS_Factorial"/>
				<OMI>5</OMI>
			</OMA>
		</OMA>
	</OMATTR>
</OMOBJ>
<?scscp end ?>

4.1-3 SCSCPwait

This function may be used by the SCSCP client to wait (using IO_select (IO: IO_select)) until the result of the procedure call will be available from stream. By default the timeout is one hour, to specify another value give it as the optional second argument in seconds. See the end of this chapter for the example.

4.1-4 OMGetObjectWithAttributes

This function is similar to the function OMGetObject from the OpenMath package, and the main difference is that it is able to understand OpenMath attribution pairs. It retrieves exactly one OpenMath object from the stream stream, and stores it in the object component of the returned record. If the OpenMath object has no attributes, the attributes component of the returned record will be an empty list, otherwise it will contain pairs [attribute_name,attribute_value], where attribute_name is a string, and attribute_value is a GAP object, whose type is determined by the kind of an attribute. Only attributes, defined by the SCSCP are allowed, otherwise an error message will be displayed.

If the procedure was not successful, the function returns fail instead of an error message like the function OMGetObject (OpenMath: OMGetObject) does. Returning fail is useful when OMGetObjectWithAttributes is used inside accept-evaluate-return loop.

As an example, the file scscp/tst/omdemo.om contains some OpenMath objects, including those from the SCSCP Specification [FHK+b]. We can retrieve them from this file, preliminary installing some SCSCP procedures using the function InstallSCSCPprocedure (5.1-1):


gap> InstallSCSCPprocedure("WS_Factorial", Factorial );
gap> InstallSCSCPprocedure("GroupIdentificationService", IdGroup );
gap> InstallSCSCPprocedure("GroupByIdNumber", SmallGroup );
gap> InstallSCSCPprocedure( "Length", Length, 1, 1 );
gap> test:=Filename( Directory( Concatenation(
>         GAPInfo.PackagesInfo.("scscp")[1].InstallationPath,"/tst/" ) ), 
>         "omdemo.om" );;
gap> stream:=InputTextFile(test);;
gap> OMGetObjectWithAttributes(stream); 
rec( 
  attributes := [ [ "option_return_object", "" ], [ "call_id", "5rc6rtG62" ] ]
    , object := 6 )
gap> OMGetObjectWithAttributes(stream);
rec( attributes := [  ], object := 1 )
gap> OMGetObjectWithAttributes(stream);
rec( attributes := [  ], object := 120 )
gap> OMGetObjectWithAttributes(stream);
rec( 
  attributes := [ [ "call_id", "alexk_9053" ], [ "option_runtime", 300000 ], 
      [ "option_min_memory", 40964 ], [ "option_max_memory", 134217728 ], 
      [ "option_debuglevel", 2 ], [ "option_return_object", "" ] ], 
  object := [ 24, 12 ] )
gap> OMGetObjectWithAttributes(stream);
rec( 
  attributes := [ [ "call_id", "alexk_9053" ], [ "option_return_cookie", "" ] 
     ], object := <pc group of size 24 with 4 generators> )
gap> OMGetObjectWithAttributes(stream);
rec( attributes := [ [ "call_id", "alexk_9053" ], [ "info_runtime", 1234 ], 
      [ "info_memory", 134217728 ] ], object := [ 24, 12 ] )
gap> CloseStream( stream );

4.2 Communication with the SCSCP client

4.2-1 OMPutProcedureCompleted

Takes a stream stream, and a record objrec, and writes to stream an OpenMath object procedure_completed with the result being objrec.object and information messages (as OpenMath attributes) given in the list objrec.attributes.


gap> t:="";; stream:=OutputTextString(t,true);;
gap> OMPutProcedureCompleted( stream, 
>      rec(object:=120, 
>      attributes:=[ [ "call_id", "user007" ] ] ) );
true
gap> Print(t);
<?scscp start ?>
<OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
	<OMATTR>
		<OMATP>
			<OMS cd="scscp1" name="call_id"/>
			<OMSTR>user007</OMSTR>
		</OMATP>
		<OMA>
			<OMS cd="scscp1" name="procedure_completed"/>
			<OMI>120</OMI>
		</OMA>
	</OMATTR>
</OMOBJ>
<?scscp end ?>

4.2-2 OMPutProcedureTerminated

Takes a stream stream, and a record with an error message objrec (for example rec( attributes := [ [ "call_id", "localhost:26133:87643:gcX33cCf" ] ], object := "localhost:26133 reports : Rational operations: <divisor> must not be zero") and writes to the stream an OpenMath object procedure_terminated containing an error determined by the symbol error_type from the content dictionary error_cd (for example, error_memory, error_runtime or error_system_specific from the scscp1 content dictionary ([FHK+a]).

This is the internal function of the package which is used only in the code for the SCSCP server to return the error message to the client.

4.3 Example: SCSCP session

In the following example we start an SCSCP session and perform ten procedure calls in a loop before closing that session. Note that we demonstrate the usage of the session ID sid and the function RandomString from the OpenMath package to produce some unique call identifier. The call ID is a mandatory attribute for any procedure call, however, it is not nesessarily random; for example, it may be just a string with the number of the procedure call.


gap> stream:=InputOutputTCPStream( "localhost", 26133 );
< input/output TCP stream to localhost:26133 >
gap> sid := StartSCSCPsession( stream );
"localhost:26133:5541"
gap> res:=[];
[  ]
gap> for i in [1..10] do
>     OMPutProcedureCall( stream, "WS_Factorial", 
>       rec( object := [ i ], 
>        attributes := [ [ "call_id", 
>          Concatenation( sid, ":", RandomString(8) ) ] ] ) );
>     SCSCPwait( stream );
>     res[i]:=OMGetObjectWithAttributes( stream ).object;
> od;
gap> CloseStream(stream);
gap> res;
[ 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800 ]

Also note the usage of SCSCPwait (4.1-3) to wait until the result of the computation will be available from stream.

In this example we assumed that there is an SCSCP server running at localhost, port 26133. In the next chapter we will explain how to configure and run a GAP SCSCP server and how to interrogate it from a GAP client to learn about its functionality. After that, we will proceed with the SCSCP client functionality for the end-user.

4 Message exchange by SCSCP

4.1 Communication with the SCSCP server