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

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

4 Message exchange by SCSCP
4.1 Communication with the SCSCP server
4.1-1 StartSCSCPsession
4.1-2 OMPutProcedureCall
4.1-3 SCSCPwait
4.1-4 OMGetObjectWithAttributes
4.2 Communication with the SCSCP client
4.2-1 OMPutProcedureCompleted
4.2-2 OMPutProcedureTerminated
4.3 Example: SCSCP session

### 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

`‣ StartSCSCPsession`( stream ) | ( function )

Returns: string

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

`‣ OMPutProcedureCall`( stream, proc_name, objrec ) | ( function )

Returns: nothing

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

This function accepts options `cd` and `debuglevel`.

`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

`‣ SCSCPwait`( stream[, timeout] ) | ( function )

Returns: nothing

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

`‣ OMGetObjectWithAttributes`( stream ) | ( function )

Returns: record with components `object` and `attributes`, or `fail`

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

`‣ OMPutProcedureCompleted`( stream, objrec ) | ( function )

Returns: `true`

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

`‣ OMPutProcedureTerminated`( stream, objrec, error_cd, error_type ) | ( function )

Returns: nothing

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.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 Bib Ind

generated by GAPDoc2HTML