Starting OX servers
*******************

Loading an OX Client on Mathematica
===================================

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

In order to execute math2ox, you need to type as follows:

     In[1]:= Install["math2ox"]

The Mathematica program oxclient.m, which is used to load math2ox and set some global variables, is in the directory $OpenXM_HOME/lib/oxmath. The standard value of $OpenXM_HOME is /usr/local/OpenXM. We recommend using oxclient.m instead of Install[]:

     In[1] := <<oxclient.m

Starting OX servers on the localhost
====================================

OxStart
-------

OxStart[S]
     ::  Start the OX server s.

return
     Integer

s
     String

  * It starts the OX server s.

  * Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.

     In[1]:= pid = OxStart["ox_sm1"]

In this example, ox_sm1 is started on the local machine.

Starting OX servers on a remote machine
=======================================

In order to connect to remote OX servers, it is convenient, secure and recommended to use ssh (Secure SHell). The function OxStartRemoteSSH starts remote OX servers by ssh.  Of course, you are supposed to be able to login the remote machine by ssh and $Remote_OpenXM_HOME/rc/cshrc or $Remote_OpenXM_HOME/rc/bashrc are executed from the login shell of your remote machine. The function OxStartRemoteSSH[] does not ask your password, that is, you need to be using ssh-agent before calling OxStartRemoteSSH[]. Then there will be no check of password.

Starting the X Window System with ssh-agent
-------------------------------------------

In this subsection, we will explain how to start ssh-agent and set your password by ssh-add for reader's convenience.  As to details, see ssh-agent (1) and ssh-add (1). If you start the X-windows system by startx, you can start ssh-agent by ssh-agent startx.

     bash$ ssh-agent startx

If you use xdm program to login your machine, then your .xsession script needs to contain the following:

     exec ssh-agent .xinitrc

where .xinitrc is executable.

After starting the X Window System, you need to type on suitable terminal emulator as follows:

     bash$ ssh-add

and input your passphrase.  Once you set your passphrase by ssh-add, you no longer need to input your passphrase to access to other machines by ssh.

OxStartRemoteSSH
----------------

OxStartRemoteSSH[S, HOST]
     ::  start the OX server s on the remote machine host by ssh.

return
     Integer

s
     String

host
     String

We note that the OxStartRemoteSSH[] is an experimental implementation.

  * It starts the OX server s.

  * Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.

     In[1]:= pid = OxStartRemoteSSH["ox_sm1", "remotehost"]

In this example, ox_sm1 is started on the remote machine remotehost.

Mathematica Client Functions
****************************

OxStart
=======

OxStart[S]
     ::  Start the OX server s.

return
     Integer

s
     String

  * It starts the OX server s.

  * Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.

     In[1]:= pid = OxStart["ox_sm1"]

In this example, ox_sm1 is started on the local machine.

OxSendMessage
=============

OxSendMessage[PID, S]
     ::  send a message s to the OX server pid.

return
     Integer

pid
     Integer

s
     String

     In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
     In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]

In this example, an OX data message (OX_DATA, (CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO)) and an OX command message (OX_COMMAND, (SM_popCMO)) are sent to the OX server pid.

OxPopCMO
========

OxPopCMO[PID]
     ::  pop an object on the top of the stack.

return
     Manual

pid
     Integer

The OxPopCMO[] function pops an object on the top of the stack of the OX stack machine pid and returns the object. The return type of the function OxPopCMO[] is Manual in terms of MathLink, that is, an object of suitable type is returned.

     In[5] := cmo = OxPopCMO[pid]

OxPopString
===========

OxPopString[PID]
     ::  get a string from the OX server pid.

return
     String

pid
     Integer

The OxPopString[] function pops an object on the top of the stack of the OX stack machine pid and returns a string which is translated from the object by the OX stack machine.

     In[5] := string = OxPopString[pid]

OxClose
=======

OxClose[PID]
     ::  close the connection to the OX server pid.

return
     none

pid
     Integer

The OxClose[] function closes the connection to the OX server pid.

     In[5] := OxClose[pid]

OxExecuteString
===============

OxExecuteString[PID, COMMAND]
     ::  execute command on the OX server pid.

return
     none

pid
     Integer

command
     String

The OxExecuteString[] function executes command on the OX server pid. The string command is interpreted in local language of the OX server.

     In[5] := OxExecuteString["print(1+2);"]

OxGet
=====

OxGet[PID]
     ::  get an object from the connection to the OX server pid.

return
     Manual

pid
     Integer

The OxGet[] function gets an object from the connection to the OX server pid.

     In[5] := cmo = OxGet[pid]

Sample Programs
***************

 1. OpenXM/lib/math/oxclient.m is a Mathematica program to load the math2ox and to define some Mathematica functions for primadec.m and beta.m.

 2. OpenXM/lib/math/primadec.m is a Mathematica program to make primary ideal decompositions by calling ox_asir. As to usages, see comments in this file.

 3. OpenXM/lib/math/beta.m is a Mathematica program to get beta-nbc bases by calling ox_asir.

Example
*******

In this section, we will present a simple OpenXM session on Mathematica to send a list

        ["Hello World", 0]

to a server and pops that list from the server.

The math2ox has the following commands:

OxStart[], OxStartInsecure[], OxStartRemoteSSH[], OxExecuteString[], OxSendMessage[], OxGet[], OxPopCMO[], OxPopString[], OxClose[], OxReset[].

First, let us load the math2ox.

     In[1]:= <<oxclient.m

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

     In[2] := pid = OxStart["ox_sm1"]

where we have the connection of reverse mode.  The OxStart function automatically invoke ox_sm1 on the localhost. If you need to connect remote OX servers, then you can use reverse mode.

     In[2] := pid = OxStartRemoteSSH["ox_sm1", "orange.math.kobe-u.ac.jp"]

Third, let us send an OX message to the OX server. We can send an OX message written in OX/CMO expressions.

     In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]

If the expression contains syntax errors, then nothing is sent.

If you need to get the object on the top of the stack of an OX server pid, then you can call the following function:

     In[5] := cmo = OxPopCMO[pid]

The function OxPopCMO above is equivalent to the following two command:

     In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]
     In[6] := cmo = OxGet[pid]

Remarks: if SM_popCMO is sent by the OxSendMessage[] function, then the OX stack machine returns the top of the stack to the math2ox. Then, in order to receive the message, we need to call the OxGet[] function always after executing OxSendMessage[]. That is OxGet flushes the communication route to pid.  If we never use the OxSendMessage function, then we do not need to call the OxGet[].

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

Last, let us close the connection.

     In[7] := OxClose[pid]

References
**********

 1. M. Noro, N. Takayama: Design and Implementation of OpenXM, 1996, 1997, 1998, 1999, 2000.

 2. http://www.math.kobe-u.ac.jp/OpenXM/

 3. 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)

 4. Stephen Wolfram: The Mathematica Book, Third edition, Wolfram Media/Cambridge University Press, 1996.

 5. T. Miyachi: Mathematica Network Programming, Iwanami Shoten Publishers, 1998. (in Japanese)