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: Set key to value.
name::cappend key value ?value? ?...?: Appends value to existing value for key.
name::clappend key value ?value? ?...?: Appends value to existing list of values for key.
name::cget key ?default?: Accesses the value for key key, or returns 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: Removes 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: Deletes the context (same as namespace delete name)
name::dump: Serializes context in a "source"-able format.

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?: Loads an existing session context with id id, or creates 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?: Creates a new session context. Automation depends on the settings of the actual context manager settings, see below.
name::commit: Makes session context persistent.
name::id: Returns id of session.
name::invalidate: Deletes session in memory and on file system.

Options:

web::filecontext name -perm perm

Sets 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: Specifies 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: Sets crypting of session context on or off. Default: 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 by Websh.
idgen is used in case that no id argument has been passed to init or new.
web::filecontext name -attachto idparam: Causes name::init to initialize with the id given in the querystring parameter idparam. (This is one important reason why the querystring should be encrypted). After web::dispatch has parsed the querystring, web::param will report the current session id in idparam, 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?: Loads an existing session context (cookie must have been sent by the client).
name::new ?id?: Creates a new session context.
name::commit: Sends a cookie (if no output to the page has been sent yet).
name::id: Returns id of session.
name::invalidate: Deletes session in memory and on client side.

Options:

web::cookiecontext name -expires time: Sets 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: Sets the path property of the cookie.
web::cookiecontext name -domain domain: Sets the domain property of the cookie.
web::cookiecontext name -secure boolean: Sets the secure property of the cookie.
web::cookiecontext name -crypt boolean: Sets crypting of cookie context on or off. Default: on.
web::cookiecontext name -channel channelName: Sets 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: 0.
-max value: Uses this value as a maximum, if wrap is true. Default: 2147483647.
-seed value: Usea this value as a starting point if persistent file does not exist yet. Default: 0.
-incr value: Uses this value as an increment for each 'nextval'. Default: 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 (back to min from max). Default: false.

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

name config: Returns a flat list of key value pairs with the filecounter's configuration.
name nextval: Returns the next value.
name curval: Returns 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: Returns the current value in the file. (Does 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