current/doc/Tcl.txt

design of the Tcl interface

*       sessions and records

The `objects´ in the OpenIsis Tcl interface are tcl commands using the
same generic syntax like "array", "info", "interp" or the Tk widgets:
$
name option ?arg arg ...?
$
Like slave interpreters created by "interp create" or widgets created by
"button", "entry" and the like, the name of the command can be choosen freely.

There are two basic `objects´ to consider when using OpenIsis:
-       a record is a command giving access to it's fields.
        It provides access to single fields, a selection of fields,
        formatting or looping over the records contents.
-       a session creates new records from scratch or by
        fetching them from a database.
        A session also implements all record commands,
        giving access to it's configuration.
        Moreover a session has two embedded records,
        the request and the result.
        Finally, new sessions may be created.

There is one builtin command introduced by OpenIsis giving access
to the default session: the command "openIsis".
If you do not intend to work with multiple sessions,
you can switch the command openIsis to a remote session.


*       synchronous vs. event based processing

Sessions within this context are always client sessions,
and all but the default session (which is local) are connected to
a remote server doing the actual work. Unlike the corresponding
sessions on the server(s), which are dispatched to multiple threads
in order to process multiple client's requests in parallel,
the client sessions do essentially nothing but communicate with
the server, which is handled pseudo-asynchronously within one thread
by means of fileevents, compare
>       Client  client basics.


A session may be configured for event based processing
by configuring a command to be executed upon request completion.

Client sessions are asynchronous in nature and the server socket
can (on Unix) easily be bound to a Tcl filehandler.
If no command is specified, each request will block until completed.


The default session, on the other hand, runs in the same process.
Although it is possible to detach processing to a slave thread,
integration is more demanding and system dependent and may not
be available until some later version. Nonetheless,
you may specify a command which will be executed after the completion.


*       the record options

Following is a short outline of the options of the record command.
Wherever a field parameter is used, it may be specified as either
a decimal number or, if a dictionary is available for this record,
as a field name. Field names may also be preceeded by a dash
for an option style look.

-       del ?field ...?
        All values for all or the specified fields are removed.
-       get ?field ...?
        Returns a list of all or the specified field's values.
        If the one and only argument is -tags, returns a plain list with
        alternating tag and value elements.
        If the one and only argument is -tagnames and the record has a fdt,
        returns a plain list with alternating tagname and value elements.
        If the -nodefaults option is not given and one argument is a list
        of two elements, the first element specifies the field name (or id)
        and the second gives the default value if the field is not present.
-       add field value ?field value ...?
        Adds the specified pairs of fields and values.
-       set field ?value field value ...?
        With only a single field specified,
        returns the first value of the single specified field.
        If values are given, each field is set to the given value,
        overriding any previous value in the same place.
        In detail, for every sequence of the same field in the list,
        the values are assigned to existing occurences of this field
        in the record. Remaining occurences in the record are deleted.
        Remaining occurences in the parameter list are added.
-       do ?options? varname body
        loops body over fields of the record,
        assigning each value in turn to varname.
        body may use break and continue.
        options include:
        -fieldid varname to assign each field id to varname,
        -fieldname varname to assign each field name to varname,
        -field field to select only occurences of field,
        -fields fieldlist to select only occurences of fields in fieldlist
-       clone ?options? newname ?field value ...?
        clone this record to newname (which must not be a valid option).
        If newname is "-", some name starting with "openIsis" is choosen.
        Following field value pairs are applied as with set.
        options include:
        -empty to make an empty clone (sharing the same dictionary)
-       copy source
        append all fields of source record to this record bypassing any
        fdt informations. useful in situations where plain field copying
        of a previously created source record with embedded subrecords
        would violate the fdt of target record.
-       fmt ?options? format
        apply ("print") format.
-       done
        have the record go away. same effect as with Tcl's rename.
-       serialize
        set result to serialized record
-       deserialize string
        deserialize record from string
-       wrap -tag tagnumber | tagname ?-number count? ?-done? embed
        wrap record given by embed command into this record with length
        field tag.  if count is given, append count as tag value and
        embed record to this record. if -done is given, have the embed
        record gone away.
-       db ?options?
        if no options are given, create a record command for the metadata
        of the db this record belongs to. otherwise apply options to a
        temporary metadata record.
-       fdt ?options?
        if no options are given, create a record command for the fdt
        of this record. otherwise apply options to a
        temporary fdt record.
-       rowid
        return mfn of record, useful only for records embedded in
        a sessions read or query response
-       .path ?option arg ...?
        access embedded record specified by path,
        where each component is of the form field or field[occ].
        Without parameters, return 0 or 1 depending on availability of
        embedded rec.
        Example: rec .4[2] set -foo bar

*       the session options

Note that a session supports the record options,
applied to it's configuration.

-       db db ?options?
        if no options are given, create a record command for the metadata
        of db. otherwise apply options to a temporary metadata record.
-       fdt db ?options?
        if no options are given, create a record command for the fdt
        of db. otherwise apply options to a temporary fdt record.
        db names -syspar, -scheme, -fd, -fdt, -dbpar, -request, -response
        may be used to access built in system fdts.
-       new -schema name ?options?
        create a new scheme with configuration specified by options.
-       new ?-db db? ?name?
        create new record (for db)
        db names -syspar, -scheme, -fd, -fdt, -dbpar, -request, -response
        may be used to create a non-db record with built in system fdt.
-       req ?-db db? ?-param val?
        Apply the -param val settings to the request record (as with set),
        then send it to the server.  See the
>       Client  common client description
        for an overview of parameters.
        preset db for data record of an insert or update request, if specified.
-       recv
        Force wait for an response. Does nothing on a synchronous connection
        or if the response is already there.
-       .req ?-db db? ?options?
        access request record
-       .res ?option ...?
        ("response/result") With further parameters,
        apply them to the result record (error, if not response there).
        Without parameters, return 0 or 1 depending on availability of response.

The following fields can be set in the request record:
-       type
        -       open, close
                a local database
        -       mount
                a remote database
        -       ls
                get a list all available (opened) databases
        -       maxrow
                get maxrowid of database
        -       query
                issue a query to database
        -       read
                read one record from database
        -       insert
                append new record to database
        -       update
                update existing record on database
        -       delete
                (not implemented yet)
-       db
        database name different from sessions default db
-       rowid
        mfn in read or update requests
-       config
        embedded configuration record when opening a local database
-       flen, fd
        fdt length and embedded fd records when opening a local database
-       rec
        embedded data record in insert or update requests
-       idx
        embedded index record in insert or update requests
-       flags
        bitwise-or of 1 (retrieve meta data of database with this request)
        and 2 (fetch records in addition to row ids in query request)
-       mode
        mode in query request
-       skip
        skip mfn in query request
-       size
        limit result set to size in query request
-       key
        key value in query request

Dependent on the request type, the response may contain these fields:
-       db
        database name(s)
-       flen, fd
        database fdt length and embedded fd records
-       config
        embedded configuration database record
-       rowid
        mfn(s) (read, query, insert requests)
-       rec
        embedded data record(s) (read, query requests)
-       error, error2
        error codes
-       msg
        error message if error is non-zero
-       total
        total size of query result set
-       size
        actual size of delivered result set


*       the session configuration

-       server
        Hostname
-       port
-       command
        command to be executed upon completion (async, if possible)
-       encoding
        encoding used by the server (default under windows is Cp850)
-       db (database)
        Name of default database on the server to be used for calls
        that don't specify one.
-       url
        specify server, port and db in url style
-       loglevel
-       logfile


*       see also

>       http://mini.net/tcl/969 Arts and Crafts of Tcl-Tk Programming

Minimum used Tcl stuff:
>       http://sourceforge.net/projects/tcl     Tcl/Tk 8.3.5
(for use with TclX, else 8.4.2 is ok)
>       http://www.hwaci.com/sw/tkhtml/ Tkhtml "2.0"

The full story includes:
>       http://sourceforge.net/projects/tclx    TclX 8.3.5
>       http://sourceforge.net/projects/tix     Tix 8.1.4
>       http://sourceforge.net/projects/blt     BLT 2.4z
>       http://sourceforge.net/projects/incrtcl [Incr Tcl] 3.2.1, [Incr Widgets] 4.0.1
>       http://sourceforge.net/projects/tcllib  Tcllib 1.3, BWidgets 1.4.1
>       http://sourceforge.net/projects/tclxml  tclXml/Dom/Xslt 2.6

Downloads:
$
for dir in tcl tclx tix blt incrtcl tcllib tclxml oratcl; do
http://belnet.dl.sourceforge.net/sourceforge/$dir
done
$
http://www.hwaci.com/sw/tkhtml/download.html


---
        $Id: Tcl.txt,v 1.15 2003/06/17 12:45:32 mawag Exp $
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 $