Caucus How-To: Sweba Scripts

I. Introduction

This page describes how to use the "sweba" program to run CML scripts in a command-line window.  If you are familiar with 'cron' (Unix) or the Schedule service (NT), you can also set up CML scripts to run by themselves, unattended.

CML was designed primarily as an interpreted language for producing dynamic "pages" that are sent to a user's web browser.  But the same language can be used to write scripts that manipulate the Caucus database, and write output to a window or a file, without being connected to a browser.  In this sense CML can be used like other classic scripting languages, such as Perl, Python, the Unix shell, or NT batch files.

In order to run CML scripts this way, your Caucus kit includes a program called sweba (in the SWEB directory) that runs CML scripts in this "stand-alone" fashion. 

In Caucus 4.0, the e-mail participation package uses sweba to import and export e-mail messages to and from conferences.  In Caucus 4.1, the new e-mail notification feature, and the CSNAP conference snapshot capability, both use sweba to run stand-alone CML scripts.  You can, of course, write your own CML scripts to run this way.

 

II: A Sample Stand-Alone CML Script.

This section describes writing and running a sample stand-alone CML script.  Our sample script displays the names of all of the conferences on the Caucus host, along with the name of the primary organizer of each conference, and his or her e-mail address.

The sample assumes that Caucus is installed in userid or account "caucus", and that the home directory is /home/caucus (Unix) or C:\caucus (NT).

1. Run as Caucus
In general, CML scripts should be run from (or "as") the Caucus userid (the id or account that owns the Caucus files).  It is possible to run CML scripts from other userids, but this can open up some potential security holes, as it may allow any user to run their own CML scripts.

2. Place CML scripts in subdirectories under CML
For the sample script, we're going to create a subdirectory /home/caucus/CML/SHOWCONFS, which will contain two files, showconfs.cml, and listconf.i.  The scripts could go anywhere, but this approach has the advantages of (a) being organized -- all CML packages live under the /home/caucus/CML directory, and (b) simplicity -- we can use the standard swebd.conf configuration file.  This last point will become clear shortly.

3. Create the actual scripts
The script showconfs.cml just says who is running the script, and iterates over all of the visible conferences.  It looks like:

   #---Showconfs.cml  Display list of all conferences, with primary
   #                  organizers and their e-mail addresses, on stdout.
   "I am '$per_name($userid()) ($userid())'.
   "I can see the conferences:
   "
   set dir SHOWCONFS
   for cnum in $cl_list()
      include $(dir)/listconf.i $(cnum)
   end

Listconf.i is an "include" file.  It does the work of actually listing a single conference:

   #---listconf.i  Display conference number inc(1), its primary
   #               organizer, and his/her e-mail address.
   set organizer $co_org($inc(1))
   " $cl_name  ($inc(1))  \
     $per_name ($(organizer)) ($(organizer))  \
     $user_var ($(organizer) e-mail)

Note that the output line that starts with " sends the output to stdout ("standard output") rather than to a web browser.  Each " line produces a single line of output (unlike what happens with a web browser).  That's why we've used the \ continuation character to put all three fields (conference name, primary organizer's name, and primary organizer's e-mail) onto one effective line, rather than starting each field with a ".

4. Run the script
To run the script under Unix, login to a command window as "caucus" and type:

   /home/caucus/SWEB/sweba /home/caucus/SWEB/swebd.conf SHOWCONFS/showconfs.cml

Similarly, under NT login as "caucus", open a command window, and type:

   C:\caucus\sweb\sweba.exe C:\caucus\sweb\swebd.conf SHOWCONFS\showconfs.cml

You can redirect the output from the script (under both Unix and NT) in the normal way, by appending a " >filename" to the end of either command line.

Running the script this way uses the standard swebd.conf configuration file, which tells sweba where to look for the CML files.  If you placed the CML files elsewhere, you would also need to make a copy of swebd.conf, and change the value of the parameter CML_Path.

5. Who am I, really?
Showconfs.cml doesn't really produce a list of all conferences; it lists all the conferences that the id "caucus" can see.  This can be a little confusing!  When you log in with a command-line window as "caucus", you have the same rights and access as if you were using Caucus via a browser with the (registered in Caucus) userid of "caucus".

It's generally a good idea for the Caucus manager to immediately register the id (in Caucus) that matches the login userid or account that owns the Caucus files, and use that id for administrative purposes.  In particular, it's a good idea to always add that id as an organizer for a new conference, so that the Caucus manager can help out the primary organizer if s/he needs assistance.  (In the case of this sample, that would also make all such conferences "visible" to the showconfs.cml script.) 

6. Programming Hints
Use the $readterm() function to read a line of input from the user running the script.  (This function only works with standalone scripts, it is a no-op when used from a browser.)

Use the $output() function to redirect the output of " lines to a file or files from within the script.  This is often the most convenient way of writing multiple files.

The CSNAP utility (provided with Caucus 4.1) in /home/caucus/CML/CSNAP is a good example of a substantial application built entirely in CML; comb the .cml and .i files there for clues on writing good CML scripts.