% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}
\definecolor{FuncColor}{rgb}{1.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,1.0}

\usepackage{fancyvrb}

\usepackage{pslatex}

\usepackage[pdftex]{graphicx}\usepackage[pdftex=true,
        a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
        pdfcreator={LaTeX with hyperref package / GAPDoc},
        colorlinks=true,backref=page,breaklinks=true,linkcolor=RoyalBlue,
        citecolor=RoyalGreen,filecolor=RoyalRed,
        urlcolor=RoyalRed,pagecolor=RoyalBlue]{hyperref}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages


\newcommand{\GAP}{\textsf{GAP}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{\textsf{SCSCP}\mbox{}}}\\[1cm]
\hypersetup{pdftitle=\textsf{SCSCP}}
\markright{\scriptsize \mbox{}\hfill \textsf{SCSCP} \hfill\mbox{}}
{\Large \textbf{Symbolic Computation Software Composability Protocol\mbox{}}}\\[1cm]
{Version 1.1.4\mbox{}}\\[1cm]
{31 May 2009\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{Alexander Konovalov    \mbox{}}}\\
{\large \textbf{Steve Linton    \mbox{}}}\\
\hypersetup{pdfauthor=Alexander Konovalov    ; Steve Linton    }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Alexander Konovalov    } --- Email: \href{mailto://alexk at mcs dot st-andrews dot ac dot uk} {\texttt{alexk at mcs dot st-andrews dot ac dot uk}}\\
 --- Homepage: \href{http://www.cs.st-andrews.ac.uk/~alexk/} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}alexk/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 School of Computer Science\\
 University of St Andrews\\
 Jack Cole Building, North Haugh,\\
 St Andrews, Fife, KY16 9SX, Scotland \end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{Steve Linton    } --- Email: \href{mailto://sal at cs dot st-andrews dot ac dot uk} {\texttt{sal at cs dot st-andrews dot ac dot uk}}\\
 --- Homepage: \href{http://www.cs.st-andrews.ac.uk/~sal/} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}sal/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 School of Computer Science\\
 University of St Andrews\\
 Jack Cole Building, North Haugh,\\
 St Andrews, Fife, KY16 9SX, Scotland \end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
 \index{SCSCP package@\textsf{SCSCP} package} The \textsf{GAP} package \textsf{SCSCP} implements the Symbolic Computation Software Composability protocol (\href{http://www.symbolic-computation.org/scscp} {\texttt{http://www.symbolic-computation.org/scscp}}) for the computational algebra system \textsf{GAP}. \mbox{}}\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
 {\copyright} 2007-2009 by Alexander Konovalov and Steve Linton

 \textsf{SCSCP} is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later version. For
details, see the FSF's own site \href{http://www.gnu.org/licenses/gpl.html} {\texttt{http://www.gnu.org/licenses/gpl.html}}.

 If you obtained \textsf{SCSCP}, we would be grateful for a short notification sent to one of the authors.

 If you publish a result which was partially obtained with the usage of \textsf{SCSCP}, please cite it in the following form:

 A. Konovalov and S. Linton. \emph{SCSCP --- Symbolic Computation Software Composability Protocol, Version 1.1;} 2009 (\href{http://www.cs.st-andrews.ac.uk/~alexk/scscp.htm} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}alexk/scscp.htm}}). \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
 The project 026133 "SCIEnce - Symbolic Computation Infrastructure for Europe"
(\href{http://www.symbolic-computation.org/} {\texttt{http://www.symbolic-computation.org/}}) is supported by the EU FP6 Programme. \mbox{}}\\[1cm]
{\small 
\section*{Colophon}
\logpage{[ 0, 0, 4 ]}
 Versions history: 
\begin{itemize}
\item Version 0.1 - first half of 2007;
\item Version 0.2 - December 2007;
\item Version 0.3 - May 2008;
\item Version 0.4 - August 2008;
\item Version 1.0 - March 2009;
\item Version 1.1 - May 2009.
\end{itemize}
 \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 5 ]}}

\tableofcontents
\newpage

  
\chapter{\textcolor{Chapter }{Preface}}\label{Preface}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X874E1D45845007FE}{}
{
  The \textsf{GAP} package \textsf{SCSCP} implements the Symbolic Computation Software Composability protocol \cite{SCSCP}. This protocol specifies an \textsf{OpenMath}-based remote procedure call framework, in which all messages (procedure calls
and returns of results of successful computation or error messages) are
encoded in \textsf{OpenMath} using content dictionaries \textsf{scscp1} and \textsf{scscp2} (\cite{scscp1cd}, \cite{scscp2cd}). Using the \textsf{SCSCP} package, \textsf{GAP} can communicate locally or remotely with any other \textsf{OpenMath}-enabled \textsf{SCSCP}-compliant application which may be not only another computer algebra system
but also another instance of the \textsf{GAP} system or even, for example, an external Java or C/C++ application via
libraries \href{http://java.symcomp.org/} {\texttt{http://java.symcomp.org/}} or \href{http://www.imcce.fr/Equipes/ASD/trip/scscp/} {\texttt{http://www.imcce.fr/Equipes/ASD/trip/scscp/}} providing an \textsf{SCSCP} API. Such communication will go into seamless manner for the \textsf{GAP} user, since all conversions from \textsf{GAP} to \textsf{OpenMath} and vice versa will be performed in the background. See the SCIEnce project
homepage \href{http://www.symbolic-computation.org/} {\texttt{http://www.symbolic-computation.org/}} for the details about computer algebra systems and other sotware supporting \textsf{SCSCP} 

 The \textsf{SCSCP} package for \textsf{GAP} has two main components: 
\begin{itemize}
\item SCSCP server;
\item SCSCP client.
\end{itemize}
 There are several ways to start \textsf{GAP} \textsf{SCSCP} server: 
\begin{itemize}
\item call \texttt{RunSCSCPserver} (\ref{RunSCSCPserver}) from the \textsf{GAP} session specifying the server name and the port number from the \textsf{GAP} session; 
\item start \textsf{GAP} as \texttt{gap myserver.g}, where \texttt{myserver.g} is the server configuration file with the last command being the call of \texttt{RunSCSCPserver} (\ref{RunSCSCPserver}) (an example of such configuration file is given in \texttt{scscp/example/myserver.g} ); 
\item start \textsf{GAP} as a daemon using the script \texttt{gapd.sh} which is supplied in the root directory of the package (for the description of
all available options see comments in \texttt{gapd.sh}). 
\end{itemize}
 During startup the server installs all procedures that it will provide and
loads their lookup mechanisms, and then begins to listen to the specified
port. The recommended port number is 26133 which has been assigned to SCSCP by
the Internet Assigned Numbers Authority (IANA) in November 2007, see \href{http://www.iana.org/assignments/port-numbers} {\texttt{http://www.iana.org/assignments/port-numbers}}. 

 When the server accepts a connection from client, it starts the
"accept-evaluate-return" loop: 
\begin{itemize}
\item accepts the \texttt{"procedure{\textunderscore}call";} message;
\item performs lookup of the appropriate GAP function;
\item evaluates the result (or produces a side-effect);
\item returns the result in the \texttt{"procedure{\textunderscore}completed"} message or returns an error in the \texttt{"procedure{\textunderscore}terminated"} message.
\end{itemize}
 The server works in a "multi-user" mode. When one client is connected, the
server is busy for other clients. As soon as the computation is finished and
the client is disconnected, the server is waiting for the next connection, and
normally it never stops until it will be terminated by the service provider.
The server maintain a queue of five incoming connections (this parameter can
be easily modified), and on each iteration evaluates the next request from the
queue. 

 There is an \textsf{SCSCP} server accessible at \texttt{chrystal.mcs.st-andrews.ac.uk}, port 26133. It is running under development versions of the \textsf{GAP} system and a selection of currently distributed packages. The reader is
encouraged to try to use examples from the manual to access this service,
replacing \texttt{"localhost"} by its address, where appropriate. Please report to Alexander Konovalov if you
will discover any bugs or if the server seems not available. 

 The SCSCP client: 
\begin{itemize}
\item establishes connection with the specified server at the specified port;
\item sends the \texttt{"procedure{\textunderscore}call"} message to the server;
\item waits for the result of the computation or returns to pick it up later;
\item fetches the response, extracting the result from the \texttt{"procedure{\textunderscore}completed"} message or entering the break loop in the case of the \texttt{"procedure{\textunderscore}terminated"} message. 
\end{itemize}
 On the top of this functionality we built a set of instructions for simple
parallel computations framework using the \textsf{SCSCP} protocol, which allows to send several procedure calls in parallel and then
collect all results or pick up the first available result, and implements the
master-worker skeleton. These tools are presented in the Chapter \ref{Parallel}. 

 The package also implements a new kind of \textsf{GAP} input-output streams, namely input-output TCP streams (see Chapter \ref{UsingStreams}), based on the functionality for TCP/IP protocol usage provided by the \textsf{GAP} package \textsf{IO}. Such streams may constitute an independent interest for adapting
streams-using \textsf{GAP} code to use streams across the network. 

 Finally, the manual describes how the communication by \textsf{SCSCP} goes between several instances of the \textsf{GAP} system, but the same behaviour is expected from any \textsf{SCSCP}-compliant application: the set of supported \textsf{OpenMath} symbols clearly will be different, but the rules of communication are
precisely specified in the \textsf{SCSCP} specification \cite{SCSCP}. See the homepage of the SCIEnce project \href{http://www.symbolic-computation.org/} {\texttt{http://www.symbolic-computation.org/}} for the information about \textsf{SCSCP}-compliant computer algebra systems and other tools developed in the project. }

  
\chapter{\textcolor{Chapter }{Installation}}\label{Intro}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X8360C04082558A12}{}
{
  
\section{\textcolor{Chapter }{Installation and system requirements}}\label{Install}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7DB566D5785B7DBC}{}
{
  The \textsf{SCSCP} client for \textsf{GAP} is fully functional under \textsf{GAP} 4.4 and works in UNIX/Linux environments, Mac OS X (UNIX installation) and MS
Windows. 

 The \textsf{SCSCP} server for \textsf{GAP} is fully functional with the \textsf{GAP} development version and goes automatically into the compatibility mode to work
with \textsf{GAP} 4.4.12 and earlier versions. The only limitation of this compatibility mode is
that in the case of an error the break loop occurs on the server and can not
be transmitted to the client (however, if the service consumer is the service
provider himself/herself, then this is not as crucial as it might be in the
general case). After the \textsf{GAP} 4.5 release the package will fully be compatible with the official \textsf{GAP} releases. 

 To use the \textsf{SCSCP} package it is necessary to install recent versions of \textsf{GAP}4 packages \textsf{IO} \cite{IO}, \textsf{GAPDoc} \cite{GAPDoc} and \textsf{OpenMath} \cite{openmath}. 

 The \textsf{SCSCP} package is distributed in standard formats (\texttt{tar.gz}, \texttt{tar.bz2}) and can be obtained from \href{http://www.cs.st-andrews.ac.uk/~alexk/scscp.htm} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}alexk/scscp.htm}} or from the \textsf{GAP} web site (the latter also offers \texttt{zoo}- and \texttt{win.zip}-archives. To unpack the \texttt{zoo}-archive the program \texttt{unzoo} is needed, which can be obtained from the \textsf{GAP} homepage \href{http://www.gap-system.org/} {\texttt{http://www.gap-system.org/}} (see section `Distribution'). To install \textsf{SCSCP} package, put its \texttt{zoo}-archive into the \texttt{pkg} subdirectory of your \textsf{GAP}4.4 installation and enter the command \texttt{unzoo -x scscp-X.X.X.zoo}, then the subdirectory \texttt{scscp} (containing subdirectories \texttt{doc}, \texttt{lib} etc.) will be created in the \texttt{pkg} subdirectory. Installation using other archive formats is performed in a
similar way. 

 When there are no access rights to the root directory of the main \textsf{GAP} installation, it is also possible to install the package \emph{outside the \textsf{GAP} main directory} by unpacking it inside a directory \texttt{MYGAPDIR/pkg}. Then to load the package \textsf{GAP} should be started with \texttt{-l ";MYGAPDIR"} option. }

 
\section{\textcolor{Chapter }{Configuration files}}\label{Config}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X878084B083D5217F}{}
{
  There are four files in the package which may need to be modified to setup and
customise the package. The first three files are related with the server's
functionality: 
\begin{itemize}
\item  \texttt{scscp/config.g} specifies: 
\begin{itemize}
\item  default \texttt{InfoLevel} for the \texttt{InfoSCSCP} (\ref{InfoSCSCP}) class; 
\item  default \textsf{SCSCP} server name and port to be used by \texttt{RunSCSCPserver} (\ref{RunSCSCPserver}) if \textsf{GAP} is started with the \texttt{scscp/example/myserver.g} file; 
\item  whether the server accepts calls to procedures which are standard \textsf{OpenMath} symbols, or only procedures installed in the transient content dictionary (see \texttt{InstallSCSCPprocedure} (\ref{InstallSCSCPprocedure})); 
\item  service description to be returned to the client by \texttt{GetServiceDescription} (\ref{GetServiceDescription}). 
\end{itemize}
 
\item  \texttt{scscp/gapd.sh} is the script to start the \textsf{GAP} \textsf{SCSCP} server as a daemon. To use it, adjust the local call of \textsf{GAP} and, if necessary, call options (for example, memory usage, startup from the
workspace etc.) and the location of the root directory of the \textsf{SCSCP} package in section 1 of this script. 
\item  \texttt{scscp/example/myserver.g} is an example of the server configuration file which loads all necessary
packages, reads all needed code, installs all procedures which will be exposed
to the client and finally starts the \textsf{SCSCP} server (see Chapter \ref{Server}). 
\end{itemize}
 The fourth file is related with the client's functionality for parallel
computations: 
\begin{itemize}
\item  The file \texttt{scscp/configpar.g} assigns the global variable \texttt{SCSCPservers} which specifies a list of hosts and ports to search for \textsf{SCSCP} services (which may be not only represented by \textsf{GAP} services, but also by another \textsf{SCSCP}-compliant systems). It will be used to run parallel computations with the \textsf{SCSCP} package (see Chapter \ref{Parallel}). 
\end{itemize}
 See comments in these configuration files for further details and examples. }

 }

  
\chapter{\textcolor{Chapter }{Using streams}}\label{UsingStreams}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X7CB06121820FD0DD}{}
{
  The package implements new kind of \textsf{GAP} input-output streams, called input-output TCP streams. Such streams are based
on the functionality for the TCP/IP protocol usage provided by the \textsf{GAP} package \textsf{IO}, and may constitute an independent interest for \textsf{GAP} users. 

 Input-output TCP streams are intended to support all operations, implemented
for streams in \textsf{GAP}. It is assumed that all existing code using streams should work with this
kind of streams as well (please let us know, if you will notice that this is
not the case!). We installed methods for input-output TCP streams to support
the following operations: \texttt{ViewObj}, \texttt{PrintObj}, \texttt{ReadByte}, \texttt{ReadLine}, \texttt{ReadAll}, \texttt{WriteByte}, \texttt{WriteLine}, \texttt{WriteAll}, \texttt{IsEndOfStream}, \texttt{CloseStream}, \texttt{FileDescriptorOfStream}, \texttt{UNIXSelect}. 

 
\section{\textcolor{Chapter }{Input-output TCP streams}}\label{Streams}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X79EB93A27D9AC115}{}
{
  

\subsection{\textcolor{Chapter }{IsInputOutputTCPStream}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X805BB9468642A787}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsInputOutputTCPStream\index{IsInputOutputTCPStream@\texttt{IsInputOutputTCPStream}}
\label{IsInputOutputTCPStream}
}\hfill{\scriptsize (filter)}}\\


 \texttt{IsInputOutputTCPStream} is a subcategory of \texttt{IsInputOutputStream}. Streams in the category \texttt{IsInputOutputTCPStream} are created with the help of the function \texttt{InputOutputTCPStream} (\ref{InputOutputTCPStream:for client}) with one or two arguments dependently on whether they will be used in the
client or server mode. Examples of their creation and usage will be given in
subsequent sections. }

 

\subsection{\textcolor{Chapter }{IsInputOutputTCPStreamRep}}
\logpage{[ 3, 1, 2 ]}\nobreak
\hyperdef{L}{X817A945B83659813}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsInputOutputTCPStreamRep\index{IsInputOutputTCPStreamRep@\texttt{IsInputOutputTCPStreamRep}}
\label{IsInputOutputTCPStreamRep}
}\hfill{\scriptsize (filter)}}\\


 This is the representation that is used for streams in the category \texttt{IsInputOutputTCPStream}. }

 

\subsection{\textcolor{Chapter }{InputOutputTCPStream (for server)}}
\logpage{[ 3, 1, 3 ]}\nobreak
\hyperdef{L}{X7E3D43CF7B049F04}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InputOutputTCPStream({\slshape socket{\textunderscore}descriptor})\index{InputOutputTCPStream@\texttt{InputOutputTCPStream}!for server}
\label{InputOutputTCPStream:for server}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 stream 



 Returns a stream in the category \texttt{IsInputOutputTCPStream} for the given socket descriptor that will be used to accept incoming
connections. An example demonstrating this will be given after the next
section. 

 However, the service provider much likely will create such stream
automatically inside the function \texttt{RunSCSCPserver} (\ref{RunSCSCPserver}) rather then manually. }

 

\subsection{\textcolor{Chapter }{InputOutputTCPStream (for client)}}
\logpage{[ 3, 1, 4 ]}\nobreak
\hyperdef{L}{X87EFDED57DB7CF77}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InputOutputTCPStream({\slshape hostname, port})\index{InputOutputTCPStream@\texttt{InputOutputTCPStream}!for client}
\label{InputOutputTCPStream:for client}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 stream 



 Returns a stream in the category \texttt{IsInputOutputTCPStream} that will be used by the client for communication with the specified server
and port. }

 }

 
\section{\textcolor{Chapter }{Example of client-server communication via input-output TCP streams}}\label{StreamsExample}
\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X86CA5D6C79B32600}{}
{
  The following example demonstrates an interaction between client and server
using input-output TCP stream, and shows how such streams are created in the
function \texttt{RunSCSCPserver} (\ref{RunSCSCPserver}). It uses some functions from the \textsf{IO} package, see the \textsf{IO} manual for their description. Now we will show step by step what is happens on
server and client (of course, if you will try this example, the numbers
denoting descriptors may be different). 

 Firts, we will start two \textsf{GAP} sessions, one for the server, another one for the client. Now we enter the
following commands on the server's side: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> sock := IO_socket( IO.PF_INET, IO.SOCK_STREAM, "tcp" );
  3
  gap> lookup := IO_gethostbyname( "localhost" );
  rec( name := "localhost", aliases := [  ], addrtype := 2, length := 4, 
    addr := [ "\177\000\000\>" ] )
  gap> port:=26133;
  26133
  gap> res := IO_bind( sock, IO_make_sockaddr_in( lookup.addr[1], port ) );
  true
  gap> IO_listen( sock, 5 );
  true
  gap> socket_descriptor := IO_accept( sock, IO_MakeIPAddressPort("0.0.0.0",0) );
  
\end{Verbatim}
 After the last command you will not see the \textsf{GAP} prompt because the server starts to wait for an incoming connection. Now we go
to the client's side and create an input-output TCP stream to the server. Here
it can be created in one step: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> clientstream:=InputOutputTCPStream( "localhost", 26133 );
  Creating a socket...
  Connecting to a remote socket via TCP/IP...
  
\end{Verbatim}
 Now we are trying to connect to the server, and as soon as the connection will
be established, the stream will be created at the client side, and we will see
the output and the new \textsf{GAP} prompt: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  < input/output TCP stream to localhost >
  gap>
  
\end{Verbatim}
 On the server you will get the socket descriptor and then you will be able to
create a stream from it: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  4
  gap> serverstream := InputOutputTCPStream( socket_descriptor );
  < input/output TCP stream to socket >
  
\end{Verbatim}
 Now we can write to this stream on the client side and then read from it on
the server side and backwards. First, write on the client: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> WriteLine( clientstream, "12345" );
  true
  
\end{Verbatim}
 Now read and write on the server: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ReadLine( serverstream );
  "12345\n"
  gap> WriteLine( serverstream, "54321" );
  true
  
\end{Verbatim}
 And finally we read on the client and close the stream: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ReadLine( clientstream );
  "54321\n"
  gap> CloseStream( clientstream );
  
\end{Verbatim}
 and similarly close the stream on the server: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> CloseStream( serverstream );
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Message exchange by \textsf{SCSCP}}}\label{SCSCPmessages}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7E9C5A238661FE15}{}
{
  To ensure the message exchange as required by \textsf{SCSCP} specification, the \textsf{SCSCP} package extends the global record \texttt{OMsymRecord} from the \textsf{OpenMath} package with new entries to support \textsf{scscp1} and \textsf{scscp2} content dictionaries (\cite{scscp1cd}, \cite{scscp2cd}), and also service-dependent transient private content dictionaries (see \ref{Server} for details about transient content dictionaries). It also overwrites some \textsf{OpenMath} functions by their extended (but backwards compatible) versions, and adds some
new \textsf{OpenMath}-related functions to send and receive \textsf{SCSCP} messages, documented below. 

 Note that functions documented in this chapter belong to the middle-level
interface, and the user may find it more convenient to use functions developed
on top of them and explained in next chapters. 
\section{\textcolor{Chapter }{Communication with the \textsf{SCSCP} server}}\label{SCSCPclient}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X7A1EC5EC813292B3}{}
{
  

\subsection{\textcolor{Chapter }{StartSCSCPsession}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X86D913277AFF2366}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StartSCSCPsession({\slshape stream})\index{StartSCSCPsession@\texttt{StartSCSCPsession}}
\label{StartSCSCPsession}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 string 



 Initialises \textsf{SCSCP} session and negotiates with the server about the version of the protocol.
Returns the string with the \texttt{service{\textunderscore}id} (which may be used later as a part of the call identifier) or causes an error
message if can not perform these tasks. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> s := InputOutputTCPStream("localhost",26133);
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  < input/output TCP stream to localhost:26133 >
  gap> StartSCSCPsession(s);
  #I  Got connection initiation message
  #I  <?scscp service_name="GAP" service_version="4.dev" service_id="localhost:2\
  6133:5541" scscp_versions="1.0 1.1 1.2 1.3" ?>
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  "localhost:26133:5541"
  
\end{Verbatim}
 After the call to \texttt{StartSCSCPsession} the \textsf{SCSCP} server is ready to accept procedure calls. }

 

\subsection{\textcolor{Chapter }{OMPutProcedureCall}}
\logpage{[ 4, 1, 2 ]}\nobreak
\hyperdef{L}{X81EC8AAA78F62CB7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OMPutProcedureCall({\slshape stream, proc{\textunderscore}name, objrec})\index{OMPutProcedureCall@\texttt{OMPutProcedureCall}}
\label{OMPutProcedureCall}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 Nothing 



  Takes a stream \mbox{\texttt{\slshape stream}}, the string \mbox{\texttt{\slshape proc{\textunderscore}name}} and a record \mbox{\texttt{\slshape objrec}}, and writes to \mbox{\texttt{\slshape stream}} an \textsf{OpenMath} object \texttt{procedure{\textunderscore}call} for the procedure \mbox{\texttt{\slshape proc{\textunderscore}name}} with arguments given by the list \texttt{objrec.object} and procedure call options (which should be encoded as \textsf{OpenMath} attributes) given in the list \texttt{objrec.attributes}. This function accepts the option \texttt{cd:="cdname"} to specify the name of the content dictionary if the procedure is actually a
standard \textsf{OpenMath} symbol note that the server may reject such a call if it accepts only calls of
procedures from the transient content dictionary, see \texttt{InstallSCSCPprocedure} (\ref{InstallSCSCPprocedure}) for explanation). If the \texttt{cdname} is not specified, \texttt{scscp{\textunderscore}transient{\textunderscore}1} content dictionary will be assumed by default. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> t:="";; stream:=OutputTextString(t,true);;
  gap> OMPutProcedureCall( stream, "WS_Factorial", rec( object:= [ 5 ], 
  >      attributes:=[ [ "call_id", "user007" ], 
  >                    ["option_runtime",1000],
  >                    ["option_min_memory",1024], 
  >                    ["option_max_memory",2048],
  >                    ["option_debuglevel",1], 
  >                    ["option_return_object"] ] ) );;
  gap> Print(t);
  <?scscp start ?>
  <OMOBJ>
  	<OMATTR>
  		<OMATP>
  			<OMS cd="scscp1" name="call_id"/>
  			<OMSTR>user007</OMSTR>
  			<OMS cd="scscp1" name="option_runtime"/>
  			<OMI>1000</OMI>
  			<OMS cd="scscp1" name="option_min_memory"/>
  			<OMI>1024</OMI>
  			<OMS cd="scscp1" name="option_max_memory"/>
  			<OMI>2048</OMI>
  			<OMS cd="scscp1" name="option_debuglevel"/>
  			<OMI>1</OMI>
  			<OMS cd="scscp1" name="option_return_object"/>
  			<OMSTR></OMSTR>
  		</OMATP>
  		<OMA>
  			<OMS cd="scscp1" name="procedure_call"/>
  			<OMA>
  				<OMS cd="scscp_transient_1" name="WS_Factorial"/>
  				<OMI> 5</OMI>
  			</OMA>
  		</OMA>
  	</OMATTR>
  </OMOBJ>
  <?scscp end ?>
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SCSCPwait}}
\logpage{[ 4, 1, 3 ]}\nobreak
\hyperdef{L}{X7ABD2EA6792279CF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSCPwait({\slshape stream[, timeout]})\index{SCSCPwait@\texttt{SCSCPwait}}
\label{SCSCPwait}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 This function may be used by the \textsf{SCSCP} client to wait (using \texttt{IO{\textunderscore}select} (\textbf{IO: IO{\textunderscore}select})) until the result of the procedure call will be available from \mbox{\texttt{\slshape stream}}. By default the timeout is one hour, to specify another value give it as the
optional second argument in seconds. See the end of this chapter for the
example. }

 

\subsection{\textcolor{Chapter }{OMGetObjectWithAttributes}}
\logpage{[ 4, 1, 4 ]}\nobreak
\hyperdef{L}{X7E0FE0CF7DD2E00F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OMGetObjectWithAttributes({\slshape stream})\index{OMGetObjectWithAttributes@\texttt{OMGetObjectWithAttributes}}
\label{OMGetObjectWithAttributes}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 record with components \texttt{object} and \texttt{attributes}, or \texttt{fail} 



  This function is similar to the function \texttt{OMGetObject} from the \textsf{OpenMath} package, and the main difference is that it is able to understand \textsf{OpenMath} attribution pairs. It retrieves exactly one \textsf{OpenMath} object from the stream \mbox{\texttt{\slshape stream}}, and stores it in the \texttt{object} component of the returned record. If the \textsf{OpenMath} object has no attributes, the \texttt{attributes} component of the returned record will be an empty list, otherwise it will
contain pairs \texttt{[attribute{\textunderscore}name,attribute{\textunderscore}value]}, where \texttt{attribute{\textunderscore}name} is a string, and \texttt{attribute{\textunderscore}value} is a \textsf{GAP} object, whose type is determined by the kind of an attribute. Only attributes,
defined by the SCSCP are allowed, otherwise an error message will be
displayed. 

 If the procedure was not successful, the function returns \texttt{fail} instead of an error message like the function \texttt{OMGetObject} (\textbf{OpenMath: OMGetObject}) does. Returning \texttt{fail} is useful when \texttt{OMGetObjectWithAttributes} is used inside accept-evaluate-return loop. }

 As an example, the file \texttt{scscp/tst/omdemo.om} contains some \textsf{OpenMath} objects, including those from the SCSCP Specification \cite{SCSCP}. We can retrieve them from this file, preliminary installing some SCSCP
procedures using the function \texttt{InstallSCSCPprocedure} (\ref{InstallSCSCPprocedure}): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> InstallSCSCPprocedure("WS_Factorial", Factorial );
  gap> InstallSCSCPprocedure("GroupIdentificationService", IdGroup );
  gap> InstallSCSCPprocedure("GroupByIdNumber", SmallGroup );
  gap> test:=Filename( Directory( Concatenation(
  >         GAPInfo.PackagesInfo.("scscp")[1].InstallationPath,"/tst/" ) ), 
  >         "omdemo.om" );;
  gap> stream:=InputTextFile(test);;
  gap> OMGetObjectWithAttributes(stream);     
  rec( object := 1, attributes := [  ] )
  gap> OMGetObjectWithAttributes(stream);
  rec( object := "Primes@localhost:26133", 
    attributes := [ [ "call_id", "call_identifier" ] ] )
  gap> OMGetObjectWithAttributes(stream);
  rec( object := 120, attributes := [  ] )
  gap> OMGetObjectWithAttributes(stream);
  rec( object := [ 24, 12 ], 
    attributes := [ [ "call_id", "alexk_9053" ], [ "option_runtime", 300000 ], 
        [ "option_min_memory", 40964 ], [ "option_max_memory", 134217728 ], 
        [ "option_debuglevel", 2 ], [ "option_return_object", "" ] ] )
  gap> CloseStream( str );
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Communication with the \textsf{SCSCP} client}}\label{SCSCPserver}
\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X83CC58F67F1A15F1}{}
{
  

\subsection{\textcolor{Chapter }{OMPutProcedureCompleted}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X7C5C23A47A86EAEC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OMPutProcedureCompleted({\slshape stream, objrec})\index{OMPutProcedureCompleted@\texttt{OMPutProcedureCompleted}}
\label{OMPutProcedureCompleted}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 Takes a stream \mbox{\texttt{\slshape stream}}, and a record \mbox{\texttt{\slshape objrec}}, and writes to \mbox{\texttt{\slshape stream}} an \textsf{OpenMath} object \texttt{procedure{\textunderscore}completed} with the result being \texttt{objrec.object} and information messages (as \textsf{OpenMath} attributes) given in the list \texttt{objrec.attributes}. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> t:="";; stream:=OutputTextString(t,true);;
  gap> OMPutProcedureCompleted( stream, 
  >      rec(object:=120, 
  >      attributes:=[ [ "call_id", "user007" ] ] ));
  gap> Print(t);
  <?scscp start ?>
  <OMOBJ>
  	<OMATTR>
  		<OMATP>
  			<OMS cd="scscp1" name="call_id"/>
  			<OMSTR>user007</OMSTR>
  		</OMATP>
  		<OMA>
  			<OMS cd="scscp1" name="procedure_completed"/>
  			<OMI> 120</OMI>
  		</OMA>
  	</OMATTR>
  </OMOBJ>
  <?scscp end ?>
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{OMPutProcedureTerminated}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X7FB47E3E86C7C9F9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OMPutProcedureTerminated({\slshape stream, objrec, error{\textunderscore}cd, error{\textunderscore}type})\index{OMPutProcedureTerminated@\texttt{OMPutProcedureTerminated}}
\label{OMPutProcedureTerminated}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 Takes a stream \mbox{\texttt{\slshape stream}}, and a record with an error message \mbox{\texttt{\slshape objrec}} (for example \texttt{rec( attributes := [ [ "call{\textunderscore}id",
"localhost:26133:87643:gcX33cCf" ] ],} \texttt{object := "localhost:26133 reports : Rational operations:
{\textless}divisor{\textgreater} must not be zero")} and writes to the \mbox{\texttt{\slshape stream}} an \textsf{OpenMath} object \texttt{procedure{\textunderscore}terminated} containing an error determined by the symbol \mbox{\texttt{\slshape error{\textunderscore}type}} from the content dictionary \mbox{\texttt{\slshape error{\textunderscore}cd}} (for example, \texttt{error{\textunderscore}memory}, \texttt{error{\textunderscore}runtime} or \texttt{error{\textunderscore}system{\textunderscore}specific} from the \textsf{scscp1} content dictionary (\cite{scscp1cd}). 

 This is the internal function of the package which is used only in the code
for the \textsf{SCSCP} server to return the error message to the client. }

 }

 
\section{\textcolor{Chapter }{Example: \textsf{SCSCP} session}}\label{SCSCPsession}
\logpage{[ 4, 3, 0 ]}
\hyperdef{L}{X791818FB7F5F6801}{}
{
  In the following example we start an \textsf{SCSCP} session and perform ten procedure calls in a loop before closing that session.
Note that we demonstrate the usage of the session ID \texttt{sid} and the function \texttt{RandomString} from the \textsf{OpenMath} package to produce some unique call identifier. The call ID is a mandatory
attribute for any procedure call, however, it is not nesessarily random; for
example, it may be just a string with the number of the procedure call. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> stream:=InputOutputTCPStream( "localhost", 26133 );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  < input/output TCP stream to localhost:26133 >
  gap> sid := StartSCSCPsession( stream );
  #I  Got connection initiation message
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  "localhost:26133:5541"
  gap> res:=[];
  [  ]
  gap> for i in [1..10] do
  >     OMPutProcedureCall( stream, "WS_Factorial", 
  >       rec( object := [ i ], 
  >        attributes := [ [ "call_id", 
  >          Concatenation( sid, ":", RandomString(8) ) ] ] ) );
  >     SCSCPwait( stream );
  >     res[i]:=OMGetObjectWithAttributes( stream ).object;
  > od;
  gap> CloseStream(stream);
  gap> res;
  [ 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800 ]
  
\end{Verbatim}
 Also note the usage of \texttt{SCSCPwait} (\ref{SCSCPwait}) to wait until the result of the computation will be available from \texttt{stream}. }

 }

  
\chapter{\textcolor{Chapter }{Running SCSCP server}}\label{Server}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X7DEE95317812A998}{}
{
  
\section{\textcolor{Chapter }{Installation of \textsf{SCSCP} procedures}}\label{InstallProcedures}
\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X84D937F07DC015BE}{}
{
  There may various ways to run \textsf{SCSCP} server, for example: 
\begin{itemize}
\item  allowing generic services like evaluation of arbitrary \textsf{OpenMath} code; 
\item  offering highly specialized procedures like identification of groups of order
512; 
\item  providing access to a database of mathematical objects. 
\end{itemize}
 Each of these use cases requires certain control over the level of
functionality exposed to the client. To achieve this, before starting \textsf{SCSCP} service its provider must call the function \texttt{InstallSCSCPprocedure} (\ref{InstallSCSCPprocedure}) 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 \textsf{SCSCP} server with the function \texttt{RunSCSCPserver} (\ref{RunSCSCPserver}). 

\subsection{\textcolor{Chapter }{InstallSCSCPprocedure}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X8031C2F4787E0C1A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InstallSCSCPprocedure({\slshape procname, procfunc[, description][, narg1[, narg2][, signature]]})\index{InstallSCSCPprocedure@\texttt{InstallSCSCPprocedure}}
\label{InstallSCSCPprocedure}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 Nothing 



 For a string \mbox{\texttt{\slshape procname}} and a function \mbox{\texttt{\slshape procfunc}}, \texttt{InstallSCSCPprocedure} makes the \mbox{\texttt{\slshape procfunc}} available as SCSCP procedure under the name \mbox{\texttt{\slshape procname}}, adding it to the transient \textsf{OpenMath} content dictionary \texttt{scscp{\textunderscore}transient{\textunderscore}1} that will exist during the service lifetime. 

 The second argument \mbox{\texttt{\slshape procfunc}} may be either a standard or user-defined \textsf{GAP} function (procedure, operation, etc.). 

 The rest of arguments are optional and may be used in a number of
combinations: 
\begin{itemize}
\item  \mbox{\texttt{\slshape 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. 
\item  \mbox{\texttt{\slshape narg1}} is a non-negative integer, specifying the minimal number of arguments, and \mbox{\texttt{\slshape narg2}} is a non-negative integer or infinity, specifying the maximal number of
arguments. If \mbox{\texttt{\slshape narg2}} is omitted then the maximal number of arguments will be set to \mbox{\texttt{\slshape narg1}}. If both \mbox{\texttt{\slshape narg1}} and \mbox{\texttt{\slshape narg2}} are omitted then the minimal number of arguments will be set to zero and their
maximal number will be set to infinity. 
\item  \mbox{\texttt{\slshape signature}} is the signature record of the procedure. If the \mbox{\texttt{\slshape signature}} is given, then the number of arguments must be explicitly specified (by \mbox{\texttt{\slshape narg1}} with or without \mbox{\texttt{\slshape 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 \texttt{scscp2.symbol{\textunderscore}set{\textunderscore}all} symbol, and to use standard \textsf{OpenMath} errors to reject requests later at the stage of their evaluation. For example,
using such approach, we will define the procedure \texttt{WS{\textunderscore}Factorial} accepting not only immediate \texttt{{\textless}OMI{\textgreater}} 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 \texttt{rec( )} corresponding to the \texttt{scscp2.symbol{\textunderscore}set{\textunderscore}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 \texttt{CDgroups}, \texttt{CDs} and \texttt{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: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  signature := rec( CDgroups := [ "scscp" ],
                    CDs := [ "arith1", "linalg1" ],
                    Symbols := rec( polyd1 := [ "DMP", "term", "SDMP" ],
                                     polyu := [ "poly_u_rep", "term" ] ) );
  
\end{Verbatim}
 
\end{itemize}
 }

 In the following example we define the function \texttt{WS{\textunderscore}Factorial} that takes an integers and returns its factorial, using only mandatory
arguments of \texttt{InstallSCSCPprocedure} (\ref{InstallSCSCPprocedure}): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> InstallSCSCPprocedure( "WS_Factorial", Factorial );
  InstallSCSCPprocedure : procedure WS_Factorial installed. 
  
\end{Verbatim}
 In the following example we install the procedure that will accept a list of
permutations and return the number in the \textsf{GAP} Small Groups library of the group they generate (for the sake of simplicity we
omit tests of validity of arguments, availability of \texttt{IdGroup} for groups of given order etc.) 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IdGroupByGenerators:=function( permlist )
  > return IdGroup( Group( permlist ) );
  > end;
  function( permlist ) ... end
  gap> InstallSCSCPprocedure( "GroupIdentificationService", IdGroupByGenerators );
  InstallSCSCPprocedure : procedure GroupIdentificationService installed. 
  
\end{Verbatim}
 After installation, the procedure may be reinstalled, if necessary: 
\begin{Verbatim}[fontsize=\small,frame=single,label=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. 
  
\end{Verbatim}
 Finally, some examples of various combinations of optional arguments: 
\begin{Verbatim}[fontsize=\small,frame=single,label=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" );
  
\end{Verbatim}
 Note that it is quite acceptable to overstate the signature of the procedure
and use only mandatory arguments in a call to \texttt{InstallSCSCPprocedure} (\ref{InstallSCSCPprocedure}), which will be installed then as a procedure that can accept arbitrary number
of arguments encoded without any restrictions on \textsf{OpenMath} symbols used, because anyway the \textsf{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 \ref{SpecialProcedures} about utilities for obtaining such information about the \textsf{SCSCP} service. Some more examples of installation of SCSCP procedures are given in
the file \texttt{scscp/example/myserver.g}. 

\subsection{\textcolor{Chapter }{OMsymRecord}}
\logpage{[ 5, 1, 2 ]}\nobreak
\hyperdef{L}{X7E03B69B7C1BF974}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OMsymRecord\index{OMsymRecord@\texttt{OMsymRecord}}
\label{OMsymRecord}
}\hfill{\scriptsize (global variable)}}\\


 This is the global record from the \textsf{OpenMath} package used for the conversion from \textsf{OpenMath} to \textsf{GAP}. It is extended in the \textsf{SCSCP} package by adding support for symbols from \texttt{scscp1} and \texttt{scscp2} content dictionaries (\cite{scscp1cd}, \cite{scscp2cd}). Additionally, \texttt{InstallSCSCPprocedure} (\ref{InstallSCSCPprocedure}) adds to this record a component corresponding to the appropriate transient
content dictionary (by default, \texttt{scscp{\textunderscore}transient{\textunderscore}1}) defining mappings between \textsf{OpenMath} symbols from this content dictionary and installed \textsf{SCSCP} procedures. }

 }

 
\section{\textcolor{Chapter }{Starting SCSCP server}}\label{RunServer}
\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X865409A27C7BBD7B}{}
{
  

\subsection{\textcolor{Chapter }{RunSCSCPserver}}
\logpage{[ 5, 2, 1 ]}\nobreak
\hyperdef{L}{X831C84577884215E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RunSCSCPserver({\slshape servertype, port})\index{RunSCSCPserver@\texttt{RunSCSCPserver}}
\label{RunSCSCPserver}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 Will start the \textsf{SCSCP} server at port given by the integer \mbox{\texttt{\slshape port}}. The first parameter \mbox{\texttt{\slshape servertype}} is either \texttt{true}, \texttt{false} or a string containing the server hostname: 
\begin{itemize}
\item  when \mbox{\texttt{\slshape servertype}} is \texttt{true}, the server will be started in a ``universal'' mode and will accept all incoming connections; 
\item  when \mbox{\texttt{\slshape servertype}} is \texttt{false}, the server will be started at \texttt{localhost} and will not accept any incoming connections from outside; 
\item  when \mbox{\texttt{\slshape servertype}} is a string, for example, \texttt{"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). 
\end{itemize}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> RunSCSCPserver( "localhost", 26133 );
  Ready to accept TCP/IP connections at localhost:26133 ...
  Waiting for new client connection at localhost:26133 ...
  
\end{Verbatim}
 Actually, there are several ways to start \textsf{GAP} \textsf{SCSCP} server: 
\begin{itemize}
\item from the \textsf{GAP} session as shown in the example above; 
\item starting \textsf{GAP} as \texttt{gap myserver.g}, where \texttt{myserver.g} is the server configuration file with the last command being the call \texttt{RunSCSCPserver}, which may take its arguments from the configuration file \texttt{scscp/config.g} (an example of such configuration file is given in \texttt{scscp/example/myserver.g} ); 
\item start \textsf{GAP} as a daemon using the script \texttt{gapd.sh} which is supplied in the root directory of the package (for the description of
all available options see comments in \texttt{gapd.sh}) and may overwrite parameters from \texttt{scscp/config.g}. 
\end{itemize}
 See Section \ref{Config} about configuring files \texttt{config.g} and \texttt{gapd.sh}. }

 }

 
\section{\textcolor{Chapter }{Procedures to get information about the \textsf{SCSCP} server}}\label{SpecialProcedures}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X789962C579109D8F}{}
{
  

\subsection{\textcolor{Chapter }{GetServiceDescription}}
\logpage{[ 5, 3, 1 ]}\nobreak
\hyperdef{L}{X7CBF8B63852898CF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GetServiceDescription({\slshape server, port})\index{GetServiceDescription@\texttt{GetServiceDescription}}
\label{GetServiceDescription}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent 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 \texttt{scscp/config.g} (for details about configuration files, see \ref{Config}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> GetServiceDescription( "localhost", 26133 );
  rec( service_name := "GAP SCSCP service", 
    version := "GAP 4.4.12 + SCSCP 1.1 started on Tue 21 Apr 2009 00:35:38 BST", 
    description := "Started with scscp/example/myserver.g from SCSCP 1.1" )
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GetAllowedHeads}}
\logpage{[ 5, 3, 2 ]}\nobreak
\hyperdef{L}{X7F387F3681775177}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GetAllowedHeads({\slshape server, port})\index{GetAllowedHeads@\texttt{GetAllowedHeads}}
\label{GetAllowedHeads}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 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 \texttt{{\textless}OMA{\textgreater}}) in an \textsf{SCSCP} procedure call to the \textsf{SCSCP} server running at \mbox{\texttt{\slshape server}}\texttt{:}\mbox{\texttt{\slshape port}}. 

 Note that it is acceptable (although not quite desirable) for a server to ``overstate'' the set of symbols it accepts and use standard \textsf{OpenMath} errors to reject requests later. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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" ] )
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsAllowedHead}}
\logpage{[ 5, 3, 3 ]}\nobreak
\hyperdef{L}{X820055F180BE57A6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsAllowedHead({\slshape cd, symbol, server, port})\index{IsAllowedHead@\texttt{IsAllowedHead}}
\label{IsAllowedHead}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Checks whether the \textsf{OpenMath} symbol \mbox{\texttt{\slshape cd}}\texttt{.}\mbox{\texttt{\slshape symbol}}, which may be a symbol from a standard or transient \textsf{OpenMath} content dictionary, is allowed to appear as ``head'' symbol (i.e. the first child of the outermost \texttt{{\textless}OMA{\textgreater}} in an \textsf{SCSCP} procedure call to the \textsf{SCSCP} server running at \mbox{\texttt{\slshape server}}\texttt{:}\mbox{\texttt{\slshape 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 \textsf{OpenMath} errors to reject requests later. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IsAllowedHead( "permgp1", "group", "localhost", 26133 );                            
  true
  gap> IsAllowedHead( "nums1", "pi", "localhost", 26133 );          
  false
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GetTransientCD}}
\logpage{[ 5, 3, 4 ]}\nobreak
\hyperdef{L}{X851F521B790512EB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GetTransientCD({\slshape transient{\textunderscore}cd, server, port})\index{GetTransientCD@\texttt{GetTransientCD}}
\label{GetTransientCD}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 record 



 Returns a record with the transient content dictionary \mbox{\texttt{\slshape transient{\textunderscore}cd}} from the \textsf{SCSCP} server running at \mbox{\texttt{\slshape server}}\texttt{:}\mbox{\texttt{\slshape port}}. Names of components of this record correspond to symbols from the \texttt{meta} content dictionary. 

 By default, the name of the transient content dictionary for the \textsf{GAP} \textsf{SCSCP} server is \texttt{scscp{\textunderscore}transient{\textunderscore}1}. Other systems may use transient content dictionaries with another names,
which, however, must always begin with \texttt{scscp{\textunderscore}transient{\textunderscore}} and may be guessed from the output of \texttt{GetAllowedHeads} (\ref{GetAllowedHeads}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> GetTransientCD( "scscp_transient_1", "localhost", 26133 );
  rec( 
    Description := "This is a transient CD for the GAP SCSCP service", 
    CDName := "scscp_transient_1", 
    CDReviewDate := "2009-04-21", 
    CDDate := "2009-04-21", 
    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" ) ] )
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GetSignature}}
\logpage{[ 5, 3, 5 ]}\nobreak
\hyperdef{L}{X79B0927285DC69D5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GetSignature({\slshape transientcd, symbol, server, port})\index{GetSignature@\texttt{GetSignature}}
\label{GetSignature}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 record 



 Returns a record with the signature of the \textsf{OpenMath} symbol \mbox{\texttt{\slshape transientcd}}\texttt{.}\mbox{\texttt{\slshape symbol}} from a transient \textsf{OpenMath} content dictionary. This record contains components corresponding to the \textsf{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 \textsf{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 \texttt{scscp2.symbol{\textunderscore}set{\textunderscore}all} symbol, and use standard \textsf{OpenMath} errors to reject requests later, like in the example below: using such
approach, the procedure \texttt{WS{\textunderscore}Factorial} is defined to accept not only immediate \texttt{{\textless}OMI{\textgreater}} objects but anything which could be evaluated to an integer. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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" ) )
  
\end{Verbatim}
 }

 }

 }

  
\chapter{\textcolor{Chapter }{Client's functionality}}\label{ClientFunctionality}
\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X7ED9B9A97F3011B5}{}
{
  Sending and getting requests to the \textsf{SCSCP} server(s), the client operates with processes. Process is an abstraction which
encapsulates an \texttt{InputOutputTCPStream} (see \texttt{IsInputOutputTCPStream} (\ref{IsInputOutputTCPStream})) from a client to the server and the process ID of the CAS running as a
server (deduced from the connection initiation message; may be unassigned, if
the server CAS did not communicate it). 
\section{\textcolor{Chapter }{Sending request and getting result}}\label{Client}
\logpage{[ 6, 1, 0 ]}
\hyperdef{L}{X7AF80F7D7C9D3C61}{}
{
  

\subsection{\textcolor{Chapter }{IsProcess}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X8036EDF37C8C6DD9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsProcess\index{IsProcess@\texttt{IsProcess}}
\label{IsProcess}
}\hfill{\scriptsize (filter)}}\\


 This is the category of processes. Processes in this category are created
using the function \texttt{NewProcess} (\ref{NewProcess}). }

 

\subsection{\textcolor{Chapter }{NewProcess}}
\logpage{[ 6, 1, 2 ]}\nobreak
\hyperdef{L}{X8712E82B811A4170}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NewProcess({\slshape command, listargs, server, port})\index{NewProcess@\texttt{NewProcess}}
\label{NewProcess}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 object in the category \texttt{IsProcess} 



 \mbox{\texttt{\slshape command}} and \texttt{server} are strings, \mbox{\texttt{\slshape listargs}} is a list of \textsf{GAP} objects and \texttt{port} is an integer. Calls the \textsf{SCSCP} procedure with the name \mbox{\texttt{\slshape command}} and the list of arguments \mbox{\texttt{\slshape listargs}} at the server and port given by \texttt{server} and \texttt{port}. Returns an object in the category \texttt{IsProcess} for the subsequent waiting the result from its underlying stream. 

 It accepts the following options: 
\begin{itemize}
\item  \texttt{output:="object"} is used to specify that the server must return the actual object evaluated as
a result of the procedure call. This is the default action requested by the
client if the \texttt{output} option is omitted. 
\item  \texttt{output:="cookie"} is used to specify that the result of the procedure call should be stored on
the server, and the server should return a remote object (see \ref{Remote} ) pointing to that result (that is, a cookie); 
\item  \texttt{output:="nothing"} is used to specify that the server is supposed to reply with a \texttt{procedure{\textunderscore}completed} message carrying no object just to signal that the call was completed
successfully (for the compatibility, this will be evaluated to a \texttt{"procedure completed"} string on the client's side); 
\item  \texttt{cd:="cdname"} is used to specify that the \textsf{OpenMath} symbol corresponding to the first argument \mbox{\texttt{\slshape command}} should be looked up in the particular content dictionary \texttt{cdname}. Otherwise, it will be looked for in the default content dictionary (\texttt{scscp{\textunderscore}transient{\textunderscore}1} for the \textsf{GAP} \textsf{SCSCP} server); 
\item  \texttt{debuglevel:=N} is used to obtain additional information attributes together with the result.
The \textsf{GAP} \textsf{SCSCP} server does the following: if \texttt{N=1}, it will report about the CPU time in milliseconds required to compute the
result; if \texttt{N=2} it will additionally report about the amount of memory used by \textsf{GAP} in bytes will be returned (using the output of \texttt{MemoryUsageByGAPinKbytes} (\ref{MemoryUsageByGAPinKbytes}) converted to bytes); if \texttt{N=3} it will additionally report the amount of memory in bytes used by the
resulting object and its subobjects (using the output of \texttt{MemoryUsage} (\textbf{Reference: MemoryUsage})). 
\end{itemize}
 See \texttt{CompleteProcess} (\ref{CompleteProcess}) and \texttt{EvaluateBySCSCP} (\ref{EvaluateBySCSCP}) for examples. }

 

\subsection{\textcolor{Chapter }{CompleteProcess}}
\logpage{[ 6, 1, 3 ]}\nobreak
\hyperdef{L}{X796557D67A4CA868}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CompleteProcess({\slshape process})\index{CompleteProcess@\texttt{CompleteProcess}}
\label{CompleteProcess}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 record with components \texttt{object} and \texttt{attributes} 



 The function waits, if necessary, until the underlying stream of the process
will contain some data, then reads the appropriate \textsf{OpenMath} object from this stream and closes it. 

 It has the option \texttt{output} which may have two values: 
\begin{itemize}
\item  \texttt{output:="cookie"} has the same meaning as for the \texttt{NewProcess} (\ref{NewProcess}) 
\item  \texttt{output:="tree"} is used to specify that the result obtained from the server should be returned
as an XML parsed tree without its evaluation. 
\end{itemize}
 }

 In the following example we demonstrate combination of the two previous
functions to send request and get result, calling the procedure \texttt{WS{\textunderscore}Factorial}, installed in the previous chapter: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> s := NewProcess( "WS_Factorial", [10], "localhost", 26133 );                  
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  < process at localhost:26133 pid=6543 >
  gap> x := CompleteProcess(s);
  rec( object := "3628800", attributes := [ [ "call_id", "localhost:26133:6543" ] ] )
  
\end{Verbatim}
 See more examples in the description of the function \texttt{EvaluateBySCSCP} (\ref{EvaluateBySCSCP}), which combines the two previous functions by sending request and getting
result in one call. 

\subsection{\textcolor{Chapter }{EvaluateBySCSCP}}
\logpage{[ 6, 1, 4 ]}\nobreak
\hyperdef{L}{X7C745B2878E0AC41}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EvaluateBySCSCP({\slshape command, listargs, server, port})\index{EvaluateBySCSCP@\texttt{EvaluateBySCSCP}}
\label{EvaluateBySCSCP}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 record with components \texttt{object} and \texttt{attributes} 



 \mbox{\texttt{\slshape command}} and \texttt{server} are strings, \mbox{\texttt{\slshape listargs}} is a list of \textsf{GAP} objects and \texttt{port} is an integer. Calls the SCSCP procedure with the name \mbox{\texttt{\slshape command}} and the list of arguments \mbox{\texttt{\slshape listargs}} at the server and port given by \texttt{server} and \texttt{port}. 

 Since \texttt{EvaluateBySCSCP} combines \texttt{NewProcess} (\ref{NewProcess}) and \texttt{CompleteProcess} (\ref{CompleteProcess}), it accepts all options which may be used by that functions ( \texttt{output}, \texttt{cd} and \texttt{debuglevel} ) with the same meanings. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133);
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  #I  Request sent ...
  #I  Waiting for reply ...
  rec( attributes := [ [ "call_id", "localhost:26133:2442:6hMEN40d" ] ], 
       object := 3628800 )
  gap> SetInfoLevel(InfoSCSCP,0);
  gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133 : output:="cookie" ); 
  rec( attributes := [ [ "call_id", "localhost:26133:2442:jNQG6rml" ] ], 
    object := < remote object TEMPVarSCSCP@localhost:26133 > )
  gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133 : output:="nothing" );
  rec( attributes := [ [ "call_id", "localhost:26133:2442:9QHQrCjv" ] ], 
    object := "procedure completed" )
  
\end{Verbatim}
 }

 Now we demonstrate the procedure \texttt{GroupIdentificationService}, also given in the previous chapter: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G:=SymmetricGroup(4);
  Sym( [ 1 .. 4 ] )
  gap> gens:=GeneratorsOfGroup(G);
  [ (1,2,3,4), (1,2) ]
  gap> EvaluateBySCSCP( "GroupIdentificationService", [ gens ],
  >                     "localhost", 26133 : debuglevel:=3 ); 
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  #I  Request sent ...
  #I  Waiting for reply ...
  rec( attributes := [ [ "call_id", "localhost:26133:2442:xOilXtnw" ], 
        [ "info_runtime", 6 ], [ "info_memory", 670175232 ], 
        [ "info_message", "Memory usage for the result is 24 bytes" ] ], 
    object := [ 24, 12 ] )
  
\end{Verbatim}
 Service provider may suggest to the client to use a counterpart function 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  IdGroupWS:=function( G )
  local H, result;
  if not IsPermGroup(G) then
    H:= Image( IsomorphismPermGroup( G ) );
  else
    H := G;
  fi;  
  result := EvaluateBySCSCP ( "GroupIdentificationService", 
              [ GeneratorsOfGroup(H) ], "localhost", 26133 );
  return result.object;
  end;
  
\end{Verbatim}
 which works exactly like \texttt{IdGroup} (\textbf{Reference: IdGroup}): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G:=DihedralGroup(64);
  <pc group of size 64 with 6 generators>
  gap> IdGroupWS(G);
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Waiting for reply ...
  [ 64, 52 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{TerminateProcess}}
\logpage{[ 6, 1, 5 ]}\nobreak
\hyperdef{L}{X7F94E72985216677}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TerminateProcess({\slshape process})\index{TerminateProcess@\texttt{TerminateProcess}}
\label{TerminateProcess}
}\hfill{\scriptsize (function)}}\\


 The function is supposed to send an ``out-of-band'' interrupt signal to the server. Current implementation works only when the
server is running as ``localhost'' by sending a \texttt{SIGINT} to the server using its PID contained in the \mbox{\texttt{\slshape process}}. It will do nothing if the server is running remotely, as the \textsf{SCSCP} specification allows the server to ignore interrupt messages. Remote
interrupts will be introduced in one of the next versions of the package. }

 }

 
\section{\textcolor{Chapter }{Remote objects}}\label{Remote}
\logpage{[ 6, 2, 0 ]}
\hyperdef{L}{X7C3B6B4C7A0666F8}{}
{
  The \textsf{SCSCP} package introduces new kind of objects - \emph{remote objects}. They provide an opportunity to manipulate with objects on remote services
without their actual transmitting over the network. Remote objects store the
information that allows to access the original object: the server name and the
port number through which the object can be accessed, and the variable name
under which it is stored in the remote system. Two remote objects are equal if
and only if all these three parameters coincide. 

 There are two types of remote object which differ by their lifetime: 
\begin{itemize}
\item temporary remote objects which exist only within a single session;
\item persistent remote objects which stay alive across multiple sessions.
\end{itemize}
 First we show the example of the temporary remote object in a session. The
procedure \texttt{PointImages} returns the set of images of a point $i$ under the generators of the group $G$. First we create the symmetric group $S_3$ on the client and store it remotely on the server (call 1), then we compute
set of images for $i=1,2$ (calls 2,3) and finally demonstrate that we may retrieve the group from the
server (call 4): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> stream:=InputOutputTCPStream( "localhost", 26133 );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  < input/output TCP stream to localhost:26133 >
  gap> StartSCSCPsession(stream);
  #I  Got connection initiation message
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  "localhost:26133:6184"
  gap> OMPutProcedureCall( stream, "store_session", 
  >       rec( object := [ SymmetricGroup(3) ], 
  >        attributes := [ [ "call_id", "1" ], 
  >                        ["option_return_cookie"] ] ) );
  true
  gap> SCSCPwait( stream );
  gap> G:=OMGetObjectWithAttributes( stream ).object;
  < remote object TEMPVarSCSCPoS5nhta3@localhost:26133 >
  gap> OMPutProcedureCall( stream, "PointImages", 
  >       rec( object := [ G, 1 ], 
  >        attributes := [ [ "call_id", "2" ] ] ) );
  true
  gap> SCSCPwait( stream );
  gap> OMGetObjectWithAttributes( stream );
  rec( attributes := [ [ "call_id", "2" ] ], object := [ 2 ] )
  gap> OMPutProcedureCall( stream, "PointImages", 
  >       rec( object := [ G, 2 ], 
  >        attributes := [ [ "call_id", "3" ] ] ) );
  true
  gap> SCSCPwait( stream );
  gap> OMGetObjectWithAttributes( stream );
  rec( attributes := [ [ "call_id", "3" ] ], object := [ 1, 3 ] )
  gap> OMPutProcedureCall( stream, "retrieve", 
  >       rec( object := [ G ], 
  >        attributes := [ [ "call_id", "4" ] ] ) );
  true
  gap> SCSCPwait( stream );
  gap> OMGetObjectWithAttributes( stream );
  rec( attributes := [ [ "call_id", "4" ] ], 
    object := Group([ (1,2,3), (1,2) ]) )
  gap> CloseStream(stream);
  
\end{Verbatim}
 After the stream is closed, it is no longer possible to retrieve the group $G$ again or use it as an argument. 

 Thus, the usage of remote objects existing during a session reduces the
network traffic, since we pass only references instead of actual \textsf{OpenMath} representation of an object. Also, the remote object on the server may
accumulate certain information in its properties and attributes, which may not
be included in it default \textsf{OpenMath} representation. 

 Now we show remote objects which remain alive after the session is closed.
Such remote objects may be accessed later, for example, by: 
\begin{itemize}
\item subsequent procedure calls from the same instance of \textsf{GAP} or another system;
\item other instances of \textsf{GAP} or another systems (if the identifier of an object is known)
\item another \textsf{SCSCP} servers which obtained a reference to such object as an argument of a
procedure call.
\end{itemize}
 

\subsection{\textcolor{Chapter }{StoreAsRemoteObjectPersistently}}
\logpage{[ 6, 2, 1 ]}\nobreak
\hyperdef{L}{X82A02E827C33EC1C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StoreAsRemoteObjectPersistently({\slshape obj, server, port})\index{StoreAsRemoteObjectPersistently@\texttt{StoreAsRemoteObjectPersistently}}
\label{StoreAsRemoteObjectPersistently}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StoreAsRemoteObject({\slshape obj, server, port})\index{StoreAsRemoteObject@\texttt{StoreAsRemoteObject}}
\label{StoreAsRemoteObject}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 remote object 



 Returns the remote object corresponding to the object created at \mbox{\texttt{\slshape server}}\texttt{:}\mbox{\texttt{\slshape port}} from the \textsf{OpenMath} representation of the first argument \mbox{\texttt{\slshape obj}}. The second form is just a synonym. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> s:=StoreAsRemoteObject( SymmetricGroup(3), "localhost", 26133 );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Waiting for reply ...
  < remote object TEMPVarSCSCP@localhost:26133 >
  
\end{Verbatim}
 Internally, the remote object carries all the information which is required to
get access to the original object: its identifier, server and port: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> s![1]; 
  "TEMPVarSCSCP"
  gap> s![2];
  "localhost"
  gap> s![3];
  26133
  
\end{Verbatim}
 When the remote object is printed in the \textsf{OpenMath} format, we use symbols \texttt{@} and \texttt{:} to combine these parameters in the \textsf{OpenMath} reference: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> OMPrint(s);
  <OMOBJ>
  	<OMR xref="TEMPVarSCSCP@localhost:26133" />
  </OMOBJ>
  
\end{Verbatim}
 This allows substitution of remote object as arguments into procedure calls in
the same manner like we do this with usual objects: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> EvaluateBySCSCP("WS_IdGroup",[s],"localhost",26133);  
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Waiting for reply ...
  rec( object := [ 6, 1 ], attributes := [ [ "call_id", "localhost:26133:6726" ] ] )
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsRemoteObject}}
\logpage{[ 6, 2, 2 ]}\nobreak
\hyperdef{L}{X812934747F689ECA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRemoteObject\index{IsRemoteObject@\texttt{IsRemoteObject}}
\label{IsRemoteObject}
}\hfill{\scriptsize (filter)}}\\


 This is the category of remote objects. }

 

\subsection{\textcolor{Chapter }{RemoteObjectsFamily}}
\logpage{[ 6, 2, 3 ]}\nobreak
\hyperdef{L}{X871AA6198192A9DD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RemoteObjectsFamily\index{RemoteObjectsFamily@\texttt{RemoteObjectsFamily}}
\label{RemoteObjectsFamily}
}\hfill{\scriptsize (family)}}\\


 This is the familty of remote objects. }

 

\subsection{\textcolor{Chapter }{RetrieveRemoteObject}}
\logpage{[ 6, 2, 4 ]}\nobreak
\hyperdef{L}{X83AD5B7A83C3CD4A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RetrieveRemoteObject({\slshape remoteobject})\index{RetrieveRemoteObject@\texttt{RetrieveRemoteObject}}
\label{RetrieveRemoteObject}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 object 



 This function retrieves the remote object from the remote service in the \textsf{OpenMath} format and constructs it locally. Note, however, that for a complex
mathematical object its default \textsf{OpenMath} representation may not contain all information about it which was accumulated
during its lifetime on the \textsf{SCSCP} server. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> RetrieveRemoteObject(s);
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Waiting for reply ...
  Group([ (1,2,3), (1,2) ])
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{UnbindRemoteObject}}
\logpage{[ 6, 2, 5 ]}\nobreak
\hyperdef{L}{X840EF8E87C94CB9B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{UnbindRemoteObject({\slshape remoteobject})\index{UnbindRemoteObject@\texttt{UnbindRemoteObject}}
\label{UnbindRemoteObject}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Removes any value currently bound to the global variable determined by \mbox{\texttt{\slshape remoteobject}} at the \textsf{SCSCP} server, and returns \texttt{true} or \texttt{false} dependently on whether this action was successful or not. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> UnbindRemoteObject(s);
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Waiting for reply ...
  true
  
\end{Verbatim}
 Finally, we show an example when first we create a group on the service
running on port 26133, and then identify it on the service running on port
26134. Instead of transmitting the group to the client and then sending it as
an argument to the second service, the latter service directly retrieves the
group from the first service. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> s:=StoreAsRemoteObject( SymmetricGroup(3), "localhost", 26133 );
< remote object TEMPVarSCSCP@localhost:26133 >
gap> EvaluateBySCSCP( "WS_IdGroup", [ s ], "localhost", 26134 );
rec( object := [ 6, 1 ], attributes := [ [ "call_id", "localhost:26134:7414" ] ] )
  
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> EvaluateBySCSCP("WS_IdGroup",[s],"localhost",26133 : output:="cookie" );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Waiting for reply ...
  rec( object := < remote object TEMPVarSCSCP2@localhost:26133 >, 
    attributes := [ [ "call_id", "localhost:26133:7328" ] ] )
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Examples of \textsf{SCSCP} usage}}\label{Examples}
\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X879574BC87EE2203}{}
{
  In this chapter we are going to demonstrate some examples of communication
between client and server using the SCSCP. 
\section{\textcolor{Chapter }{Providing services with the SCSCP package}}\label{ProvidingServices}
\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X875D36D286CFC465}{}
{
  You can try to run the SCSCP server with the configuration file \texttt{scscp/example/myserver.g}. To do this, go to that directory and enter \texttt{gap myserver.g}. After this you will see some information messages and finally the server
will start to wait for the connection. The final part of the startup screen
may look as follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  #I  Installed SCSCP procedure Factorial
  #I  Installed SCSCP procedure WS_Factorial
  #I  Installed SCSCP procedure GroupIdentificationService
  #I  Installed SCSCP procedure IdGroup512ByCode
  #I  Installed SCSCP procedure WS_IdGroup
  #I  Installed SCSCP procedure WS_Karatsuba
  #I  Installed SCSCP procedure EvaluateOpenMathCode
  #I  Ready to accept TCP/IP connections at localhost:26133 ...
  #I  Waiting for new client connection at localhost:26133 ...
  
\end{Verbatim}
 See further self-explanatory comments in the file \texttt{scscp/example/myserver.g}. There also some test files in the directory \texttt{scscp/tst/} supplied with detailed comments. First, you may use demonstration files,
preliminary turning on the demonstration mode as it is explained in these
files, or just executing step by step each command from \texttt{scscp/tst/demo.g} and \texttt{scscp/tst/omdemo.g}. Then you can try to use files \texttt{scscp/tst/id512.g}, \texttt{scscp/tst/idperm.g} and \texttt{scscp/tst/factor.g} for further tests of \textsf{SCSCP} services. }

 
\section{\textcolor{Chapter }{Identifying groups of order 512}}\label{Id512}
\logpage{[ 7, 2, 0 ]}
\hyperdef{L}{X7AE719DF7E2083BA}{}
{
  We will give an example guiding you through all steps of creation of your own \textsf{SCSCP} service. 

 The \textsf{GAP} Small Group Library does not provide identification for groups of order 512
using the function \texttt{IdGroup}: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IdGroup( DihedralGroup( 256 ) );
  [ 256, 539 ]
  gap> IdGroup(DihedralGroup(512)); 
  Error, the group identification for groups of size 
  512 is not available called from
  <function>( <arguments> ) called from read-eval-loop
  Entering break read-eval-print loop ...
  you can 'quit;' to quit to outer loop, or
  you can 'return;' to continue
  brk> 
  
\end{Verbatim}
 However, the \textsf{GAP} package \textsf{ANUPQ} \cite{ANUPQ} has a function \texttt{IdStandardPresented512Group} that does this work as demonstrated below: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> LoadPackage("anupq");
  -------------------------------------------------------------
  Loading ANUPQ 3.0 (ANU p-Quotient package)
  C code by  Eamonn O'Brien <obrien@math.auckland.ac.nz>
             (ANU pq binary version: 1.8)
  GAP code by Werner Nickel <nickel@mathematik.tu-darmstadt.de>
          and   Greg Gamble  <gregg@math.rwth-aachen.de>
  
              For help, type: ?ANUPQ
  -------------------------------------------------------------
  true
  gap> G := DihedralGroup( 512 );            
  <pc group of size 512 with 9 generators>
  gap> F := PqStandardPresentation( G );
  <fp group on the generators [ f1, f2, f3, f4, f5, f6, f7, f8, f9 ]>
  gap> H := PcGroupFpGroup( F );
  <pc group of size 512 with 9 generators>
  gap> IdStandardPresented512Group( H );
  [ 512, 2042 ]
  
\end{Verbatim}
 The package \textsf{ANUPQ} requires \textsf{UNIX} environment and it is natural to provide an identification service for groups
of order 512 to make it available for other platforms. 

 Now we need to decide how the client will transmit a group to the server. Can
we encode this group in \textsf{OpenMath}? But there is no content dictionary for PcGroups. Should we convert it to a
permutation representation to be able to use existing content dictionaries?
But then the resulting \textsf{OpenMath} code will be not compact. However, the \textsf{SCSCP} protocol provides enough freedom for the user to select its own data
representation, and since we are linking together two copies of the same
system, we may use the \emph{pcgs code} to pass the data to the server (see \texttt{CodePcGroup} (\textbf{Reference: CodePcGroup}). 

 First we create a function which accepts the integer number that is the code
for pcgs of a group of order 512 and returns the number of this group in the
GAP Small Groups library: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  IdGroup512ByCode := function( code )
  local G, F, H;
  G := PcGroupCode( code, 512 );
  F := PqStandardPresentation( G );
H := PcGroupFpGroup( F );
return IdStandardPresented512Group( H );
  end;
  
\end{Verbatim}
 After such function was created on the server, we need to make it ``visible'' as an \textsf{SCSCP} procedure: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> InstallSCSCPprocedure("IdGroup512", IdGroup512ByCode );
  InstallSCSCPprocedure : procedure IdGroup512 installed. 
  
\end{Verbatim}
 Note that this function assumes that the argument is a valid code for some
group of order 512, and we wish the client to make it sure that this is the
case. To do this, and also for the client's convenience, we provide the
client's counterpart for this service. Here the group must be a pc-group of
order 512, otherwise an error message will appear. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  IdGroup512:=function( G )
  local code, result;
  if Size( G ) <> 512 then
    Error( "G must be a group of order 512 \n" );
  fi;
  code := CodePcGroup( G );
  result := EvaluateBySCSCP( "IdGroup512ByCode", [ code ], 
                             "localhost", 26133 );
  return result.object;
  end;
  
\end{Verbatim}
 Now the client can call the function \texttt{IdGroup512}, and the procedure of getting result is as much straightforward as using \texttt{IdGroup} for those groups where it works: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IdGroup512(DihedralGroup(512));
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  #I  Request sent ...
  #I  Waiting for reply ...
  [ 512, 2042 ]
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Parallel computing with \textsf{SCSCP}}}\label{Parallel}
\logpage{[ 8, 0, 0 ]}
\hyperdef{L}{X7C80E6FA7CB91D28}{}
{
  
\section{\textcolor{Chapter }{Managing multiple requests}}\label{Workflows}
\logpage{[ 8, 1, 0 ]}
\hyperdef{L}{X7BB9C05286A1375B}{}
{
  Using procedure calls explained in the previous section, the user can create
several requests to multiple services to execute them in parallel, or to wait
until the fastest result will be available. 

\subsection{\textcolor{Chapter }{SynchronizeProcesses}}
\logpage{[ 8, 1, 1 ]}\nobreak
\hyperdef{L}{X8249D1A9804C6E08}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SynchronizeProcesses({\slshape process1, process2, ..., processN})\index{SynchronizeProcesses@\texttt{SynchronizeProcesses}}
\label{SynchronizeProcesses}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SynchronizeProcesses({\slshape proclist})\index{SynchronizeProcesses@\texttt{SynchronizeProcesses}!for list of processes}
\label{SynchronizeProcesses:for list of processes}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 list of records with components \texttt{object} and \texttt{attributes} 



 The function collects results of from each process given in the argument, and
returns the list, $i$-th entry of which is the result obtained from the $i$-th process. The function accepts both one argument that is a list of
processes, and arbitrary number of arguments, each of them being a process. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a:=NewProcess( "WS_Factorial", [10], "localhost", 26133 );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  #I  Request sent ...
  < process at localhost:26133 pid=2064 >
  gap> b:=NewProcess( "WS_Factorial", [20], "localhost", 26134 );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  #I  Request sent ...
  < process at localhost:26134 pid=1975 >
  gap> SynchronizeProcesses(a,b);
  #I  Process number 1 is ready
  #I  Closed 1st process, waiting for 2nd ...
  [ rec( attributes := [ [ "call_id", "localhost:26133:2064:yCWBGYFO" ] ], 
        object := 3628800 ), 
    rec( attributes := [ [ "call_id", "localhost:26134:1975:yAAWvGTL" ] ], 
        object := 2432902008176640000 ) ]
  
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{FirstProcess}}
\logpage{[ 8, 1, 2 ]}\nobreak
\hyperdef{L}{X7B56C3BB87C0A226}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FirstProcess({\slshape process1, process2, ..., processN})\index{FirstProcess@\texttt{FirstProcess}}
\label{FirstProcess}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FirstProcess({\slshape proclist})\index{FirstProcess@\texttt{FirstProcess}!for list of processes}
\label{FirstProcess:for list of processes}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 records with components \texttt{object} and \texttt{attributes} 



 The function waits for the result from each process given in the argument, and
returns the result coming first, terminating all remaining processes at the
same time. The function accepts both one argument that is a list of processes,
and arbitrary number of arguments, each of them being a process. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a:=NewProcess( "WS_Factorial", [10], "localhost", 26133 );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  #I  Request sent ...
  < process at localhost:26133 pid=2064 >
  gap> b:=NewProcess( "WS_Factorial", [20], "localhost", 26134 );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  #I  Requesting version 1.3 from the server ...
  #I  Server confirmed version 1.3 to the client ...
  #I  Request sent ...
  < process at localhost:26134 pid=1975 >
  gap>  FirstProcess(a,b); 
  #I  Process number 1 is ready
  rec( attributes := [ [ "call_id", "localhost:26133:2064:mdb8RaO2" ] ], 
    object := 3628800 )
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{SCSCPservers}}
\logpage{[ 8, 1, 3 ]}\nobreak
\hyperdef{L}{X7CDA73307ABE9998}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSCPservers\index{SCSCPservers@\texttt{SCSCPservers}}
\label{SCSCPservers}
}\hfill{\scriptsize (global variable)}}\\


 \texttt{SCSCPservers} is a list of hosts and ports to search for \textsf{SCSCP} services (which may be not only represented by \textsf{GAP} services, but also by another \textsf{SCSCP}-compliant systems). 

 It is used by parallel skeletons \texttt{ParQuickWithSCSCP} (\ref{ParQuickWithSCSCP}) and \texttt{ParListWithSCSCP} (\ref{ParListWithSCSCP}). 

 The initial value of this variable is specified in the file \texttt{scscp/configpar.g} and may be reassigned later. }

 

\subsection{\textcolor{Chapter }{ParQuickWithSCSCP}}
\logpage{[ 8, 1, 4 ]}\nobreak
\hyperdef{L}{X8783850E81463D0F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParQuickWithSCSCP({\slshape commands, listargs})\index{ParQuickWithSCSCP@\texttt{ParQuickWithSCSCP}}
\label{ParQuickWithSCSCP}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 record with components \texttt{object} and \texttt{attributes} 



 This function is constructed using the \texttt{FirstProcess} (\ref{FirstProcess}). It is useful when it is not known which partcular method is more efficient,
because it allows to call in parallel several procedures (given by the list of
their names \mbox{\texttt{\slshape commands}}) with the same list of arguments \mbox{\texttt{\slshape listargs}} (having the same meaning as in \texttt{EvaluateBySCSCP} (\ref{EvaluateBySCSCP})) and obtain the result of that procedure call which will be computed faster. 

 }

 In the example below we call two factorisation methods from the \textsf{GAP} package \textsf{FactInt} to factorise $2^{150}+1$. The example is selected in such a way that the runtime of these two methods
is approximately the same, so you should expect results from both methods in
some random order from repeated calls. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ParQuickWithSCSCP( [ "WS_FactorsECM", "WS_FactorsMPQS" ], [ 2^150+1 ] );
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Process number 2 is ready
  rec( object := [ 5, 5, 5, 13, 41, 61, 101, 1201, 1321, 8101, 63901, 268501, 
        13334701, 1182468601 ], 
   attributes := [ [ "call_id", "localhost:26134:6731" ] ] )
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{MasterWorker skeleton}}\label{MasterWorker}
\logpage{[ 8, 2, 0 ]}
\hyperdef{L}{X7C1FD82A812DDBD0}{}
{
  In this section we will present more general framework to run parallel
computations, which has a number of useful features: 
\begin{itemize}
\item  it is implemented purely in \textsf{GAP}; 
\item  the client (i.e. master, which orchestrates the computation) will work in
UNIX/Linux, Mac OS X and MS Windows; 
\item  it may orchestrate both \textsf{GAP} and non-\textsf{GAP} \textsf{SCSCP} servers; 
\item  if one of servers (i.e. workers) will be lost, it will retry the computation
on another available server; 
\item  it allows to add dynamically new workers during the computation on hostnames
and ports from a range perviously declared in \texttt{SCSCPservers} (\ref{SCSCPservers}). 
\end{itemize}
 To configure this functionality, the file \texttt{scscp/configpar.g} assigns the global variable \texttt{SCSCPservers} which specifies a list of hosts and ports to search for \textsf{SCSCP} services (which may be not only represented by \textsf{GAP} services, but also by another \textsf{SCSCP}-compliant systems). See comments in this file for further instructions. 

\subsection{\textcolor{Chapter }{ParListWithSCSCP}}
\logpage{[ 8, 2, 1 ]}\nobreak
\hyperdef{L}{X788208B57D4C497F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParListWithSCSCP({\slshape listargs, procname})\index{ParListWithSCSCP@\texttt{ParListWithSCSCP}}
\label{ParListWithSCSCP}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 list 



 \texttt{ParListWithSCSCP} implements the well-known master-worker skeleton: we have a master (\textsf{SCSCP} client) and a number of workers (\textsf{SCSCP} servers) which obtain pieces of work from the client, perform the required job
and report back with the result, waiting for the next job. 

 It returns the list of the same length as \mbox{\texttt{\slshape listargs}}, $i$-th element of which is the result of calling the procedure \mbox{\texttt{\slshape procname}} with the argument \mbox{\texttt{\slshape listargs[i]}}. 

 It accepts two options which should be given as non-negative integers: \texttt{timeout} which specifies how long the client will wait for the result (if not given,
the default value is one hour) and \texttt{recallfrequency} which specifies the number of iterations after which the search for new
services will be performed (if not given the default value is zero meaning no
such search at all). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ParListWithSCSCP( List( [2..6], n -> SymmetricGroup(n)), "WS_IdGroup" );
  #I  master -> [ "localhost", 26133 ] : SymmetricGroup( [ 1 .. 2 ] )
  #I  master -> [ "localhost", 26134 ] : SymmetricGroup( [ 1 .. 3 ] )
  #I  [ "localhost", 26133 ] --> master : [ 2, 1 ]
  #I  master -> [ "localhost", 26133 ] : SymmetricGroup( [ 1 .. 4 ] )
  #I  [ "localhost", 26134 ] --> master : [ 6, 1 ]
  #I  master -> [ "localhost", 26134 ] : SymmetricGroup( [ 1 .. 5 ] )
  #I  [ "localhost", 26133 ] --> master : [ 24, 12 ]
  #I  master -> [ "localhost", 26133 ] : SymmetricGroup( [ 1 .. 6 ] )
  #I  [ "localhost", 26133 ] --> master : [ 720, 763 ]
  #I  [ "localhost", 26134 ] --> master : [ 120, 34 ]
  [ [ 2, 1 ], [ 6, 1 ], [ 24, 12 ], [ 120, 34 ], [ 720, 763 ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SCSCPreset}}
\logpage{[ 8, 2, 2 ]}\nobreak
\hyperdef{L}{X8689C2B9840D7E3C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSCPreset({\slshape })\index{SCSCPreset@\texttt{SCSCPreset}}
\label{SCSCPreset}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 If an error occurs during a call of \texttt{ParQuickWithSCSCP} (\ref{ParQuickWithSCSCP}) and \texttt{ParListWithSCSCP} (\ref{ParListWithSCSCP}), some of parallel requests may be still running at the remaining services,
making them inaccessible for further procedure calls. \texttt{SCSCPreset} resets them by closing all open streams to \textsf{SCSCP} servers. }

 

\subsection{\textcolor{Chapter }{SCSCPLogTracesToGlobal}}
\logpage{[ 8, 2, 3 ]}\nobreak
\hyperdef{L}{X84ACC8B4800D0E34}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSCPLogTracesToGlobal({\slshape testname})\index{SCSCPLogTracesToGlobal@\texttt{SCSCPLogTracesToGlobal}}
\label{SCSCPLogTracesToGlobal}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSCPLogTracesToGlobal({\slshape })\index{SCSCPLogTracesToGlobal@\texttt{SCSCPLogTracesToGlobal}!to stop tracing}
\label{SCSCPLogTracesToGlobal:to stop tracing}
}\hfill{\scriptsize (function)}}\\


 To analyse the performance of parallel \textsf{SCSCP} framework, we make use of the \textsf{EdenTV} program \cite{EdenTV} developed initially to visualize the performance of parallel programs written
in functional programming language Eden, and now distributed under the GNU
Public License and available from \href{http://www.mathematik.uni-marburg.de/~eden/?content=EdenTV} {\texttt{http://www.mathematik.uni-marburg.de/\texttt{\symbol{126}}eden/?content=EdenTV}}. 

 Called with the string containing the name of the test, this functions turns
on writing information about key activity events into trace files in current
directories for the client and servers listed \texttt{SCSCPservers} (\ref{SCSCPservers}). The trace file will have the name of the format \mbox{\texttt{\slshape testname}}\texttt{.client.tr} for the client and \mbox{\texttt{\slshape testname}}\texttt{.{\textless}hostname{\textgreater}.{\textless}port{\textgreater}.tr} for the server. After the test these files should be collected from remote
servers and concatenated (e.g. using \texttt{cat}) together with the standard preamble from the file \texttt{scscp/tracing/stdhead.txt} (we recommend to put after the preamble first all traces from servers and then
the client's traces to have nicer diagrams). The resulting file then may be
opened with \textsf{EdenTV}. 

 In the following example we use a dual core MacBook laptop to generate trace
files for two tests and then show their corresponding trace diagrams: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  SCSCPLogTracesToGlobal("quillen100");
  ParListWithSCSCP( List( [1..100], i->[512,i]), "QuillenSeriesByIdGroup" );
  SCSCPLogTracesToGlobal();
  SCSCPLogTracesToGlobal( "euler" );
  ParListWithSCSCP( [1..1000], "WS_Phi" );
  SCSCPLogTracesToGlobal();
  
\end{Verbatim}
 \centerline{\resizebox{110mm}{!}{\includegraphics{img/quillen.pdf}}}  \vspace{10pt}\centerline{\resizebox{110mm}{!}{\includegraphics{img/euler.pdf}}}   The diagrams (made on an dual core MacBook laptop), shows that in the first
case parallelising is efficient and master successfully distributes load to
workers, while in the second case a single computation is just too short, so
most of the time is spent on communication. To parallelize the Euler's
function example efficiently, tasks must rather be grouped in chunks, which
should be enough large to reduce the communication overload, but enough small
to ensure that tasks are evenly distributed. 

 Of course, tracing can be used to investigate communication between a client
and a single server in a non-parallel context as well. For this purpose, \texttt{SCSCPservers} (\ref{SCSCPservers}) must be modified to contain only one server. }

 \texttt{ParListWithSCSCP} (\ref{ParListWithSCSCP}) can be easily modified to have parallel versions of other list operations like \texttt{ForAll} (\textbf{Reference: ForAll}), \texttt{ForAny} (\textbf{Reference: ForAny}), \texttt{First} (\textbf{Reference: First}), \texttt{Number} (\textbf{Reference: Number}), \texttt{Filtered} (\textbf{Reference: Filtered}), and also to have the skeleton in which the queue may be modified during the
computation (for example, to compute orbits). We plan to provide such tools in
one of the next versions of the package. }

 
\section{\textcolor{Chapter }{Example: parallelising Karatsuba multiplication for polynomials}}\label{Karatsuba}
\logpage{[ 8, 3, 0 ]}
\hyperdef{L}{X78C5AEA07F961325}{}
{
  The file \texttt{scscp/example/karatsuba.g} contains an implementation of the Karatsuba multiplication algorithm for
polynomials. This algorithm can be easily parallelized since each recursive
step creates three recursive calls of the same function for other polynomials. \emph{We will not parallelize each} recursive call, since this will create enormous data flow. Instead of this we
parallelize only the top-level function. For our experiments with
parallelising Karatsuba multiplication for polynomials with integer
coefficients we used the multi-core workstation, on which we started one \textsf{SCSCP} client and two \textsf{SCSCP} servers. After reading the file \texttt{scscp/example/karatsuba.g}, the following function was created on the server 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  KaratsubaPolynomialMultiplicationExtRepByString:=function(s1,s2)
  return String( KaratsubaPolynomialMultiplicationExtRep( 
                   EvalString(s1), EvalString(s2) ) );
  end;
  
\end{Verbatim}
 and then was made available as an \textsf{SCSCP} procedure under the name \texttt{WS{\textunderscore}Karatsuba} by the command 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  InstallSCSCPprocedure( "WS_Karatsuba", 
                         KaratsubaPolynomialMultiplicationExtRepByString);
  
\end{Verbatim}
 This function provides a "bridge" between the client's function \texttt{KaratsubaPolynomialMultiplicationWS} and the server's function \texttt{KaratsubaPolynomialMultiplicationExtRep}, which performs the actual work on the server. \texttt{WS{\textunderscore}Karatsuba} converts its string arguments into internal representation of univariate
polynomials (basically, lists of integers) and then converts the result back
into string (since such data exchange format was chosen).  \newpage  We are going to parallelize the following part of the client's code: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  ...
  u := KaratsubaPolynomialMultiplicationExtRep(f1,g1);
  v := KaratsubaPolynomialMultiplicationExtRep(f0,g0);
  w := KaratsubaPolynomialMultiplicationExtRep(
         PlusLaurentPolynomialsExtRep(f1,f0),
         PlusLaurentPolynomialsExtRep(g1,g0) );
  ...
  
\end{Verbatim}
 and this can be done straightforwardly - we replace two first calls by calls
of the appropriate \textsf{SCSCP} services, then perform the 3rd call locally and then collect the results from
the two remote calls: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  ...
  u := NewProcess( "WS_Karatsuba",[ String(f1), String(g1) ],"localhost", 26133);   
  v := NewProcess( "WS_Karatsuba",[ String(f0), String(g0) ],"localhost", 26134);   
  w := KaratsubaPolynomialMultiplicationExtRep(
         PlusLaurentPolynomialsExtRep(f1,f0),
         PlusLaurentPolynomialsExtRep(g1,g0) );
  wsresult:=SynchronizeProcesses2( u,v );
  u := EvalString( wsresult[1].object );
  v := EvalString( wsresult[2].object );
  ...
  
\end{Verbatim}
 We obtain almost double speedup on three cores on randomly generated
polynomials of degree 32000: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> fam:=FamilyObj(1);;
  gap> f:=LaurentPolynomialByCoefficients( fam, 
  >         List([1..32000],i->Random(Integers)), 0, 1 );;
  gap> g:=LaurentPolynomialByCoefficients( fam, 
  >         List([1..32000],i->Random(Integers)), 0, 1 );;
  gap> t2:=KaratsubaPolynomialMultiplication(f,g);;time;
  5892
  gap> t3:=KaratsubaPolynomialMultiplicationWS(f,g);;time;
  2974
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Service functions}}\label{Service}
\logpage{[ 9, 0, 0 ]}
\hyperdef{L}{X80DFB24F8289C323}{}
{
  
\section{\textcolor{Chapter }{Tools for making documentation}}\label{Doctools}
\logpage{[ 9, 1, 0 ]}
\hyperdef{L}{X7A77D39F82157AC6}{}
{
  

\subsection{\textcolor{Chapter }{SCSCPBuildManual}}
\logpage{[ 9, 1, 1 ]}\nobreak
\hyperdef{L}{X8731BD997E646BE4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSCPBuildManual({\slshape })\index{SCSCPBuildManual@\texttt{SCSCPBuildManual}}
\label{SCSCPBuildManual}
}\hfill{\scriptsize (function)}}\\


 This function is used to build the manual in PDF and HTML formats and also in
the plain text format for the online help. To build the PDF version, a recent
and fairly complete {\TeX} distribution is recommended. 

 Since the \textsf{SCSCP} manual is distributed together with the package, it is not necessary for the
user to use this function, which is normally used only by developers. }

 

\subsection{\textcolor{Chapter }{SCSCPBuildManualHTML}}
\logpage{[ 9, 1, 2 ]}\nobreak
\hyperdef{L}{X82CC99C485D7E8DE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSCPBuildManualHTML({\slshape })\index{SCSCPBuildManualHTML@\texttt{SCSCPBuildManualHTML}}
\label{SCSCPBuildManualHTML}
}\hfill{\scriptsize (function)}}\\


 This function is used to build the manual only in HTML format. This does not
require {\TeX} installation and works in any operating system. 

 Since the \textsf{SCSCP} manual is distributed together with the package, it is not necessary for the
user to use this function, which is normally used only by developers. }

 }

 
\section{\textcolor{Chapter }{Other commands}}\label{Other}
\logpage{[ 9, 2, 0 ]}
\hyperdef{L}{X7B16423A7FBED034}{}
{
  

\subsection{\textcolor{Chapter }{PingSCSCPservice}}
\logpage{[ 9, 2, 1 ]}\nobreak
\hyperdef{L}{X78B08D767F9ADB28}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PingSCSCPservice({\slshape hostname, portnumber})\index{PingSCSCPservice@\texttt{PingSCSCPservice}}
\label{PingSCSCPservice}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 This function returns \texttt{true} if the client can establish connection with the SCSCP server at \mbox{\texttt{\slshape hostname}}:\mbox{\texttt{\slshape portnumber}}. Otherwise, it returns \texttt{fail}. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> PingSCSCPservice("localhost",26133);
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  true
  gap> PingSCSCPservice("localhost",26134);                     
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  Error: rec(
    number := 61,
    message := "Connection refused" )
  fail
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{PingStatistic}}
\logpage{[ 9, 2, 2 ]}\nobreak
\hyperdef{L}{X8345DE358064674E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PingStatistic({\slshape hostname, portnumber, n})\index{PingStatistic@\texttt{PingStatistic}}
\label{PingStatistic}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 The function is similar to the UNIX \texttt{ping}. It tries \mbox{\texttt{\slshape n}} times to establish connection with the SCSCP server at \mbox{\texttt{\slshape hostname}}:\mbox{\texttt{\slshape portnumber}}, and then displays statistical information. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> PingStatistic("localhost",26133,5);
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message nr 1
  ...
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message nr 5
  100 packets transmitted, 100 received, 0% packet loss, time 26ms
  min/avg/max = [ 0, 13/50, 2 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{InfoSCSCP}}
\logpage{[ 9, 2, 3 ]}\nobreak
\hyperdef{L}{X831E6A5D8695A3F9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InfoSCSCP\index{InfoSCSCP@\texttt{InfoSCSCP}}
\label{InfoSCSCP}
}\hfill{\scriptsize (info class)}}\\


 \texttt{InfoSCSCP} is a special Info class for the \textsf{SCSCP} package. The amount of information to be displayed can be specified by the
user by setting InfoLevel for this class from 0 to 4, and the default value of
InfoLevel for the package is specified in the file \texttt{scscp/config.g}. The higher the level is, the more information will be displayed. To change
the InfoLevel to \texttt{k}, use the command \texttt{SetInfoLevel(InfoSCSCP, k)}. In the following examples we demonstrate various degrees of output details
using Info messages. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133); 
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message 
  #I  Request sent ...
  #I  Waiting for reply ...
  rec( object := "3628800", attributes := [ [ "call_id", "localhost:26133:38" ] ] )
  
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> SetInfoLevel(InfoSCSCP,0);                              
  gap> EvaluateBySCSCP( "WS_Factorial",[10],"localhost",26133);
  rec( object := "3628800", attributes := [ [ "call_id", "localhost:26133:41" ] ] )
  
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> SetInfoLevel(InfoSCSCP,3);
  gap> G:=SymmetricGroup(4);;
  gap> gens:=GeneratorsOfGroup(G);  
  [ (1,2,3,4), (1,2) ]
  gap> EvaluateBySCSCP( "GroupIdentificationService",[gens],"localhost",26133);
  #I  Creating a socket ...
  #I  Connecting to a remote socket via TCP/IP ...
  #I  Got connection initiation message
  #I Composing procedure_call message: 
  <?scscp start ?>
  <OMOBJ>
      <OMATTR>
  		<OMATP>
  			<OMS cd="scscp1" name="call_id"/>
  			<OMSTR>localhost:26133:1212</OMSTR>
  		</OMATP>
  		<OMA>
  			<OMS cd="scscp1" name="procedure_call"/>
  			<OMA>
  				<OMS cd="scscp_transient_1" name="GroupIdentificationService"/>
  				<OMA>
  					<OMS cd="list1" name="list"/>
  					<OMA>
  						<OMS cd="permut1" name="permutation"/>
  						<OMI> 2</OMI>
  						<OMI> 3</OMI>
  						<OMI> 4</OMI>
  						<OMI> 1</OMI>
  					</OMA>
  					<OMA>
  						<OMS cd="permut1" name="permutation"/>
  						<OMI> 2</OMI>
  						<OMI> 1</OMI>
  					</OMA>
  				</OMA>
  			</OMA>
  		</OMA>
  	</OMATTR>
  </OMOBJ>
  <?scscp end ?>
  #I  Request sent ...
  #I  Waiting for reply ...
  #I  <?scscp start ?>
  #I Received message: 
  <OMOBJ>
  	<OMATTR>
  		<OMATP>
  			<OMS cd="scscp1" name="call_id"/>
  			<OMSTR>localhost:26133:1212</OMSTR>
  		</OMATP>
  		<OMA>
  			<OMS cd="scscp1" name="procedure_completed"/>
  			<OMA>
  				<OMS cd="list1" name="list"/>
  				<OMI> 24</OMI>
  				<OMI> 12</OMI>
  			</OMA>
  		</OMA>
  	</OMATTR>
  </OMOBJ>
  #I  <?scscp end ?>
  #I  Got back: object [ 24, 12 ] with attributes [ [ "call_id", "localhost:26133:1212" ] ]
  rec( object := [ 24, 12 ], attributes := [ [ "call_id", "localhost:26133:1212" ] ] )
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{DateISO8601}}
\logpage{[ 9, 2, 4 ]}\nobreak
\hyperdef{L}{X845DFBDA83AEF6B0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DateISO8601({\slshape })\index{DateISO8601@\texttt{DateISO8601}}
\label{DateISO8601}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 string 



 Returns the current date in the ISO-8601 YYYY-MM-DD format. This is an
internal function of the package which is used by the \textsf{SCSCP} server to generate the transient content dictionary, accordingly to the
definition of the \textsf{OpenMath} symbol \texttt{meta.CDDate}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> DateISO8601();
  "2009-03-31"
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CurrentTimestamp}}
\logpage{[ 9, 2, 5 ]}\nobreak
\hyperdef{L}{X79CE2568789D17D6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CurrentTimestamp({\slshape })\index{CurrentTimestamp@\texttt{CurrentTimestamp}}
\label{CurrentTimestamp}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 string 



 Returns the result of the call to \texttt{date}. This is an internal function of the package which is used to add the
timestamp to the \textsf{SCSCP} service description. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> CurrentTimestamp();
  "Tue 31 Mar 2009 11:19:38 BST"
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Hostname}}
\logpage{[ 9, 2, 6 ]}\nobreak
\hyperdef{L}{X83A08C8883E5D3E1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Hostname({\slshape })\index{Hostname@\texttt{Hostname}}
\label{Hostname}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 string 



 Returns the result of the call to \texttt{hostname}. This function may be used in the configuration file \texttt{scscp/config.g} to specify that the default hostname which will be used by the \textsf{SCSCP} server will be detected automatically using \texttt{hostname}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Hostname();
  "scscp.symbolic-computation.co.uk"
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{MemoryUsageByGAPinKbytes}}
\logpage{[ 9, 2, 7 ]}\nobreak
\hyperdef{L}{X8312112E79686EF6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MemoryUsageByGAPinKbytes({\slshape })\index{MemoryUsageByGAPinKbytes@\texttt{MemoryUsageByGAPinKbytes}}
\label{MemoryUsageByGAPinKbytes}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 integer 



 Returns the current volume of the memory used by \textsf{GAP} in kylobytes. This is equivalent to calling \texttt{ps -p {\textless}PID{\textgreater} -o vsz}, where \texttt{{\textless}PID{\textgreater}} is the process ID of the \textsf{GAP} process. This is an internal function of the package which is used by the \textsf{SCSCP} server to report its memory usage in the \texttt{info{\textunderscore}memory} attribute when being called with the option \texttt{debuglevel=2} (see options in \texttt{EvaluateBySCSCP} (\ref{EvaluateBySCSCP}) and \texttt{NewProcess} (\ref{NewProcess})). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> MemoryUsageByGAPinKbytes();
  649848
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LastReceivedCallID}}
\logpage{[ 9, 2, 8 ]}\nobreak
\hyperdef{L}{X844EC26F84D921CE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LastReceivedCallID({\slshape })\index{LastReceivedCallID@\texttt{LastReceivedCallID}}
\label{LastReceivedCallID}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 string 



 Returns the call ID contained in the most recently received message. It may
contain some useful debugging information; in particular, the call ID for the \textsf{GAP} \textsf{SCSCP} client and server contains colon-separated server name, port number, process
ID and a random string. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> LastReceivedCallID();
  "scscp.symbolic-computation.co.uk:26133:77372:choDZBgA"
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}PickleToString}}
\logpage{[ 9, 2, 9 ]}\nobreak
\hyperdef{L}{X84F055ED860120D5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}PickleToString({\slshape obj})\index{IOPickleToString@\texttt{IO{\textunderscore}PickleToString}}
\label{IOPickleToString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 string containing "pickled" object 



 This function "pickles" or "serialises" the object \mbox{\texttt{\slshape obj}} using the operation \texttt{IO{\textunderscore}Pickle} (\textbf{IO: IO{\textunderscore}Pickle}) from the \textsf{IO} package, and writes it to a string, from which it could be later restored
using \texttt{IO{\textunderscore}UnpickleFromString} (\ref{IOUnpickleFromString}). This provides a way to design \textsf{SCSCP} procedures which transmit \textsf{GAP} objects in the "pickled" format as \textsf{OpenMath} strings, which may be useful for objects which may be "pickled" by the \textsf{IO} package but can not be converted to \textsf{OpenMath} or for which the "pickled" representation is more compact or can be
encoded/decoded much faster. 

 See \texttt{IO{\textunderscore}Pickle} (\textbf{IO: IO{\textunderscore}Pickle}) and \texttt{IO{\textunderscore}Unpickle} (\textbf{IO: IO{\textunderscore}Unpickle}) for more details. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> f := IO_PickleToString( GF( 125 ) );
  "FFIEINTG\>15INTG\>13FAIL"
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}UnpickleFromString}}
\logpage{[ 9, 2, 10 ]}\nobreak
\hyperdef{L}{X813EACD27C218E19}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}UnpickleFromString({\slshape s})\index{IOUnpickleFromString@\texttt{IO{\textunderscore}UnpickleFromString}}
\label{IOUnpickleFromString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 "unpickled" GAP object 



 This function "unpickles" the string \mbox{\texttt{\slshape s}} which was created using the function \texttt{IO{\textunderscore}PickleToString} (\ref{IOPickleToString}), using the operation \texttt{IO{\textunderscore}Unpickle} (\textbf{IO: IO{\textunderscore}Unpickle}) from the \textsf{IO} package. See \texttt{IO{\textunderscore}PickleToString} (\ref{IOPickleToString}) for more details and suggestions about its usage. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IO_UnpickleFromString( f );                    
  GF(5^3)
  gap> f = IO_UnpickleFromString( IO_PickleToString( f ) ); 
  true
  
\end{Verbatim}
 }

 }

 }

 \def\bibname{References\logpage{[ "Bib", 0, 0 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}

\bibliographystyle{alpha}
\bibliography{manual}

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}
