CML Reference Guide

Chapter 1:  Introduction


This document is the reference guide for CML, the Caucus Markup Language.  CML is a scripting language that combines HTML tags with simple programming constructs and database functions.  The CML language interpreter is the core of the World Wide Web interface to the Caucus conferencing system (hence the name).

This guide assumes considerable familiarity with HTML, the World Wide Web, Web browsers, and the Caucus conferencing system.  For more information about Caucus, see the Screen Porch home page at, and the Caucus FAQ at

This document is copyright © 1996-98 by Screen Porch LLC.  It may not be distributed or reprinted without permission from Screen Porch.  This is a work-in-progress, and will be frequently revised.  This edition corresponds to the CML interpreter provided with the "Caucus 4.08" package.  Corrections and comments (but not questions) should be sent to the author at [email protected].

1.1 Incompatible Changes in 4.0

For the most part, CML pages written for Caucus version 3.1 will work properly under version 4.0.  There is only one known change in version 4.0 that may cause incompatibilities.  The shell functions $shell(), $jshell(), $silent(), and $asynch() now always execute as the real userid of the Caucus subserver process (rather than, in some cases in 3.1, as the effective userid).

To run a shell command as the effective userid, use the new $xshell() function.

1.2 What's New in version 4.0

The following functions and features have been added since Caucus version 3.1.

New item & response functions
$re_epoch() response time in seconds
$re_bits() special property bits of response
$add_resp() Expanded way to add a response
$add_item() Expanded way to add an item
$re_copied() Information about "copied" responses
$re_copier() Who copied a "copied" response?
New logic, math, and string functions
$bit_and() bitwise and
$bit_or() bitwise or
$bit_not() bitwise negation
$hex2dec() hexadecimal to decimal conversion
$dec2hex() decimal to hexadecimal conversion
$random() Produce a random number
$epoch() Convert date to epoch timing
$timezone() Difference in seconds to UTC
$dateof() Convert epoch time to full date
$quote() quote text as one word
$unquote() undoes effect of $quote()
$asc2dec() decimal values of characters in string
New conference creation and manipulation functions
$create_conf() create a new conference
$co_remove() delete an existing conference
$co_makeorg() add yourself as an organizer to a conference
$set_co_org() change primary organizer of a conference
$co_rename() rename a conference
$jshell() japanese shell output
$xshell() Comprehensive shell access function
New file access functions
$rename() rename a file
$dirlist() list contents of a directory
$delfile() delete a file
$file_data() check contents of file against a range of values
New CML directives and language features
Eval New directive (to replace "set ignore")
Quit Immediately cease CML page processing
Macros Dynamically defineable and expandable macros
New system, license, and state information functions
$admin_mail() Administrator E-mail
$opsys() host server operating system
$caucus_lib() Caucus library directory path
$disk_failure() Did a disk-write error occur?
$cml_path() CML directory path
$caucus_path() full pathname of Caucus home directory
$http_lib() full URL of Caucus library directory
$lice_max_users()  total # users allowed by license
$lice_act_users() actual # users
$lice_expires() epoch time when license expires
$all_users() list of all caucus userids
$new_win() set size of windows created by $t2url()
$browser_format() browser language code
$set_browser_format() set browser language code
New sorting functions
$gen_sort() sort arbitrary list of words
$num_sort() sort arbitrary list of numbers
$triplet_sort() sort triplet list of item numbers
$item_sort() sort items by title, author, response date
New management functions
$mgr_list() display list of managers and their capabilities
$set_mgr_list() set list of managers and capabilities
$pw_...() new password functions
$per_delete() delete person
New miscellaneous functions
$cl_visible() is conference visible to this user?
$clear...() clear user/conf/item/site variable caches
1.3 What's New in version 4.08
$set_per_name Change a person's name
$set_per_phone Change a person's telephone number
$set_per_intro Change a person's brief introduction
$set_per_join Make a person a member of a conference
$charval Value of a character in a string (previously undocumented)