CML Reference Guide

Chapter 4.2:  Browser & Server Information


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

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

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

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()        {protected}
Evaluates to the full pathname of the top level CML directory, as set in swebd.conf.

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

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

Evaluates to the content of the parameter Config xyz in swebd.conf.  Use Config and $config() to define arbitrary values in swebd.conf and pass them to (any of) the CML interface(s).

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

"Flushes" any buffered output accumulated by swebs, passing it through swebsock and on to the user's browser.  Use $page_flush() in pages that may take a long time to complete. 

Technical Details:
See the Caucus Architecture Description for background on the processes and programs that interoperate to make Caucus work.  Swebsock waits for output from swebs for PageTime seconds; if it hasn't heard anything in that time, it assumes swebs is dead, and tries to start up a brand new Caucus session (a new swebs process).

If you have a page that takes a long time to complete, you can use $page_flush() to send incremental output on to swebsock.  Each call to $page_flush() resets the "clock" to 0, which then begins to count up to PageTime again.  Warning: using $page_flush() slows down things even further, so use it carefully.  (One possibility is to use the $time() and $pagetime() functions to determine when you truly need to call $page_flush().)

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

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

Evaluates to the userid supplied by the user, either through the browser pop-up dialog box (old login method), or through the cookie-based new login box.  (Generally indistinguishable from $userid().)

If which is 1 (or is not supplied), evaluates to the URL of the HTTP "referer" page (i.e., the page that led here, the page previous to this page).  If which is 0, evaluates to the URL of the referring page that entered Caucus (the page before the 1st page of the Caucus session).

Evaluates to the contents of the HTTP "accept" string, which is the list of file types that this browser is known to accept (handle) natively.  (Plug-ins are handled in a different manner.)

Evaluates to the HTTP "request_uri" string, which is the portion of the current page URL that follows the hostname, e.g. "/reg/swebsock/0006353/0299534/CC44/main/center.cml?3+0+x+x+x+x+x+x".

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

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

$timeout(secs)        {protected}
Evaluates to the most recent value of the Timeout parameter.  (After a CML page is evaluated, if Timeout seconds pass without a request for another page, the dedicated swebs process exits automatically.  See swebd.conf for the initial value of this parameter).

If secs is specified, Timeout is set to secs.  This function is frequently used to (a) effectively terminate the swebs process (setting Timeout to a very low value), or (b) where specific CML pages are invoked (such as a Caucus item page) from an outside (static) web page, and the resulting swebs should not "live" very long.

$goodbye()        {protected}
Obsolete.  See $timeout().  Tells the swebs server dedicated to this user to change its timeout period to one minute.  (Equivalent to $timeout(60).)  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)        {protected}
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.

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

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

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

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.

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().

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.

$dst()   (4.06)
Evaluates to "1" if daylight savings time is in effect in the server's local timezone, else "0".

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

Evaluates to the actual number of users who have "registered" with Caucus.

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

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

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

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.

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.

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

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.

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