chap9.txt

  
  9 Service functions
  
  
  9.1 Pinging SCSCP servers
  
  9.1-1 PingSCSCPservice
  
  PingSCSCPservice( hostname, portnumber )  function
  Returns:  true or fail
  
  This  function  returns true if the client can establish connection with the
  SCSCP server at hostname:portnumber. Otherwise, it returns fail.
  
    Example  
    
    gap> PingSCSCPservice("localhost",26133);
    true
    gap> PingSCSCPservice("localhost",26140);                     
    Error: rec(
      message := "Connection refused",
      number := 61 )
    fail
    
  
  
  9.1-2 PingStatistic
  
  PingStatistic( hostname, portnumber, n )  function
  Returns:  nothing
  
  The  function  is  similar  to  the UNIX ping. It tries n times to establish
  connection  with  the SCSCP server at hostname:portnumber, and then displays
  statistical information.
  
    Example  
    
    gap> PingStatistic("localhost",26133,1000);
    1000 packets transmitted, 1000 received, 0% packet loss, time 208ms
    min/avg/max = [ 0, 26/125, 6 ]
    
  
  
  
  9.2 Info classes for SCSCP
  
  9.2-1 InfoSCSCP
  
  InfoSCSCP info class
  
  InfoSCSCP  is  a  special  Info  class  for the SCSCP package. The amount of
  information  to  be  displayed  can  be  specified  by  the  user by setting
  InfoLevel for this class from 0 to 4, and the default value of InfoLevel for
  the  package  is  specified in the file scscp/config.g. The higher the level
  is,  the  more  information will be displayed. To change the InfoLevel to k,
  use  the  command  SetInfoLevel(InfoSCSCP,  k). In the following examples we
  demonstrate various degrees of output details using Info messages.
  
  Default Info level:
  
    Example  
    
    gap> SetInfoLevel(InfoSCSCP,2);                              
    gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133); 
    #I  Creating a socket ...
    #I  Connecting to a remote socket via TCP/IP ...
    #I  Got connection initiation message
    #I  <?scscp service_name="GAP" service_version="4.dev" service_id="localhost:2\
    6133:286" scscp_versions="1.0 1.1 1.2 1.3" ?>
    #I  Requesting version 1.3 from the server ...
    #I  Server confirmed version 1.3 to the client ...
    #I  Request sent ...
    #I  Waiting for reply ...
    #I  <?scscp start ?>
    #I  <?scscp end ?>
    #I  Got back: object 3628800 with attributes 
    [ [ "call_id", "localhost:26133:286:JL6KRQeh" ] ]
    rec( attributes := [ [ "call_id", "localhost:26133:286:JL6KRQeh" ] ], 
      object := 3628800 )
    
  
  
  Minimal Info level:
  
    Example  
    
    gap> SetInfoLevel(InfoSCSCP,0);                              
    gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133);
    rec( attributes := [ [ "call_id", "localhost:26133:286:jzjsp6th" ] ], 
      object := 3628800 )
    
  
  
  Verbose Info level:
  
    Example  
    
    gap> SetInfoLevel(InfoSCSCP,3);
    gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133);
    #I  Creating a socket ...
    #I  Connecting to a remote socket via TCP/IP ...
    #I  Got connection initiation message
    #I  <?scscp service_name="GAP" service_version="4.dev" service_id="localhost:2\
    6133:286" scscp_versions="1.0 1.1 1.2 1.3" ?>
    #I  Requesting version 1.3 from the server ...
    #I  Server confirmed version 1.3 to the client ...
    #I  Composing procedure_call message: 
    <?scscp start ?>
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMATTR>
    		<OMATP>
    			<OMS cd="scscp1" name="call_id"/>
    			<OMSTR>localhost:26133:286:Jok6cQAf</OMSTR>
    			<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>10</OMI>
    			</OMA>
    		</OMA>
    	</OMATTR>
    </OMOBJ>
    <?scscp end ?>
    #I  Total length 396 characters 
    #I  Request sent ...
    #I  Waiting for reply ...
    #I  <?scscp start ?>
    #I Received message: 
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMATTR>
    		<OMATP>
    			<OMS cd="scscp1" name="call_id"/>
    			<OMSTR>localhost:26133:286:Jok6cQAf</OMSTR>
    		</OMATP>
    		<OMA>
    			<OMS cd="scscp1" name="procedure_completed"/>
    			<OMI>3628800</OMI>
    		</OMA>
    	</OMATTR>
    </OMOBJ>
    #I  <?scscp end ?>
    #I  Got back: object 3628800 with attributes 
    [ [ "call_id", "localhost:26133:286:Jok6cQAf" ] ]
    rec( attributes := [ [ "call_id", "localhost:26133:286:Jok6cQAf" ] ], 
      object := 3628800 )
    gap> SetInfoLevel(InfoSCSCP,0);
    
  
  
  9.2-2 InfoMasterWorker
  
  InfoMasterWorker info class
  
  InfoMasterWorker  is  a  special  Info  class for the Master-Worker skeleton
  ParListWithSCSCP  (8.2-1).  The amount of information to be displayed can be
  specified  by  the user by setting InfoLevel for this class from 0 to 5, and
  the  default  value  of  InfoLevel  for the package is specified in the file
  scscp/config.g.  The  higher  the  level  is,  the  more information will be
  displayed.    To    change   the   InfoLevel   to   k,   use   the   command
  SetInfoLevel(InfoMasterWorker,  k). In the following examples we demonstrate
  various degrees of output details using Info messages.
  
  Default Info level:
  
    Example  
    
    gap> SetInfoLevel(InfoMasterWorker,2);
    gap> ParListWithSCSCP( List( [2..6], n -> SymmetricGroup(n)), "WS_IdGroup" );
    #I  1/5:master --> localhost:26133
    #I  2/5:master --> localhost:26134
    #I  3/5:master --> localhost:26133
    #I  4/5:master --> localhost:26134
    #I  5/5:master --> localhost:26133
    [ [ 2, 1 ], [ 6, 1 ], [ 24, 12 ], [ 120, 34 ], [ 720, 763 ] ]
    
  
  
  Minimal Info level:
  
    Example  
    
    gap> SetInfoLevel(InfoSCSCP,0);       
    gap> SetInfoLevel(InfoMasterWorker,0);
    gap> ParListWithSCSCP( List( [2..6], n -> SymmetricGroup(n)), "WS_IdGroup" );
    [ [ 2, 1 ], [ 6, 1 ], [ 24, 12 ], [ 120, 34 ], [ 720, 763 ] ]
    
  
  
  Verbose Info level:
  
    Example  
    
    gap> SetInfoLevel(InfoMasterWorker,5);                                       
    gap> ParListWithSCSCP( List( [2..6], n -> SymmetricGroup(n)), "WS_IdGroup" );
    #I  1/5:master --> localhost:26133 : SymmetricGroup( [ 1 .. 2 ] )
    #I  2/5:master --> localhost:26134 : SymmetricGroup( [ 1 .. 3 ] )
    #I  localhost:26133 --> 1/5:master : [ 2, 1 ]
    #I  3/5:master --> localhost:26133 : SymmetricGroup( [ 1 .. 4 ] )
    #I  localhost:26134 --> 2/5:master : [ 6, 1 ]
    #I  4/5:master --> localhost:26134 : SymmetricGroup( [ 1 .. 5 ] )
    #I  localhost:26133 --> 3/5:master : [ 24, 12 ]
    #I  5/5:master --> localhost:26133 : SymmetricGroup( [ 1 .. 6 ] )
    #I  localhost:26134 --> 4/5:master : [ 120, 34 ]
    #I  localhost:26133 --> 5/5:master : [ 720, 763 ]
    [ [ 2, 1 ], [ 6, 1 ], [ 24, 12 ], [ 120, 34 ], [ 720, 763 ] ]
    gap> SetInfoLevel(InfoMasterWorker,2);
    
  
  
  
  9.3 Other SCSCP Utilities
  
  9.3-1 DateISO8601
  
  DateISO8601(  )  function
  Returns:  string
  
  Returns  the  current  date  in  the  ISO-8601 YYYY-MM-DD format. This is an
  internal  function  of  the  package  which  is  used by the SCSCP server to
  generate  the transient content dictionary, accordingly to the definition of
  the OpenMath symbol meta.CDDate.
  
    Example  
    
    gap> DateISO8601();
    "2017-02-05"
    
  
  
  9.3-2 CurrentTimestamp
  
  CurrentTimestamp(  )  function
  Returns:  string
  
  Returns  the result of the call to date. This is an internal function of the
  package which is used to add the timestamp to the SCSCP service description.
  
    Example  
    
    gap> CurrentTimestamp();
    "Tue 30 Jan 2017 11:19:38 BST"
    
  
  
  9.3-3 Hostname
  
  Hostname(  )  function
  Returns:  string
  
  Returns the result of the call to hostname. This function may be used in the
  configuration file scscp/config.g to specify that the default hostname which
  will  be  used  by  the  SCSCP  server  will be detected automatically using
  hostname.
  
    Example  
    
    gap> Hostname();
    "scscp.gap-system.org"
    
  
  
  9.3-4 MemoryUsageByGAPinKbytes
  
  MemoryUsageByGAPinKbytes(  )  function
  Returns:  integer
  
  Returns  the  current volume of the memory used by GAP in kylobytes. This is
  equivalent  to  calling ps -p <PID> -o vsz, where <PID> is the process ID of
  the  GAP  process. This is an internal function of the package which is used
  by  the SCSCP server to report its memory usage in the info_memory attribute
  when   being   called   with   the   option  debuglevel=2  (see  options  in
  EvaluateBySCSCP (6.3-1) and NewProcess (6.2-2)).
  
    Example  
    
    gap> MemoryUsageByGAPinKbytes();
    649848
    
  
  
  9.3-5 LastReceivedCallID
  
  LastReceivedCallID(  )  function
  Returns:  string
  
  Returns  the call ID contained in the most recently received message. It may
  contain  some  useful  debugging information; in particular, the call ID for
  the  GAP  SCSCP client and server contains colon-separated server name, port
  number, process ID and a random string.
  
    Example  
    
    gap> LastReceivedCallID();
    "scscp.gap-system.org:26133:77372:choDZBgA"
    
  
  
  9.3-6 IO_PickleToString
  
  IO_PickleToString( obj )  function
  Returns:  string containing "pickled" object
  
  This  function  "pickles" or "serialises" the object obj using the operation
  IO_Pickle  (IO:  IO_Pickle)  from the IO package, and writes it to a string,
  from  which  it could be later restored using IO_UnpickleFromString (9.3-7).
  This provides a way to design SCSCP procedures which transmit GAP objects in
  the  "pickled"  format  as OpenMath strings, which may be useful for objects
  which  may  be  "pickled"  by  the  IO  package  but can not be converted to
  OpenMath or for which the "pickled" representation is more compact or can be
  encoded/decoded much faster.
  
  See  IO_Pickle  (IO:  IO_Pickle)  and IO_Unpickle (IO: IO_Unpickle) for more
  details.
  
    Example  
    
    gap> f := IO_PickleToString( GF( 125 ) );
    "FFIEINTG\>15INTG\>13FAIL"
    
  
  
  9.3-7 IO_UnpickleFromString
  
  IO_UnpickleFromString( s )  function
  Returns:  "unpickled" GAP object
  
  This  function "unpickles" the string s which was created using the function
  IO_PickleToString (9.3-6), using the operation IO_Unpickle (IO: IO_Unpickle)
  from  the  IO  package.  See  IO_PickleToString (9.3-6) for more details and
  suggestions about its usage.
  
    Example  
    
    gap> IO_UnpickleFromString( f );                    
    GF(5^3)
    gap> f = IO_UnpickleFromString( IO_PickleToString( f ) ); 
    true