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 $