git.rot13.org Git - webpac/blob - openisis/doc/Tcl.txt

   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 $