%% $OpenXM: OpenXM/doc/OpenXM-specs/library.tex,v 1.7 2020/03/14 01:21:56 takayama Exp $
/*&jp
\section{ OX サーバに対する C ライブラリインタフェース }

一部のOX サーバでは C のライブラリとしてリンクして使用するもできる.
ライブラリとして使用するための C の関数は
Asir の OX サーバ用クライアント関数に似たインタフェースを持つ.

ライブラリ関数には, CMO を binary encoding して渡す.
ライブラリ関数からは, CMO が binary encoded form で戻る.

*/
/*&eg
\section{ OX servers as a C library}

In some OX servers, one can use the OX server as a C library.
The API to the C library
is similar to Asir OX client API such as
{\tt ox\_push\_cmo()}, {\tt ox\_pop\_cmo()}.

CMO should be converted into the binary encoded form to call these functions.
*/
/*&C

\medbreak
\begin{verbatim}
  int xxx_ox_init(int type)
\end{verbatim}
*/
/*&eg
  This function initializes the library interface.
  {\tt type} specifies the byte order to send int32 to the OX server xxx.
  If type is equal to 0, the native byte order will be used.
  If type is equal to 1, the network byte order will be used.
  In case of error, -1 will be returned.
*/
/*&jp
  この関数はライブラリインタフェースの初期化を行う. 
  OX サーバ xxx へ int32 を送るための byte order を type で指定する.
  type = 0 の場合 native byte order が設定される. 
  type = 1 の場合 network byte order が設定される. 
  失敗した場合, -1 を戻す.
*/

/*&C

\smallskip
\begin{verbatim}
  void xxx_ox_push_cmo(void *cmo)
\end{verbatim}
*/
/*&eg
Push the binary encoded CMO {\tt cmo} onto the stack of the OX server xxx.
*/
/*&jp
Binary encoded された CMO を, OX サーバ xxx
の stack に push する. 
*/
/*&C

\smallskip
\begin{verbatim}
  int xxx_ox_pop_cmo(void cmo, int limit)
\end{verbatim}
*/
/*&eg
Pop a binary encoded CMO from the OX server xxx
and write it at {\tt cmo}.
The return value is the size of the CMO in bytes.
In case of the stack underflow, the return value is 0.
If the size exceeds the {\tt limit}, -1 will be returned
and the CMO is not popped and will not be written to {\tt cmo}.
*/
/*&jp
Binary encoded された CMO (サイズは size) を,  OX サーバより
pop して, cmo に書き込む.
戻り値は CMO のサイズを byte で戻す.
Stack underflow の場合の戻り値は 0 である.
ただし, limit より大きいサイズの CMO は書き込まれない.
この場合, 戻り値は -1 となる.
*/

/*&C

\smallskip
\begin{verbatim}
  int xxx_ox_peek_cmo_size()
\end{verbatim}
*/
/*&eg
Return the size of the CMO at the top of the stack.
*/
/*&jp
stack の一番上にある CMO のサイズを byte で戻す.
*/

\smallbreak
\begin{verbatim}
 void xxx_ox_push_cmd(int cmd)
\end{verbatim}
/*&eg
This function sends a stack machine command 
({\tt OX\_COMMAND},int32 cmd) to a server.
*/
/*&jp
({\tt OX\_COMMAND},int32 cmd) をサーバに送る. 
*/

\begin{verbatim}
 void xxx_ox_execute_string(char *s) 
\end{verbatim}
/*&eg
This function requests a server to execute a command expressed by 
a string {\tt s}.
{\tt s} should be acceptable by the parser of the server.
*/
/*&jp
文字列 {\tt s} をサーバに実行させる. {\tt s} はサーバのパーザ
が受理可能なものでなければならない. 
*/

//&C

/*&jp
ライブラリモードのサンプルソースは {\tt OpenXM/doc/oxlib}
にある.
*/

/*&eg
Sample source codes to use the library mode interface can be found in
{\tt OpenXM/doc/oxlib}.
*/

