1 |
the OpenIsis client API |
2 |
|
3 |
* overview |
4 |
|
5 |
The client API is the set of calls needed to contact an OpenIsis |
6 |
> Server server. |
7 |
Although the server may run in process, it is usually connected |
8 |
via the network, so this is called the "network API", |
9 |
indicated by the letter "N". |
10 |
|
11 |
With the exeption of some local control and utility calls, |
12 |
all calls are bound to a session and asynchronous in nature. |
13 |
The API may, however, be set for synchronous operation, |
14 |
meaning that attempts to retrieve results will block |
15 |
until results are available. |
16 |
Asynchronous operation may not be avialable on all connections. |
17 |
|
18 |
|
19 |
* basics |
20 |
|
21 |
From another point of view, there is only ONE call actually |
22 |
talking to the server, which is split in two halves: |
23 |
- nSend sends a request record to a server |
24 |
In synchronous mode, this will also call nRecv, |
25 |
so that the result record is available immediately. |
26 |
- nRecv receives all or part of a response from the server. |
27 |
In asynchronous mode, this may or may not give a response. |
28 |
|
29 |
At any time, there may be only one request active on a session. |
30 |
The session holds record buffers for both the request and response, |
31 |
which will be overwritten by any successive request. |
32 |
Records embedded within the response will be stripped out, |
33 |
so that they are available separately. |
34 |
|
35 |
|
36 |
* common communication parameters |
37 |
|
38 |
| tag | C-name | |
39 |
| 900 | COM_SID | |
40 |
| 901 | COM_SER | |
41 |
| 902 | COM_DBN | |
42 |
| 903 | COM_TMS | |
43 |
| 904 | COM_ROW | |
44 |
| 907 | COM_CFG | |
45 |
| 908 | COM_REC | |
46 |
|
47 |
|
48 |
* the request |
49 |
|
50 |
The request record may contain the following fields: |
51 |
- database |
52 |
This required field contains a database name. |
53 |
- view |
54 |
a named format to use. The view "#" selects rowids. |
55 |
- rowid |
56 |
Selects the record with the given rowid to be added to the result list. |
57 |
- query |
58 |
Selects the records matching query to be added to the result list. |
59 |
- terms |
60 |
selects a record containing terms to be added to the response. |
61 |
May contain subfields f (from inclusive) and t (to exclusive). |
62 |
- meta |
63 |
selects a record containing the FDT (for the given language). |
64 |
- maxid |
65 |
- a skip rowid |
66 |
- output size (number of records or terms) |
67 |
- a record to write |
68 |
|
69 |
The client session prepares the request with a field containing |
70 |
the session id and a request serial number. |
71 |
Since a client session is commonly used against one database only, |
72 |
it will remember the database used on the first call and |
73 |
automatically prepend a database field to any successive call, |
74 |
if necessary. |
75 |
|
76 |
| tag | C-name | |
77 |
| 920 | RQS_TYPE | |
78 |
| 921 | RQS_FLG | |
79 |
| 922 | RQS_QMOD | |
80 |
| 923 | RQS_SKIP | |
81 |
| 924 | RQS_SIZE | |
82 |
| 925 | RQS_KEY | |
83 |
| 926 | RQS_IDX | |
84 |
|
85 |
| no | C-name | description |
86 |
| 1 | RQST_OPEN | open db |
87 |
| 3 | RQST_CLOS | close db |
88 |
| 4 | RQST_MNT | mount db |
89 |
| 6 | RQST_LSDB | list available dbs |
90 |
| 10 | RQST_MROW | get maxrowid of db |
91 |
| 11 | RQST_QRY | exec query on db |
92 |
| 12 | RQST_READ | get rec for rowid |
93 |
| 20 | RQST_INS | insert rec |
94 |
| 21 | RQST_UPD | update rec |
95 |
| 22 | RQST_DEL | delete row |
96 |
| 30 | RQST_EVAL | command evaluation |
97 |
|
98 |
* the response |
99 |
|
100 |
The response record is made up of: |
101 |
- session id and serial |
102 |
- error |
103 |
- number processed items |
104 |
- embedded result records |
105 |
|
106 |
| tag | C-name | |
107 |
| 940 | RSP_DBID | |
108 |
| 941 | RSP_ERR | |
109 |
| 942 | RSP_MSG | |
110 |
| 943 | RSP_NUMT | |
111 |
| 944 | RSP_NUMR | |
112 |
| 945 | RSP_CERR | |
113 |
|
114 |
|
115 |
* client processing sequence |
116 |
|
117 |
a request is processed in the following steps: |
118 |
- create a new request record with session id, serial and database |
119 |
- fill in request fields |
120 |
- send the request by nSend. |
121 |
A server connection is opened as needed. |
122 |
In the asynchronous case, the sending socket is registered |
123 |
against some select loop in order to trigger writing, |
124 |
whenever the socket is writable. |
125 |
- receive the response by nRecv. |
126 |
Asynchronous handling analogous to writing. |
127 |
- completing the response in the session's response buffer |
128 |
may trigger some callback like calling some TCL code |
129 |
|
130 |
In synchronous mode, the complete send, receive and callback |
131 |
sequence will be finished on return of the initial send call. |
132 |
|
133 |
|
134 |
--- |
135 |
$Id: Client.txt,v 1.2 2003/06/30 09:49:17 kripke Exp $ |