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 InstallSCSCPprocedure (5.1-1) 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 RunSCSCPserver (5.2-1).
‣ InstallSCSCPprocedure( procname, procfunc[, description][, narg1[, narg2][, signature]] ) | ( function ) |
Returns: nothing
For a string procname and a function procfunc, InstallSCSCPprocedure 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 InstallSCSCPprocedure:
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 InstallSCSCPprocedure, 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 5.3 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.
‣ OMsymRecord | ( global variable ) |
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 ([FHK+a], [FHK+c]). Additionally, InstallSCSCPprocedure (5.1-1) 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.
‣ RunSCSCPserver( servertype, port ) | ( function ) |
Returns: 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.gap-system.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 is more than one way to run 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 RunSCSCPserver, 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 2.2 about configuring files config.g and gapd.sh.
‣ GetServiceDescription( server, port ) | ( function ) |
Returns: 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 2.2).
gap> GetServiceDescription( "localhost", 26133 ); rec( description := "Started with the configuration file scscp/example/myserver.g\ on Thu 16 Feb 2017 16:03:56 GMT", service_name := "GAP SCSCP service", version := "GAP 4.8.6 + SCSCP 2.2.1" )
‣ GetAllowedHeads( server, port ) | ( function ) |
Returns: record
Returns the record with components corresponding to content dictionaries. The name of each component is the name of the content dictionary, and its the value is either a boolean or a list of strings. In case it's value is a list, it contains 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. If it's value is true, it means the server allows all symbols from the corresponding content dictionary.
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 := [ "AClosestVectorCombinationsMatFFEVecFFE", "Determinant", "GroupIdentificationService", "IO_UnpickleStringAndPickleItBack", "IdGroup512ByCode", "Identity", "IsPrimeInt", "Length", "MathieuGroup", "MatrixGroup", "NormalizedUnitCFcommutator", "NormalizedUnitCFpower", "NrConjugacyClasses", "NrSmallGroups", "NumberCFGroups", "NumberCFSolvableGroups", "PointImages", "QuillenSeriesByIdGroup", "ResetMinimumDistanceService", "SCSCPStartTracing", "SCSCPStopTracing", "Size", "SylowSubgroup", "WS_AlternatingGroup", "WS_AutomorphismGroup", "WS_ConwayPolynomial", "WS_Factorial", "WS_FactorsCFRAC", "WS_FactorsECM", "WS_FactorsMPQS", "WS_FactorsPminus1", "WS_FactorsPplus1", "WS_FactorsTD", "WS_IdGroup", "WS_LatticeSubgroups", "WS_Mult", "WS_MultMatrix", "WS_Phi", "WS_PrimitiveGroup", "WS_SmallGroup", "WS_SymmetricGroup", "WS_TransitiveGroup", "addition" ] )
‣ IsAllowedHead( cd, symbol, server, port ) | ( function ) |
Returns: 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( "setname1", "Q", "localhost", 26133 ); true gap> IsAllowedHead( "setname1", "R", "localhost", 26133 ); false
‣ GetTransientCD( transient_cd, server, port ) | ( function ) |
Returns: 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 GetAllowedHeads (5.3-2).
gap> GetTransientCD( "scscp_transient_1", "localhost", 26133 ); rec( CDDate := "2017-02-08", CDDefinitions := [ rec( Description := "Size is currently undocumented.", Name := "Size" ), rec( Description := "Length is currently undocumented.", Name := "Length" ), rec( Description := "NrConjugacyClasses is currently undocumented.", Name := "NrConjugacyClasses" ), ... rec( Description := "MatrixGroup is currently undocumented.", Name := "MatrixGroup" ) ], CDName := "scscp_transient_1", CDReviewDate := "2017-02-08", CDRevision := "0", CDStatus := "private", CDVersion := "0", Description := "This is a transient CD for the GAP SCSCP service" )
‣ GetSignature( transientcd, symbol, server, port ) | ( function ) |
Returns: 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( maxarg := 1, minarg := 1, symbol := rec( cd := "scscp_transient_1", name := "WS_Factorial" ), symbolargs := rec( cd := "scscp2", name := "symbol_set_all" ) )
generated by GAPDoc2HTML