examples.xml

<Chapter Label="Examples">
<Heading>Examples of &SCSCP; usage</Heading>    

In this chapter we are going to demonstrate some examples of communication
between client and server using the SCSCP.

<Section Label="ProvidingServices">
<Heading>Providing services with the SCSCP package</Heading>

You can try to run the SCSCP server with the configuration file
<File>scscp/example/myserver.g</File>. To do this, go to that directory
and enter <C>gap myserver.g</C>. After this you will see some information
messages and finally the server will start to wait for the connection. The
final part of the startup screen may look as follows:

<Log>
<![CDATA[
#I  Installed SCSCP procedure Factorial
#I  Installed SCSCP procedure WS_Factorial
#I  Installed SCSCP procedure GroupIdentificationService
#I  Installed SCSCP procedure IdGroup512ByCode
#I  Installed SCSCP procedure WS_IdGroup
#I  Installed SCSCP procedure WS_Karatsuba
#I  Installed SCSCP procedure EvaluateOpenMathCode
#I  Ready to accept TCP/IP connections at localhost:26133 ...
#I  Waiting for new client connection at localhost:26133 ...
]]>
</Log>

See further self-explanatory comments in the file 
<File>scscp/example/myserver.g</File>.
There also some test files in the directory <File>scscp/tst/</File>
supplied with detailed comments. First, you may use demonstration
files, preliminary turning on the demonstration mode as it is
explained in these files, or just executing step by step each command
from <File>scscp/tst/demo.g</File> and <File>scscp/tst/omdemo.g</File>.
Then you can try to use files <File>scscp/tst/id512.g</File>, 
<File>scscp/tst/idperm.g</File> and <File>scscp/tst/factor.g</File>
for further tests of &SCSCP; services.
</Section>

<Section Label="Id512">
<Heading>Identifying groups of order 512</Heading>

We will give an example guiding you through all steps
of creation of your own &SCSCP; service.
<P/>

The &GAP; Small Group Library does not provide identification for
groups of order 512 using the function <C>IdGroup</C>:

<Log>
<![CDATA[
gap> IdGroup( DihedralGroup( 256 ) );
[ 256, 539 ]
gap> IdGroup(DihedralGroup(512)); 
Error, the group identification for groups of size 512 is not available 
called from
<function "unknown">( <arguments> )
 called from read-eval loop at line 71 of *stdin*
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
brk> 
]]>
</Log>

However, the &GAP; package &ANUPQ; <Cite Key="ANUPQ"/> has a function
<C>IdStandardPresented512Group</C> that does this work as demonstrated
below:
 
<Example>
<![CDATA[
gap> LoadPackage("anupq");
---------------------------------------------------------------------------
Loading    ANUPQ (ANU p-Quotient) 3.1.4
GAP code by  Greg Gamble <[email protected]> (address for correspondence)
           Werner Nickel (http://www.mathematik.tu-darmstadt.de/~nickel/)
           [uses ANU pq binary (C code program) version: 1.9]
C code by  Eamonn O'Brien (http://www.math.auckland.ac.nz/~obrien)
Co-maintained by Max Horn <[email protected]>

            For help, type: ?ANUPQ
---------------------------------------------------------------------------
true
gap> G := DihedralGroup( 512 );            
<pc group of size 512 with 9 generators>
gap> F := PqStandardPresentation( G );
<fp group on the generators [ f1, f2, f3, f4, f5, f6, f7, f8, f9 ]>
gap> H := PcGroupFpGroup( F );
<pc group of size 512 with 9 generators>
gap> IdStandardPresented512Group( H );
[ 512, 2042 ]
]]>
</Example>

The package &ANUPQ; requires <Package>UNIX</Package> environment 
and it is natural to provide an identification service for groups of
order 512 to make it available for other platforms.
<P/>

Now we need to decide how the client will transmit a group to the server.
Can we encode this group in &OpenMath;? But there is no content dictionary
for PcGroups. Should we convert it to a permutation representation to be 
able to use existing content dictionaries? But then the resulting &OpenMath;
code will be not compact. However, the &SCSCP; protocol provides enough 
freedom for the user to select its own data representation, and since we 
are linking together two copies of the same system, we may use the 
<E>pcgs code</E> to pass the data to the server 
(see <Ref BookName="ref" Func="CodePcGroup" />. 
<P/>

First we create a function which accepts the integer number that is the code for 
pcgs of a group of order 512 and returns the number of this group in the
GAP Small Groups library:

<Log>
<![CDATA[
IdGroup512ByCode := function( code )
local G, F, H;
G := PcGroupCode( code, 512 );
F := PqStandardPresentation( G );
H := PcGroupFpGroup( F );
return IdStandardPresented512Group( H );
end;
]]>
</Log>

After such function was created on the server, we need to make it
<Q>visible</Q> as an &SCSCP; procedure:

<Log>
<![CDATA[
gap> InstallSCSCPprocedure("IdGroup512", IdGroup512ByCode );
InstallSCSCPprocedure : procedure IdGroup512 installed. 
]]>
</Log>

Note that this function assumes that the argument is a valid code
for some group of order 512, and we wish the client to make it
sure that this is the case. To do this, and also for the client's
convenience, we provide the client's counterpart for this 
service. Here the group must be a pc-group of order 512, otherwise
an error message will appear.

<Example>
<![CDATA[
gap> IdGroup512 := function( G )
>    local code, result;
>    if Size( G ) <> 512 then
>      Error( "G must be a group of order 512 \n" );
>    fi;
>    code := CodePcGroup( G );
>    result := EvaluateBySCSCP( "IdGroup512ByCode", [ code ], 
>                               "localhost", 26133 );
>    return result.object;
> end;;
]]>
</Example>

Now the client can call the function <C>IdGroup512</C>, and the procedure
of getting result is as much straightforward as using <C>IdGroup</C> for
those groups where it works:

<Example>
<![CDATA[
gap> IdGroup512(DihedralGroup(512));
[ 512, 2042 ]
]]>
</Example>

</Section>

</Chapter>