+++ /dev/null
-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 $
projects / webpac / blobdiff