Running SCSCP server
Installation of &SCSCP; procedures

There may various ways to run &SCSCP; server, for example: allowing generic services like evaluation of arbitrary &OpenMath; code; offering highly specialized procedures like identification of groups of order 512; providing access to a database of mathematical objects. Each of these use cases requires certain control over the level of functionality exposed to the client. To achieve this, before starting &SCSCP; service its provider must call the function to make required procedures visible for the client.

Additionally, the service can be made made accessible only for clients running on the same computer, or accessible only through a particular network interface, or generally accessible. This customization is made at the stage of starting the &SCSCP; server with the function .

Nothing
For a string procname and a function procfunc, makes the procfunc available as SCSCP procedure under the name procname, adding it to the transient &OpenMath; content dictionary scscp_transient_1 that will exist during the service lifetime.

The second argument procfunc may be either a standard or user-defined &GAP; function (procedure, operation, etc.).

The rest of arguments are optional and may be used in a number of combinations: description is a string with the description of the procedure. It may be used by the help system. If it is omitted, the procedure will be reported as undocumented. narg1 is a non-negative integer, specifying the minimal number of arguments, and narg2 is a non-negative integer or infinity, specifying the maximal number of arguments. If narg2 is omitted then the maximal number of arguments will be set to narg1. If both narg1 and narg2 are omitted then the minimal number of arguments will be set to zero and their maximal number will be set to infinity. signature is the signature record of the procedure. If the signature is given, then the number of arguments must be explicitly specified (by narg1 with or without narg2) at least to zero and infinity respectively (to ensure proper matching of arguments). Note that it is completely acceptable for a symbol from a transient content dictionary to overstate the set of symbols which may occur in its children using the scscp2.symbol_set_all symbol, and to use standard &OpenMath; errors to reject requests later at the stage of their evaluation. For example, using such approach, we will define the procedure WS_Factorial accepting not only immediate <OMI> objects but anything which could be evaluated to an integer.

. The signature must be either a list of records, where i-th record corresponds to the i-th argument, or a record itself meaning that it specifies the signature for all arguments. In the latter case the record may be rec( ) corresponding to the scscp2.symbol_set_all symbol (this will be assumed by default if the signature will be omitted).

If more detailed description of allowed arguments is needed, the signature record (one for all arguments or a specific one) may have components CDgroups, CDs and Symbols. The first two are lists of names of content dictionary groups and content dictionaries, and the third is a record whose components are names of content dictionaries, containing lists of names of allowed symbols from these dictionaries, for example: signature := rec( CDgroups := [ "scscp" ], CDs := [ "arith1", "linalg1" ], Symbols := rec( polyd1 := [ "DMP", "term", "SDMP" ], polyu := [ "poly_u_rep", "term" ] ) );

In the following example we define the function WS_Factorial that takes an integers and returns its factorial, using only mandatory arguments of :

gap> InstallSCSCPprocedure( "WS_Factorial", Factorial ); InstallSCSCPprocedure : procedure WS_Factorial installed.

In the following example we install the procedure that will accept a list of permutations and return the number in the &GAP; Small Groups library of the group they generate (for the sake of simplicity we omit tests of validity of arguments, availability of IdGroup for groups of given order etc.)

gap> IdGroupByGenerators:=function( permlist ) > return IdGroup( Group( permlist ) ); > end; function( permlist ) ... end gap> InstallSCSCPprocedure( "GroupIdentificationService", IdGroupByGenerators ); InstallSCSCPprocedure : procedure GroupIdentificationService installed.

After installation, the procedure may be reinstalled, if necessary:

gap> InstallSCSCPprocedure( "WS_Factorial", Factorial ); WS_Factorial is already installed. Do you want to reinstall it [y/n]? y InstallSCSCPprocedure : procedure WS_Factorial reinstalled.

Finally, some examples of various combinations of optional arguments: InstallSCSCPprocedure( "WS_Phi", Phi, "Euler's totient function, see ?Phi in GAP", 1, 1 ); InstallSCSCPprocedure( "GroupIdentificationService", IdGroupByGenerators, 1, infinity, rec() ); InstallSCSCPprocedure( "IdGroup512ByCode", IdGroup512ByCode, 1 ); InstallSCSCPprocedure( "WS_IdGroup", IdGroup, "See ?IdGroup in GAP" );

Note that it is quite acceptable to overstate the signature of the procedure and use only mandatory arguments in a call to , which will be installed then as a procedure that can accept arbitrary number of arguments encoded without any restrictions on &OpenMath; symbols used, because anyway the &GAP; system will return an error in case of the wrong number or type of arguments, though it might be a good practice to give a way to the client to get more precise procedure description a priori, that is before sending request. See about utilities for obtaining such information about the &SCSCP; service.

Some more examples of installation of SCSCP procedures are given in the file scscp/example/myserver.g.

This is the global record from the &OpenMath; package used for the conversion from &OpenMath; to &GAP;. It is extended in the &SCSCP; package by adding support for symbols from scscp1 and scscp2 content dictionaries (, ). Additionally, adds to this record a component corresponding to the appropriate transient content dictionary (by default, scscp_transient_1) defining mappings between &OpenMath; symbols from this content dictionary and installed &SCSCP; procedures.
Starting SCSCP server
nothing
Will start the &SCSCP; server at port given by the integer port. The first parameter servertype is either true, false or a string containing the server hostname: when servertype is true, the server will be started in a universal mode and will accept all incoming connections; when servertype is false, the server will be started at localhost and will not accept any incoming connections from outside; when servertype is a string, for example, "scscp.symbolic-computation.org", the server will be accessible only by specified server name (this may be useful to manage accessibility if, for example, the hardware has several network interfaces).

gap> RunSCSCPserver( "localhost", 26133 ); Ready to accept TCP/IP connections at localhost:26133 ... Waiting for new client connection at localhost:26133 ...

Actually, there are several ways to start &GAP; &SCSCP; server: from the &GAP; session as shown in the example above; starting &GAP; as gap myserver.g, where myserver.g is the server configuration file with the last command being the call , which may take its arguments from the configuration file scscp/config.g (an example of such configuration file is given in scscp/example/myserver.g ); start &GAP; as a daemon using the script gapd.sh which is supplied in the root directory of the package (for the description of all available options see comments in gapd.sh) and may overwrite parameters from scscp/config.g.

See Section about configuring files config.g and gapd.sh.

Procedures to get information about the &SCSCP; server
record
Returns the record with three components containing strings with the name, version and description of the service as specified by the service provider in the scscp/config.g (for details about configuration files, see ). gap> GetServiceDescription( "localhost", 26133 ); rec( service_name := "GAP SCSCP service", version := "GAP 4.4.12 + SCSCP 1.1 started on Tue 30 Mar 2010 00:35:38 BST", description := "Started with scscp/example/myserver.g from SCSCP 1.2" )
record
Returns the record with components corresponding to content dictionaries. Each component is a list of names of symbols from the corresponding content dictionary which are allowed to appear as a head symbol (i.e. the first child of the outermost <OMA>) in an &SCSCP; procedure call to the &SCSCP; server running at server : port.

Note that it is acceptable (although not quite desirable) for a server to overstate the set of symbols it accepts and use standard &OpenMath; errors to reject requests later. gap> GetAllowedHeads("localhost",26133); rec( scscp_transient_1 := [ "GroupIdentificationService", "IO_UnpickleStringAndPickleItBack", "IdGroup512ByCode", "PointImages", "QuillenSeriesByIdGroup", "SCSCPStartTracing", "SCSCPStopTracing", "WS_ConwayPolynomial", "WS_Factorial", "WS_FactorsCFRAC", "WS_FactorsECM", "WS_FactorsMPQS", "WS_FactorsPminus1", "WS_FactorsPplus1", "WS_FactorsTD", "WS_IdGroup", "WS_Karatsuba", "WS_Phi" ] )
true
or false
Checks whether the &OpenMath; symbol cd . symbol, which may be a symbol from a standard or transient &OpenMath; content dictionary, is allowed to appear as head symbol (i.e. the first child of the outermost <OMA> in an &SCSCP; procedure call to the &SCSCP; server running at server : port. This enables the client to check whether a particular symbol is allowed without requesting the full list of symbols.

Also, it is acceptable (although not necessarily desirable) for a server to overstate the set of symbols it accepts and use standard &OpenMath; errors to reject requests later. gap> IsAllowedHead( "permgp1", "group", "localhost", 26133 ); true gap> IsAllowedHead( "nums1", "pi", "localhost", 26133 ); false
record
Returns a record with the transient content dictionary transient_cd from the &SCSCP; server running at server : port. Names of components of this record correspond to symbols from the meta content dictionary.

By default, the name of the transient content dictionary for the &GAP; &SCSCP; server is scscp_transient_1. Other systems may use transient content dictionaries with another names, which, however, must always begin with scscp_transient_ and may be guessed from the output of . gap> GetTransientCD( "scscp_transient_1", "localhost", 26133 ); rec( Description := "This is a transient CD for the GAP SCSCP service", CDName := "scscp_transient_1", CDReviewDate := "2010-03-30", CDDate := "2010-03-30", CDVersion := "0", CDRevision := "0", CDStatus := "private", CDDefinitions := [ rec( Name := "WS_Factorial", Description := "See ?Factorial in GAP" ), rec( Name := "WS_Phi", Description := "Euler's totient function, see ?Phi in GAP" ), ... rec( Name := "SCSCPStartTracing", Description := "To turn on tracing using given filename on the server" ), rec( Name := "SCSCPStopTracing", Description := "To turn off tracing on the server" ) ] )
record
Returns a record with the signature of the &OpenMath; symbol transientcd . symbol from a transient &OpenMath; content dictionary. This record contains components corresponding to the &OpenMath; symbol whose signature is described, the minimal and maximal number of its children (that is, of its arguments), and symbols which may be used in the &OpenMath; encoding of its children. Note that it is acceptable for a symbol from a transient content dictionary to overstate the set of symbols which may occur in its children using the scscp2.symbol_set_all symbol, and use standard &OpenMath; errors to reject requests later, like in the example below: using such approach, the procedure WS_Factorial is defined to accept not only immediate <OMI> objects but anything which could be evaluated to an integer. gap> GetSignature("scscp_transient_1","WS_Factorial","localhost",26133); rec( symbol := rec( name := "WS_Factorial", cd := "scscp_transient_1" ), minarg := 1, maxarg := 1, symbolargs := rec( name := "symbol_set_all", cd := "scscp2" ) )