=================================================================== RCS file: /home/cvs/OpenXM/src/ox_toolkit/README,v retrieving revision 1.1 retrieving revision 1.6 diff -u -p -r1.1 -r1.6 --- OpenXM/src/ox_toolkit/README 1999/12/09 22:44:55 1.1 +++ OpenXM/src/ox_toolkit/README 1999/12/22 11:29:15 1.6 @@ -1,31 +1,44 @@ # Author: 小原功任 @ 金沢大学理学部計算科学教室 # URI: http://omega.s.kanazawa-u.ac.jp/ohara/ -# $OpenXM$ +# $OpenXM: OpenXM/src/ox_toolkit/README,v 1.5 1999/12/15 09:24:46 ohara Exp $ -☆ libox.a マニュアル。 +/*&ja ox_toolkit ユーザガイド +*/ +/*&en A user's guide for OpenXM C library. + +*/ +/*&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 #include #include -各構造体および関数の宣言はそれぞれのヘッダファイルを見てください。 -ここでは基本的な考え方について説明します。 +*/ +/*&ja +1. データ型 -まず、すべての CMO データはそのデータ型に対応した new 関数によって生成 -します。たとえば CMO_ZZ 型のオブジェクトは new_cmo_zz() 関数によって生 -成されます。 +このツールキットで定義されている各構造体の生成については次節を参照せよ。 -CMO データを送受信するには、CMO の種類によらず send_cmo(), -receive_cmo() を用います。これらの関数は OX ヘッダを扱いませんので、OX -メッセージを送受信するときには send_ox_tag(), receive_ox_tag() をその -前に呼ぶ必要があります。 - - -☆ CMO オブジェクト +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 @@ -43,11 +56,56 @@ cmo_distributed_polynomial cmo_indeterminate cmo_error2 +*/ +/*&ja このうち cmo 型はいわば抽象基底クラスに相当するものであり、この型のオ -ブジェクトをつくってはいけない。また cmo_distributed_polynomial は -cmo_list の派生クラスであると思ってもよい。ユーザはオブジェクトの実体を -直接扱ってはならない。必ず、new_... 関数、すなわち +ブジェクトを明示的には生成されない。このクラスはポインタ型のキャストの +ために用意されている。また 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); @@ -66,14 +124,289 @@ new_cmo_ring_by_name(cmo* ob); new_cmo_indeterminate(cmo* ob); new_cmo_error2(cmo* ob); -によってオブジェクトを生成し、ユーザはポインタのみを扱うこと。 +*/ +/*&ja +3. 高水準 API -☆ OX オブジェクト -次のデータ型(構造体)が用意されている。 +高水準 API は「OpenXM クライアント」から利用することを前提に設計されている。 -ox -ox_command -ox_data +3.1 通信の開始 -このうち、ox 型は抽象基底クラスなので、オブジェクトをつくってはいけない。 +通信を開始する場合には、次の関数のいずれかを利用する。 +*/ +/*&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 の各関数で利用される。 + +*/ +/*&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 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. + +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 + +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 + +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 + +int next_serial(); + +*/ +/*&ja +シリアルナンバを生成する。 +*/ +/*&en +next_serial() generates a serial number for ox message. +*/ +/*&common + +4.5 + +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 + +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 パーサ + +OpenXM C library には 文字列表現された +OX expression および CMO expression から、 +ox 構造体または cmo 構造体を生成するためのパーサが付属している。 + +ここではこのパーサについて説明する。 + +int setflag_parse(int flag); + +setflag_parse(PFLAG_ADDREV) によって、CMO の短縮表現を許す。 + +int init_parser(char *str); + +パーサが処理すべき文字列をセットする。 + +cmo *parse(); + +Lisp 表現による OX expression, CMO expression の構文解析器。あらかじめ +設定された文字列を解析して ox 構造体、あるいは cmo 構造体を生成する。 +*/ +/*&ja + +7. 付属プログラムについて + +testclient + +テスト用の小さな OpenXM クライアント。OX expression を入力して送信する +ことのみ可能。SM_popCMO, SM_popString を含むメッセージを送信した場合に +は、サーバから送られてくるメッセージを表示する。 + +bconv + +バイトコードエンコーダ。OX expression あるいは CMO expression を入力す +ると、対応するバイト列を表示する。 + +ox_Xsample + +GUI 表示する OpenXM サーバのサンプル。 + +*/