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.

 

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

 

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

 

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

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