[BACK]Return to README CVS log [TXT][DIR] Up to [local] / OpenXM / src / ox_toolkit

Annotation of OpenXM/src/ox_toolkit/README, Revision 1.8

1.1       ohara       1: # Author: 小原功任 @ 金沢大学理学部計算科学教室
                      2: # URI:    http://omega.s.kanazawa-u.ac.jp/ohara/
1.8     ! ohara       3: # $OpenXM: OpenXM/src/ox_toolkit/README,v 1.7 2000/01/14 10:23:34 ohara Exp $
1.1       ohara       4:
1.4       ohara       5: /*&ja ox_toolkit ユーザガイド
1.1       ohara       6:
1.4       ohara       7: */
1.6       ohara       8: /*&en A user's guide for OpenXM C library.
1.4       ohara       9:
                     10: */
1.7       ohara      11: /* &ja いきさつ
                     12: このライブラリは ox_math および math2ox を開発するために設計された。
                     13: ライブラリ自身には、 Mathematica に依存した部分はない。
                     14: */
                     15: /* &en Introduction
                     16:
                     17: */
1.4       ohara      18: /*&ja
1.1       ohara      19: libox.a を利用するには次のヘッダファイルをインクルードする必要があります。
1.4       ohara      20: */
                     21: /*&en
                     22: How to use OpenXM C library?
                     23:
1.6       ohara      24: In order to use libox.a, you need to include the following header files:
1.4       ohara      25: */
                     26: /*&common
1.1       ohara      27:
                     28: #include <oxtag.h>
                     29: #include <ox.h>
                     30: #include <parse.h>
                     31:
1.4       ohara      32: */
                     33: /*&ja
1.2       ohara      34: 1. データ型
1.1       ohara      35:
1.2       ohara      36: このツールキットで定義されている各構造体の生成については次節を参照せよ。
                     37:
                     38: 1.1 CMO (Common Math Object)
1.1       ohara      39: 次のデータ型(構造体)が用意されている。
1.4       ohara      40: */
                     41: /*&en
                     42: 1. Types
                     43:
                     44: 1.1 CMO (Common Math Object)
1.6       ohara      45: The following structures are defined in ox.h:
1.4       ohara      46: */
                     47: /*&common
1.1       ohara      48:
                     49: cmo
                     50: cmo_null
                     51: cmo_int32
                     52: cmo_datum
                     53: cmo_string
                     54: cmo_mathcap
                     55: cmo_list
                     56: cmo_monomial32
                     57: cmo_zz
                     58: cmo_qq
                     59: cmo_zero
                     60: cmo_dms_generic
                     61: cmo_ring_by_name
                     62: cmo_distributed_polynomial
                     63: cmo_indeterminate
                     64: cmo_error2
                     65:
1.4       ohara      66: */
                     67: /*&ja
1.1       ohara      68: このうち cmo 型はいわば抽象基底クラスに相当するものであり、この型のオ
1.2       ohara      69: ブジェクトを明示的には生成されない。このクラスはポインタ型のキャストの
                     70: ために用意されている。また cmo_distributed_polynomial は cmo_list の派
                     71: 生クラスであると思ってもよい。
                     72:
1.4       ohara      73: */
                     74: /*&en
1.7       ohara      75: The cmo above is abstract base class; you never make an object of cmo
                     76: class.
1.4       ohara      77:
                     78: */
                     79: /*&ja
1.2       ohara      80: 1.2 OX オブジェクト
                     81: 次のデータ型(構造体)が用意されている。
1.4       ohara      82: */
                     83: /*&en
                     84: 1.2 OX objects
1.6       ohara      85: The following structures are defined in ox.h:
1.4       ohara      86: */
                     87: /*&common
1.2       ohara      88:
                     89: ox
                     90: ox_command
                     91: ox_data
                     92:
1.4       ohara      93: */
                     94: /*&ja
1.2       ohara      95: このうち、ox 型は抽象基底クラスなので、オブジェクトをつくってはいけない。
                     96:
1.4       ohara      97: */
                     98: /*&en
                     99: The ox above is abstract base class.
                    100:
                    101: */
                    102: /*&ja
1.2       ohara     103: 2. オブジェクトの生成
                    104:
                    105: オブジェクトを生成するために、new 関数群が用意されている。それぞれの関
                    106: 数はオブジェクトを生成して、そのオブジェクトへのポインタを返す。
1.4       ohara     107: */
                    108: /*&en
                    109: 2. How to make CMObjects?
                    110:
1.7       ohara     111: Use the following functions to generate an object.  It returns a
                    112: pointer to the object.  */ /*&common
1.1       ohara     113:
                    114: new_cmo_null();
                    115: new_cmo_int32(int i);
                    116: new_cmo_string(char* s);
                    117: new_cmo_mathcap(cmo* ob);
                    118: new_cmo_list();
                    119: new_cmo_monomial32();
                    120: new_cmo_monomial32_size(int size);
                    121: new_cmo_zz();
                    122: new_cmo_zz_size(int size);
                    123: new_cmo_zz_set_si(int integer);
                    124: new_cmo_zz_noinit();
                    125: new_cmo_zero();
                    126: new_cmo_distributed_polynomial();
                    127: new_cmo_dms_generic();
                    128: new_cmo_ring_by_name(cmo* ob);
                    129: new_cmo_indeterminate(cmo* ob);
                    130: new_cmo_error2(cmo* ob);
                    131:
1.4       ohara     132: */
                    133: /*&ja
1.2       ohara     134: 3. 高水準 API
                    135:
                    136: 高水準 API は「OpenXM クライアント」から利用することを前提に設計されている。
                    137:
                    138: 3.1 通信の開始
                    139:
                    140: 通信を開始する場合には、次の関数のいずれかを利用する。
1.4       ohara     141: */
                    142: /*&en
                    143: 3. High-level API
                    144:
1.6       ohara     145: High-level API is prepared to help an implementation of OpenXM clients.
1.4       ohara     146:
1.6       ohara     147: 3.1 How to make connections to OpenXM servers?
1.4       ohara     148:
1.7       ohara     149: In order to open a connection to an OpenXM server, you need to call
                    150: ox_start() or to call ox_start_insecure_nonreverse().
1.4       ohara     151: */
                    152: /*&common
1.2       ohara     153:
                    154: ox_file_t ox_start(char* host, char* prog1, char* prog2);
                    155: ox_file_t ox_start_insecure_nonreverse(char* host, short portControl, short portStream);
                    156:
1.4       ohara     157: */
                    158: /*&ja
1.2       ohara     159: 第一の関数は、ローカルマシン上に OpenXM サーバを起動し、そのサーバとの
                    160: 間に"reverse モード"で通信路を開設する。通信に使われるポート番号は自動
                    161: 的に生成される。host はローカルマシンのホスト名(あるいは "localhost")、
                    162: prog1 はコントロールサーバの実行ファイル名、
                    163: prog2 は計算サーバの実行ファイル名でなければならない。
                    164:
                    165: 第二の関数は、リモートマシン上に既に起動されている OpenXM サーバとの間に
                    166: 通信路を開設する。通信に使われるポート番号は明示的に与えなければならない。
                    167: host はリモートマシンのホスト名、
                    168: portControl はコントロールサーバとの通信のためのポート番号、
                    169: portStream は計算サーバとの通信のためのポート番号である。
                    170:
                    171: それぞれの関数はサーバ(正確には二つのサーバの組)の識別子を返す。
                    172: この識別子は高水準 API の各関数で利用される。
                    173:
1.4       ohara     174: */
1.7       ohara     175: /*&en
                    176: The ox_start() function invoke an OpenXM server on its local machine
                    177: and open a connection to the server with "reverse" mode.  The client
                    178: choose a port number of TCP/IP automatically.
                    179:
                    180: The ox_start_insecure_nonreverse() function open a connection to an
                    181: OpenXM server run on a remote host and you need to provide port numbers.
                    182:
                    183: */
1.4       ohara     184: /*&ja
1.2       ohara     185: 3.2 通信の終了
                    186:
                    187: 通信の終了のためには次の二つの関数が用意されている。
                    188:
1.4       ohara     189: */
                    190: /*&en
1.6       ohara     191: 3.2 How to close connections to OpenXM servers?
1.4       ohara     192:
1.7       ohara     193: In order to close a connection to an OpenXM server, you need to call
                    194: ox_close() or to call ox_shutdown().
1.4       ohara     195:
                    196: */
                    197: /*&common
1.2       ohara     198: void ox_close(ox_file_t sv);
                    199: void ox_shutdown(ox_file_t sv);
                    200:
1.4       ohara     201: */
                    202: /*&ja
1.2       ohara     203: 第一の関数はコントロールサーバに SM_control_kill を送ることによって、
                    204: サーバを終了させる。第二の関数は計算サーバに SM_shutdown を送ることに
                    205: よって、サーバを終了させる(予定)。
                    206:
1.7       ohara     207: */
1.4       ohara     208: /*&ja
1.2       ohara     209: 3.3 SM コマンドの送信
1.4       ohara     210: */
                    211: /*&en
1.6       ohara     212: 3.3 How to command to OpenXM stack machines?
1.4       ohara     213: */
                    214: /*&common
1.5       ohara     215:
1.2       ohara     216: void  ox_push_cmd(ox_file_t sv, int sm_code);
                    217:
1.4       ohara     218: */
                    219: /*&ja
1.2       ohara     220: サーバにスタックマシンコマンドを送る。コマンドはコマンド番号で与える。
1.7       ohara     221:
1.4       ohara     222: */
                    223: /*&en
1.5       ohara     224: ox_push_cmd() sends an operation code to an OpenXM stack machine.
1.7       ohara     225: See OpenXM/src/ox_toolkit/oxtag.h for a list of operation codes.
                    226:
1.4       ohara     227: */
                    228: /*&ja
1.2       ohara     229: 3.4 CMO の送受信
1.7       ohara     230: */
                    231: /*&en
                    232: 3.4 How to receive a CMO?
                    233: */
                    234: /*&common
1.2       ohara     235:
                    236: void  ox_push_cmo(ox_file_t sv, cmo *c);
                    237: cmo*  ox_pop_cmo(ox_file_t sv);
                    238: char* ox_popString(ox_file_t sv);
                    239:
1.7       ohara     240: */
                    241: /*&ja
1.2       ohara     242: ox_push_cmo は cmo を送信、ox_pop_cmo は cmo を受信する。ox_popString
                    243: は cmo を文字列形式に変換して受信するが、変換の結果はサーバによって異
                    244: なる。
                    245:
1.7       ohara     246: */
                    247: /*&en
                    248: */
                    249: /*&ja
1.2       ohara     250: 3.5 スタック処理
1.7       ohara     251: */
                    252: /*&common
1.2       ohara     253:
                    254: int ox_pops(ox_file_t sv, int num);
                    255:
1.7       ohara     256: */
                    257: /*&ja
1.2       ohara     258: スタック上の num 個のオブジェクトを廃棄する。
                    259:
1.7       ohara     260: */
                    261: /*&ja
                    262: 3.6 通信路のフラッシュ
                    263: */
                    264: /*&common
1.2       ohara     265:
                    266: int ox_flush(ox_file_t sv);
                    267:
1.7       ohara     268: */
                    269: /*&ja
1.2       ohara     270: 通信路を flush する(実際には何もしない)。
                    271:
1.7       ohara     272: */
                    273: /*&ja
                    274: 3.7 通信の中断
                    275: */
                    276: /*&common
1.2       ohara     277:
                    278: void ox_reset(ox_file_t sv);
                    279:
1.7       ohara     280: */
                    281: /*&ja
1.2       ohara     282: 計算を中断する。
                    283:
1.7       ohara     284: */
                    285: /*&ja
                    286: 3.8 ローカル言語で書かれたコマンドの評価
                    287: */
                    288: /*&common
1.2       ohara     289:
                    290: void ox_execute_string(ox_file_t sv, char* str);
                    291:
1.7       ohara     292: */
                    293: /*&ja
1.2       ohara     294: サーバのローカル言語で書かれた命令を評価し、結果をスタックに積む。
                    295:
1.7       ohara     296: */
                    297: /*&ja
                    298: 3.9 関数呼び出し
                    299: */
                    300: /*&common
1.2       ohara     301:
1.6       ohara     302: int ox_cmo_rpc(ox_file_t sv, char *function, int argc, cmo *argv[]);
1.2       ohara     303:
1.7       ohara     304: */
                    305: /*&ja
1.2       ohara     306: function(argv[1], ...) を計算し、結果をスタックに積む。
                    307:
1.7       ohara     308: */
                    309: /*&ja
                    310: 3.10 Mathcap の受信
1.2       ohara     311:
1.7       ohara     312: */
                    313: /*&common
1.2       ohara     314: cmo_mathcap* ox_mathcap(ox_file_t sv);
                    315:
1.7       ohara     316: */
                    317: /*&ja
1.2       ohara     318: Mathcap を受け取る。現在は Mathcap の処理はユーザプログラムに任されている。
                    319: いずれこの関数は廃止される予定。
1.4       ohara     320: */
                    321: /*&ja
1.5       ohara     322:
1.2       ohara     323: 4. 低水準 API
1.1       ohara     324:
1.3       ohara     325: 低水準 API はファイルディスクリプタを直接利用する。
1.1       ohara     326:
1.3       ohara     327: 4.1 通信に使われるバイトオーダの決定
1.4       ohara     328: */
                    329: /*&en
1.5       ohara     330:
1.4       ohara     331: 4. Low-level API.
                    332:
1.5       ohara     333: In this section, ``fd'' is an identifier of an OpenXM connection.
                    334:
1.4       ohara     335: 4.1 How to decide a byte order of integers?
1.7       ohara     336:
1.4       ohara     337: */
                    338: /*&common
1.3       ohara     339: int decideByteOrderServer(int fd, int order);
                    340:
1.4       ohara     341: */
                    342: /*&ja
1.3       ohara     343: このツールキットは、サーバが開始されるときにはすでに通信路が設定されて
                    344: いるが、その通信路に用いるバイトオーダの決定は行われていないと仮定して
                    345: いる。詳しくは、高山-野呂, "OpenXM の設計と実装" を参照せよ。
                    346:
                    347: (注意) クライアント側でのバイトオーダの設定は、高水準 API で自動的に行われる。
1.5       ohara     348: */
                    349: /*&en
1.6       ohara     350: You need to call it when your OpenXM server is initialized.
                    351: This function always choose the network byte order
                    352: as an expression for integers.
1.4       ohara     353: */
                    354: /*&common
1.5       ohara     355:
1.3       ohara     356: 4.2
                    357:
1.7       ohara     358: */
                    359: /*&common
1.3       ohara     360: int send_int32(int fd, int integer);
1.5       ohara     361: int receive_int32(int fd);
1.3       ohara     362:
1.4       ohara     363: */
                    364: /*&ja
1.3       ohara     365: fd に 32bit 整数を書き込む。
1.5       ohara     366: fd から 32bit 整数を読み込む。
                    367: */
                    368: /*&en
                    369: send_int32() writes 32bits integer to an OpenXM connection.
                    370: receive_int32() reads 32bits integer from an OpenXM connection.
1.4       ohara     371: */
                    372: /*&common
1.3       ohara     373:
                    374: 4.3
                    375:
1.7       ohara     376: */
                    377: /*&common
1.3       ohara     378: int  send_cmo(int fd, cmo* m);
1.5       ohara     379: cmo* receive_cmo(int fd);
1.3       ohara     380:
1.4       ohara     381: */
                    382: /*&ja
1.3       ohara     383: fd に cmo を書き込む。
1.5       ohara     384: fd から cmo を読み込む。
                    385: */
                    386: /*&en
                    387: send_cmo() writes an CMObject to an OpenXM connection.
                    388: receive_cmo() reads an CMObject from an OpenXM connection.
1.4       ohara     389: */
                    390: /*&common
1.3       ohara     391:
                    392: 4.4
                    393:
1.7       ohara     394: */
                    395: /*&common
1.3       ohara     396: int next_serial();
                    397:
1.5       ohara     398: */
                    399: /*&ja
1.3       ohara     400: シリアルナンバを生成する。
1.5       ohara     401: */
                    402: /*&en
1.6       ohara     403: next_serial() generates a serial number for ox message.
1.5       ohara     404: */
                    405: /*&common
1.3       ohara     406:
                    407: 4.5
                    408:
1.7       ohara     409: */
                    410: /*&common
1.3       ohara     411: int  send_ox_tag(int fd, int tag);
                    412: int  receive_ox_tag(int fd);
                    413:
1.5       ohara     414: */
                    415: /*&ja
                    416: fd に OX メッセージのヘッダ(tag+serial#)を書き込む。シリアル番号は
                    417: 自動的に生成される。
                    418: fd から OX メッセージのヘッダ(tag+serial#)を読み込む。
                    419: */
                    420: /*&en
1.6       ohara     421: send_ox_tag() writes a tag and an automatically generated serial number
1.5       ohara     422: of an ox message to an OpenXM conection.
1.6       ohara     423: receive_ox_tag() reads a tag and a serial number of an ox message.
1.5       ohara     424: */
                    425: /*&common
1.3       ohara     426:
                    427: 4.6
                    428:
1.7       ohara     429: */
                    430: /*&common
1.3       ohara     431: int  send_ox(int fd, ox* m);
                    432: int  send_ox_cmo(int fd, cmo* m);
                    433: void send_ox_command(int fd, int sm_command);
                    434:
1.5       ohara     435: */
                    436: /*&ja
1.3       ohara     437: ox メッセージを送信する。
1.6       ohara     438: */
                    439:
                    440: /*&ja
                    441:
                    442: 5. OX expression パーサ
                    443:
1.7       ohara     444: */
                    445: /*&ja
1.6       ohara     446: OpenXM C library には 文字列表現された
                    447: OX expression および CMO expression から、
                    448: ox 構造体または cmo 構造体を生成するためのパーサが付属している。
                    449:
                    450: ここではこのパーサについて説明する。
                    451:
1.7       ohara     452: */
                    453: /*&common
1.6       ohara     454: int setflag_parse(int flag);
                    455:
1.7       ohara     456: */
                    457: /*&ja
1.6       ohara     458: setflag_parse(PFLAG_ADDREV) によって、CMO の短縮表現を許す。
                    459:
1.7       ohara     460: */
                    461: /*&common
1.6       ohara     462: int init_parser(char *str);
                    463:
1.7       ohara     464: */
                    465: /*&ja
1.6       ohara     466: パーサが処理すべき文字列をセットする。
                    467:
1.7       ohara     468: */
                    469: /*&common
1.6       ohara     470: cmo *parse();
                    471:
1.7       ohara     472: */
                    473: /*&ja
1.6       ohara     474: Lisp 表現による OX expression, CMO expression の構文解析器。あらかじめ
                    475: 設定された文字列を解析して ox 構造体、あるいは cmo 構造体を生成する。
                    476: */
                    477: /*&ja
                    478:
                    479: 7. 付属プログラムについて
                    480:
1.7       ohara     481: */
                    482: /*&en
                    483:
                    484: 7. Sample programs.
                    485:
                    486: */
                    487: /*&common
1.6       ohara     488: testclient
                    489:
1.7       ohara     490: */
                    491: /*&ja
1.6       ohara     492: テスト用の小さな OpenXM クライアント。OX expression を入力して送信する
                    493: ことのみ可能。SM_popCMO, SM_popString を含むメッセージを送信した場合に
                    494: は、サーバから送られてくるメッセージを表示する。
                    495:
1.7       ohara     496: */
                    497: /*&en
                    498: This is a small OpenXM client.  We send an OX message by inputting an
                    499: OX expression and display data messages gotten from a server.
                    500:
                    501: */
                    502: /*&common
1.6       ohara     503: bconv
                    504:
1.7       ohara     505: */
                    506: /*&ja
1.6       ohara     507: バイトコードエンコーダ。OX expression あるいは CMO expression を入力す
                    508: ると、対応するバイト列を表示する。
                    509:
1.7       ohara     510: */
                    511: /*&en
                    512: A byte code encoder.  It shows a byte stream which corresponds to an
                    513: OX expression.
                    514:
                    515: /*&common
1.6       ohara     516: ox_Xsample
                    517:
1.7       ohara     518: */
                    519: /*&ja
1.6       ohara     520: GUI 表示する OpenXM サーバのサンプル。
                    521:
                    522: */
1.8     ! ohara     523: /*&ja
        !           524: 8. 付録
        !           525:
        !           526: 8.1 ox.c における関数の命名規則
        !           527:
        !           528: (1) receive_cmo 関数はCMOタグとデータ本体を受信する. この関数は CMOタ
        !           529: グの値が事前に分からないときに使用する. 返り値として、cmo へのポインタ
        !           530: を返す.
        !           531: (2) receive_cmo_X 関数は, CMOタグを親の関数で受信してから呼び出される
        !           532: 関数で、データ本体のみを受信し、cmo_X へのポインタを返す.  しかも、関
        !           533: 数内部で new_cmo_X 関数を呼び出す.
        !           534: (3) send_cmo 関数はCMOタグとデータ本体を送信する.
        !           535: (4) send_cmo_X 関数はCMOタグを親の関数で送信してから呼び出される関数で、
        !           536: データ本体のみを送信する.
        !           537: (5) ただし receive_ox_tag を除いて, receive_ox_X 関数は作らない.
        !           538: receive_cmo を利用する.
        !           539: (6) send_ox_X 関数は OX タグを含めて送信する.
        !           540: (7) ox_X 関数は一連の送受信を含むより抽象的な操作を表現する.  ox_X 関
        !           541: 数は、第一引数として、ox_file_t型の変数 sv をとる.
        !           542: (8) Y_cmo 関数と Y_cmo_X 関数の関係は次の通り:
        !           543: まず Y_cmo 関数で cmo のタグを処理し、タグを除いた残りの部分をY_cmo_X
        !           544: 関数が処理する.  cmo の内部に cmo_Z へのポインタがあるときには、その種
        !           545: 類によらずに Y_cmo 関数を呼び出す.
        !           546:
        !           547: */
        !           548:

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