Context handling

Context handling
Prev		Next

web::context

Creation

web::context name

Creates a namespace name with the following commands:

name::subcommand args

Subcommands are: cset, cappend, clappend, cget, cexists, cunset, carray, cnames, delete, and dump. Manages data of the context. The subcommands behave like the Tcl commands with similar names.

name::cset key value: store value.
name::cappend key value ?value? ?...?: append value to existing value for key.
name::clappend key value ?value? ?...?: append value to existing list of values for key.
name::cget key ?default?: access the value for key key, or return default if key does not exist in the context. If default is omitted, an empty string is returned if key is unknown.
name::cexists key: returns true (1) if key exists in context, false (0) otherwise.
name::cunset key: remove key from context.
name::carray option key arg: array manipulation as known from the Tcl command array.
name::cnames ?pattern?: lists existing keys of context matching pattern.
name::delete: delete the context (same as namespace delete name)
name::dump: serialize context.

Example 12. web::context

% web::context sc
% sc::cset lang FR
FR
% # ... some code ...
% set lang [sc::cget lang EN]
FR
%

web::filecontext

Creation:

web::filecontext name ?options?

Options are: -perm, -path, -crypt, -idgen, and -attachto. Creates a namespace name to manage file-based context data:

name::subcommand args

Subcommands are: cset, cappend, clappend, cget, cexists, cunset, carray, cnames, init, new, commit, invalidate, and id. Manages file-based context data. The subcommands have their familiar behaviour of the Tcl commands with similar names. Please refer to the section context management for a description of the commands cset, cappend, clappend, cget, cexists, cunset, carray, and cnames.

name::init ?id?: load an existing session context with id id, or create a new one, if possible. Automation depends on the settings of the actual context manager settings, see below.
If you specify an id, you must decide when to create a new file and when to use the old one, if any, by yourself.
name::new ?id?: create a new session context. Automation depends on the settings of the actual context manager settings, see below.
name::commit: make session context persistent.
name::id: return id of session.
name::invalidate: delete session in memory and on file system.

Options:

web::filecontext name -perm perm

set the file permissions of the session context files perm is an unix-like octal value like 0644. If not specified, files are created with the permissions defined in web::config filepermissions, which again defaults to 0644.

web::filecontext name -path path: specify where to store session context files and how to name them. Suppose that the session id is 99. -path [file join .. data s%d.dat] would then cause filecontext to save the session context as ../data/s99.dat.
web::filecontext name -crypt boolean: Flag to turn crypting of session context on and off. Default is on.
web::filecontext name -idgen idgen: Sets command idgen to find a new session id. See doc of web::filecounter below for an implementation provided with Websh.
idgen is used in case that no id argument has been passed to init or new.
web::filecontext name -attachto idparam: the next using the querystring (this is one reason why the querystring is encrypted). After web::dispatch has parsed the querystring, web::param will report the current session id, if any. Note that you can maintain several sessions in parallel, and attach every session to its own idparam.
Using web::dispatch -track further automates the passing of session ids from request to request.

Note: Whenever you create a new file-based context, the context is initialized and you loose whatever information that you might have stored in the context before you initialized it as a file-based session context.

web::cookiecontext

Creation:

web::cookiecontext name ?options?

Options are: -expires, -path, -domain, -secure, -crypt, and -channel. Creates a namespace name to manage cookie-based context data:

name::subcommand args: Subcommands are: cset, cappend, clappend, cget, cexists, cunset, carray, cnames, init, new, commit, invalidate, and id.

name::init ?id?: load an existing session context (cookie must have been sent by the client).
name::new ?id?: create a new session context.
name::commit: send a cookie.
name::id: return id of session.
name::invalidate: delete session in memory and on client side.

Options:

web::cookiecontext name -expires time: set the expiration date of the cookie. Possible values for time are seconds (time in seconds since 1970-01-01) or date-string (any time string that Tcl can scan. Note that therefore many relative times, such as 24 hours, week, 2 weeks, tomorrow, etc. are possible. Default is now + 24 hours (i.e. cookie expires in 24 hours. (Please note that the behavior of some of these relative time specifiers changed from Tcl8.4 to Tcl8.5.) Use -expires "" to send a cookie without an expires parameter.
web::cookiecontext name -path path: set the path property of the cookie.
web::cookiecontext name -domain domain: set the domain property of the cookie.
web::cookiecontext name -secure boolean: set the secure property of the cookie.
web::cookiecontext name -crypt boolean: Flag to turn crypting of cookie context on and off. Default is on.
web::cookiecontext name -channel channelName: The response object to send the cookie to (see also web::response).

Because cookies are client-based, in principle no id is needed. Websh uses id to name the cookie, however, and the new, init, and load commands still require the id argument. (fixme: any changes?) Please note that property settings of a cookie context can only be changed before anything is output on the respective channel.

web::filecounter

This is a numeric sequence-number generator which stores its state in a file. Basic usage:

Creation:: web::filecounter name -filename fname ?options?
Options are: -min, -max, -seed, -incr, -mask, -wrap
-filename filename: Uses filename to store the current value (no default)
-min value: Uses this value as a minimum at start and after wrap, if wrap is true (default is 0).
-max value: Uses this value as a maximum, if wrap is true (default is 2147483647).
-seed value: If persistent file does not yet exists, use this value as a starting point (default is 0).
-incr value: Uses this value as an increment for each 'nextval' (default is 1).
-perms value: Sets the permissions on the newly created files. (Default is configured in web::config filepermissions, which defaults to 0644.)
-wrap boolean: Indicates whether this counter should wrap around its values (from min to max) (default is false).

After creation, a new command name is registered with the following subcommands:

name config: Return a flat list of key value pairs with the filecounter's configuration.
name nextval: Return the next value.
name curval: Return the current value, that is, the value that the last call to "nextval" or "getval" reported (as opposed to the current value in the file).
name getval: Return the current value in the file. (Do not increment file as in "nextval".)

Example 13. web::filecounter

% web::filecounter fc1 -filename test.dat
fc1
% fc1 config
file test.dat handle fc1 seed 0 min 0 max 2147483647 incr 1 perms 0644 wrap false curr {not valid}
% fc1 curval
web::filecounter: no current value available
% fc1 nextval
0
% fc1 config
file test.dat handle fc1 seed 0 min 0 max 2147483647 incr 1 perms 0644 wrap false curr 0
% fc1 nextval
1
% web::filecounter fc2 -filename test.dat
fc2
% fc2 curval
web::filecounter: no current value available
% fc2 getval
1
% fc2 nextval
2
% fc2 curval
2
% fc1 curval
1
% fc1 nextval
3
% fc2 getval
3
% web::filecounter fc3 -filename othertest.dat -min 1 -max 10 -seed 1 -incr 2 -wrap 1
fc3
% fc3 config
file othertest.dat handle fc3 seed 1 min 1 max 10 incr 2 perms 0644 wrap true curr {not valid}
% fc3 nextval
1
% fc3 nextval
3
%

Prev		Next
Logging	Home	File handling and file I/O