|
THE META-HTML LANGUAGE REFERENCE MANUAL
|
Section Intro:
Session Operators
Synopsis:
Meta-HTML solves the problem of keeping state for a particular session, and it does it in a server and browser independent manner. Our method requires no additional CGI programs to be written, and you don't have to be a programmer to take advantage of it.
The basic essence of sessions is the session database. An entry in the session database can have exactly one of three possible states: present, missing, or timed out.
Commands:
Variables:
More Information:
Using the session commands, you can:
- Create a session.
This generates a unique entry in the session database, and returns that information as a session identifier (SID). You can associate a special key with the session at creation time, and you can decide whether the key must be unique or not. Session information can be located by either the SID or the key.
- Delete a session.
This removes the entry in the database associated with a specific SID, thus placing the session in the "missing" state.
- Change a session's timeout value.
With each session there is an associated timeout value, which is the number of minutes the session can live without any activity on the part of the user. When the session is created, a default timeout is installed; currently this is five minutes. Using set-session-timeout
, you can change this value. A special signal value of "0" causes the session to live forever (or until it is deleted with delete-session
).
- Require a session to be present.
Using the require-session
form allows you to check the state of the session, and optionally execute code for the cases where it is missing or timed out.
- Manipulate persistent variables.
Commands exist to associate a name with a value in the session database, to retrieve the value associated with a name in the session database, and to store and retrieve a group of associations at once from the session database.
Function Documentation
<create-session [VAR1[=MISSING-CODE]] ... [VARN=[MISSING-CODE]] [ALT=ALTCODE] [ALLOW-MULTIPLE]>
|
Simple
|
Create a session, and place the session identifier in the variable SID
. The key for the session is created by concatenating the values of the VARs together, separated by hyphens (-
). If a VAR doesn't have a value, but does have an optional MISSING-CODE assignment, then the session is not created, and the MISSING-CODE for that variable is evaluated. If all of the variables have values in the page (or have no missing action), and the session could not be created, then ALTCODE is evaluated if it is present.
Finally, if ALLOW-MULTIPLE is present, it indicates that the key does not have to be unique; it is enough that the session is created and a session ID returned.
Immediately end the current session. This never returns anything. The current session is indicated by the value of the variable SID
, so you can delete sessions other than your own by setting that variable. Also see sessions-of-key
.
<get-session-var [NAME...]>
|
Simple
|
Get the value for NAME from the session database record
associated with the current session.
<require-session [MISSING=MISSING-CODE] [TIMEOUT=TIMEOUT-CODE]>
|
Simple
|
<set-var anonymous="Anonymous Session">
<require-session
missing="<create-session anonymous allow-multiple>
<redirect <get-var SID>/<get-var mhtml::current-doc>"
timeout=<redirect /timed-out.mhtml>>
In the real world, additional care should be taken when returning new
URLs. The variable MHTML::COOKIE-COMPATIBLE is
true
when the attached browser/server combination is
capable of handling HTTP Cookies. In this case, it is preferable to
use the HTTP Cookie handling facilities instead of returning the
session ID in the URL. Here is how one might write the above example
to handle both cases:
<set-var anonymous="Anonymous Session" session-timeout=60>
<require-session
missing = <prog
<create-session anonymous allow-multiple>
<set-session-timeout <get-var session-timeout>>
<when <not <get-var mhtml::cookie-compatible>>>
<redirect <concat
<get-var mhtml::http-to-host>/
<get-var SID><get-var mhtml::relative-prefix>/
<get-var mhtml::current-doc>>>
</when>>
timeout = <prog
<set-var SID="">
<if <get-var mhtml::cookie-compatible>
<replace-page
<get-var mhtml::relative-prefix>/timedout.mhtml>
<redirect
<get-var mhtml::url-to-dir-sans-sid>/timedout.mhtml>>>>
For more detail on the built-in variables provided by the Meta-HTML
Server and CGI Engine, see Server Variables.
<session-export PACKAGE [TO-PACKAGE]>
|
Simple
|
Save the package variables of PACKAGE in the current session. If TO-PACKAGE is supplied, it indicates a new package name to assign to each variable from PACKAGE that is saved.
This function is quite useful when you wish to save all of the variables that were posted from the previous URL (presumably, that URL contained a form whose action pointed to the current URL) in the session database record for the current session. For example, if the previous URL posted the variables FOO
and BAR
, then executing
<session-export posted blue>
results in the session database containing values for
blue::FOO
and blue::BAR
. These values can either be looked up directly, or retrieved as a group (see session-import
for more information).
<session-import PACKAGE [TO-PACKAGE]>
|
Simple
|
Get the values of the session variables which belong to PACKAGE and set their values in the current package. If TO-PACKAGE is supplied, it is the name of the package which will receive the variable values. Thus, if the session data for the current session contains:
((BLUE::FOO . bar))
and then at a later time in the same session the command:
<session-import blue>
is given, then the variable FOO
in the current package will be set to bar
. This is extremely useful when bouncing back and forth between forms, see session-export
.
<sessions-of-key [KEY]>
|
Simple
|
Returns a newline separated list of the session ID's whose key matches
KEY. If KEY is not specified, or if it contains only
whitespace, all session ID's in the session database are returned.
Since the list is newline separated, it is suitable for assignment to
an array, as in:
<set-var sids[]=<sessions-of-key "On-Line Shopping">>
<set-session-timeout VALUE>
|
Simple
|
Make the current session time out after VALUE minutes.
You cannot supply the value of (0
); that is accomplished
with delete-session
.
<set-session-var [NAME=VALUE...]>
|
Simple
|
Give the NAMEs the associated VALUEs in
the session database record associated with the current session.
<unset-session-var [NAME] ...>
|
Simple
|
Make NAMEs have no value in the session database record associated with the current session.
<with-locked-session> body </with-locked-session>
|
Complex
|
Executes BODY in an environment where access to the current session is blocked. This allows concurrency (such as might be required when multiple GET
s are being processed for a single user) to take place without introducing any race conditions for access to the current session record of the session database.
Edit Section
Function Index
Variable Index

The
META-HTML
Reference Manual V1.4
Copyright © 1995, 1996,
Brian J. Fox,
1996, 1997 Universal Access Inc.
Found a bug? Send mail to
bug-manual@metahtml.com