Chapter 4.17:  User, Conference, Item, Site Variables

[TOP] [UP] [PREV] [NEXT]

The "regular" CML variables (e.g., "set var xyz" or "$(var)") are ephemeral: once the dedicated swebs server has exited, the values of those variables are lost.

CML also provides a set of variables that are persistent across sessions, and tied to a particular user, conference, item, or to the site as a whole.  Such variables may contain any amount of text, including newlines.  They provide a convenient way to extend a Caucus interface, and to customize how the interface appears to a particular user or in a particular conference or item.

Note that evaluating a variable is a fairly fast process.  (All variables for a particular user, conference, item or site, are loaded when needed, and cached.)  Setting a variable is much slower, since the values must be written to disk.

$user_var(user vname)

Evaluates to the value of userid user's variable called vname.

$set_user_var(user vname value)        {protected}

Sets userid user's variable vname to value.

$clear_user_var()        {protected}

Clears the user variable cache.

$list_user_var(user str)        {protected}

Evaluates to a blank-separated list of user's variable names that begin with str.  If str is not supplied, lists all of user's variables.

 

$conf_var(cnum vname)

Evaluates to the value of conference cnum's variable called vname.

$set_conf_var(cnum vname value)        {protected}

Sets conference cnum's variable vname to value.

$clear_conf_var()        {protected}

Clears the conference variable cache.

$list_conf_var(cnum str)        {protected}

Evaluates to a blank-separated list of conference cnum's variable names that begin with str.  If str is not supplied, lists all of cnum's variables.

 

$item_var(cnum inum vname)

Evaluates to the value of conference cnum, item inum's variable called vname.

$set_item_var(cnum inum vname value)        {protected}

Sets conference cnum, item inum's variable vname to value.

$clear_item_var()        {protected}

Clears the item variable cache.

$list_item_var(cnum inum str)        {protected}

Evaluates to a blank-separated list of conference cnum, item inum's variable names that begin with str.  If str is not supplied, lists all of item inum's variables.

 

$site_var(vname)

Evaluates to the value of the site variable called vname.  Site variables are "global" across an entire installation of Caucus and are available to all users.

$set_site_var(vname value)        {protected}

Sets site variable vname to value.

$clear_site_var()        {protected}

Clears the site variable cache.

$list_site_var(x  str)        {protected}

Evaluates to a blank-separated list of the site variable names that begin with str.  If str is not supplied, lists all of the site variables.  X is ignored but required (yes, it's a bug).

 

It is important to remember that all of these variables are cached for each user.  This makes getting the value of a variable very fast; but it also means that if someone else changes a variable, your copy of the variable may be out of date.

In most cases this doesn't matter.  But if you need to be sure that the value of a variable is up-to-date, call the appropriate $clear_... function immediately before using the variable.  For example, the code below:

     eval $clear_conf_var()
     set quote $conf_var($(cnum) daily_quote)

ensures that the user has the most up-to-date value of the conference variable "daily_quote".

If you have several processes that may intertwine reading and writing the same variables, you may need a locking mechanism to ensure that one process does not trash the work of another process.  Caucus provides a very simple set of locks:

$lock (number timeout)        {protected}

Attempts to secure an exclusive lock on number (a decimal value between 0 and 9,999,999 inclusive), within timeout seconds.  If the lock is granted within timeout seconds, the function returns and evaluates to 1.  Otherwise, if timeout seconds have elapsed and the lock can still not be granted (presumably because it is being held by another session), $lock() returns 0.

If either number or timeout are not supplied, $lock() fails immediately.  If timeout is zero, $lock() succeeds if and only if the lock can be granted immediately.

$unlock (number)

Unlocks (releases) a lock on number that was previously granted by $lock().