File: [local] / OpenXM / src / ox_toolkit / README (download)
Revision 1.6, Wed Dec 22 11:29:15 1999 UTC (24 years, 9 months ago) by ohara
Branch: MAIN
Changes since 1.5: +69 -21
lines
I wrote a part of Section 5 and 7. (in Japanese)
|
# Author: 小原功任 @ 金沢大学理学部計算科学教室
# URI: http://omega.s.kanazawa-u.ac.jp/ohara/
# $OpenXM: OpenXM/src/ox_toolkit/README,v 1.6 1999/12/22 11:29:15 ohara Exp $
/*&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 <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 の各関数で利用される。
*/
/*&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 サーバのサンプル。
*/