===================================================================
RCS file: /home/cvs/OpenXM/doc/OpenXM-specs/stackmachine.tex,v
retrieving revision 1.4
retrieving revision 1.13
diff -u -p -r1.4 -r1.13
--- OpenXM/doc/OpenXM-specs/stackmachine.tex	2000/01/24 02:48:24	1.4
+++ OpenXM/doc/OpenXM-specs/stackmachine.tex	2016/08/22 09:08:50	1.13
@@ -1,3 +1,4 @@
+%%  $OpenXM: OpenXM/doc/OpenXM-specs/stackmachine.tex,v 1.12 2004/03/08 03:08:12 takayama Exp $
 //&jp \section{ OX スタックマシン }
 //&eg \section{ OX stack machine }
 \label{sec:stackmachine}
@@ -236,6 +237,11 @@ The server can avoid to send OX messages unknown to it
 */
 @plugin/mathcap.h)
 
+Stack before the request:
+\begin{tabular}{|c|}  \hline
+{\it Mathcap m}  \\
+\hline
+\end{tabular}\\
 Request:
 \begin{tabular}{|c|c|}  \hline
 {\tt int32 OX\_DATA} & {\sl Mathcap} m  \\ \hline
@@ -348,7 +354,7 @@ It requests a server to pop an object from {\tt Operan
 to convert it into a character string according to the output format
 of the local system, and to send the character string via TCP/IP stream.
 {\tt (char *)NULL} is returned when the stack is empty.
-The returned strings is sent as a CMO string data.
+The returned string is sent as a CMO string data.
 {\tt CMO\_ERROR2} should be returned if an error has occurred.
 */
 
@@ -430,10 +436,45 @@ Stack after the request:
 \end{tabular}
 
 Output: none.
+
+\item
+\begin{verbatim}
+SM_pushCMOtag
+\end{verbatim}
+/*&jp
+スタックの先頭オブジェクトが CMO に変換された場合の CMO tag を
+{\tt CMO\_INT32} としてスタックへ push する.
+先頭オブジェクトはスタックに留まる.
+先頭オブジェクトをCMO へ変換する方法が無い場合は, エラー object を積む.
+*/
+/*&eg
+It requests a server to push the CMO tag of the top object on the server
+stack. The tag is pushed as {\tt CMO\_INT32}.
+The top object remains on the stack.
+If there is no way to translate the object into CMO,
+push an error object.
+*/
+
+Request:
+\begin{tabular}{|c|c|}  \hline
+{\tt int32 OX\_COMMAND} & {\tt int32 SM\_pushCMOtag} \\
+\hline 
+\end{tabular}
+
+Stack after the request:
+\begin{tabular}{|c|c|c|}  \hline
+{\tt int32 OX\_DATA} & {\sl CMO\_INT32} \ tag\\
+\hline 
+\end{tabular}
+
+Output: none.
 \end{enumerate}
 
 \medbreak
 \noindent
+
+//&C \subsubsection{ MathCap }  \label{subsubsection:mathcap}
+
 /*&jp
 {\bf 例}: \ 
 mathcap の問い合わせに対して, {\tt ox\_sm1} は次のように答える.
@@ -453,7 +494,8 @@ Class.mathcap 
 \end{verbatim}
 
 /*&jp
-mathcap は 3つの要素をもつリストである.  まづ, 最初の要素を見よう.
+mathcap は 3つ以上の要素をもつリストである.  まづ, 最初の要素(これもリスト)を見よう.
+リストの先頭の数字は OpenXM プロトコルのバージョンである.
 Ox\_system は openXM システム名である.  読み込むライブラリがちがって
 いて, 関数名(または シンボル)の意味がちがうときはこの名前もかえる. た
 とえば, open math の basic content dictionary 対応の関数定義マクロを読
@@ -463,23 +505,126 @@ Ox\_system は openXM システム名である.  読み込むライブ
 は, 処理可能な数学データの形式, およびCMOの場合なら処理可能なCMOのタグ
 のリストが続く.  上の例では, 514 は {\tt OX\_DATA} をあらわし, 数学デー
 タのフォマットは(サイズ情報なしの) CMO であることを示す.
+四番目のリストは optinal で, CMO string のリストである.
+文字列は option名, または option名=値, なる形式で与える.
+option 名は英数字およびアンダーバーで記述. = 以下は utf-8 文字コードを利用してよい.
 */
 /*&eg
-A mathcap has three components. The first one contains informations
-to identify the system and hosts on which the application runs.
+A mathcap has three or more than three components. 
+The first one, which is also a list,
+contains informations
+to identify the version number of the OpenXM protocol,
+the system and hosts on which the application runs.
 In the above example, {\tt Ox\_system} denotes the system name.
 {\tt HOSTTYPE} represents the OS type and taken from \verb+$HOSTTYPE+
 enviroment variable.
 The second component consists of avaiable SM commands.
 The third component is a list of pairs. Each pair consists
-of an OX message tag and the available message tags.
+of an OX message tag and the list of available message tags.
 Again in the above example, 514 is the value of {\tt OX\_DATA}
 and it indicates that the server accepts CMO (without size information)
 as mathematical data messages. In this case the subsequent
 list represents available CMO tags.
+The fourth list is optinal.  
+This is a list of cmo strings.
+Each string has the formats ``an option name'' or ``an optionname=value''.
+The option name must consists only of alphabets, numbers, and under bars. 
+The symbol = may be followed by a string in the utf-8 character codes.
 */
 
+/*&C
+\noindent
+OpenXM/XML expression of the example above:
+\begin{verbatim}
+  <cmo_mathcap>
+     <cmo_list for="mathcap">
+
+       <cmo_list>
+          <int32 for="length"> 4 </int32>
+          <cmo_int32 for="Protocol version">  001001003 </cmo_int32>
+          <cmo_string for="system name"> Ox_system=ox_sm1.plain  </cmo_string>
+          <cmo_string for="system version"> Version=2.990911  </cmo_string>
+          <cmo_string for="hosttype"> HOSTTYPE=i386  </cmo_string>
+       </cmo_list>
+
+       <cmo_list for="Available SM tags">
+          <int32 for="length"> 11 </int32>
+          <cmo_int32> 262 </cmo_int32> 
+          <cmo_int32> 263 </cmo_int32> 
+           ...
+       </cmo_list>
+
+       <cmo_list for="Available OX_DATA tags">
+          <int32 for="length"> 2 </int32>
+          <cmo_list for="OX_DATA tag">
+             <int32 for="length"> 1 </int32>
+             <cmo_int32 comment="OX_DATA">  514 </cmo_int32>
+          </cmo_list>
+          <cmo_list for="Available CMO tags">
+             <int32 for="length"> 21 </int32>
+             <cmo_int32 comment="CMO_ERROR2">  2130706434 </cmo_int32>
+             <cmo_int32 comment="CMO_NULL"> 1 </cmo_int32>
+              ....
+          </cmo_list>
+
+       </cmo_list>
+     </cmo_list>
+  </cmo_mathcap>
+\end{verbatim}
+*/
+
+/*&C
+\noindent
+Example of the use of the fourth argument (optional parameter).
+\begin{verbatim}
+  <cmo_mathcap>
+     <cmo_list for="mathcap">
+
+       <cmo_list>
+          <int32 for="length"> 4 </int32>
+          <cmo_int32 for="Protocol version">  001001003 </cmo_int32>
+          <cmo_string for="system name"> Ox_system=ox_sm1.plain  </cmo_string>
+          <cmo_string for="system version"> Version=2.990911  </cmo_string>
+          <cmo_string for="hosttype"> HOSTTYPE=i386  </cmo_string>
+       </cmo_list>
+
+       <cmo_list for="Available SM tags">
+          <int32 for="length"> 11 </int32>
+          <cmo_int32> 262 </cmo_int32> 
+          <cmo_int32> 263 </cmo_int32> 
+           ...
+       </cmo_list>
+
+       <cmo_list for="Available OX_DATA tags">
+          <int32 for="length"> 2 </int32>
+          <cmo_list for="OX_DATA tag">
+             <int32 for="length"> 1 </int32>
+             <cmo_int32 comment="OX_DATA">  514 </cmo_int32>
+          </cmo_list>
+          <cmo_list for="Available CMO tags">
+             <int32 for="length"> 21 </int32>
+             <cmo_int32 comment="CMO_ERROR2">  2130706434 </cmo_int32>
+             <cmo_int32 comment="CMO_NULL"> 1 </cmo_int32>
+              ....
+          </cmo_list>
+       </cmo_list>
+
+       <cmo_list for="optional info">
+          <int32 for="length"> 2 </int32>
+          <cmo_string> no_ox_reset </cmo_string>
+          <cmo_string> opt_sample=Hello world. </cmo_string>
+       </cmo_list>
+
+     </cmo_list>
+  </cmo_mathcap>
+\end{verbatim}
+*/
+
 \medbreak
+
+//&jp \subsubsection{ 例 }
+//&eg \subsubsection{ Examples }
+
 \noindent
 //&jp {\bf 例}: \ 
 //&eg {\bf Example}: \ 
@@ -563,7 +708,7 @@ operand stack より, {\it n} 個の元 ({\it obj1, obj2, $
 */
 /*&eg
 It requests a server to pop {\it n} and to discard elements {\it obj1, obj2,
-$\ldots$, objn}) from the stack.
+$\ldots$, objn} from the stack.
 */
 
 //&jp Stack before the request: \\
@@ -629,7 +774,7 @@ OutputObj} をスタックへ戻す.  関数自体は正常終了なら 0
 It requests a server to pop {\it name} and to evaluate a variable
 {\it name} in the current name space. The Output of the evaluation
 {\it OutputObj} is pushed to the stack.
-If an error has occurred {\tt CMO\_ERROR2} is pushed to the stack.
+If an error has occurred {\tt CMO\_ERROR2} is pushed onto the stack.
 */
 
 //&jp Stack before the request:
@@ -736,6 +881,52 @@ Output:  
 {\tt int32 OX\_DATA} &   {\it Serialized CMO} \\
 \hline 
 \end{tabular}
+
+
+\item 
+\begin{verbatim}
+SM_executeFunctionWithOptionalArgument
+\end{verbatim}
+/*&jp
+スタックより {\it n} 個のデータおよび一つの optional 引数 {\it opt} を pop して, 
+サーバのローカル関数{\it s} を実行する.  エラーのときのみ {\tt CMO\_ERROR2} を stack へ push す
+る.
+{\it opt} はキーワードと値のリストのリストである. キーワードは文字列型である.
+*/
+/*&eg
+It requests a server to pop {\it s} as a function name, 
+to pop an optional argument {\it opt},
+to pop {\it n} as the number of arguments and to execute
+a local function {\it s} with {\it n} arguments popped from
+the stack.
+If an error has occurred {\tt CMO\_ERROR2} is pushed to the stack.
+{\it opt} is a list of lists of a keyword and a value.
+Keywords are strings.
+*/
+
+//&jp Stack before the request: \\
+//&eg Stack before the request: \\
+\begin{tabular}{|c|c|c|c|c|c|}  \hline
+{\it objn} & $\cdots$ & {\it obj1} & {\it INT32 n} & {\it Obj opt} & {\it String s} \\
+\hline 
+\end{tabular}
+
+Request:
+\begin{tabular}{|c|c|}  \hline
+{\tt int32 OX\_COMMAND} & {\tt int32 SM\_executeFunctionWithOptionalArgument}  \\
+\hline
+\end{tabular}
+
+//&jp Stack after the request: 関数実行の結果.
+//&eg Stack after the request: The Output of the execution.
+
+Output: none.
+
+\noindent
+Example of {\it opt} : \verb@ (("p", 13),("vars",("x","y")))@
+
+\noindent
+[Added in 2004-3-8]
 
 \end{enumerate}