1 |
dpavlin |
237 |
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 $ |