Caucus 4.3 -- Data Definitions

Charles Roth 22 October 1999
Last revised:    29 September 2001

I. Introduction

The collection of CML files that make up the Caucus 4.3 interface use and manipulate a wide variety of data.  Most of the data is stored in the internal Caucus database, and manipulated by CML functions such as $cl_list(), $re_text(), etc., where the purpose and layout of the data is clear from the function descriptions in the CML Reference Guide.

There are, however, several other types of data that do not fall into this category.  As the Caucus 4.x interface grows more sophisticated (and complicated), there is a greater need for a centralized description of what those pieces of data are, and how they should be used.

That is the purpose of this document.  It is intended as a reference base for the on-going development of Caucus 4.x, as well as a guide for others who may be customizing their local Caucus installation. The remaining sections are:

  1. CML File Arguments
  2. Persistent Variables
  3. Locking
  4. Global Switches
  5. Manager Permissions
  6. Appendix A: Index to Persistent Variables

 

II. CML file arguments

Typically, each CML file in Caucus 4.x is invoked with a set of "arguments" that are passed to it via the URL.  For example, in the typical Caucus URL:

http://localhost/sweb/swebsock/0001083/0767162/CS41/viewitem.cml?8+4+3+1+0+0+1+x#here

the file is viewitem.cml, and the arguments are "8+4+3+1+0+0+1+x" -- everything after the "?" and before the "#".  (The "#here" is just an HTML "anchor name" that tells the browser to scroll the document to the anchor named "here".)  The value of these arguments is available to the CML file through the function $arg(): $arg(1) is "8", $arg(2) is "4", and so on. 

Caucus 4.x uses a (mostly) standard assigned meaning for each of these arguments -- there's nothing magic or inherent about those meanings, it's just what was chosen when the Caucus interface was implemented in CML.  The meanings are:

$arg(1)  Cache-defeater.  This argument is a number that increments by (at least) one for every page produced during your Caucus session.  It was an early device for forcing users' browsers to not cache a Caucus page, by ensuring that every URL was different from any previous URL.
 
$arg(2)  Calling page.  The CML functions $page_save() and $page_return() provide a mechanism for saving a Caucus URL in an indexed table.  Thus a page that, after some action, needs to return to the previously "calling" page can call $page_return() with the value of $arg(2).  But this means in turn that it is the responsibility of any Caucus page to include an index to itself as the 2nd arg to any page that it links to. 

Typically, in the calling page this sequence would look something like: 

   set nxt   $page_save (1 manage.cml \
                 $arg(2)+$arg(3)+$arg(4)+$arg(5)+$arg(6)+$arg(7)+$arg(8) \
                 # Caucus Management)
      ...

   "<A HREF=man_create.cml?$(nch)+$(nxt)+$arg(3)+$arg(4)+$arg(5)+\
         $arg(6)+$arg(7)+$arg(8)>Create a conference</A>
In the "called" page, the return would look something like: 
   "%location($(href)/$page_return ($arg(2) # \
                manage.cml?$(nch)+0+x+x+x+x+x+x))
 
$arg(3)  Conference number.  For any page that is "inside" a conference, $arg(3) is the conference number.  For other pages, this is usually "x".

Note that the file location.i, in particular, uses arguments 3, 4, and 5 to automatically build the "compass bar" that tells a Caucus user where they are.

 
$arg(4)  Item number.  For any page that is "inside" an item, or directly referenced from an item, $arg(4) is the item number.  For other pages, this is usually "x".
 
$arg(5)  Response number.  This is the number of the response we're at.  If you go to read the new responses, and you get to item 5, response 27, then response 27 is the first new response and that's "where you're at".  It is not the first (earliest) response actually loaded in the page, it's the one that you (and the browser) are initially positioned at.

If you go to another page that is considered "below" this level (such as the People, Notebook, or Search pages), the current response number is inherited -- which is another way of saying that the response number is just passed along as argument 5, and then those pages can allow an easy return to where you were.

As usual, if the response number is not relevant, this argument has the value "x".

 
$arg(6)  Starting response number.  In some cases (some calls to viewitem.cml), there is a need to explicitly specify the first (or "starting") response in an item display.  (Again, this is distinct from the current response number, $arg(5).)  Usually this has the value "x", which means we're either not in an item at all, or that viewitem.cml should calculate the proper starting response automatically.
 
$arg(7)  
$arg(8)		 Index into item triplet.  Arguments 7 and 8 are used together as a threading mechanism for traversing a list of items.  They allow viewitem.cml (and any pages it calls) to step along a list of items to be viewed, in order.  (When these arguments are not in use, they have the value "x".)

A specific response in the Caucus 4.x interface is represented as an item "triplet" -- e.g., "5 7 14" means conference 5, item 7, response 14.  A list of specific responses is represented by concatenating the triplets into one string, as in "5 7 14 5 8 1" (the same response as above, plus conference 5 item 8 response 1).  This is called a "triplet list".

Thus, whenever a user is reading a sequence of items (such as when reading all the new material in a Caucus Center or in a particular conference), Caucus generates the proper triplet list.  Viewitem.cml is then called repeatedly, to step down this list.

Argument 8 is the name of a variable that contains the triplet list in use.  Argument 7 is a word index into that variable.  Imagine a user viewing a list of 3 items, where the triplet list is stored in a variable called "nlist52".  When viewing the first item, argument 8 is "nlist52", and argument 7 is "1".  (Arguments 3, 4, and 5 are then read right out of the triplet starting at position 1 in nlist52.)

Reading the second item, argument 7 is now "4", and the conference, item, and response numbers are read out of the triplet starting at position 4 in nlist52.  And so on.

For further details about this procedure, see the header comments in viewitem.cml. 

 
$arg(9)  Multiple uses.  This argument is used for several different purposes, as described below:

Userid.  When going to a page about a person, argument 9 contains the userid of the person in question.

Saved response text.  While a user is editing text in an item or response box, there is occasionally a need to go out to another page, and then return and finish the editing.  (For example, while uploading a file into a response.)  In this situation, viewitem.cml saves the current text in a variable, and puts the name of the variable in $arg(9).  It also stores the "type" of text (word-wrapped, html, etc.) in $arg(10).

Group file.  The Caucus manager "manage user groups" page uses argument 9 to reference the filename that contains a particular group.

Lists of conferences.  The personal and "popular" conference lists use argument 9 to control whether a list of all conferences should be shown along with that page.

Searching.  The search pages use argument 9 to carry around the name of the variable that contains the triplet list of the remaining items to be searched.

 

III. Persistent variables

The Caucus 4.x interface CML code uses several sets of persistent "variables" to store user interface and personal preference information.  Persistent variables retain their values across Caucus sessions, hence the name.  Caucus persistent variables are fast to read but slow to write, which means that where possible they should be used only for rarely-updated values.  (See the functions $site_var(), $conf_var(), $item_var(), and $user_var() for more details.)

There are 4 possible "scopes" of these variables:

The functional groupings of persistent variables are described in detail below.  Typically a grouping only applies across one type or scope of variables, but occasionally there are interface elements that span two types.

  1. Public user information.  Some of the information that appears on a page about a user is stored in a set of user variables:
    e-mail Person's e-mail address
    homepage       URL of person's home page
    picture Full URL of person's uploaded picture

  2. Personal user preferences.  These user variables control precisely how different aspects of the user interface appear to the user:
    pageresps      How many responses should appear on a page?
    context How many responses should appear "before" the selected response (e.g., how many to show before the first new response).
    lmargin How much left margin should appear in response display?
    rmargin How much right margin...
    boxwide How wide (in fixed-pitch characters) should the response box be?
    boxhigh How high (in lines) should the response box be?
    cmlerr Warn user about any CML errors that occur?  (no, yes, pop=pop-up window)

  3. Personal Conference List.  These user variables control the operation of the personal conference list.
    my_confs  List of conferences, one per line
    item_detail    1 to show item/response breakout in detail, else 0
    sort_all  1 to keep the personal conference list sorted by name, else 0
    sort_new  1 to list conferences with new material first, else 0.  (Overrides sorting by name.)

  4. Window Control.  These user variables control the sizing of pop-up windows.
    xs_person
    ys_person         		 X and Y size, in pixels, of pop-up "person" window
    xs_indv
    ys_indv     		 X and Y size, in pixels, of pop-up "act on responses" window
    xs_goto
    ys_goto     		 X and Y size, in pixels, of pop-up "goto" window

  5. User Notebook.  These user variables store the data for, and control the operation of, an individual user's "notebook".
    mark_categories
    List of notebook categories, one entry per line.  Each line contains a category name (spaces replaced by underscores), and a flag to control if the category should appear on the Caucus Center page (1=yes, 0=no).
    mark_xxx
    Storage for a category called xxx, one entry per line.  Each line contains 5 fields: the CML page name; the arguments to that CML page; the page-anchor (e.g., "#here"); the page title (in $quote()'d form); and a "watch" code (1 means report new activity on this entry, else 0).

  6. Conference Home Page.  Mostly conference variables.  Controls look and feel of conference home page.
    home_page Word(s) appended to conference name to make conference home page title, e.g. "Home".
    defhome Number of default conference home page (if variant home pages are enabled).  See "confhome" in Local/switch.i for more details.
    defhomeP.A Show link to alternate conference home page A from conference home page P?  A and P are home page numbers as defined in Local/switch.i for variant conference home pages.
    greet1 Text of conference greeting (at top of conference home page)
    greet_tp Type of text (wordwrap, literal, html, cml) of conference greeting
    columns Which columns of information should be displayed, in which order, in list of items on conference home page.  Values include: empty, number, title, author, new, last, last_date, frozen.
    default_list   Controls which items are listed by default (for all users) on the conference home page.  The first word is the selection code, one of: all, new, num, name, author, since, past, mine, forgot, or none.  The rest of the words are the selection data, such as a list of item numbers (for code "num"), or item title keywords (code "name").  If empty, implies all.  See confhome.cml and iselect.i.
    ikey.cnum User variable.  Overrides default_list to control the list of items for conference cnum for this user.  Same values as default_list.

  7. Conference Information.  Conference variables.  Storage for information "about" conference, primarily for deciding whether to join a conference or not.
    description    One-liner describing conference; appears on Caucus Center page or other lists of conferences.
    intro1 Text of conference introduction (appears if confirmation of joining a conference is turned on).
    intro_tp Type of text (wordwrap, literal, html, cml) of conference introduction

  8. Conference User Capabilities.  Conference variables.  Controls specific abilities of users (for info that is not already stored in the direct Caucus database).
    useforms (obsolete)
    icreator Allow item creator to freeze, delete, or rename item?
    allowhtml Allow HTML text in items and responses?
    allowcml Allow CML text in items and responses?
    allowanon Allow anonymous items?
    allowcopy Allow copying items and responses in (and into) this conference?
    changelimit Limit (in # of seconds) during which user may change a response.  Empty means always, 0 means never.
    tag_list_user  List of HTML tags allowed and disallowed for ordinary users in HTML or CML text in items and responses.  See the definition of the default tag_list in Local/switch2.i for details on the format of this list.
    tag_list_org Same as tag_list_user, but as applied to organizers.

  9. Conference E-mail Notification.  Conference variables.  A conference organizer may define automatic "e-mail notification" of new material to all members of a conference.  These variables control if notification is done, how often (schedules), and on which groups of items.  See the file cus_en.cml for more information.  Et is the epoch-time of the creation of an item group, which uniquely identifies a group in a conference.

    en_run
    (Site variable.)  Inherits value of global switch en_run.  Does e-notification run every hour?  (1=yes, 0=no)
    en_allow
    Manager has specifically allowed notification for this conference (1=yes, 0/empty=no).  (Overrides the global switch e_notify.)
    en_on
    Is e-notification enabled (by the organizer) in this conference?  (1=yes, 0/empty = no).
    i_notify
    Allow individual e-mail notification schedules (which may override the organizer-defined schedule) (1=yes, 0/empty=no)
    en_items-et
    The first five words are control information for an item group: item group active (1 or 0), include newly created items (1 or 0), report on newly created items (1 or 0), highest-reported item (number), derived from organizer group (epoch time value if yes, else 0).  The remainder of the string is the "english" form of the list of items, as reported by $it_pack().
    en_dates-et
    Controls the days on which notification is done for this item group.  The first word is week days (1) vs month days (0).  The rest is the list of day numbers.
    en_hours-et
    Controls the times at which notification is done for this item group.  The first word is "detailed report" (1) vs summary report (0).  (This feature has not been implemented in 4.3; only summary reports are produced.)  The rest is the list of hour numbers (0 to 23).

  10. Personal E-mail Notification.  User and conference variables.  If individual e-notification is enabled, these variables add additional e-mail notification item groups, or override existing organizer-defined groups.

    en_user_uid
    (Conference variable.)  Exists (not empty) if userid uid has defined an individual e-mail notification schedule.

    (The rest are all user variables that define a particular group of items for e-mail notification.  Each item group is defined by its conference number cn, and the epoch-time et of the group's creation.)

    en_items_cn-et
    The first five words are control information: item group active (1 or 0), include newly created items (1 or 0), report on newly created items (1 or 0), highest-reported item (number), derived from organizer group (epoch time value if yes, else 0).  The remainder of the string is the "english" form of the list of items, as reported by $it_pack().
    en_dates_cn-et
    Controls the days on which notification is done for this item group.  The first word is week days (1) vs month days (0).  The rest is the list of day numbers.
    en_hours_cn-et
    Controls the times at which notification is done for this item group.  The first word is "detailed report" (1) vs summary report (0).  (This feature has not been implemented in 4.3; only summary reports are produced.)  The rest is the list of hour numbers (0 to 23).

  11. Conference Colors.  Conference variables.  Controls the various "colors" for a conference that may be customized by the organizer.
    confback Page background color
    conftext Text color
    conflink Link text color
    confvlink Visited link text color
    confcont Contrasting background color for certain areas (such as list of items on conference home page)
    confbgim Background image (instead of color) for page
    conf_colors    Combined string of other color settings, for ease of use in <BODY> tag.  Strictly derivative from the other settings.

  12. Conference E-mail Participation.  Conference variables.  Controls member participation via e-mail.
    email          List of e-mail addresses, one per line, of users who are participating in the conference via e-mail

  13. Caucus Center Controls  Site variables.  Controls customized layout of Caucus Center page.  Dir is the interface directory name.  See center.cml and cenblk.i for details on how these variables are used.

    if_dir_blks Number of customized "blocks".
    if_dir_blkN Text of block N.  First word is one of: p (personal conference list),  a (all conference list),  j (join conference by name),  r (popular conference list),  n (notebook entries),  0 (nothing),  iN (take text from item N of interface storage conference -- rest of text is macro to invoke item N),  t rest of text is CML text to use
    if_dir_ccenter  Name of Caucus Center
    if_dir_cchide Show Caucus Center name on Caucus Center page?  (1=no, 0/empty=yes)
    if_dir_cclogo CML text to display upper-left corner "logo" on Caucus Center page
    if_dir_allogo CML text to display upper-left corner "logo" on all other pages

  14. Administration.  Site variables. 
    warn_admin     If a Caucus license is limited to a certain limiting number of users, the primary manager is warned (via e-mail) when the total number of users approaches the limit.  If this happens, warn_admin is the epoch time when the manager was last warned.  (This is used to limit the warnings to no more than one per day.)

 

IV. Locking

The standard Caucus interface files use the $lock() function to lock certain abstractions of data objects while they are being modified.  This prevents corruption of the values of the data objects that could be otherwise caused by the collision of different Caucus sessions writing the same data simultaneously.

The abstractions being locked are listed below:

  1. Site variables.  The lock number is 10.

    Caucus Systems reserves lock numbers 0 through 499 for possible site-wide locks.  This leaves lock numbers 500 - 999 available for arbitrary uses.

    Lock 10 is used for locking the site variables before writing them.  The only code (as of 4.3 interface revision 43) that uses this, so far, is the Caucus Center page customization -- see man_cc.cml and related files.

  2. Conference variables for conference N.  The lock number is 1000 * N, plus 1.

    This scheme essentially reserves a thousand possible lock numbers for each conference, and specifically uses lock "1" in a specific conference's block of a thousand, for rewriting the conference variables.  Caucus Systems reserves locks 0 through 499 (that is, 1000 * N through 1000 * N + 499) for its own purposes.  Locks 500 - 999 are available for arbitrary uses.

    The only code that uses this (as of 4.3 interface revision 43) so far is the conference and personal e-mail notification code -- because they use a bunch of conference variables.  In theory, all uses of $set_conf_var() should probably share this locking scheme, but in practice there have been no problems, as conference variables are but rarely set.

 

V. Global Switches

Another group of data structures are the "global switches" -- regular (non-persistent) CML variables whose values are set every time at the beginning of the Caucus session.  These switches control different aspects of the user interface, and are very rarely changed.

The switches are always explicitly set inside one of three CML files:

  1. defaults.i
  2. Local/switch.i
  3. Local/switch2.i

The first file (defaults.i) contains the default values for many of the switches.  It should never be changed.  Of particular interest are the "src_" switches which contain the full <IMG> tag fields for the standard icons used in the Caucus interface.  (See the file itself for more details.)

The second file (Local/switch.i) contains basic switches that relate to where and how Caucus is installed.  The Caucus manager may need to change these (by editing the file directly) when, or shortly after, Caucus is installed. They include:

sweb Name of the web server software's ScriptAlias (or equivalent alias) that points to where the Caucus software is installed.  The default value is also "sweb".  If there are multiple instances of Caucus installed on a single (hardware) server, each instance must have a unique sweb value.
use_javascript  Normally 1.  Set to 0 to disable use of javascript (as much as possible).
http Hypertext transfer protocol in use.  Should be "http" or "https" (until new protocols come along!)
img Full URL of Caucus icon directory.
icon Same as img.
confhome Controls the use of "variant" or multiple conference home pages.

The third file (Local/switch2.i) contains switches specific to user-interface control, such as "how many responses (maximum) should appear in a single page", or "should the e-mail notifier be run every hour?".  These switches are controlled by a Caucus manager, from the manager options page, "Edit the Caucus switches" selection.  Since the file has a fixed format (in order to be read and displayed by that Caucus page), use the "Edit the... switches" page to change the switches in preference to manually editing the file.  (See that page or the file for detailed descriptions of each switch.)

 

VI. Manager Permissions

Caucus "managers" are given special abilities to manage the use and operation of Caucus.  Their abilities are represented as a bit mask, which is set and returned by the $set_mgr_list() and $mgr_list() functions.  Normally, each bit controls one manager feature or capability, although there is some (rare) interaction between the bits.

Management capabilities started simple and got more complicated over time and later versions.  Some capabilities are controlled directly by the CML functions; for example, you must have bit value "2" in order to create a conference.  Some capabilities are used purely by the CML code, but are not otherwise enforced (which means they might change over later revisions of the CML code).

To make matters worse, not all possible combinations of bits can be set from the "manage the list of managers" page, and in rare cases may require direct editing of the MISC/managers file, where this information really resides.

In any case, here is the table of bit values, and what they control.  (Capabilities shown in italics are experimental and not officially part of 4.3.)

 

Appendix A. Index to persistent variables

Given the name of a persistent variable, use this index to find its meaning or purpose.  Italicized parts of variable names vary according to the purpose of the variable.