1 |
dpavlin |
237 |
design of the Tcl interface |
2 |
|
|
|
3 |
|
|
* sessions and records |
4 |
|
|
|
5 |
|
|
The `objects´ in the OpenIsis Tcl interface are tcl commands using the |
6 |
|
|
same generic syntax like "array", "info", "interp" or the Tk widgets: |
7 |
|
|
$ |
8 |
|
|
name option ?arg arg ...? |
9 |
|
|
$ |
10 |
|
|
Like slave interpreters created by "interp create" or widgets created by |
11 |
|
|
"button", "entry" and the like, the name of the command can be choosen freely. |
12 |
|
|
|
13 |
|
|
There are two basic `objects´ to consider when using OpenIsis: |
14 |
|
|
- a record is a command giving access to it's fields. |
15 |
|
|
It provides access to single fields, a selection of fields, |
16 |
|
|
formatting or looping over the records contents. |
17 |
|
|
- a session creates new records from scratch or by |
18 |
|
|
fetching them from a database. |
19 |
|
|
A session also implements all record commands, |
20 |
|
|
giving access to it's configuration. |
21 |
|
|
Moreover a session has two embedded records, |
22 |
|
|
the request and the result. |
23 |
|
|
Finally, new sessions may be created. |
24 |
|
|
|
25 |
|
|
There is one builtin command introduced by OpenIsis giving access |
26 |
|
|
to the default session: the command "openIsis". |
27 |
|
|
If you do not intend to work with multiple sessions, |
28 |
|
|
you can switch the command openIsis to a remote session. |
29 |
|
|
|
30 |
|
|
|
31 |
|
|
* synchronous vs. event based processing |
32 |
|
|
|
33 |
|
|
Sessions within this context are always client sessions, |
34 |
|
|
and all but the default session (which is local) are connected to |
35 |
|
|
a remote server doing the actual work. Unlike the corresponding |
36 |
|
|
sessions on the server(s), which are dispatched to multiple threads |
37 |
|
|
in order to process multiple client's requests in parallel, |
38 |
|
|
the client sessions do essentially nothing but communicate with |
39 |
|
|
the server, which is handled pseudo-asynchronously within one thread |
40 |
|
|
by means of fileevents, compare |
41 |
|
|
> Client client basics. |
42 |
|
|
|
43 |
|
|
|
44 |
|
|
A session may be configured for event based processing |
45 |
|
|
by configuring a command to be executed upon request completion. |
46 |
|
|
|
47 |
|
|
Client sessions are asynchronous in nature and the server socket |
48 |
|
|
can (on Unix) easily be bound to a Tcl filehandler. |
49 |
|
|
If no command is specified, each request will block until completed. |
50 |
|
|
|
51 |
|
|
|
52 |
|
|
The default session, on the other hand, runs in the same process. |
53 |
|
|
Although it is possible to detach processing to a slave thread, |
54 |
|
|
integration is more demanding and system dependent and may not |
55 |
|
|
be available until some later version. Nonetheless, |
56 |
|
|
you may specify a command which will be executed after the completion. |
57 |
|
|
|
58 |
|
|
|
59 |
|
|
* the record options |
60 |
|
|
|
61 |
|
|
Following is a short outline of the options of the record command. |
62 |
|
|
Wherever a field parameter is used, it may be specified as either |
63 |
|
|
a decimal number or, if a dictionary is available for this record, |
64 |
|
|
as a field name. Field names may also be preceeded by a dash |
65 |
|
|
for an option style look. |
66 |
|
|
|
67 |
|
|
- del ?field ...? |
68 |
|
|
All values for all or the specified fields are removed. |
69 |
|
|
- get ?field ...? |
70 |
|
|
Returns a list of all or the specified field's values. |
71 |
|
|
If the one and only argument is -tags, returns a plain list with |
72 |
|
|
alternating tag and value elements. |
73 |
|
|
If the one and only argument is -tagnames and the record has a fdt, |
74 |
|
|
returns a plain list with alternating tagname and value elements. |
75 |
|
|
If the -nodefaults option is not given and one argument is a list |
76 |
|
|
of two elements, the first element specifies the field name (or id) |
77 |
|
|
and the second gives the default value if the field is not present. |
78 |
|
|
- add field value ?field value ...? |
79 |
|
|
Adds the specified pairs of fields and values. |
80 |
|
|
- set field ?value field value ...? |
81 |
|
|
With only a single field specified, |
82 |
|
|
returns the first value of the single specified field. |
83 |
|
|
If values are given, each field is set to the given value, |
84 |
|
|
overriding any previous value in the same place. |
85 |
|
|
In detail, for every sequence of the same field in the list, |
86 |
|
|
the values are assigned to existing occurences of this field |
87 |
|
|
in the record. Remaining occurences in the record are deleted. |
88 |
|
|
Remaining occurences in the parameter list are added. |
89 |
|
|
- do ?options? varname body |
90 |
|
|
loops body over fields of the record, |
91 |
|
|
assigning each value in turn to varname. |
92 |
|
|
body may use break and continue. |
93 |
|
|
options include: |
94 |
|
|
-fieldid varname to assign each field id to varname, |
95 |
|
|
-fieldname varname to assign each field name to varname, |
96 |
|
|
-field field to select only occurences of field, |
97 |
|
|
-fields fieldlist to select only occurences of fields in fieldlist |
98 |
|
|
- clone ?options? newname ?field value ...? |
99 |
|
|
clone this record to newname (which must not be a valid option). |
100 |
|
|
If newname is "-", some name starting with "openIsis" is choosen. |
101 |
|
|
Following field value pairs are applied as with set. |
102 |
|
|
options include: |
103 |
|
|
-empty to make an empty clone (sharing the same dictionary) |
104 |
|
|
- copy source |
105 |
|
|
append all fields of source record to this record bypassing any |
106 |
|
|
fdt informations. useful in situations where plain field copying |
107 |
|
|
of a previously created source record with embedded subrecords |
108 |
|
|
would violate the fdt of target record. |
109 |
|
|
- fmt ?options? format |
110 |
|
|
apply ("print") format. |
111 |
|
|
- done |
112 |
|
|
have the record go away. same effect as with Tcl's rename. |
113 |
|
|
- serialize |
114 |
|
|
set result to serialized record |
115 |
|
|
- deserialize string |
116 |
|
|
deserialize record from string |
117 |
|
|
- wrap -tag tagnumber | tagname ?-number count? ?-done? embed |
118 |
|
|
wrap record given by embed command into this record with length |
119 |
|
|
field tag. if count is given, append count as tag value and |
120 |
|
|
embed record to this record. if -done is given, have the embed |
121 |
|
|
record gone away. |
122 |
|
|
- db ?options? |
123 |
|
|
if no options are given, create a record command for the metadata |
124 |
|
|
of the db this record belongs to. otherwise apply options to a |
125 |
|
|
temporary metadata record. |
126 |
|
|
- fdt ?options? |
127 |
|
|
if no options are given, create a record command for the fdt |
128 |
|
|
of this record. otherwise apply options to a |
129 |
|
|
temporary fdt record. |
130 |
|
|
- rowid |
131 |
|
|
return mfn of record, useful only for records embedded in |
132 |
|
|
a sessions read or query response |
133 |
|
|
- .path ?option arg ...? |
134 |
|
|
access embedded record specified by path, |
135 |
|
|
where each component is of the form field or field[occ]. |
136 |
|
|
Without parameters, return 0 or 1 depending on availability of |
137 |
|
|
embedded rec. |
138 |
|
|
Example: rec .4[2] set -foo bar |
139 |
|
|
|
140 |
|
|
* the session options |
141 |
|
|
|
142 |
|
|
Note that a session supports the record options, |
143 |
|
|
applied to it's configuration. |
144 |
|
|
|
145 |
|
|
- db db ?options? |
146 |
|
|
if no options are given, create a record command for the metadata |
147 |
|
|
of db. otherwise apply options to a temporary metadata record. |
148 |
|
|
- fdt db ?options? |
149 |
|
|
if no options are given, create a record command for the fdt |
150 |
|
|
of db. otherwise apply options to a temporary fdt record. |
151 |
|
|
db names -syspar, -scheme, -fd, -fdt, -dbpar, -request, -response |
152 |
|
|
may be used to access built in system fdts. |
153 |
|
|
- new -schema name ?options? |
154 |
|
|
create a new scheme with configuration specified by options. |
155 |
|
|
- new ?-db db? ?name? |
156 |
|
|
create new record (for db) |
157 |
|
|
db names -syspar, -scheme, -fd, -fdt, -dbpar, -request, -response |
158 |
|
|
may be used to create a non-db record with built in system fdt. |
159 |
|
|
- req ?-db db? ?-param val? |
160 |
|
|
Apply the -param val settings to the request record (as with set), |
161 |
|
|
then send it to the server. See the |
162 |
|
|
> Client common client description |
163 |
|
|
for an overview of parameters. |
164 |
|
|
preset db for data record of an insert or update request, if specified. |
165 |
|
|
- recv |
166 |
|
|
Force wait for an response. Does nothing on a synchronous connection |
167 |
|
|
or if the response is already there. |
168 |
|
|
- .req ?-db db? ?options? |
169 |
|
|
access request record |
170 |
|
|
- .res ?option ...? |
171 |
|
|
("response/result") With further parameters, |
172 |
|
|
apply them to the result record (error, if not response there). |
173 |
|
|
Without parameters, return 0 or 1 depending on availability of response. |
174 |
|
|
|
175 |
|
|
The following fields can be set in the request record: |
176 |
|
|
- type |
177 |
|
|
- open, close |
178 |
|
|
a local database |
179 |
|
|
- mount |
180 |
|
|
a remote database |
181 |
|
|
- ls |
182 |
|
|
get a list all available (opened) databases |
183 |
|
|
- maxrow |
184 |
|
|
get maxrowid of database |
185 |
|
|
- query |
186 |
|
|
issue a query to database |
187 |
|
|
- read |
188 |
|
|
read one record from database |
189 |
|
|
- insert |
190 |
|
|
append new record to database |
191 |
|
|
- update |
192 |
|
|
update existing record on database |
193 |
|
|
- delete |
194 |
|
|
(not implemented yet) |
195 |
|
|
- db |
196 |
|
|
database name different from sessions default db |
197 |
|
|
- rowid |
198 |
|
|
mfn in read or update requests |
199 |
|
|
- config |
200 |
|
|
embedded configuration record when opening a local database |
201 |
|
|
- flen, fd |
202 |
|
|
fdt length and embedded fd records when opening a local database |
203 |
|
|
- rec |
204 |
|
|
embedded data record in insert or update requests |
205 |
|
|
- idx |
206 |
|
|
embedded index record in insert or update requests |
207 |
|
|
- flags |
208 |
|
|
bitwise-or of 1 (retrieve meta data of database with this request) |
209 |
|
|
and 2 (fetch records in addition to row ids in query request) |
210 |
|
|
- mode |
211 |
|
|
mode in query request |
212 |
|
|
- skip |
213 |
|
|
skip mfn in query request |
214 |
|
|
- size |
215 |
|
|
limit result set to size in query request |
216 |
|
|
- key |
217 |
|
|
key value in query request |
218 |
|
|
|
219 |
|
|
Dependent on the request type, the response may contain these fields: |
220 |
|
|
- db |
221 |
|
|
database name(s) |
222 |
|
|
- flen, fd |
223 |
|
|
database fdt length and embedded fd records |
224 |
|
|
- config |
225 |
|
|
embedded configuration database record |
226 |
|
|
- rowid |
227 |
|
|
mfn(s) (read, query, insert requests) |
228 |
|
|
- rec |
229 |
|
|
embedded data record(s) (read, query requests) |
230 |
|
|
- error, error2 |
231 |
|
|
error codes |
232 |
|
|
- msg |
233 |
|
|
error message if error is non-zero |
234 |
|
|
- total |
235 |
|
|
total size of query result set |
236 |
|
|
- size |
237 |
|
|
actual size of delivered result set |
238 |
|
|
|
239 |
|
|
|
240 |
|
|
* the session configuration |
241 |
|
|
|
242 |
|
|
- server |
243 |
|
|
Hostname |
244 |
|
|
- port |
245 |
|
|
- command |
246 |
|
|
command to be executed upon completion (async, if possible) |
247 |
|
|
- encoding |
248 |
|
|
encoding used by the server (default under windows is Cp850) |
249 |
|
|
- db (database) |
250 |
|
|
Name of default database on the server to be used for calls |
251 |
|
|
that don't specify one. |
252 |
|
|
- url |
253 |
|
|
specify server, port and db in url style |
254 |
|
|
- loglevel |
255 |
|
|
- logfile |
256 |
|
|
|
257 |
|
|
|
258 |
|
|
* see also |
259 |
|
|
|
260 |
|
|
> http://mini.net/tcl/969 Arts and Crafts of Tcl-Tk Programming |
261 |
|
|
|
262 |
|
|
Minimum used Tcl stuff: |
263 |
|
|
> http://sourceforge.net/projects/tcl Tcl/Tk 8.3.5 |
264 |
|
|
(for use with TclX, else 8.4.2 is ok) |
265 |
|
|
> http://www.hwaci.com/sw/tkhtml/ Tkhtml "2.0" |
266 |
|
|
|
267 |
|
|
The full story includes: |
268 |
|
|
> http://sourceforge.net/projects/tclx TclX 8.3.5 |
269 |
|
|
> http://sourceforge.net/projects/tix Tix 8.1.4 |
270 |
|
|
> http://sourceforge.net/projects/blt BLT 2.4z |
271 |
|
|
> http://sourceforge.net/projects/incrtcl [Incr Tcl] 3.2.1, [Incr Widgets] 4.0.1 |
272 |
|
|
> http://sourceforge.net/projects/tcllib Tcllib 1.3, BWidgets 1.4.1 |
273 |
|
|
> http://sourceforge.net/projects/tclxml tclXml/Dom/Xslt 2.6 |
274 |
|
|
|
275 |
|
|
Downloads: |
276 |
|
|
$ |
277 |
|
|
for dir in tcl tclx tix blt incrtcl tcllib tclxml oratcl; do |
278 |
|
|
http://belnet.dl.sourceforge.net/sourceforge/$dir |
279 |
|
|
done |
280 |
|
|
$ |
281 |
|
|
http://www.hwaci.com/sw/tkhtml/download.html |
282 |
|
|
|
283 |
|
|
|
284 |
|
|
--- |
285 |
|
|
$Id: Tcl.txt,v 1.15 2003/06/17 12:45:32 mawag Exp $ |