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 $