chap4.txt

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