current/doc/Client.txt

the OpenIsis client API

*       overview

The client API is the set of calls needed to contact an OpenIsis
>       Server  server.
Although the server may run in process, it is usually connected
via the network, so this is called the "network API",
indicated by the letter "N".

With the exeption of some local control and utility calls,
all calls are bound to a session and asynchronous in nature.
The API may, however, be set for synchronous operation,
meaning that attempts to retrieve results will block
until results are available.
Asynchronous operation may not be avialable on all connections.


*       basics

From another point of view, there is only ONE call actually
talking to the server, which is split in two halves:
-       nSend sends a request record to a server
        In synchronous mode, this will also call nRecv,
        so that the result record is available immediately.
-       nRecv receives all or part of a response from the server.
        In asynchronous mode, this may or may not give a response.

At any time, there may be only one request active on a session.
The session holds record buffers for both the request and response,
which will be overwritten by any successive request.
Records embedded within the response will be stripped out,
so that they are available separately.


*       common communication parameters

| tag | C-name  |
| 900 | COM_SID |
| 901 | COM_SER |
| 902 | COM_DBN |
| 903 | COM_TMS |
| 904 | COM_ROW |
| 907 | COM_CFG |
| 908 | COM_REC |


*       the request

The request record may contain the following fields:
-       database
        This required field contains a database name.
-       view
        a named format to use. The view "#" selects rowids.
-       rowid
        Selects the record with the given rowid to be added to the result list.
-       query
        Selects the records matching query to be added to the result list.
-       terms
        selects a record containing terms to be added to the response.
        May contain subfields f (from inclusive) and t (to exclusive).
-       meta
        selects a record containing the FDT (for the given language).
-       maxid
-       a skip rowid
-       output size (number of records or terms)
-       a record to write

The client session prepares the request with a field containing
the session id and a request serial number.
Since a client session is commonly used against one database only,
it will remember the database used on the first call and
automatically prepend a database field to any successive call,
if necessary.

| tag | C-name   |
| 920 | RQS_TYPE |
| 921 | RQS_FLG  |
| 922 | RQS_QMOD |
| 923 | RQS_SKIP |
| 924 | RQS_SIZE |
| 925 | RQS_KEY  |
| 926 | RQS_IDX  |

| no | C-name    | description
|  1 | RQST_OPEN | open db
|  3 | RQST_CLOS | close db
|  4 | RQST_MNT  | mount db
|  6 | RQST_LSDB | list available dbs
| 10 | RQST_MROW | get maxrowid of db
| 11 | RQST_QRY  | exec query on db
| 12 | RQST_READ | get rec for rowid
| 20 | RQST_INS  | insert rec
| 21 | RQST_UPD  | update rec
| 22 | RQST_DEL  | delete row
| 30 | RQST_EVAL | command evaluation

*       the response

The response record is made up of:
-       session id and serial
-       error
-       number processed items
-       embedded result records

| tag | C-name   |
| 940 | RSP_DBID |
| 941 | RSP_ERR  |
| 942 | RSP_MSG  |
| 943 | RSP_NUMT |
| 944 | RSP_NUMR |
| 945 | RSP_CERR |


*       client processing sequence

a request is processed in the following steps:
-       create a new request record with session id, serial and database
-       fill in request fields
-       send the request by nSend.
        A server connection is opened as needed.
        In the asynchronous case, the sending socket is registered
        against some select loop in order to trigger writing,
        whenever the socket is writable.
-       receive the response by nRecv.
        Asynchronous handling analogous to writing.
-       completing the response in the session's response buffer
        may trigger some callback like calling some TCL code

In synchronous mode, the complete send, receive and callback
sequence will be finished on return of the initial send call.


---
        $Id: Client.txt,v 1.2 2003/06/30 09:49:17 kripke Exp $
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 $