OpenXM/src/ox_toolkit/README - diff

Return to README CVS log

Up to [local] / OpenXM / src / ox_toolkit

Diff for /OpenXM/src/ox_toolkit/README between version 1.5 and 1.15

-version 1.5, 1999/12/15 09:24:46
+version 1.15, 2000/11/21 07:59:08
 Line 1
 Line 1
 Line 1
  # 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 $
+ # $OpenXM: OpenXM/src/ox_toolkit/README,v 1.14 2000/11/20 17:59:34 ohara Exp $
  /*&ja ox_toolkit ユーザガイド
  */
- /*&en A user's guide for 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?
- The OpenXM C libraiy has header files:
+ In order to use libox.a, you need to include the following header files:
  */
  /*&common
- #include <oxtag.h>
+ #include <ox_toolkit.h>
- #include <ox.h>
- #include <parse.h>
  */
  /*&ja
-Line 35  The OpenXM C libraiy has header files:
+Line 40  The OpenXM C libraiy has header files:
 Line 35  The OpenXM C libraiy has header files:
 Line 40  The OpenXM C libraiy has header files:
 . Types
 .1 CMO (Common Math Object)
- The following structures is defined in ox.h:
+ The following structures are defined in ox_toolkit.h:
  */
  /*&common
-Line 65  cmo_error2
+Line 70  cmo_error2
 Line 65  cmo_error2
 Line 70  cmo_error2
  */
  /*&en
- The cmo above is similer to abstract base class;
+ The cmo above is abstract base class; you never make an object of cmo
- you never make an object of cmo class.
+ class.
  */
  /*&ja
-Line 75  you never make an object of cmo class.
+Line 80  you never make an object of cmo class.
 Line 75  you never make an object of cmo class.
 Line 80  you never make an object of cmo class.
  */
  /*&en
 .2 OX objects
- The following structures is defined in ox.h:
+ The following structures are defined in ox_toolkit.h:
  */
  /*&common
-Line 101  The ox above is abstract base class.
+Line 106  The ox above is abstract base class.
 Line 101  The ox above is abstract base class.
 Line 106  The ox above is abstract base class.
  /*&en
 . How to make CMObjects?
- You may use new functions which generate an object and return its pointer.
+ Use the following functions to generate an object.  It returns a
- */
+ pointer to the object.  */ /*&common
- /*&common
  new_cmo_null();
  new_cmo_int32(int i);
-Line 125  new_cmo_error2(cmo* ob);
+Line 129  new_cmo_error2(cmo* ob);
 Line 125  new_cmo_error2(cmo* ob);
 Line 129  new_cmo_error2(cmo* ob);
  */
  /*&ja
-. 高水準 API
+. コネクション
+ OXFILE は OpenXM での通信路を表現するクラスである。このクラスのオブジェ
+ クトを明示的には生成しないこと。必ずコンストラクタを利用しなければなら
+ ない。これはクライアントとサーバで接続時の手順が異なることに由来する。
+ バイトオーダに関連した処理はこのクラスのメソッドで実現される。このクラ
+ スのメソッドとして次のものが用意されている。
+.1 コンストラクタ
+ OXFILE *oxf_connect_active(char *hostname, short port);
+ 能動的に接続する場合のコンストラクタ。通常、サーバで利用する。
+ OXFILE *oxf_connect_passive(int listened);
+ 受動的に接続するためのコンストラクタ。
+ 内部で accept() を呼ぶので、listened には mysocketListen() の返した値が必要。
+ OXFILE *oxf_open(int fd);
+ インスタンスを生成するだけで、接続は行わない。すでにオープンされたファ
+ イルディスクリプタを fd に指定する。計算サーバでの利用を想定。
+.2 認証に関連したメソッド
+ int  oxf_confirm_client(OXFILE *oxfp, char *passwd);
+ クライアント側での認証を行う。返り値が1のときに成功、0のときに失敗。
+ int  oxf_confirm_server(OXFILE *oxfp, char *passwd);
+ サーバ側での認証を行う。常に成功する。
+ void oxf_determine_byteorder_client(OXFILE *oxfp);
+ void oxf_determine_byteorder_server(OXFILE *oxfp);
+ oxfp の指す通信路でのバイトオーダを決定し、oxfp のインスタンスを書き換える。
+ void oxf_setopt(OXFILE *oxfp, int mode);
+ oxfp の設定を行う。oxf_determine_byteorder_XXX() で用いられている。
+.3 その他のメソッド
+ int oxf_read(void *buffer, size_t size, size_t num, OXFILE *oxfp);
+ int oxf_write(void *buffer, size_t size, size_t num, OXFILE *oxfp);
+ void oxf_flush(OXFILE *oxfp);
+ void oxf_close(OXFILE *oxfp);
+ fread, fwrite, fflush, fclose に準拠。
+ */
+ /*&ja
+. 高水準 API(この記述は古いので使わないこと)
  高水準 API は「OpenXM クライアント」から利用することを前提に設計されている。
 .1 通信の開始
  通信を開始する場合には、次の関数のいずれかを利用する。
  */
  /*&en
 . High-level API
- High-level API is prepared for implementation of your OpenXM clients.
+ High-level API is prepared to help an implementation of OpenXM clients.
-.1 How to make connection to OpenXM server?
+.1 How to make connections to OpenXM servers?
- You may call ox_start or ox_start_insecure_nonreverse.
+ 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);
+ OXFILE *ox_start(char* host, char* prog1, char* prog2);
- ox_file_t ox_start_insecure_nonreverse(char* host, short portControl, short portStream);
+ OXFILE *ox_start_insecure_nonreverse(char* host, short portControl, short portStream);
  */
  /*&ja
-Line 165  portStream は計算サーバとの通信のためのポート番号であ�
+Line 224  portStream は計算サーバとの通信のためのポート番号であ�
 Line 165  portStream は計算サーバとの通信のためのポート番号であ�
 Line 224  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
 .2 通信の終了
  通信の終了のためには次の二つの関数が用意されている。
  */
  /*&en
-.2 How to close connection to OpenXM server?
+.2 How to close connections to OpenXM servers?
- You may call ox_close or ox_shutdown.
+ 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_close(OXFILE *sv);
- void ox_shutdown(ox_file_t sv);
+ void ox_shutdown(OXFILE *sv);
  */
  /*&ja
-Line 187  void ox_shutdown(ox_file_t sv);
+Line 256  void ox_shutdown(ox_file_t sv);
 Line 187  void ox_shutdown(ox_file_t sv);
 Line 256  void ox_shutdown(ox_file_t sv);
  サーバを終了させる。第二の関数は計算サーバに SM_shutdown を送ることに
  よって、サーバを終了させる(予定)。
- /*
+ */
  /*&ja
 .3 SM コマンドの送信
  */
  /*&en
-.3 How to command to OpenXM stack machine?
+.3 How to command to OpenXM stack machines?
  */
  /*&common
- void  ox_push_cmd(ox_file_t sv, int sm_code);
+ void  ox_push_cmd(OXFILE *sv, int sm_code);
  */
  /*&ja
  サーバにスタックマシンコマンドを送る。コマンドはコマンド番号で与える。
  */
  /*&en
  ox_push_cmd() sends an operation code to an OpenXM stack machine.
- Table of opecode is defined in oxtag.h.
+ See OpenXM/include/ox_toolkit_tags.h for a list of operation codes.
  */
  /*&ja
+.4 CMO の送受信
+ */
+ /*&en
+.4 How to receive a CMO?
+ */
+ /*&common
-.4 CMO の送受信
+ void  ox_push_cmo(OXFILE *sv, cmo *c);
+ cmo*  ox_pop_cmo(OXFILE *sv);
+ char* ox_popString(OXFILE *sv);
- void  ox_push_cmo(ox_file_t sv, cmo *c);
+ */
- cmo*  ox_pop_cmo(ox_file_t sv);
+ /*&ja
- char* ox_popString(ox_file_t sv);
  ox_push_cmo は cmo を送信、ox_pop_cmo は cmo を受信する。ox_popString
  は cmo を文字列形式に変換して受信するが、変換の結果はサーバによって異
  なる。
-.5 スタック処理
+ */
+ /*&en
+ */
+ /*&ja
+.5 スタック処理
+ */
+ /*&common
- int ox_pops(ox_file_t sv, int num);
+ int ox_pops(OXFILE *sv, int num);
+ */
+ /*&ja
  スタック上の num 個のオブジェクトを廃棄する。
-.6
+ */
+ /*&ja
+.6 通信路のフラッシュ
+ */
+ /*&common
- int ox_flush(ox_file_t sv);
+ int ox_flush(OXFILE *sv);
+ */
+ /*&ja
  通信路を flush する(実際には何もしない)。
-.7
+ */
+ /*&ja
+.7 通信の中断
+ */
+ /*&common
- void ox_reset(ox_file_t sv);
+ void ox_reset(OXFILE *sv);
+ */
+ /*&ja
  計算を中断する。
-.8
+ */
+ /*&ja
+.8 ローカル言語で書かれたコマンドの評価
+ */
+ /*&common
- void ox_execute_string(ox_file_t sv, char* str);
+ void ox_execute_string(OXFILE *sv, char* str);
+ */
+ /*&ja
  サーバのローカル言語で書かれた命令を評価し、結果をスタックに積む。
-.9
+ */
+ /*&ja
+.9 関数呼び出し
+ */
+ /*&common
- int   ox_cmo_rpc(ox_file_t sv, char *function, int argc, cmo *argv[]);
+ int ox_cmo_rpc(OXFILE *sv, char *function, int argc, cmo *argv[]);
+ */
+ /*&ja
  function(argv[1], ...) を計算し、結果をスタックに積む。
-.10
+ */
+ /*&ja
+.10 Mathcap の受信
- cmo_mathcap* ox_mathcap(ox_file_t sv);
+ */
+ /*&common
+ cmo_mathcap* ox_mathcap(OXFILE *sv);
+ */
+ /*&ja
  Mathcap を受け取る。現在は Mathcap の処理はユーザプログラムに任されている。
  いずれこの関数は廃止される予定。
  */
  /*&ja
 . 低水準 API
  低水準 API はファイルディスクリプタを直接利用する。
 .1 通信に使われるバイトオーダの決定
  */
  /*&en
 . Low-level API.
  In this section, ``fd'' is an identifier of an OpenXM connection.
 .1 How to decide a byte order of integers?
  */
  /*&common
  int decideByteOrderServer(int fd, int order);
  */
-Line 284  int decideByteOrderServer(int fd, int order);
+Line 399  int decideByteOrderServer(int fd, int order);
 Line 284  int decideByteOrderServer(int fd, int order);
 Line 399  int decideByteOrderServer(int fd, int order);
  (注意) クライアント側でのバイトオーダの設定は、高水準 API で自動的に行われる。
  */
  /*&en
- You must call it when your OpenXM server is initialized.
+ You need to call it when your OpenXM server is initialized.
- This function always choose the network byte order for integers.
+ This function always choose the network byte order
+ as an expression for integers.
  */
  /*&common
 .2
+ */
+ /*&common
  int send_int32(int fd, int integer);
  int receive_int32(int fd);
-Line 305  receive_int32() reads 32bits integer from an OpenXM co
+Line 423  receive_int32() reads 32bits integer from an OpenXM co
 Line 305  receive_int32() reads 32bits integer from an OpenXM co
 Line 423  receive_int32() reads 32bits integer from an OpenXM co
  */
  /*&common
 .3
+ */
+ /*&common
  int  send_cmo(int fd, cmo* m);
  cmo* receive_cmo(int fd);
-Line 321  receive_cmo() reads an CMObject from an OpenXM connect
+Line 441  receive_cmo() reads an CMObject from an OpenXM connect
 Line 321  receive_cmo() reads an CMObject from an OpenXM connect
 Line 441  receive_cmo() reads an CMObject from an OpenXM connect
  */
  /*&common
 .4
+ */
+ /*&common
  int next_serial();
  */
-Line 330  int next_serial();
+Line 452  int next_serial();
 Line 330  int next_serial();
 Line 452  int next_serial();
  シリアルナンバを生成する。
  */
  /*&en
- next_serial() generates serial number for ox message.
+ next_serial() generates a serial number for ox message.
  */
  /*&common
 .5
+ */
+ /*&common
  int  send_ox_tag(int fd, int tag);
  int  receive_ox_tag(int fd);
-Line 346  fd に OX メッセージのヘッダ(tag+serial#)を書き込む。シ
+Line 470  fd に OX メッセージのヘッダ(tag+serial#)を書き込む。シ
 Line 346  fd に OX メッセージのヘッダ(tag+serial#)を書き込む。シ
 Line 470  fd に OX メッセージのヘッダ(tag+serial#)を書き込む。シ
  fd から OX メッセージのヘッダ(tag+serial#)を読み込む。
  */
  /*&en
- send_ox_tag() writes a tag and automatically generated serial number
+ 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 serial number of an ox message.
+ receive_ox_tag() reads a tag and a serial number of an ox message.
  */
  /*&common
-.6
+.6 Sending OX messages.
+ */
+ /*&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 メッセージを送信する。
- */
+ OX メッセージを送信する。
+ */
+ /*&ja
+. OX expression パーサ
+ */
+ /*&en
+. Parser for OX expressions
+ */
+ /*&ja
+ OpenXM C library には 文字列表現された OX expression および CMO
+ expression から、ox 構造体または cmo 構造体を生成するためのパーサが付
+ 属している。ここではこのパーサについて説明する。
+ */
+ /*&en
+ We have a parser which generate an OX object or a CMO from a string
+ encoded OX/CMO expression.  In this section, we explain the parser.
+ */
+ /*&en
+.1 Setting an option
+ */
+ /*&ja
+.1 オプション
+ */
+ /*&common
+ int setflag_parse(int flag);
+ */
+ /*&ja
+ setflag_parse(PFLAG_ADDREV) によって、CMO の短縮表現を許す。
+ */
+ /*&en
+ We set an option for the parser.  If we call
+ setflag_parse(PFLAG_ADDREV), then the parser admits external
+ expressios.
+ */
+ /*&en
+.2 Initializing
+ */
+ /*&ja
+.2 初期化
+ */
+ /*&common
+ int init_parser(char *str);
+ */
+ /*&ja
+ パーサが処理すべき文字列をセットする。
+ */
+ /*&en
+ We give the parser an OX/CMO expression, that is, a Lisp style string.
+ */
+ /*&en
+.3 Getting an object
+ */
+ /*&ja
+.3 結果を得る
+ */
+ /*&common
+ cmo *parse();
+ */
+ /*&ja
+ Lisp 表現による OX expression, CMO expression の構文解析器。あらかじめ
+ 設定された文字列を解析して ox 構造体、あるいは cmo 構造体を生成する。
+ */
+ /*&en
+ The parser returns an OX/CMO object.  If the given string is illegal,
+ then the parser returns NULL.
+ */
+ /*&ja
+. Mathcap クラス
+ データベース
+.1. 概要
+ Mathcap クラスは OpenXM アプリケーションの Mathcap を表現するクラスで
+ ある。これは cmo_mathcap とは別物である。Mathcap クラスのインスタンス
+ は各通信路ごとに生成され、OXFILE クラスのメンバになる。このことは、複
+ 数の計算プロセスと同時に通信するクライアントを作成するためである。さて、
+ Mathcap クラスは、静的メンバももつ。これら静的メンバは、通信路から独立
+ した、 OpenXM アプリケーション自体の情報を保持するために用いられる。また。
+ インスタンスの生成時にもその情報は利用される。
+.2. メソッド
+ Mathcap クラスは mathcap.c で実装されている。ユーザは次の関数を介して、
+ Mathcap クラスにアクセスすることができる。
+ void mathcap_init(int version, char *id, char *sysname, int cmo[], sm_cmd[]);
+ 静的メンバを初期化する。Mathcap クラスのインスタンスを生成するまえに、
+ したがって、クライアントおよびサーバはプログラムを開始するときに、この
+ 関数を呼ばなければならない。cmo は、そのアプリケーションの利用する CMO
+ のタグのリストであって、0 で終端しなければならない。NULL のときには既
+ 定値が用いられる。sm_cmd も同様。
+ cmo_mathcap *mathcap_get(mathcap *this);
+ Mathcap クラスのインスタンスを cmo_mathcap クラスのインスタンスに変換する。
+ mathcap *mathcap_update(mathcap *this, cmo_mathcap *mc);
+ 通信相手から入手した cmo_mathcap オブジェクトを用いて、Mathcap クラスの
+ インスタンスを更新する。
+ */
+ /*&ja
+. 付属プログラムについて
+ */
+ /*&en
+. 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 サーバのサンプル。
+ */
+ /*&ja
+. 付録
+.1 ox.c における関数の命名規則
+ (1) receive_cmo 関数はCMOタグとデータ本体を受信する. この関数は CMOタ
+ グの値が事前に分からないときに使用する. 返り値として、cmo へのポインタ
+ を返す.
+ (2) receive_cmo_X 関数は, CMOタグを親の関数で受信してから呼び出される
+ 関数で、データ本体のみを受信し、cmo_X へのポインタを返す.  しかも、関
+ 数内部で new_cmo_X 関数を呼び出す.
+ (3) send_cmo 関数はCMOタグとデータ本体を送信する.
+ (4) send_cmo_X 関数はCMOタグを親の関数で送信してから呼び出される関数で、
+ データ本体のみを送信する.
+ (5) ただし receive_ox_tag を除いて, receive_ox_X 関数は作らない.
+ receive_cmo を利用する.
+ (6) send_ox_X 関数は OX タグを含めて送信する.
+ (7) ox_X 関数は一連の送受信を含むより抽象的な操作を表現する.  ox_X 関
+ 数は、第一引数として、ox_file_t型の変数 sv をとる.
+ (8) Y_cmo 関数と Y_cmo_X 関数の関係は次の通り:
+ まず Y_cmo 関数で cmo のタグを処理し、タグを除いた残りの部分をY_cmo_X
+ 関数が処理する.  cmo の内部に cmo_Z へのポインタがあるときには、その種
+ 類によらずに Y_cmo 関数を呼び出す.
+ */

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>