| THE META-HTML LANGUAGE REFERENCE MANUAL

Stream Operators | [TOC] | Database Commands

## 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:

create-session delete-session get-session-var require-session | session-export session-import sessions-of-key set-session-timeout | set-session-var unset-session-var with-locked-session

Variables:

mhtml::sid-prefix | sid |  |

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.

`<delete-session>` | Simple

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

Check that the current session is valid and not timed out. If either of those things are true, the respective code is evaluated. Usually, the targets of TIMEOUT and MISSING are a `redirect` command which points to a page explaining the problem.

You could force an anonymous session with the following code:

      <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