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