===================================================================
RCS file: /home/cvs/OpenXM/doc/issac2000/openxm-clients.tex,v
retrieving revision 1.1
retrieving revision 1.11
diff -u -p -r1.1 -r1.11
--- OpenXM/doc/issac2000/openxm-clients.tex	1999/12/23 10:25:08	1.1
+++ OpenXM/doc/issac2000/openxm-clients.tex	2000/01/17 06:10:40	1.11
@@ -1 +1,88 @@
-% $OpenXM$
+% $OpenXM: OpenXM/doc/issac2000/openxm-clients.tex,v 1.10 2000/01/17 01:24:27 noro Exp $
+
+\section{OpenXM Clients}    
+
+\subsection{Risa/Asir}
+
+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 {\tt OX} data and sending of {\tt SM} commands.
+As a client, Asir provides the following functions
+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
+and {\tt ox\_get()} for receiving data from a stream.
+
+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 some of them.
+
+\begin{itemize}
+\item {\tt ox\_pop\_cmo()}
+
+It requests a server to send data on the stack to the stream, then
+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 requests the server to execute
+the function. It does not wait the termination of the function call.
+
+\item {\tt ox\_reset()}
+
+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 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.  
+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}
+}
+
+The {\tt math2ox} adds the following functions to Mathematica.
+\begin{quote}
+{\tt OxStart[s\_String]} \\
+{\tt OxStartInsecure[s\_String]} \\
+{\tt OxExecuteString[s\_String]}  \\
+{\tt OxParse[s\_String]} \\
+{\tt OxGet[]} \\
+{\tt OxPopCMO[]} \\
+{\tt OxPopString[]} \\
+{\tt OxClose[]} \\
+{\tt OxReset[]}
+\end{quote}
+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}.