%#!platex
%% $OpenXM: OpenXM/src/ox_math/documents/math2ox.tex,v 1.3 2000/01/21 09:55:21 takayama Exp $

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

\begin{document}
\maketitle

\section{Mathematica Client}

We provide an OX client named {\tt math2ox} by an external module for
Mathematica. That is, we can call an OX server on Mathematica.  The
math2ox has communication with the OX server by OpenXM protocols and
communication with Mathematica by MathLink.  The math2ox interpret our
commands and translate them to OX messages.

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], OxParse[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] := 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] := 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] := OxParse["(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
In[5] := OxParse["(OX_COMMAND, (SM_popCMO))"]
\end{verbatim}
If the expression is illegal, then nothing is sent.

Remarks: if SM\_popCMO is sent by the {\tt OxParse[]} 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.
\begin{verbatim}
In[6] := OxGet[]
\end{verbatim}

If we do not use the {\tt OxParse} 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}