===================================================================
RCS file: /home/cvs/OpenXM/src/ox_math/documents/math2ox.texi,v
retrieving revision 1.2
retrieving revision 1.8
diff -u -p -r1.2 -r1.8
--- OpenXM/src/ox_math/documents/math2ox.texi	2000/03/11 09:17:42	1.2
+++ OpenXM/src/ox_math/documents/math2ox.texi	2000/03/15 10:52:20	1.8
@@ -1,4 +1,4 @@
-%% $OpenXM: OpenXM/src/ox_math/documents/math2ox.texi,v 1.1 2000/03/08 06:59:37 ohara Exp $
+%% $OpenXM: OpenXM/src/ox_math/documents/math2ox.texi,v 1.7 2000/03/15 08:22:20 ohara Exp $
 
 \input texinfo
 @iftex
@@ -34,23 +34,158 @@
 @node Top,, (dir), (dir)
 
 @menu
+* Starting OX servers::
 * Mathematica Client Functions::
 * Sample Programs::
+* Example::
+* References::
 @end menu
 
-@node Mathematica Client Functions,,, Top
+@node Starting OX servers,,, Top
+@chapter Starting OX servers
 
-@chapter Mathematica Client Functions
+@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
@@ -68,12 +203,11 @@ String
 
 @itemize @bullet
 @item  It starts the OX server @code{s}. 
-@item Servers are looked for in the directory $OenXM_HOME/bin , hoge hoge.
+@item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
 @end itemize
 
 @example
-In[1]:= Install["math2ox"]
-In[2]:= pid = OxStart["ox_sm1"]
+In[1]:= pid = OxStart["ox_sm1"]
 @end example
 
 In this example, @code{ox_sm1} is started on the local machine.
@@ -87,23 +221,18 @@ In this example, @code{ox_sm1} is started on the local
 @findex OxSendMessage
 @table @t
 @item OxSendMessage[@var{pid}, @var{s}]
-::  SendMessage @code{s} to the OX server @code{pid}.
+::  send a message @code{s} to the OX server @code{pid}.
 @end table
 
 @table @var
 @item return
 Integer
-@item id
+@item pid
 Integer
 @item s
 String
 @end table
 
-@itemize @bullet
-@item  It starts the OX server @code{s}. 
-@item Servers are looked for in the directory $OenXM_HOME/bin , hoge hoge.
-@end itemize
-
 @example
 In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
 In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]
@@ -114,29 +243,282 @@ In this example, an OX data message 
 and an OX command message (OX_COMMAND, (SM_popCMO)) are sent to 
 the OX server @code{pid}.
 
-@c  Put descriptions of a next function.
+@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
 
-@node Starting OX servers on a remote machines,,, Top
-@chapter Starting OX servers on a remote machines
+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
 
-@tex
-\noindent
-1.
-{\tt OpenXM/lib/math/primadec.m} is a Mathematica program
+@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
-{\tt ox\_asir}.
+@code{ox_asir}.
 As to usages, see comments in this file.
 
-\noindent 2.
-{\tt OpenXM/lib/math/beta.m} is a Mathematica program
-to get beta-nbc bases by calling {\tt ox\_asir}.
-@end tex
+@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