<!-- $Id: service.xml 3110 2009-05-26 14:57:43Z alexk $ -->

<Chapter Label="Service">
<Heading>Service functions</Heading>

<Section Label="Doctools">
<Heading>Tools for making documentation</Heading>

<ManSection>
   <Func Name="SCSCPBuildManual" 
          Arg="" 
         Comm="requires GAPDoc, UNIX or Linux and TeX;" />
   <Description>
      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.
      <P/>
      Since the &SCSCP; 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.
   </Description>
</ManSection>


<ManSection>
   <Func Name="SCSCPBuildManualHTML" 
          Arg=""
	     Comm="requires only GAPDoc" />
   <Description>
      This function is used to build the manual only in HTML format.
      This does not require &TeX; installation and works in any operating
      system.
      <P/>
      Since the &SCSCP; 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.
   </Description>
</ManSection>

</Section>

<Section Label="Other">
<Heading>Other commands</Heading>

<ManSection>
   <Func Name="PingSCSCPservice"
         Arg="hostname portnumber" />
   <Returns>
     <K>true</K> or <K>fail</K>
   </Returns>	 
   <Description>
        This function returns <K>true</K> if the client can establish
        connection with the SCSCP server at <A>hostname</A>:<A>portnumber</A>.
        Otherwise, it returns <K>fail</K>.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> PingSCSCPservice("localhost",26133);
#I  Creating a socket ...
#I  Connecting to a remote socket via TCP/IP ...
#I  Got connection initiation message
true
gap> PingSCSCPservice("localhost",26134);                     
#I  Creating a socket ...
#I  Connecting to a remote socket via TCP/IP ...
Error: rec(
  number := 61,
  message := "Connection refused" )
fail
]]>
</Example>


<ManSection>
   <Func Name="PingStatistic" 
         Arg="hostname portnumber n" />
   <Returns>
     nothing
   </Returns>	 
   <Description>
        The function is similar to the UNIX <C>ping</C>. It tries <A>n</A> times 
        to establish connection with the SCSCP server at 
        <A>hostname</A>:<A>portnumber</A>, and then displays statistical information.
   </Description>
</ManSection>

<Example>
<![CDATA[
gap> PingStatistic("localhost",26133,5);
#I  Creating a socket ...
#I  Connecting to a remote socket via TCP/IP ...
#I  Got connection initiation message nr 1
...
#I  Creating a socket ...
#I  Connecting to a remote socket via TCP/IP ...
#I  Got connection initiation message nr 5
100 packets transmitted, 100 received, 0% packet loss, time 26ms
min/avg/max = [ 0, 13/50, 2 ]
]]>
</Example>


<ManSection>
   <InfoClass Name="InfoSCSCP"
              Comm="Info class for SCSCP algorithms" />
   <Description>
      <C>InfoSCSCP</C> 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 <File>scscp/config.g</File>. 
      The higher the level is, the more information will be displayed. 
      To change the InfoLevel to <C>k</C>, use the command 
      <C>SetInfoLevel(InfoSCSCP, k)</C>. 
      In the following examples we demonstrate various degrees of output 
      details using Info messages.
   </Description>
</ManSection>

<Example>
<![CDATA[
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  Request sent ...
#I  Waiting for reply ...
rec( object := "3628800", attributes := [ [ "call_id", "localhost:26133:38" ] ] )
]]>
</Example>

<Example>
<![CDATA[
gap> SetInfoLevel(InfoSCSCP,0);                              
gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133);
rec( object := "3628800", attributes := [ [ "call_id", "localhost:26133:41" ] ] )
]]>
</Example>

<Example>
<![CDATA[
gap> SetInfoLevel(InfoSCSCP,3);
gap> G:=SymmetricGroup(4);;
gap> gens:=GeneratorsOfGroup(G);  
[ (1,2,3,4), (1,2) ]
gap> EvaluateBySCSCP( "GroupIdentificationService",[gens],"localhost",26133);
#I  Creating a socket ...
#I  Connecting to a remote socket via TCP/IP ...
#I  Got connection initiation message
#I Composing procedure_call message: 
<?scscp start ?>
<OMOBJ>
    <OMATTR>
		<OMATP>
			<OMS cd="scscp1" name="call_id"/>
			<OMSTR>localhost:26133:1212</OMSTR>
		</OMATP>
		<OMA>
			<OMS cd="scscp1" name="procedure_call"/>
			<OMA>
				<OMS cd="scscp_transient_1" name="GroupIdentificationService"/>
				<OMA>
					<OMS cd="list1" name="list"/>
					<OMA>
						<OMS cd="permut1" name="permutation"/>
						<OMI> 2</OMI>
						<OMI> 3</OMI>
						<OMI> 4</OMI>
						<OMI> 1</OMI>
					</OMA>
					<OMA>
						<OMS cd="permut1" name="permutation"/>
						<OMI> 2</OMI>
						<OMI> 1</OMI>
					</OMA>
				</OMA>
			</OMA>
		</OMA>
	</OMATTR>
</OMOBJ>
<?scscp end ?>
#I  Request sent ...
#I  Waiting for reply ...
#I  <?scscp start ?>
#I Received message: 
<OMOBJ>
	<OMATTR>
		<OMATP>
			<OMS cd="scscp1" name="call_id"/>
			<OMSTR>localhost:26133:1212</OMSTR>
		</OMATP>
		<OMA>
			<OMS cd="scscp1" name="procedure_completed"/>
			<OMA>
				<OMS cd="list1" name="list"/>
				<OMI> 24</OMI>
				<OMI> 12</OMI>
			</OMA>
		</OMA>
	</OMATTR>
</OMOBJ>
#I  <?scscp end ?>
#I  Got back: object [ 24, 12 ] with attributes [ [ "call_id", "localhost:26133:1212" ] ]
rec( object := [ 24, 12 ], attributes := [ [ "call_id", "localhost:26133:1212" ] ] )
]]>
</Example>


<ManSection>
    <Func Name="DateISO8601"
      Arg=""
      Comm="" />
    <Returns>
        string
    </Returns>	 
    <Description>
    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 <C>meta.CDDate</C>.
<Log>
<![CDATA[
gap> DateISO8601();
"2009-03-31"
]]>
</Log>
    </Description>
</ManSection>

<ManSection>
    <Func Name="CurrentTimestamp"
      Arg=""
      Comm="" />
    <Returns>
        string
    </Returns>	 
    <Description>
    Returns the result of the call to <File>date</File>. This is an internal function
    of the package which is used to add the timestamp to the &SCSCP; service description.
<Log>
<![CDATA[
gap> CurrentTimestamp();
"Tue 31 Mar 2009 11:19:38 BST"
]]>
</Log>
    </Description>
</ManSection>

<ManSection>
    <Func Name="Hostname"
      Arg=""
      Comm="" />
    <Returns>
        string    
    </Returns>	 
    <Description>
     Returns the result of the call to <File>hostname</File>.
     This function may be used in the configuration file <File>scscp/config.g</File>
     to specify that the default hostname which will be used by the &SCSCP; server
     will be detected automatically using <File>hostname</File>.
<Log>
<![CDATA[
gap> Hostname();
"scscp.symbolic-computation.co.uk"
]]>
</Log>     
    </Description>
</ManSection>

<ManSection>
    <Func Name="MemoryUsageByGAPinKbytes"
      Arg=""
      Comm="" />
    <Returns>
        integer
    </Returns>	 
    <Description>
    Returns the current volume of the memory used by &GAP; in kylobytes. This is
    equivalent to calling <File>ps -p &lt;PID> -o vsz</File>, where <C>&lt;PID></C> 
    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 
    <C>info_memory</C> attribute when being called with the option <C>debuglevel=2</C>
    (see options in <Ref Func="EvaluateBySCSCP" /> and <Ref Func="NewProcess" />).
<Log>
<![CDATA[
gap> MemoryUsageByGAPinKbytes();
649848
]]>
</Log>     
    </Description>
</ManSection>

<ManSection>
    <Func Name="LastReceivedCallID"
      Arg=""
      Comm="" />
    <Returns>
        string
    </Returns>	 
    <Description>
    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.
<Log>
<![CDATA[
gap> LastReceivedCallID();
"scscp.symbolic-computation.co.uk:26133:77372:choDZBgA"
]]>
</Log> 
    </Description>
</ManSection>

<ManSection>
    <Func Name="IO_PickleToString"
      Arg="obj"
      Comm="" />
    <Returns>
        string containing "pickled" object
    </Returns>	 
    <Description>
        This function "pickles" or "serialises" the object <A>obj</A> using 
        the operation <Ref BookName="IO" Oper="IO_Pickle" /> from the &IO;
        package, and writes it to a string, from which it could be later 
        restored using <Ref Func="IO_UnpickleFromString" />. 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. 
        <P/>
        See <Ref BookName="IO" Oper="IO_Pickle" /> and 
        <Ref BookName="IO" Oper="IO_Unpickle" /> for more details.

<Example>
<![CDATA[
gap> f := IO_PickleToString( GF( 125 ) );
"FFIEINTG\>15INTG\>13FAIL"
]]>
</Example>        
        
    </Description>
</ManSection>

<ManSection>
    <Func Name="IO_UnpickleFromString"
      Arg="s"
      Comm="" />
    <Returns>
        "unpickled" GAP object
    </Returns>	 
    <Description>
        This function "unpickles" the string <A>s</A> which was
        created using the function <Ref Func="IO_PickleToString" />,
        using the operation <Ref BookName="IO" Oper="IO_Unpickle" /> 
        from the &IO; package. See <Ref Func="IO_PickleToString" />
        for more details and suggestions about its usage.
<Example>
<![CDATA[
gap> IO_UnpickleFromString( f );                    
GF(5^3)
gap> f = IO_UnpickleFromString( IO_PickleToString( f ) ); 
true
]]>
</Example>   
     
    </Description>
</ManSection>

</Section>

</Chapter>