=================================================================== RCS file: /home/cvs/OpenXM/doc/issac2000/openxm-clients.tex,v retrieving revision 1.4 retrieving revision 1.12 diff -u -p -r1.4 -r1.12 --- OpenXM/doc/issac2000/openxm-clients.tex 2000/01/13 09:21:34 1.4 +++ OpenXM/doc/issac2000/openxm-clients.tex 2000/01/17 07:15:52 1.12 @@ -1,39 +1,23 @@ -% $OpenXM: OpenXM/doc/issac2000/openxm-clients.tex,v 1.3 2000/01/11 05:17:11 noro Exp $ +% $OpenXM: OpenXM/doc/issac2000/openxm-clients.tex,v 1.11 2000/01/17 06:10:40 noro Exp $ \section{OpenXM Clients} -(noryo and Ohara) -MEMO: keywords: -Asir and Mathematica clients. \subsection{Risa/Asir} -Risa/Asir provides a launcher to invoke an OpenXM server and to set up the -communication between the server and itself. It also provides primitives -for communication as built-in functions. - -\subsubsection{{\tt ox\_launch}} -{\tt ox\_launch} is a general purpose launcher. This application -invokes a server and initiates the server-client communication -according to the protocol stated in Section \ref{launcher}, then -itself becomes a control server. -Several facilities related to {{\tt ox\_launch}} are provided -as built-in functions of Risa/Asir: a function to invoke a server -automatically from a give host name and a server name, and a set -of functions to execute the port generation, {\tt bind}, {\tt listen}, -{\tt connect} and {\tt accept} operations on sockets individually. - -\subsubsection{Manipulating servers} - -Fundamental operations on OpenXM servers are sending and receiving -of {\tt OX} data and sending of {\tt OX} commands. The following functions -are provided to execute these primitive operations: -{\tt ox\_push\_cmo()} for pushing data to a server, -{\tt ox\_push\_cmd()} for sending an {\tt SM} command to a server +Risa/Asir provides a launcher {\tt ox\_launch} +to invoke an OpenXM server and to set up the +communication between the server and itself. +Fundamental operations on OpenXM servers are +exchange of OX data and sending of stack machine commands. +As a client, Asir provides the following functions +to execute these primitive operations: +{\tt ox\_push\_cmo()} for pushing data, +{\tt ox\_push\_cmd()} for sending a stack machine command and {\tt ox\_get()} for receiving data from a stream. -Some operations including the reset operation are realized by +Some operations including the reset operation are implemented by combining these primitives. Among them, frequently used ones are -provided as built-in functions. We show several ones. +provided as built-in functions. We show some of them. \begin{itemize} \item {\tt ox\_pop\_cmo()} @@ -44,7 +28,7 @@ it receives the data from the stream. \item {\tt ox\_cmo\_rpc()} After pushing the name of a function, arguments and the number of the -arguments to the stack of a server, it request the server to execute +arguments to the stack of a server, it requests the server to execute the function. It does not wait the termination of the function call. \item {\tt ox\_reset()} @@ -52,21 +36,32 @@ the function. It does not wait the termination of the After sending {\tt SM\_control\_reset\_connection} to a control server, it completes the operations stated in Section \ref{control}. \end{itemize} -Furthermore {\tt ox\_select()} is provided to detect streams ready for -reading. It is realized by the {\tt select()} system call and is used +Furthermore {\tt ox\_select()} is provided to detect if streams are ready for +reading. It is implemented by the {\tt select()} system call and is used to avoid blocking on read operations. \subsection{Mathematica} We provide an OpenXM client {\tt math2ox} written as an external module -for Mathematica. Our client communicates to Mathematica by MathLink and -to an OpenXM server by OpenXM protocols. The {\tt math2ox} needs -{\tt ox} command attached to kan/sm1 to connect an OpenXM server. +for Mathematica. +The module {\tt math2ox} communicates with Mathematica by MathLink and +with any OpenXM server by the OpenXM protocol. +By using the module {\tt math2ox}, +we can call OpenXM servers from Mathematica; +here is a demonstration of a computation of the de Rham cohomology groups +of ${\bf C}^2 \setminus V(x^3-y^2)$ from Mathematica. +{\footnotesize +\begin{verbatim} +In[1]:= Install["math2ox"] +In[2]:= OxStart["../lib/sm1/bin/ox_sm1_forAsir"] +In[3]:= OxExecute[" [(x^3-y^2) (x,y)] deRham "] +In[4]:= OxPopString[] +Out[4]= [ 1 , 1 , 0 ] (* The dimension of + cohomology groups *) +\end{verbatim} +} -\subsubsection{Functions} - -The {\tt math2ox} has the following functions functions named -like Risa/Asir; +The {\tt math2ox} adds the following functions to Mathematica. \begin{quote} {\tt OxStart[s\_String]} \\ {\tt OxStartInsecure[s\_String]} \\ @@ -78,13 +73,16 @@ like Risa/Asir; {\tt OxClose[]} \\ {\tt OxReset[]} \end{quote} -For example, the {\tt OxPopCMO[]} function above requests a server to -send data on the stack to the stream, then it receives the data from the -stream. - -The {\tt OxParse[]} and the {\tt OxGet[]} above are low level functions. -By using the {\tt OxParse[]} function, we can send suitable OX messages, -which are written as an OX expression, to a server. OX expressions are -Lisp-like expressions for OX messages and are defined -in~\cite{noro-takayama}. The {\tt OxGet[]} receives an OX data message -and returns its object. +Although the list of functions speaks itself, +we add some explanations. +The function {\tt OxPopCMO[]} executes the same operation +as {\tt ox\_pop\_cmo()} in Risa/Asir; +it pops data from the server stack. +The {\tt OxGet[]} receives an OX data message +and returns its translation to an local object. +The function {\tt OxParse[]} helps debugging to connect Mathematica +and ox servers. +By using the function, one can send OX messages, +written by the OX expression, to a server. +OX expressions are Lisp-like expressions for OX messages and are defined +in~\cite{noro-takayama}.