/[webpac]/openisis/current/doc/Client.txt
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /openisis/current/doc/Client.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 237 - (show annotations)
Mon Mar 8 17:43:12 2004 UTC (16 years, 7 months ago) by dpavlin
File MIME type: text/plain
File size: 3973 byte(s)
initial import of openisis 0.9.0 vendor drop

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 $

  ViewVC Help
Powered by ViewVC 1.1.26