%% $OpenXM: OpenXM/src/ox_math/documents/math2ox.texi,v 1.8 2000/03/15 10:52:20 ohara Exp $

\input texinfo
@iftex
@catcode`@#=6
@def@b#1{{@bf@gt #1}}
@catcode`@#=@other
@end iftex
@overfullrule=0pt
@c -*-texinfo-*-
@comment %**start of header
@setfilename Math2ox
@settitle Math2ox
@comment %**end of header
@comment %@setchapternewpage odd

@iftex
@comment @finalout
@end iftex

@titlepage

@title Math2ox
@subtitle Math2ox User's Manual (English Edition)
@subtitle Edition 1.1.2 for OpenXM/oxmath
@subtitle March 2000

@author  by Katsuyoshi Ohara
@end titlepage

@synindex vr fn

@comment  node-name,  next,  previous,  up
@node Top,, (dir), (dir)

@menu
* Starting OX servers::
* Mathematica Client Functions::
* Sample Programs::
* Example::
* References::
@end menu

@node Starting OX servers,,, Top
@chapter Starting OX servers

@node Loading an OX Client on Mathematica,,, Starting OX servers
@section Loading an OX Client on Mathematica

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

In order to execute @code{math2ox}, you need to type as follows:
@example
In[1]:= Install["math2ox"]
@end example

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

@node Starting OX servers on the localhost,,, Starting OX servers
@section Starting OX servers on the localhost

@c  Description of OxStart
@menu
* OxStart::
@end menu
@node OxStart,,, 
@subsection @code{OxStart}
@findex OxStart
@table @t
@item OxStart[@var{s}]
::  Start the OX server @code{s}. 
@end table

@table @var
@item return
Integer
@item s
String
@end table

@itemize @bullet
@item  It starts the OX server @code{s}. 
@item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
@end itemize

@example
In[1]:= pid = OxStart["ox_sm1"]
@end example

In this example, @code{ox_sm1} is started on the local machine.

@node Starting OX servers on a remote machine,,, Top
@section Starting OX servers on a remote machine

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

@node Starting the X Window System with ssh-agent,,, Starting OX servers on a remote machine
@subsection 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 convinience.  As to details, see ssh-agent (1)
and ssh-add (1).
If you start the X-windows system by @code{startx}, you can start
ssh-agent by @code{ssh-agent startx}.

@example
bash$ ssh-agent startx
@end example
If you use @code{xdm} program to login your machine, 
then your @code{.xsession} script needs to contain the followings:
@example
exec ssh-agent .xinitrc
@end example
@noindent 
where @code{.xinitrc} is executable.

After starting the X Window System, you need to type on suitable terminal
emulator as follows:
@example
bash$ ssh-add
@end example
@noindent
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.

@c  Description of OxStartRemoteSSH
@menu
* OxStartRemoteSSH::
@end menu
@node OxStartRemoteSSH,,, 
@subsection @code{OxStartRemoteSSH}
@findex OxStartRemoteSSH
@table @t
@item OxStartRemoteSSH[@var{s}, @var{host}]
::  start the OX server @code{s} on the remote machine @code{host} by ssh. 
@end table

@table @var
@item return
Integer
@item s
String
@item host
String
@end table

We note that the @code{OxStartRemoteSSH[]} is an experimental implementation.

@itemize @bullet
@item  It starts the OX server @code{s}. 
@item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
@end itemize

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

In this example, @code{ox_sm1} is started on the remote machine @code{remotehost}.

@node Mathematica Client Functions,,, Top
@chapter Mathematica Client Functions

@c  Description of OxStart
@menu
* OxStart::
@end menu
@node OxStart,,, Mathematica Client Functions
@section @code{OxStart}
@findex OxStart
@table @t
@item OxStart[@var{s}]
::  Start the OX server @code{s}. 
@end table

@table @var
@item return
Integer
@item s
String
@end table

@itemize @bullet
@item  It starts the OX server @code{s}. 
@item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
@end itemize

@example
In[1]:= pid = OxStart["ox_sm1"]
@end example

In this example, @code{ox_sm1} is started on the local machine.

@c  Description of OxSendMessage
@menu
* OxSendMessage::
@end menu
@node OxSendMessage,,, Mathematica Client Functions
@section @code{OxSendMessage}
@findex OxSendMessage
@table @t
@item OxSendMessage[@var{pid}, @var{s}]
::  send a message @code{s} to the OX server @code{pid}.
@end table

@table @var
@item return
Integer
@item pid
Integer
@item s
String
@end table

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

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 @code{pid}.

@c  Description of OxPopCMO
@menu
* OxPopCMO::
@end menu
@node OxPopCMO,,, Mathematica Client Functions
@section @code{OxPopCMO}
@findex OxPopCMO
@table @t
@item OxPopCMO[@var{pid}]
::  pop an object on the top of the stack.
@end table

@table @var
@item return
Manual
@item pid
Integer
@end table

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

@example
In[5] := cmo = OxPopCMO[pid]
@end example

@c  Description of OxPopString
@menu
* OxPopString::
@end menu
@node OxPopString,,, Mathematica Client Functions
@section @code{OxPopString}
@findex OxPopString
@table @t
@item OxPopString[@var{pid}]
::  get a string from the OX server @code{pid}.
@end table

@table @var
@item return
String
@item pid
Integer
@end table

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

@example
In[5] := string = OxPopString[pid]
@end example

@c  Description of OxClose
@menu
* OxClose::
@end menu
@node OxClose,,, Mathematica Client Functions
@section @code{OxClose}
@findex OxClose
@table @t
@item OxClose[@var{pid}]
::  close the connection to the OX server @code{pid}.
@end table

@table @var
@item return
none
@item pid
Integer
@end table

The @code{OxClose[]} function closes the connection to the OX server 
@code{pid}.

@example
In[5] := OxClose[pid]
@end example

@c  Description of OxExecuteString
@menu
* OxExecuteString::
@end menu
@node OxExecuteString,,, Mathematica Client Functions
@section @code{OxExecuteString}
@findex OxExecuteString
@table @t
@item OxExecuteString[@var{pid}, @var{command}]
::  execute @code{command} on the OX server @code{pid}.
@end table

@table @var
@item return
none
@item pid
Integer
@item command
String
@end table

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

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

@c  Description of OxGet
@menu
* OxGet::
@end menu
@node OxGet,,, Mathematica Client Functions
@section @code{OxGet}
@findex OxGet
@table @t
@item OxGet[@var{pid}]
::  get an object from the connection to the OX server @code{pid}.
@end table

@table @var
@item return
Manual
@item pid
Integer
@end table

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

@example
In[5] := cmo = OxGet[pid]
@end example

@c  Put descriptions of a next function.

@node Sample Programs,,, Top
@chapter Sample Programs

@enumerate
@item
@code{OpenXM/lib/math/oxclient.m} is a Mathematica program
to load the @code{math2ox} and to define some Mathematica 
functions for @code{primadec.m} and @code{beta.m}.

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

@item
@code{OpenXM/lib/math/beta.m} is a Mathematica program
to get beta-nbc bases by calling @code{ox_asir}.
@end enumerate

@node Example,,, Top
@chapter Example

 In this section, we will present a simple OpenXM session
on Mathematica to send a list 
@example
   ["Hello World", 0]
@end example
@noindent
to a server and pops that list from the server.

The @code{math2ox} has the following commands:

@code{OxStart[], 
OxStartInsecure[],
OxStartRemoteSSH[], 
OxExecuteString[], 
OxSendMessage[], 
OxGet[],
OxPopCMO[],
OxPopString[], 
OxClose[], 
OxReset[]}.

First, let us load the @code{math2ox}.
@example
In[1]:= <<oxclient.m
@end example

Second, let us open a connection with an OX server.
For example, if we want to call the @code{ox_sm1} (the kan/sm1 server), then
@example
In[2] := pid = OxStart["ox_sm1"]
@end example
@noindent
where we have the connection of reverse mode.  The @code{OxStart}
function automatically invoke @code{ox_sm1} on the localhost.  
If you need to connect remote OX servers, then you can use reverse mode.
@example
In[2] := pid = OxStartRemoteSSH["ox_sm1", "orange.math.kobe-u.ac.jp"]
@end example

@c  Remarks: old version.
@c  @example
@c  In[2] := pid = OxStartInsecure["water.s.kanazawa-u.ac.jp", 1300, 1400]
@c  @end example
@c  The mode is not secured but you can crypt data stream by using ssh
@c  (Secure SHell).
@c  @example
@c  In[3] := Run["ssh -f water ox -insecure -ox ox_sm1 -host water"]
@c  @end example

Third, let us send an OX message to the OX server.
We can send an OX message written in OX/CMO expressions.
@example
In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
@end example
@noindent
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
@code{pid}, then you can call the following function:
@example
In[5] := cmo = OxPopCMO[pid]
@end example

The function @code{OxPopCMO} above is equivalent to 
the following two command:
@example
In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]
In[6] := cmo = OxGet[pid]
@end example

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

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

Last, let us close the connection.
@example
In[7] := OxClose[pid]
@end example

@c @node Bibliography,,, Top
@c @unnumbered Bibliography
@node References,,, Top
@unnumbered References

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

@item
@code{http://www.math.kobe-u.ac.jp/OpenXM/}

@item
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)

@item
Stephen Wolfram:
{The Mathematica Book}, Third edition,
Wolfram Media/Cambridge University Press, 1996.

@item
T. Miyachi:
{Mathematica Network Programming},
Iwanami Shoten Publishers, 1998. (in Japanese)
@end enumerate

@node Index,,, Top
@unnumbered Index
@printindex fn
@printindex cp
@iftex
@vfill @eject
@end iftex
@summarycontents
@contents
@bye