Goto Chapter: Top 1 2 3 4 5 6 7 8 9 Bib Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

5 Running SCSCP server
 5.1 Installation of SCSCP procedures
 5.2 Starting SCSCP server
 5.3 Procedures to get information about the SCSCP server

5 Running SCSCP server

5.1 Installation of SCSCP procedures

There may various ways to run SCSCP server, for example:

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).

5.1-1 InstallSCSCPprocedure
‣ 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:

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.

5.1-2 OMsymRecord
‣ 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.

5.2 Starting SCSCP server

5.2-1 RunSCSCPserver
‣ 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:


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:

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

5.3 Procedures to get information about the SCSCP server

5.3-1 GetServiceDescription
‣ 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" )

5.3-2 GetAllowedHeads
‣ 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" 
     ] )

5.3-3 IsAllowedHead
‣ 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

5.3-4 GetTransientCD
‣ 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" )

5.3-5 GetSignature
‣ 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" ) )

 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 Bib Ind

generated by GAPDoc2HTML