chap5.txt

  
  5 Running SCSCP server
  
  
  5.1 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 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:
  
      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:
  
          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:
  
    Example  
    
    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.)
  
    Example  
    
    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:
  
    Example  
    
    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:
  
    Example  
    
    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:
  
      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).
  
    Example  
    
    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.
  
  
  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).
  
    Example  
    
    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.
  
    Example  
    
    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.
  
    Example  
    
    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).
  
    Example  
    
    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.
  
    Example  
    
    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" ) )