  
  [1X9 Service functions[0X
  
  
  [1X9.1 Tools for making documentation[0X
  
  [1X9.1-1 SCSCPBuildManual[0m
  
  [2X> SCSCPBuildManual( [0X[3X[0X[2X ) _____________________________________________[0Xfunction
  
  This  function  is used to build the manual in PDF and HTML formats and also
  in  the  plain  text format for the online help. To build the PDF version, a
  recent and fairly complete TeX distribution is recommended.
  
  Since  the  [5XSCSCP[0m manual is distributed together with the package, it is not
  necessary  for the user to use this function, which is normally used only by
  developers.
  
  [1X9.1-2 SCSCPBuildManualHTML[0m
  
  [2X> SCSCPBuildManualHTML( [0X[3X[0X[2X ) _________________________________________[0Xfunction
  
  This function is used to build the manual only in HTML format. This does not
  require TeX installation and works in any operating system.
  
  Since  the  [5XSCSCP[0m manual is distributed together with the package, it is not
  necessary  for the user to use this function, which is normally used only by
  developers.
  
  
  [1X9.2 Other commands[0X
  
  [1X9.2-1 PingSCSCPservice[0m
  
  [2X> PingSCSCPservice( [0X[3Xhostname, portnumber[0X[2X ) _________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0m or [9Xfail[0m
  
  This  function  returns [9Xtrue[0m if the client can establish connection with the
  SCSCP server at [3Xhostname[0m:[3Xportnumber[0m. Otherwise, it returns [9Xfail[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> PingSCSCPservice("localhost",26133);[0X
    [4X#I  Creating a socket ...[0X
    [4X#I  Connecting to a remote socket via TCP/IP ...[0X
    [4X#I  Got connection initiation message[0X
    [4Xtrue[0X
    [4Xgap> PingSCSCPservice("localhost",26134);                     [0X
    [4X#I  Creating a socket ...[0X
    [4X#I  Connecting to a remote socket via TCP/IP ...[0X
    [4XError: rec([0X
    [4X  number := 61,[0X
    [4X  message := "Connection refused" )[0X
    [4Xfail[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-2 PingStatistic[0m
  
  [2X> PingStatistic( [0X[3Xhostname, portnumber, n[0X[2X ) _________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  The  function  is  similar  to  the UNIX [10Xping[0m. It tries [3Xn[0m times to establish
  connection  with  the SCSCP server at [3Xhostname[0m:[3Xportnumber[0m, and then displays
  statistical information.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> PingStatistic("localhost",26133,5);[0X
    [4X#I  Creating a socket ...[0X
    [4X#I  Connecting to a remote socket via TCP/IP ...[0X
    [4X#I  Got connection initiation message nr 1[0X
    [4X...[0X
    [4X#I  Creating a socket ...[0X
    [4X#I  Connecting to a remote socket via TCP/IP ...[0X
    [4X#I  Got connection initiation message nr 5[0X
    [4X100 packets transmitted, 100 received, 0% packet loss, time 26ms[0X
    [4Xmin/avg/max = [ 0, 13/50, 2 ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-3 InfoSCSCP[0m
  
  [2X> InfoSCSCP_______________________________________________________[0Xinfo class
  
  [10XInfoSCSCP[0m  is  a  special  Info  class  for the [5XSCSCP[0m 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 [11Xscscp/config.g[0m. The higher the level
  is,  the  more  information will be displayed. To change the InfoLevel to [10Xk[0m,
  use  the  command  [10XSetInfoLevel(InfoSCSCP,  k)[0m. In the following examples we
  demonstrate various degrees of output details using Info messages.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133); [0X
    [4X#I  Creating a socket ...[0X
    [4X#I  Connecting to a remote socket via TCP/IP ...[0X
    [4X#I  Got connection initiation message [0X
    [4X#I  Request sent ...[0X
    [4X#I  Waiting for reply ...[0X
    [4Xrec( object := "3628800", attributes := [ [ "call_id", "localhost:26133:38" ] ] )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> SetInfoLevel(InfoSCSCP,0);                              [0X
    [4Xgap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133);[0X
    [4Xrec( object := "3628800", attributes := [ [ "call_id", "localhost:26133:41" ] ] )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> SetInfoLevel(InfoSCSCP,3);[0X
    [4Xgap> G:=SymmetricGroup(4);;[0X
    [4Xgap> gens:=GeneratorsOfGroup(G);  [0X
    [4X[ (1,2,3,4), (1,2) ][0X
    [4Xgap> EvaluateBySCSCP( "GroupIdentificationService",[gens],"localhost",26133);[0X
    [4X#I  Creating a socket ...[0X
    [4X#I  Connecting to a remote socket via TCP/IP ...[0X
    [4X#I  Got connection initiation message[0X
    [4X#I Composing procedure_call message: [0X
    [4X<?scscp start ?>[0X
    [4X<OMOBJ>[0X
    [4X    <OMATTR>[0X
    [4X		<OMATP>[0X
    [4X			<OMS cd="scscp1" name="call_id"/>[0X
    [4X			<OMSTR>localhost:26133:1212</OMSTR>[0X
    [4X		</OMATP>[0X
    [4X		<OMA>[0X
    [4X			<OMS cd="scscp1" name="procedure_call"/>[0X
    [4X			<OMA>[0X
    [4X				<OMS cd="scscp_transient_1" name="GroupIdentificationService"/>[0X
    [4X				<OMA>[0X
    [4X					<OMS cd="list1" name="list"/>[0X
    [4X					<OMA>[0X
    [4X						<OMS cd="permut1" name="permutation"/>[0X
    [4X						<OMI> 2</OMI>[0X
    [4X						<OMI> 3</OMI>[0X
    [4X						<OMI> 4</OMI>[0X
    [4X						<OMI> 1</OMI>[0X
    [4X					</OMA>[0X
    [4X					<OMA>[0X
    [4X						<OMS cd="permut1" name="permutation"/>[0X
    [4X						<OMI> 2</OMI>[0X
    [4X						<OMI> 1</OMI>[0X
    [4X					</OMA>[0X
    [4X				</OMA>[0X
    [4X			</OMA>[0X
    [4X		</OMA>[0X
    [4X	</OMATTR>[0X
    [4X</OMOBJ>[0X
    [4X<?scscp end ?>[0X
    [4X#I  Request sent ...[0X
    [4X#I  Waiting for reply ...[0X
    [4X#I  <?scscp start ?>[0X
    [4X#I Received message: [0X
    [4X<OMOBJ>[0X
    [4X	<OMATTR>[0X
    [4X		<OMATP>[0X
    [4X			<OMS cd="scscp1" name="call_id"/>[0X
    [4X			<OMSTR>localhost:26133:1212</OMSTR>[0X
    [4X		</OMATP>[0X
    [4X		<OMA>[0X
    [4X			<OMS cd="scscp1" name="procedure_completed"/>[0X
    [4X			<OMA>[0X
    [4X				<OMS cd="list1" name="list"/>[0X
    [4X				<OMI> 24</OMI>[0X
    [4X				<OMI> 12</OMI>[0X
    [4X			</OMA>[0X
    [4X		</OMA>[0X
    [4X	</OMATTR>[0X
    [4X</OMOBJ>[0X
    [4X#I  <?scscp end ?>[0X
    [4X#I  Got back: object [ 24, 12 ] with attributes [ [ "call_id", "localhost:26133:1212" ] ][0X
    [4Xrec( object := [ 24, 12 ], attributes := [ [ "call_id", "localhost:26133:1212" ] ] )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-4 InfoMasterWorker[0m
  
  [2X> InfoMasterWorker________________________________________________[0Xinfo class
  
  [10XInfoMasterWorker[0m  is  a  special  Info  class for the Master-Worker skeleton
  [2XParListWithSCSCP[0m  ([14X8.2-1[0m).  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
  [11Xscscp/config.g[0m.  The  higher  the  level  is,  the  more information will be
  displayed.    To    change   the   InfoLevel   to   [10Xk[0m,   use   the   command
  [10XSetInfoLevel(InfoMasterWorker,  k)[0m. In the following examples we demonstrate
  various degrees of output details using Info messages.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> SetInfoLevel(InfoSCSCP,0);       [0X
    [4Xgap> SetInfoLevel(InfoMasterWorker,2);[0X
    [4Xgap> ParListWithSCSCP( List( [2..6], n -> SymmetricGroup(n)), "WS_IdGroup" );[0X
    [4X#I  1/5:master --> localhost:26133[0X
    [4X#I  2/5:master --> localhost:26134[0X
    [4X#I  3/5:master --> localhost:26133[0X
    [4X#I  4/5:master --> localhost:26134[0X
    [4X#I  5/5:master --> localhost:26133[0X
    [4X[ [ 2, 1 ], [ 6, 1 ], [ 24, 12 ], [ 120, 34 ], [ 720, 763 ] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> SetInfoLevel(InfoSCSCP,0);       [0X
    [4Xgap> SetInfoLevel(InfoMasterWorker,0);[0X
    [4Xgap> ParListWithSCSCP( List( [2..6], n -> SymmetricGroup(n)), "WS_IdGroup" );[0X
    [4X[ [ 2, 1 ], [ 6, 1 ], [ 24, 12 ], [ 120, 34 ], [ 720, 763 ] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> SetInfoLevel(InfoMasterWorker,5);                                       [0X
    [4Xgap> ParListWithSCSCP( List( [2..6], n -> SymmetricGroup(n)), "WS_IdGroup" );[0X
    [4X#I  1/5:master --> localhost:26133 : SymmetricGroup( [ 1 .. 2 ] )[0X
    [4X#I  2/5:master --> localhost:26134 : SymmetricGroup( [ 1 .. 3 ] )[0X
    [4X#I  localhost:26133 --> 1/5:master : [ 2, 1 ][0X
    [4X#I  3/5:master --> localhost:26133 : SymmetricGroup( [ 1 .. 4 ] )[0X
    [4X#I  localhost:26134 --> 2/5:master : [ 6, 1 ][0X
    [4X#I  4/5:master --> localhost:26134 : SymmetricGroup( [ 1 .. 5 ] )[0X
    [4X#I  localhost:26133 --> 3/5:master : [ 24, 12 ][0X
    [4X#I  5/5:master --> localhost:26133 : SymmetricGroup( [ 1 .. 6 ] )[0X
    [4X#I  localhost:26134 --> 4/5:master : [ 120, 34 ][0X
    [4X#I  localhost:26133 --> 5/5:master : [ 720, 763 ][0X
    [4X[ [ 2, 1 ], [ 6, 1 ], [ 24, 12 ], [ 120, 34 ], [ 720, 763 ] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-5 DateISO8601[0m
  
  [2X> DateISO8601( [0X[3X[0X[2X ) __________________________________________________[0Xfunction
  [6XReturns:[0X  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 [5XSCSCP[0m server to
  generate  the transient content dictionary, accordingly to the definition of
  the [5XOpenMath[0m symbol [10Xmeta.CDDate[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> DateISO8601();[0X
    [4X"2010-03-30"[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-6 CurrentTimestamp[0m
  
  [2X> CurrentTimestamp( [0X[3X[0X[2X ) _____________________________________________[0Xfunction
  [6XReturns:[0X  string
  
  Returns  the result of the call to [11Xdate[0m. This is an internal function of the
  package which is used to add the timestamp to the [5XSCSCP[0m service description.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> CurrentTimestamp();[0X
    [4X"Tue 30 Mar 2010 11:19:38 BST"[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-7 Hostname[0m
  
  [2X> Hostname( [0X[3X[0X[2X ) _____________________________________________________[0Xfunction
  [6XReturns:[0X  string
  
  Returns the result of the call to [11Xhostname[0m. This function may be used in the
  configuration file [11Xscscp/config.g[0m to specify that the default hostname which
  will  be  used  by  the  [5XSCSCP[0m  server  will be detected automatically using
  [11Xhostname[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> Hostname();[0X
    [4X"scscp.symbolic-computation.co.uk"[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-8 MemoryUsageByGAPinKbytes[0m
  
  [2X> MemoryUsageByGAPinKbytes( [0X[3X[0X[2X ) _____________________________________[0Xfunction
  [6XReturns:[0X  integer
  
  Returns  the  current volume of the memory used by [5XGAP[0m in kylobytes. This is
  equivalent  to  calling [11Xps -p <PID> -o vsz[0m, where [10X<PID>[0m is the process ID of
  the  [5XGAP[0m  process. This is an internal function of the package which is used
  by  the [5XSCSCP[0m server to report its memory usage in the [10Xinfo_memory[0m attribute
  when   being   called   with   the   option  [10Xdebuglevel=2[0m  (see  options  in
  [2XEvaluateBySCSCP[0m ([14X6.1-4[0m) and [2XNewProcess[0m ([14X6.1-2[0m)).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> MemoryUsageByGAPinKbytes();[0X
    [4X649848[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-9 LastReceivedCallID[0m
  
  [2X> LastReceivedCallID( [0X[3X[0X[2X ) ___________________________________________[0Xfunction
  [6XReturns:[0X  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  [5XGAP[0m  [5XSCSCP[0m client and server contains colon-separated server name, port
  number, process ID and a random string.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> LastReceivedCallID();[0X
    [4X"scscp.symbolic-computation.co.uk:26133:77372:choDZBgA"[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-10 IO_PickleToString[0m
  
  [2X> IO_PickleToString( [0X[3Xobj[0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  string containing "pickled" object
  
  This  function  "pickles" or "serialises" the object [3Xobj[0m using the operation
  [2XIO_Pickle[0m  ([14XIO:  IO_Pickle[0m)  from the [5XIO[0m package, and writes it to a string,
  from  which it could be later restored using [2XIO_UnpickleFromString[0m ([14X9.2-11[0m).
  This provides a way to design [5XSCSCP[0m procedures which transmit [5XGAP[0m objects in
  the  "pickled"  format  as [5XOpenMath[0m strings, which may be useful for objects
  which  may  be  "pickled"  by  the  [5XIO[0m  package  but can not be converted to
  [5XOpenMath[0m or for which the "pickled" representation is more compact or can be
  encoded/decoded much faster.
  
  See  [2XIO_Pickle[0m  ([14XIO:  IO_Pickle[0m)  and [2XIO_Unpickle[0m ([14XIO: IO_Unpickle[0m) for more
  details.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> f := IO_PickleToString( GF( 125 ) );[0X
    [4X"FFIEINTG\>15INTG\>13FAIL"[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X9.2-11 IO_UnpickleFromString[0m
  
  [2X> IO_UnpickleFromString( [0X[3Xs[0X[2X ) _______________________________________[0Xfunction
  [6XReturns:[0X  "unpickled" GAP object
  
  This  function "unpickles" the string [3Xs[0m which was created using the function
  [2XIO_PickleToString[0m   ([14X9.2-10[0m),   using   the   operation   [2XIO_Unpickle[0m   ([14XIO:
  IO_Unpickle[0m)  from  the  [5XIO[0m package. See [2XIO_PickleToString[0m ([14X9.2-10[0m) for more
  details and suggestions about its usage.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> IO_UnpickleFromString( f );                    [0X
    [4XGF(5^3)[0X
    [4Xgap> f = IO_UnpickleFromString( IO_PickleToString( f ) ); [0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
