# Author: 小原功任 @ 金沢大学理学部計算科学教室
# URI:    http://omega.s.kanazawa-u.ac.jp/ohara/
# $OpenXM: OpenXM/src/ox_toolkit/README,v 1.4 1999/12/15 08:04:50 ohara Exp $

/*&ja ox_toolkit ユーザガイド

*/
/*&en A user's guide for ox_toolkit.

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

The OpenXM C libraiy has 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 is 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 similer to abstract base class; 
you never make an object of cmo class.

*/
/*&ja
1.2 OX オブジェクト
次のデータ型(構造体)が用意されている。
*/
/*&en
1.2 OX objects
The following structures is 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?

You may use new functions which generate an object and return its pointer.
*/
/*&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 for implementation of your OpenXM clients.

3.1 How to make connection to OpenXM server?

You may call ox_start or 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 の各関数で利用される。

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

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

*/
/*&en
3.2 How to close connection to OpenXM server?

You may call ox_close or 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 machine?

*/
/*&common
void  ox_push_cmd(ox_file_t sv, int sm_code);

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

*/
/*&en
This function send operation code to an OpenXM stack machine.
Table of opecode is defined in oxtag.h.
*/
/*&ja
3.4 CMO の送受信

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);

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

3.5 スタック処理

int ox_pops(ox_file_t sv, int num);

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

3.6

int ox_flush(ox_file_t sv);

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

3.7 

void ox_reset(ox_file_t sv);

計算を中断する。

3.8

void ox_execute_string(ox_file_t sv, char* str);

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

3.9 

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

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

3.10

cmo_mathcap* ox_mathcap(ox_file_t sv);

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

*/
/*&ja
4. 低水準 API

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

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

*/
/*&en
4. Low-level API.

4.1 How to decide a byte order of integers?

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

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

(注意) クライアント側でのバイトオーダの設定は、高水準 API で自動的に行われる。

*/
/*&common
4.2 

int send_int32(int fd, int integer);

*/
/*&ja
fd に 32bit 整数を書き込む。

*/
/*&common
int receive_int32(int fd);

*/
/*&ja
fd から 32bit 整数を読み込む。

*/
/*&common
4.3 

int  send_cmo(int fd, cmo* m);

*/
/*&ja
fd に cmo を書き込む。

*/
/*&common
cmo* receive_cmo(int fd);

*/
/*&ja
fd から cmo を読み込む。

4.4

int next_serial();

シリアルナンバを生成する。

4.5

int  send_ox_tag(int fd, int tag);

fd に OX メッセージのヘッダ(tag+id)を書き込む。
シリアル番号は自動的に生成される。

int  receive_ox_tag(int fd);

fd から OX メッセージのヘッダ(tag+id)を読み込む。

4.6 

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

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