/[webpac]/trunk2/openisis/doc/Tcl.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 /trunk2/openisis/doc/Tcl.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 337 - (show annotations)
Thu Jun 10 19:22:40 2004 UTC (19 years, 9 months ago) by dpavlin
File MIME type: text/plain
File size: 10020 byte(s)
new trunk for webpac v2

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

  ViewVC Help
Powered by ViewVC 1.1.26