Chapter 4.1:  CML State Functions

[TOP] [UP] [NEXT]

The CML state functions are the glue that ties a group of CML pages and a Sweb server together.  To understand more about why they exist, see the design document "The Web Caucus".  For the CML author, it is only necessary to understand where they must be used.

$host()

Evaluates to the host name (and http port number) of the current host.  This is a useful way to build HTML links that require the current host name, and still keep your CML code portable.  Example:

"<A HREF="http://$host()/dir/page.html">some text</A>

$pid()

Evaluates to the pid (process id) and security code for the swebs server that is dedicated to your browser.  You must include this in links to CML pages.  Example:

"<A HREF="http://$host()/sweb/swebsock/$pid()/SP/test.cml?15+bye">
" name</A>

$arg(n)

Evaluates to the N'th argument to this CML page.  In the previous example, clicking on link "name" will bring up the CML page test.cml.  In test.cml, $arg(1) will then evaluate to "15", and $arg(2) will evaluate to "bye".

$inc(n)

Evaluates to the N'th argument to this "include" file.  See the include directive.  Note that when $inc(n) is evaluated, it automatically "unquotes" itself, so that in the following code fragment:

in "including" file:	include file.i $quote(Hello, world)
in "file.i"	"$sizeof($inc(1))

$sizeof() evaluates to 2!

$form(myfield)

When a CML page is the "recipient" of an HTML form (as in <FORM ACTION="...">), the form data is available through the CML $form function.  The function evaluates to the data entered by the user in field myfield (as in NAME="myfield" in an <INPUT> or <TEXTAREA> HTML tag), or (in the case of TYPE="submit" fields) to the VALUE string for the button with NAME="myfield".  If there are multiple values for the field myfield (as in a <SELECT MULTIPLE> field), the values are concatenated together, separated by single spaces.  For a checkbox name="x", $form(x) evaluates to "on" if checked, and to nothing if not checked.

The $form() function transparently handles both standard ("application/x-www-form-urlencoded") and "multipart/form-data" forms.  $form() may be used only with METHOD=POST forms.

Multipart forms may be used with some browsers to upload an entire file, with an HTML tag of the form <INPUT TYPE="file" NAME="myfile">.  In this case, $form(myfile) evaluates to the name of a temporary file on the server host.  (The uploaded data has been placed in that file).  The temporary file will be automatically deleted when the swebs process exits (i.e., when the user's session is over).  The original name of the file is also available as $form(name.myfile)

$debug(n)        {protected}

N = 1 turns on debugging, which writes data to a logging file in /tmp. N = 0 turns off debugging.  The default is 0.

$caucus_id()

Evaluates to the name of the caucus userid, i.e. the userid that owns the Caucus files.