Command dispatching and session management

Websh provides a command dispatching mechanism to produce, for example, different HTML pages within one "application", which is most likely one file on the file system. The name of the command to be used for a particular page is encoded in the querystring (see web::cmdurl for details on how to produce such querystrings). Command dispatching is initiated with the command web::dispatch. Commands are defined with web::command.

web::command

web::command ?cmdName? cmdBody

Registers cmdBody as cmdName. If cmdName is omitted, "default" is used.

web::getcommand

web::getcommand ?cmdName?

Retrieves the body of the command commandName or of the command "default" if cmdName is omitted.

web::cmdurl

web::cmdurl ?options? cmdName ?key-value-list?

web::cmdurl ?options? cmdName ?k1 v1 ... kN vN?

Options are: -notimestamp, and -urlformat

Generate URLs including querystring. By default, URLs are self-referencing, but the exact output is subject to configuration. The querystring is encrypted, using the encryption method specified by configuration (see web::config). If cmdName is "", no command parameter is produced in the query string.

-notimestamp
do not add a timestamp to the URL.
-urlformat list
specify what items will be used to format just this URL. Default is: {scriptname pathinfo querystring}.
Note: Use web::cmdurlcfg to define the url format for all URLs produced by web::cmdurl in one request.
scheme
include the protocol, only "http" and "https" are currently supported.
host
include the host name, e.g. "websh.com".
port
include the port, e.g. "80"
Trying to set this item without host will throw an error.
scriptname
include scriptname, e.g. "/cgi-bin/orderbooks".
pathinfo
include pathinfo, e.g. "/merchants/shop1".
querystring
include the querystring, e.g. "select=download".

Note

Note that there are two more commands that control the output of web::cmdurl: web::config cmdparam and web::config timeparam.

Example 2. web::cmdurl

	  % web::cmdurl -notimestamp -urlformat [list scheme host scriptname pathinfo querystring] "test"
	  http://websh.com/bin/returnmail/member?XDZuRD2rnsfHjFH
	  %
	

web::cmdurlcfg

web::cmdurlcfg ?options? ?key? ?value?

Command options are exactly like those of web::param.

web::cmdurlcfg option ?value?

Options are -scheme, -host, -port, -scriptname, -pathinfo, -querystring, -urlformat

If value is omitted, the current value is returned. Otherwise, the value is stored. Configuration for web::cmdurl. This command serves two purposes:

  1. management of static parameters
  2. configuration for web::cmdurl

By "static parameters", we mean those which are set for every page, instead of set on a per-page basis.

Management of static parameters

In order to set, retrieve, append or unset static parameters, use the syntax of the web::param command, for example:

web::cmdurlcfg -set key value
add the static parameter key.
web::cmdurlcfg
returns a list of all known static parameters.

Important: web::cmdurl compares every key from the static parameters (see web::cmdurlcfg) against the keys from the command line. The static parameter is only used if there is no parameter of the same name given on the command line.

Configuration for web::cmdurl

-protocol ?value?
protocol to be used. Defaults to the scheme used to access the page, which is overridden if the user gives sets a value.
-servername ?value?
server name to be used. Default: taken from request.
-port
port number to be used. Default: 80.
-scriptname
name of CGI executable. Default: taken from request.
-pathinfo
path info (path after scriptname). Default: taken from request.
-urlformat list
changes the urlformat permanently. See web::cmdurl for the description of this option.

In all cases, "web::cmdurlcfg -option value" sets the value of the given option and returns the value that was used before the change, while "web::cmdurlcfg -option" returns the current value. If no value has been set using web::cmdurlcfg, but is requested for the URL generation, the value from the request will be used. This value, however, can not be retrieved using web::cmdurlcfg.

Note that setting a value to an empty string amounts to unset. Note also: web::cmdurl compares every key from the static parameters see -->(web::cmdurlcfg) against the keys from the command line. The static parameter is only used if there is no such parameter on the command line.

Example 3. web::cmdurl

	  % web::cmdurl ""
	  ?XDqPtk34XvyPh41gUBo
	  % web::cmdurlcfg -scriptname bin/test_script
	  % web::cmdurl ""
	  bin/test_script?XDqPtk34XvyPh41gUBo
	  % web::cmdurlcfg -scriptname ""
	  % web::cmdurl ""
	  ?XDqPtk34XvyPh41gUBo
	  %
	

web::dispatch

web::dispatch ?options?

Options are: -cmd, -querystring, -postdata, -track and -hook.

Parse information and call a command.

-cmd cmdName
switch into command cmdName. If cmdName is an empty string, no command is called. By default, cmdName is taken from the querystring.
-querystring string
parse string as the querystring. If string is an empty string, querystring parsing is turned off. By default, querystring is taken from the request data (CGI environment or apache module request object).
-postdata string ?content_type?
parse string as POST data input with type content_type. content_type can be application/x-www-form-urlencoded or multipart/form-data; boundary=xxx. In the second case, content-type must specify the boundary as well. By default, POST data is taken from the request data.
If string is an empty string, postdata parsing is turned off.
Default for content_type is "application/x-www-form-urlencoded".
-postdata channelName content_length content_type
As above, but reads the POST data from channel channelName.
Use the keyword end for content_length to indicate that Websh should read all content.
Examples for content_type include:
  • multipart/form-data; boundary=xxxx
  • application/x-www-form-urlencoded
-track paramKeyList
Track a parameter: register it as "static" for the generation of URLs with web::cmdurl. Thus, each parameter with the key in paramKeyList will be repeated in every URL generated with web::cmdurl. See the documentation of web::cmdurl for details.
-hook code
Causes web::dispatch to eval code just before the command (from any source) is evaluated. When code is evaluated, the full request information has been parsed. That is, web::param, web::formvar etc. will have up-to-date information when code is evaluated.

Note that, if no command is passed to web::dispatch either in the querystring or with the -cmd option, web::dispatch will call the command "default".

Example 4. web::command and web::dispatch

	  % set tst {puts "On the hook"}
	  puts "On the hook"
	  % web::command acmd {puts "this is acmd"}
	  % web::dispatch -cmd acmd -querystring "" -postdata ""
	  this is acmd
	  % web::dispatch -cmd acmd -querystring "" -postdata "" -hook $tst
	  On the hook
	  this is acmd
	  %
	

Session management

Websh session management consits of two parts:

  • session id tracking
  • session context management

Session context managers are described in detail below (web::filecontext, web::cookiecontext). Session id tracking is managed by web::dispatch -track. The two parts are connected with the -attachto option of the session context manager. The control is as follows:

  • A user uses the Websh script for the first time.web::dispatch -track will not see any session id, and, consequently, not set the static parameter id.
  • Within the application, the session is initialized using mgr::init. init will find no static parameter id (which has been specified at creation time of the session manager using the -attachto option). Now, it tries to create a new session id. This will be possible if a session id generator has been specified when the manager was created using the -idgen option. From now, on the session id will be a static parameter, and will therefore be present in every URL generated with web::cmdurl.
  • The next time the user visits the Websh application using one of these URLs, web::dispatch will detect the session id, and mgr::init will directly load the corresponding session context without generating a new session id.

Example 5. Examples

See http://tcl.apache.org/websh/examples.ws3 for several sample application demonstrating Websh's session management facilities.