CML Reference Guide

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)
Sets userid user's variable vname to value.

$clear_user_var()
Clears the user variable cache.

$list_user_var(user str)
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)
Sets conference cnum's variable vname to value.

$clear_conf_var()
Clears the conference variable cache.

$list_conf_var(cnum str)
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)
Sets conference cnum, item inum's variable vname to value.

$clear_item_var()
Clears the item variable cache.

$list_item_var(cnum inum str)
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)
Sets site variable vname to value.

$clear_site_var()
Clears the site variable cache.

$list_site_var(str)
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.

 

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:

     $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".

You may also wish to use cooperative "advisory" locks on variable sets; see the $lock() function in the object model pages.