# Author: 小原功任 @ 金沢大学理学部計算科学教室
# URI:    http://omega.s.kanazawa-u.ac.jp/ohara/
# $OpenXM: OpenXM/src/ox_toolkit/README,v 1.7 2000/01/14 10:23:34 ohara Exp $

/*&ja ox_toolkit ユーザガイド

*/
/*&en A user's guide for OpenXM C library.

*/
/* &ja いきさつ
このライブラリは ox_math および math2ox を開発するために設計された。
ライブラリ自身には、 Mathematica に依存した部分はない。
*/
/* &en Introduction

*/
/*&ja
libox.a を利用するには次のヘッダファイルをインクルードする必要があります。
*/
/*&en
How to use OpenXM C library?

In order to use libox.a, you need to include the following header files:
*/
/*&common

#include <oxtag.h>
#include <ox.h>
#include <parse.h>

*/
/*&ja
1. データ型

このツールキットで定義されている各構造体の生成については次節を参照せよ。

1.1 CMO (Common Math Object)
次のデータ型(構造体)が用意されている。
*/
/*&en
1. Types

1.1 CMO (Common Math Object)
The following structures are defined in ox.h:
*/
/*&common

cmo
cmo_null
cmo_int32
cmo_datum
cmo_string
cmo_mathcap
cmo_list
cmo_monomial32
cmo_zz
cmo_qq
cmo_zero
cmo_dms_generic
cmo_ring_by_name
cmo_distributed_polynomial
cmo_indeterminate
cmo_error2

*/
/*&ja
このうち cmo 型はいわば抽象基底クラスに相当するものであり、この型のオ
ブジェクトを明示的には生成されない。このクラスはポインタ型のキャストの
ために用意されている。また cmo_distributed_polynomial は cmo_list の派
生クラスであると思ってもよい。

*/
/*&en
The cmo above is abstract base class; you never make an object of cmo
class.

*/
/*&ja
1.2 OX オブジェクト
次のデータ型(構造体)が用意されている。
*/
/*&en
1.2 OX objects
The following structures are defined in ox.h:
*/
/*&common

ox
ox_command
ox_data

*/
/*&ja
このうち、ox 型は抽象基底クラスなので、オブジェクトをつくってはいけない。

*/
/*&en
The ox above is abstract base class.

*/
/*&ja
2. オブジェクトの生成

オブジェクトを生成するために、new 関数群が用意されている。それぞれの関
数はオブジェクトを生成して、そのオブジェクトへのポインタを返す。
*/
/*&en
2. How to make CMObjects?

Use the following functions to generate an object.  It returns a
pointer to the object.  */ /*&common

new_cmo_null();
new_cmo_int32(int i);
new_cmo_string(char* s);
new_cmo_mathcap(cmo* ob);
new_cmo_list();
new_cmo_monomial32();
new_cmo_monomial32_size(int size);
new_cmo_zz();
new_cmo_zz_size(int size);
new_cmo_zz_set_si(int integer);
new_cmo_zz_noinit();
new_cmo_zero();
new_cmo_distributed_polynomial();
new_cmo_dms_generic();
new_cmo_ring_by_name(cmo* ob);
new_cmo_indeterminate(cmo* ob);
new_cmo_error2(cmo* ob);

*/
/*&ja
3. 高水準 API

高水準 API は「OpenXM クライアント」から利用することを前提に設計されている。

3.1 通信の開始   

通信を開始する場合には、次の関数のいずれかを利用する。
*/
/*&en
3. High-level API

High-level API is prepared to help an implementation of OpenXM clients.

3.1 How to make connections to OpenXM servers?

In order to open a connection to an OpenXM server, you need to call
ox_start() or to call ox_start_insecure_nonreverse().
*/
/*&common

ox_file_t ox_start(char* host, char* prog1, char* prog2);
ox_file_t ox_start_insecure_nonreverse(char* host, short portControl, short portStream);

*/
/*&ja
第一の関数は、ローカルマシン上に OpenXM サーバを起動し、そのサーバとの
間に"reverse モード"で通信路を開設する。通信に使われるポート番号は自動
的に生成される。host はローカルマシンのホスト名(あるいは "localhost")、
prog1 はコントロールサーバの実行ファイル名、
prog2 は計算サーバの実行ファイル名でなければならない。

第二の関数は、リモートマシン上に既に起動されている OpenXM サーバとの間に
通信路を開設する。通信に使われるポート番号は明示的に与えなければならない。
host はリモートマシンのホスト名、
portControl はコントロールサーバとの通信のためのポート番号、
portStream は計算サーバとの通信のためのポート番号である。

それぞれの関数はサーバ(正確には二つのサーバの組)の識別子を返す。
この識別子は高水準 API の各関数で利用される。

*/
/*&en
The ox_start() function invoke an OpenXM server on its local machine
and open a connection to the server with "reverse" mode.  The client
choose a port number of TCP/IP automatically.

The ox_start_insecure_nonreverse() function open a connection to an
OpenXM server run on a remote host and you need to provide port numbers.

*/
/*&ja
3.2 通信の終了

通信の終了のためには次の二つの関数が用意されている。

*/
/*&en
3.2 How to close connections to OpenXM servers?

In order to close a connection to an OpenXM server, you need to call
ox_close() or to call ox_shutdown().

*/
/*&common
void ox_close(ox_file_t sv);
void ox_shutdown(ox_file_t sv);

*/
/*&ja
第一の関数はコントロールサーバに SM_control_kill を送ることによって、
サーバを終了させる。第二の関数は計算サーバに SM_shutdown を送ることに
よって、サーバを終了させる(予定)。

*/
/*&ja
3.3 SM コマンドの送信
*/
/*&en
3.3 How to command to OpenXM stack machines?
*/
/*&common

void  ox_push_cmd(ox_file_t sv, int sm_code);

*/
/*&ja
サーバにスタックマシンコマンドを送る。コマンドはコマンド番号で与える。

*/
/*&en
ox_push_cmd() sends an operation code to an OpenXM stack machine.
See OpenXM/src/ox_toolkit/oxtag.h for a list of operation codes.

*/
/*&ja
3.4 CMO の送受信
*/
/*&en
3.4 How to receive a CMO?
*/
/*&common

void  ox_push_cmo(ox_file_t sv, cmo *c);
cmo*  ox_pop_cmo(ox_file_t sv);
char* ox_popString(ox_file_t sv);

*/
/*&ja
ox_push_cmo は cmo を送信、ox_pop_cmo は cmo を受信する。ox_popString
は cmo を文字列形式に変換して受信するが、変換の結果はサーバによって異
なる。

*/
/*&en
*/
/*&ja
3.5 スタック処理
*/
/*&common

int ox_pops(ox_file_t sv, int num);

*/
/*&ja
スタック上の num 個のオブジェクトを廃棄する。

*/
/*&ja
3.6 通信路のフラッシュ
*/
/*&common

int ox_flush(ox_file_t sv);

*/
/*&ja
通信路を flush する(実際には何もしない)。

*/
/*&ja
3.7 通信の中断
*/
/*&common

void ox_reset(ox_file_t sv);

*/
/*&ja
計算を中断する。

*/
/*&ja
3.8 ローカル言語で書かれたコマンドの評価
*/
/*&common

void ox_execute_string(ox_file_t sv, char* str);

*/
/*&ja
サーバのローカル言語で書かれた命令を評価し、結果をスタックに積む。

*/
/*&ja
3.9 関数呼び出し
*/
/*&common

int ox_cmo_rpc(ox_file_t sv, char *function, int argc, cmo *argv[]);

*/
/*&ja
function(argv[1], ...) を計算し、結果をスタックに積む。

*/
/*&ja
3.10 Mathcap の受信

*/
/*&common
cmo_mathcap* ox_mathcap(ox_file_t sv);

*/
/*&ja
Mathcap を受け取る。現在は Mathcap の処理はユーザプログラムに任されている。
いずれこの関数は廃止される予定。
*/
/*&ja

4. 低水準 API

低水準 API はファイルディスクリプタを直接利用する。

4.1 通信に使われるバイトオーダの決定
*/
/*&en

4. Low-level API.

In this section, ``fd'' is an identifier of an OpenXM connection.

4.1 How to decide a byte order of integers?

*/
/*&common
int decideByteOrderServer(int fd, int order);

*/
/*&ja
このツールキットは、サーバが開始されるときにはすでに通信路が設定されて
いるが、その通信路に用いるバイトオーダの決定は行われていないと仮定して
いる。詳しくは、高山-野呂, "OpenXM の設計と実装" を参照せよ。

(注意) クライアント側でのバイトオーダの設定は、高水準 API で自動的に行われる。
*/
/*&en
You need to call it when your OpenXM server is initialized.
This function always choose the network byte order 
as an expression for integers.
*/
/*&common

4.2 

*/
/*&common
int send_int32(int fd, int integer);
int receive_int32(int fd);

*/
/*&ja
fd に 32bit 整数を書き込む。
fd から 32bit 整数を読み込む。
*/
/*&en
send_int32() writes 32bits integer to an OpenXM connection.
receive_int32() reads 32bits integer from an OpenXM connection.
*/
/*&common

4.3 

*/
/*&common
int  send_cmo(int fd, cmo* m);
cmo* receive_cmo(int fd);

*/
/*&ja
fd に cmo を書き込む。
fd から cmo を読み込む。
*/
/*&en
send_cmo() writes an CMObject to an OpenXM connection.
receive_cmo() reads an CMObject from an OpenXM connection.
*/
/*&common

4.4

*/
/*&common
int next_serial();

*/
/*&ja
シリアルナンバを生成する。
*/
/*&en
next_serial() generates a serial number for ox message.
*/
/*&common

4.5

*/
/*&common
int  send_ox_tag(int fd, int tag);
int  receive_ox_tag(int fd);

*/
/*&ja
fd に OX メッセージのヘッダ(tag+serial#)を書き込む。シリアル番号は
自動的に生成される。
fd から OX メッセージのヘッダ(tag+serial#)を読み込む。
*/
/*&en
send_ox_tag() writes a tag and an automatically generated serial number 
of an ox message to an OpenXM conection.
receive_ox_tag() reads a tag and a serial number of an ox message.
*/
/*&common

4.6 

*/
/*&common
int  send_ox(int fd, ox* m);
int  send_ox_cmo(int fd, cmo* m);
void send_ox_command(int fd, int sm_command);

*/
/*&ja
ox メッセージを送信する。
*/

/*&ja

5. OX expression パーサ

*/
/*&ja
OpenXM C library には 文字列表現された 
OX expression および CMO expression から、
ox 構造体または cmo 構造体を生成するためのパーサが付属している。

ここではこのパーサについて説明する。

*/
/*&common
int setflag_parse(int flag);

*/
/*&ja
setflag_parse(PFLAG_ADDREV) によって、CMO の短縮表現を許す。

*/
/*&common
int init_parser(char *str);

*/
/*&ja
パーサが処理すべき文字列をセットする。

*/
/*&common
cmo *parse();

*/
/*&ja
Lisp 表現による OX expression, CMO expression の構文解析器。あらかじめ
設定された文字列を解析して ox 構造体、あるいは cmo 構造体を生成する。
*/
/*&ja

7. 付属プログラムについて

*/
/*&en

7. Sample programs.

*/
/*&common
testclient

*/
/*&ja
テスト用の小さな OpenXM クライアント。OX expression を入力して送信する
ことのみ可能。SM_popCMO, SM_popString を含むメッセージを送信した場合に
は、サーバから送られてくるメッセージを表示する。

*/
/*&en
This is a small OpenXM client.  We send an OX message by inputting an
OX expression and display data messages gotten from a server.

*/
/*&common
bconv

*/
/*&ja
バイトコードエンコーダ。OX expression あるいは CMO expression を入力す
ると、対応するバイト列を表示する。

*/
/*&en
A byte code encoder.  It shows a byte stream which corresponds to an
OX expression.

/*&common
ox_Xsample

*/
/*&ja
GUI 表示する OpenXM サーバのサンプル。

*/