  
  [1X5 Running SCSCP server[0X
  
  
  [1X5.1 Installation of [5XSCSCP[1X procedures[0X
  
  There may various ways to run [5XSCSCP[0m server, for example:
  
  --    allowing generic services like evaluation of arbitrary [5XOpenMath[0m 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 [5XSCSCP[0m
  service its provider must call the function [2XInstallSCSCPprocedure[0m ([14X5.1-1[0m) 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  [5XSCSCP[0m server with the function [2XRunSCSCPserver[0m
  ([14X5.2-1[0m).
  
  [1X5.1-1 InstallSCSCPprocedure[0m
  
  [2X> InstallSCSCPprocedure( [0X[3Xprocname, procfunc[, description][, narg1[, narg2][, signature]][0X[2X ) [0Xfunction
  [6XReturns:[0X  Nothing
  
  For  a  string [3Xprocname[0m and a function [3Xprocfunc[0m, [2XInstallSCSCPprocedure[0m makes
  the [3Xprocfunc[0m available as SCSCP procedure under the name [3Xprocname[0m, adding it
  to  the  transient  [5XOpenMath[0m  content dictionary [10Xscscp_transient_1[0m that will
  exist during the service lifetime.
  
  The  second  argument  [3Xprocfunc[0m may be either a standard or user-defined [5XGAP[0m
  function (procedure, operation, etc.).
  
  The  rest  of  arguments  are  optional  and  may  be  used  in  a number of
  combinations:
  
  --    [3Xdescription[0m  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.
  
  --    [3Xnarg1[0m  is  a  non-negative  integer,  specifying the minimal number of
        arguments, and [3Xnarg2[0m is a non-negative integer or infinity, specifying
        the  maximal number of arguments. If [3Xnarg2[0m is omitted then the maximal
        number  of arguments will be set to [3Xnarg1[0m. If both [3Xnarg1[0m and [3Xnarg2[0m are
        omitted  then  the minimal number of arguments will be set to zero and
        their maximal number will be set to infinity.
  
  --    [3Xsignature[0m  is  the signature record of the procedure. If the [3Xsignature[0m
        is  given,  then  the number of arguments must be explicitly specified
        (by  [3Xnarg1[0m  with  or  without  [3Xnarg2[0m)  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  [10Xscscp2.symbol_set_all[0m symbol, and to use standard [5XOpenMath[0m errors
        to  reject  requests  later  at  the  stage  of  their evaluation. For
        example,   using   such   approach,   we  will  define  the  procedure
        [10XWS_Factorial[0m  accepting  not only immediate [10X<OMI>[0m 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 [10Xrec( )[0m corresponding to the [10Xscscp2.symbol_set_all[0m 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 [10XCDgroups[0m, [10XCDs[0m and [10XSymbols[0m. 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:
  
        [4X------------------------  Example  ------------------------[0X
          [4X[0X
          [4Xsignature := rec( CDgroups := [ "scscp" ],[0X
          [4X                  CDs := [ "arith1", "linalg1" ],[0X
          [4X                  Symbols := rec( polyd1 := [ "DMP", "term", "SDMP" ],[0X
          [4X                                   polyu := [ "poly_u_rep", "term" ] ) );[0X
          [4X[0X
        [4X------------------------------------------------------------[0X
  
  In  the  following example we define the function [10XWS_Factorial[0m that takes an
  integers  and  returns  its  factorial,  using  only  mandatory arguments of
  [2XInstallSCSCPprocedure[0m:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> InstallSCSCPprocedure( "WS_Factorial", Factorial );[0X
    [4XInstallSCSCPprocedure : procedure WS_Factorial installed. [0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  In the following example we install the procedure that will accept a list of
  permutations  and  return  the number in the [5XGAP[0m Small Groups library of the
  group they generate (for the sake of simplicity we omit tests of validity of
  arguments, availability of [10XIdGroup[0m for groups of given order etc.)
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> IdGroupByGenerators:=function( permlist )[0X
    [4X> return IdGroup( Group( permlist ) );[0X
    [4X> end;[0X
    [4Xfunction( permlist ) ... end[0X
    [4Xgap> InstallSCSCPprocedure( "GroupIdentificationService", IdGroupByGenerators );[0X
    [4XInstallSCSCPprocedure : procedure GroupIdentificationService installed. [0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  After installation, the procedure may be reinstalled, if necessary:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> InstallSCSCPprocedure( "WS_Factorial", Factorial );[0X
    [4XWS_Factorial is already installed. Do you want to reinstall it [y/n]? y[0X
    [4XInstallSCSCPprocedure : procedure WS_Factorial reinstalled. [0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Finally, some examples of various combinations of optional arguments:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4XInstallSCSCPprocedure( "WS_Phi", Phi, [0X
    [4X                       "Euler's totient function, see ?Phi in GAP", 1, 1 );[0X
    [4XInstallSCSCPprocedure( "GroupIdentificationService", [0X
    [4X                        IdGroupByGenerators, 1, infinity, rec() );[0X
    [4XInstallSCSCPprocedure( "IdGroup512ByCode", IdGroup512ByCode, 1 );[0X
    [4XInstallSCSCPprocedure( "WS_IdGroup", IdGroup, "See ?IdGroup in GAP" );[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Note that it is quite acceptable to overstate the signature of the procedure
  and  use  only mandatory arguments in a call to [2XInstallSCSCPprocedure[0m, which
  will  be  installed  then as a procedure that can accept arbitrary number of
  arguments encoded without any restrictions on [5XOpenMath[0m symbols used, because
  anyway  the  [5XGAP[0m  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  [14X5.3[0m  about  utilities for obtaining such information
  about  the  [5XSCSCP[0m  service.  Some  more  examples  of  installation of SCSCP
  procedures are given in the file [11Xscscp/example/myserver.g[0m.
  
  [1X5.1-2 OMsymRecord[0m
  
  [2X> OMsymRecord________________________________________________[0Xglobal variable
  
  This  is the global record from the [5XOpenMath[0m package used for the conversion
  from  [5XOpenMath[0m to [5XGAP[0m. It is extended in the [5XSCSCP[0m package by adding support
  for   symbols  from  [10Xscscp1[0m  and  [10Xscscp2[0m  content  dictionaries  ([FHKLLRa],
  [FHKLR]).  Additionally, [2XInstallSCSCPprocedure[0m ([14X5.1-1[0m) adds to this record a
  component  corresponding to the appropriate transient content dictionary (by
  default,  [10Xscscp_transient_1[0m) defining mappings between [5XOpenMath[0m symbols from
  this content dictionary and installed [5XSCSCP[0m procedures.
  
  
  [1X5.2 Starting SCSCP server[0X
  
  [1X5.2-1 RunSCSCPserver[0m
  
  [2X> RunSCSCPserver( [0X[3Xservertype, port[0X[2X ) _______________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  Will  start  the  [5XSCSCP[0m  server at port given by the integer [3Xport[0m. The first
  parameter [3Xservertype[0m is either [9Xtrue[0m, [9Xfalse[0m or a string containing the server
  hostname:
  
  --    when  [3Xservertype[0m  is [9Xtrue[0m, the server will be started in a "universal"
        mode and will accept all incoming connections;
  
  --    when  [3Xservertype[0m is [9Xfalse[0m, the server will be started at [11Xlocalhost[0m and
        will not accept any incoming connections from outside;
  
  --    when      [3Xservertype[0m      is      a      string,      for     example,
        [11X"scscp.symbolic-computation.org"[0m,  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).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> RunSCSCPserver( "localhost", 26133 );[0X
    [4XReady to accept TCP/IP connections at localhost:26133 ...[0X
    [4XWaiting for new client connection at localhost:26133 ...[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Actually, there are several ways to start [5XGAP[0m [5XSCSCP[0m server:
  
  --    from the [5XGAP[0m session as shown in the example above;
  
  --    starting  [5XGAP[0m  as  [10Xgap  myserver.g[0m,  where  [11Xmyserver.g[0m  is  the server
        configuration   file   with   the   last   command   being   the  call
        [2XRunSCSCPserver[0m,  which  may  take its arguments from the configuration
        file [11Xscscp/config.g[0m (an example of such configuration file is given in
        [11Xscscp/example/myserver.g[0m );
  
  --    start  [5XGAP[0m  as  a daemon using the script [11Xgapd.sh[0m which is supplied in
        the  root  directory  of  the  package  (for  the  description  of all
        available   options   see  comments  in  [11Xgapd.sh[0m)  and  may  overwrite
        parameters from [11Xscscp/config.g[0m.
  
  See Section [14X2.2[0m about configuring files [11Xconfig.g[0m and [11Xgapd.sh[0m.
  
  
  [1X5.3 Procedures to get information about the [5XSCSCP[1X server[0X
  
  [1X5.3-1 GetServiceDescription[0m
  
  [2X> GetServiceDescription( [0X[3Xserver, port[0X[2X ) ____________________________[0Xfunction
  [6XReturns:[0X  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 [11Xscscp/config.g[0m (for details about configuration files, see [14X2.2[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> GetServiceDescription( "localhost", 26133 );[0X
    [4Xrec( service_name := "GAP SCSCP service", [0X
    [4X  version := "GAP 4.4.12 + SCSCP 1.1 started on Tue 30 Mar 2010 00:35:38 BST", [0X
    [4X  description := "Started with scscp/example/myserver.g from SCSCP 1.2" )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X5.3-2 GetAllowedHeads[0m
  
  [2X> GetAllowedHeads( [0X[3Xserver, port[0X[2X ) __________________________________[0Xfunction
  [6XReturns:[0X  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 [10X<OMA>[0m) in an [5XSCSCP[0m procedure call to the [5XSCSCP[0m server
  running at [3Xserver[0m[10X:[0m[3Xport[0m.
  
  Note  that  it  is acceptable (although not quite desirable) for a server to
  "overstate"  the  set of symbols it accepts and use standard [5XOpenMath[0m errors
  to reject requests later.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> GetAllowedHeads("localhost",26133);[0X
    [4Xrec( scscp_transient_1 := [ "GroupIdentificationService", [0X
    [4X      "IO_UnpickleStringAndPickleItBack", "IdGroup512ByCode", "PointImages", [0X
    [4X      "QuillenSeriesByIdGroup", "SCSCPStartTracing", "SCSCPStopTracing", [0X
    [4X      "WS_ConwayPolynomial", "WS_Factorial", "WS_FactorsCFRAC", "WS_FactorsECM", [0X
    [4X      "WS_FactorsMPQS", "WS_FactorsPminus1", "WS_FactorsPplus1", "WS_FactorsTD", [0X
    [4X      "WS_IdGroup", "WS_Karatsuba", "WS_Phi" ] )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X5.3-3 IsAllowedHead[0m
  
  [2X> IsAllowedHead( [0X[3Xcd, symbol, server, port[0X[2X ) ________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0m or [9Xfalse[0m
  
  Checks  whether  the [5XOpenMath[0m symbol [3Xcd[0m[10X.[0m[3Xsymbol[0m, which may be a symbol from a
  standard  or  transient [5XOpenMath[0m content dictionary, is allowed to appear as
  "head"  symbol  (i.e.  the  first  child  of the outermost [10X<OMA>[0m in an [5XSCSCP[0m
  procedure  call to the [5XSCSCP[0m server running at [3Xserver[0m[10X:[0m[3Xport[0m. 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 [5XOpenMath[0m errors
  to reject requests later.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> IsAllowedHead( "permgp1", "group", "localhost", 26133 );                            [0X
    [4Xtrue[0X
    [4Xgap> IsAllowedHead( "nums1", "pi", "localhost", 26133 );          [0X
    [4Xfalse[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X5.3-4 GetTransientCD[0m
  
  [2X> GetTransientCD( [0X[3Xtransient_cd, server, port[0X[2X ) _____________________[0Xfunction
  [6XReturns:[0X  record
  
  Returns a record with the transient content dictionary [3Xtransient_cd[0m from the
  [5XSCSCP[0m  server  running  at  [3Xserver[0m[10X:[0m[3Xport[0m.  Names of components of this record
  correspond to symbols from the [10Xmeta[0m content dictionary.
  
  By  default,  the name of the transient content dictionary for the [5XGAP[0m [5XSCSCP[0m
  server  is  [10Xscscp_transient_1[0m.  Other  systems  may  use  transient  content
  dictionaries  with  another  names,  which,  however, must always begin with
  [10Xscscp_transient_[0m  and  may  be  guessed  from  the output of [2XGetAllowedHeads[0m
  ([14X5.3-2[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> GetTransientCD( "scscp_transient_1", "localhost", 26133 );[0X
    [4Xrec( [0X
    [4X  Description := "This is a transient CD for the GAP SCSCP service", [0X
    [4X  CDName := "scscp_transient_1", [0X
    [4X  CDReviewDate := "2010-03-30", [0X
    [4X  CDDate := "2010-03-30", [0X
    [4X  CDVersion := "0", [0X
    [4X  CDRevision := "0", [0X
    [4X  CDStatus := "private", [0X
    [4X  CDDefinitions := [0X
    [4X    [ rec( Name := "WS_Factorial", [0X
    [4X           Description := "See ?Factorial in GAP" ), [0X
    [4X      rec( Name := "WS_Phi", [0X
    [4X           Description := "Euler's totient function, see ?Phi in GAP" ), [0X
    [4X  ...[0X
    [4X      rec( Name := "SCSCPStartTracing", [0X
    [4X           Description := "To turn on tracing using given filename on the server" ), [0X
    [4X      rec( Name := "SCSCPStopTracing", [0X
    [4X           Description := "To turn off tracing on the server" ) ] )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X5.3-5 GetSignature[0m
  
  [2X> GetSignature( [0X[3Xtransientcd, symbol, server, port[0X[2X ) ________________[0Xfunction
  [6XReturns:[0X  record
  
  Returns   a   record   with   the   signature   of   the   [5XOpenMath[0m   symbol
  [3Xtransientcd[0m[10X.[0m[3Xsymbol[0m from a transient [5XOpenMath[0m content dictionary. This record
  contains  components corresponding to the [5XOpenMath[0m 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 [5XOpenMath[0m 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 [10Xscscp2.symbol_set_all[0m symbol, and use standard [5XOpenMath[0m errors to
  reject  requests  later, like in the example below: using such approach, the
  procedure [10XWS_Factorial[0m is defined to accept not only immediate [10X<OMI>[0m objects
  but anything which could be evaluated to an integer.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> GetSignature("scscp_transient_1","WS_Factorial","localhost",26133);[0X
    [4Xrec( symbol := rec( name := "WS_Factorial", cd := "scscp_transient_1" ),[0X
    [4X     minarg := 1, maxarg := 1,[0X
    [4X     symbolargs := rec( name := "symbol_set_all", cd := "scscp2" ) )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
