CML Reference Guide

Chapter 4.2:  Browser & Server Information

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

$userid()
Userid of the current user.  Defaults to effective userid of Caucus if no access-authorization userid supplied.  See $http_remote_user().

$cml_dir()
Evaluates to the directory name of the current CML file.  For example, if the URL is

http://screenporch.com/spi/swebsock/0008404/0083664/SP31/center.cml?1+x+x

then $cml_dir() will evaluate to "SP31".

$cml_page(url)
Given a full url, evaluates to the name of the CML or HTML file that is part of the url.  (All other information, including host, directory, query string, and page fragment, are removed.)

$cml_path()
Evaluates to the full pathname of the top level CML directory, as set in swebd.conf.

$caucus_path()
Evaluates to the full pathname of the Caucus home directory, as set in swebd.conf.

$caucus_lib()
Evaluates to the full pathname of the Caucus library directory, as set in swebd.conf.

$pagetime()
Evaluates to the PageTime parameter, as set in swebd.conf.  (In general, each CML page must complete within PageTime seconds.)

$http_lib()
Evaluates to the full URL of the Caucus library directory, as set in swebd.conf.

$http_user_agent()
Contents of the CGI environment variable HTTP_USER_AGENT.  Usually a multi-word string that describes the browser client program.

$http_remote_user()
Evaluates to the contents of the CGI environment variable HTTP_REMOTE_USER (or, if that is blank, to HTTP_AUTH_USER).  This is the userid supplied by the user in the pop-up dialog box.

$browser_format()
Evaluates to the browser language code number, as originally set by the parameter BROWSER_FORMAT in swebd.conf.

$set_browser_format(code)
Sets the browser format to language code number code, overriding the original value from swebd.conf.

$goodbye()
Tells the swebs server dedicated to this user to change its timeout period to one minute.  This is a graceful way to exit Caucus, and lowers system load.  It is not required, the swebs server will eventually timeout by itself.

$new_win(width height)
Functions like $t2url() translate URLs into HTML code that pops up a new window containing the URL.  New_win() sets the size of such a new window to be width pixels wide by height pixels high.  If width or height are not specified, new window size is left unchanged.

Evaluates to the new window width and height, respectively, separated by a space.

$unique()
Return a unique number each time.  Useful for tagging distinct instances of a particular page.

$version()
Returns version number of Caucus server software (e.g., "3.1.04").

$is_passwd()
Obsolete.  See new password functions.  Evaluates to '1' if a password changer program was defined in the configuration file swebd.conf, and '0' otherwise.

$reval(string)
Recursively evaluates string for CML functions.  If string contains a CML function, which when evaluated expands to a CML function, reval() makes sure that string is continually interpreted until no CML functions remain.

Without reval(), CML text is scanned only once for CML functions.

$protect(string)
Prevents certain CML functions from taking effect.  Any CML functions in string operate in a "protected" mode.  This is useful, for example, in evaluating CML code that may have been placed (by a user) in the text of an HTML response.

Functions which have no effect when evaluated inside $protect() include: shell(), silent(), passwd(), set_wrap(), any set_co...(), any set_it...(), any set_my...(), any ad_...(), any chg_...(), mac_define(), set_user_var(), and set_conf_var().

$time()
Returns the current time on the server, in "epoch" timing, i.e. an integral number of seconds since 00:00 Jan 1, 1970 GMT.  (See $epoch().)

$timezone()   (4.06)
Returns the difference, in seconds, between the local timezone and UTC (aka GMT).  This includes the effect of daylight savings time.  For example, for a host using Eastern Standard (not Daylight) Time, $timezone() returns -18000.

$lice_max_users()
Evaluates to the total number of Caucus users (or "seats") allowed by this license.  (A value of 0 means "unlimited".)

$lice_act_users()
Evaluates to the actual number of users who have "registered" with Caucus.

$lice_expires()
Returns the epoch time at which this license expires, or 0 if it does not expire.

$lice_customer()
Evaluates to the 7 character customer code (5 digits of customer number plus a two letter operating system code).

$lice_confs()
Evaluates to the maximum number of conferences allowed by this license (or 0 for unlimited).

$opsys()
Evaluates to a string describing the operating system of the host server.  The first word is either "unix" or "nt".  Subsequent words describe the particular version or platform.

$disk_failure()
Normally this function evaluates to an empty string.  If Caucus encounters a disk-write error (such as caused by a suddenly completely full disk), $disk_failure() evaluates to an error code number, followed by the full pathname of the file at which the error was encountered.

$reloaded()
Evaluates to 1 if the current page is a RELOAD of a recent page, (or if $cache_clear() was just called), and 0 otherwise. 

Typically this means the user pressed the RELOAD button on their browser, or pressed BACK several times and then hit RELOAD.  "Recent" means within the last 10 CML pages (which may translate to a smaller number of pages displayed in the browser.)

$cache_timeout(secs)
Sets the "cache timeout" to secs seconds.  Caucus caches certain information (specifically the number of items and responses in a conference), and forces a reload of this cache after a certain time.  The default value for this timeout is 300 seconds; use $cache_timeout() to set it to a different value.

$cache_clear()
Immediately clears the cache (see $cache_timeout).  Causes $reloaded() to return 1 for the rest of this page.