%#!platex
%% $OpenXM: OpenXM/src/ox_math/documents/math2ox.tex,v 1.4 2000/03/11 09:17:41 ohara Exp $

\documentclass{article}
\title{Mathematica Client for Open XM}
\date{January 20, 2000}
\author{Katsuyoshi Ohara}

\begin{document}
\maketitle

\section{Mathematica Client}

The program {\tt math2ox} is an external module for Mathematica
to call OpenXM servers.
The {\tt math2ox} communicates with OpenXM servers by the OpenXM protocol
and communicates with Mathematica by MathLink.

The {\tt math2ox} has the following commands:\\
{\tt OxStart[s\_String], 
OxStartInsecure[s\_String, p\_Integer, q\_Integer],
OxStartRemoteSSH[s\_String, t\_String], 
OxExecuteString[s\_String], OxSendMessage[s\_String], OxGet[], OxPopCMO[],
OxPopString[], OxClose[], OxReset[]}.

First, let us load the math2ox.
\begin{verbatim}
In[1]:= Install["math2ox"]
\end{verbatim}

Second, let us open a connection with an OX server.
For example, if we want to call the ox\_sm1 (the kan/sm1 server), then
\begin{verbatim}
In[2] := oxid = OxStart["ox_sm1"]
\end{verbatim}
where we have the connection of reverse mode.  The OxStart function
automatically invoke ox\_sm1 on the local machine.  If you need to
connect an OX server on a remote machine, then you can use reverse mode.
\begin{verbatim}
In[2] := oxid = OxStartInsecure["water.s.kanazawa-u.ac.jp", 1300, 1400]
\end{verbatim}
The mode is not secured but you can crypt data stream by using ssh
(Secure SHell).
\begin{verbatim}
In[3] := Run["ssh -f water ox -insecure -ox ox_sm1 -host water"]
\end{verbatim}

Third, let us send an OX message to the OX server.
We can send an OX message written in OX/CMO expressions.
\begin{verbatim}
In[4] := OxSendMessage["(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
In[5] := OxSendMessage["(OX_COMMAND, (SM_popCMO))"]
\end{verbatim}
If the expression conains syntax errors, then nothing is sent.

Remarks: if SM\_popCMO is sent by the {\tt OxSendMessage[]} function, then the
OX stack machine returns the top of the stack to the {\tt math2ox}.
Then, in order to receive the message, we need to call the {\tt OxGet[]}
function always after executing {\tt OxSendMessage[]}
\begin{verbatim}
In[6] := OxGet[]
\end{verbatim}

If we do not use the {\tt OxSendMessage} function and use the {\tt OxPopCMO[]}
function, then we do not need to call the {\tt OxGet[]}.
\begin{verbatim}
In[5] := OxPopCMO[]
\end{verbatim}

Fourth, if we send a command expressed in the local language of the OX
server, then we need to call the {\tt OxExecuteString[]} function.

Last, let us close the connection.
\begin{verbatim}
In[7] := OxClose[]
\end{verbatim}

\section{Examples}

\begin{enumerate}
\item
{\tt OpenXM/lib/math/primadec.m} is a Mathematica program
to make primary ideal decompositions by calling
{\tt ox\_asir}.
As to usages, see comments in this file.
\item 
{\tt OpenXM/lib/math/beta.m} is a Mathematica program
to get beta-nbc bases by calling {\tt ox\_asir}.
\end{enumerate}



\appendix

\begin{thebibliography}{99}
\bibitem{Openxxx-1998}
M. Noro, N. Takayama:
Design and Implementation of OpenXM, 1996, 1997, 1998, 1999, 2000.
\bibitem{openxm-web}
{\footnotesize {\tt http://www.math.kobe-u.ac.jp/OpenXM/}}
\bibitem{Ohara-Takayama-Noro-1999}
M. Noro, K. Ohara, N. Takayama:
{Introduction to Open Asir}, 1999, Suusiki Shori, Vol 7, No 2,
2--17. (ISBN4-87243-086-7, SEG Publishing, Tokyo). (in Japanese)
\bibitem{Wolfram-1996}
Stephen Wolfram:
{The Mathematica Book}, Third edition,
Wolfram Media/Cambridge University Press, 1996.

\bibitem{miyachi-1998}
T. Miyachi:
{Mathematica Network Programming},
Iwanami Book Co., 1998. (in Japanese)
\end{thebibliography}

\end{document}