CML Reference Guide

Chapter 4.26:  Caucus 5.0 Functions

 [TOP] [UP] [PREV]

In Caucus 5.0, the underlying proprietary flat-file database is replaced by MySQL, a full-featured, open-source, relational database management system ("RDBMS").  When Caucus 5.0 is released, there will be a new version of the CML reference guide; in the meantime, new functions in 5.0 will be documented here, along with an indication of which functions they replace.

Note: even when new functions are meant to entirely replace the equivalent old functions, the old functions (at least for now) are still operational.  The old functions should only be used for conversion purposes, e.g. as part of a script used to read the old data and write it in the new database.

See the Caucus 5.0 Schema for detailed descriptions of the MySQL tables used in Caucus 5.0.

  1. User Information

    Personal information about all users are stored in a single table (called user_info), and referenced by field name (aka "column name").  The three functions that follow provide direct access to the user_info table.  (The $sql_query_open() function may also be used to run queries against this table.)

    $add_user_info (field type)        {protected}
    Creates a new column called field, of a given type.  Type must be one of the following:
      string arbitrary text, up to 255 characters long
      text arbitrary text, any length (up to 16MB)
      date Date and time, in the form "YYYY-MM-DD HH:MM:SS"
      number   an integer number
      dollars a number with two decimal points

    Evaluates to 1 if successful, else 0.

    The user_info table initially has the pre-defined fields shown below.  Only 'lname' is required to have a value for a user to exist.

      lname string "Last" name
      fname   string First (& middle, etc.) name
      prefix string Prefix or salutation
      suffix string Suffix or organization
      intro text "Brief introduction"
      phone string Telephone(s)
      email string e-mail address
      active **   number   is user active?
      laston ** date date last on Caucus

    The fields marked with "**" are automatically maintained by Caucus, and generally should not be set with $set_user_info().

    $set_user_info (userid field value)        {protected}
    Assigns value to field for user userid.

    $user_info (userid field)
    Evaluates to the value of field for userid.

    These three functions effectively replace most of the "$per" and "$my" functions, specifically:

    • $per_name(id)
    • $per_intro(id)
    • $per_phone(id)
    • $per_laston(id)
    • $set_per_name(id name)
    • $set_per_phone(id phone)
    • $set_per_intro(id text)
    • $my_name()
    • $my_phone()
    • $my_intro()
    • $my_laston()
    • $set_my_name(name)
    • $set_my_phone(number)
    • $set_my_intro(text)

    They also replace any instances of $user_var() and $set_user_var() that are used for personal information -- such as the fields that a manager may add on the "modify the XYZ registration interface" page.

    Example
    The new user_info functions are meant as simple "drop-in" replacements for the old functions listed above.  In cases where CML code is displaying many user fields at once, building a regular SQL query may be simpler and more efficient.  For example, consider the following CML code fragment for displaying a list of all users, sorted alphabetically by last name: 

       "<table>
   set query SELECT prefix, fname, lname, suffix, userid, email \
               FROM user_info ORDER BY lname
   set h $sql_query_open($(query))
   while $sql_query_row ($(h))
      "<tr>
      "<td>$(prefix) $(fname) $(lname) $(suffix) ($(userid))</td>
      "<td>$(email)</td>
   end
   eval $sql_query_close($(h))
   "</table>

    'Magic' Fields
    Certain fields are 'magic', in that they have some special behaviour, and should not be written to from any kind of SQL query.

    • lname.  To create a new user, evaluate $set_user_info (userid lname lastname).  You must do this first, before attempting to call $set_user_info() to set any other values for that userid.

    • laston.  This field is set automatically by Caucus when a user logs in, and when they log out.  Calling $set_user_info (userid laston xyz) sets the "laston" field to the current date and time (ignoring the value of xyz), and only if userid is same as the current user.

  2. User Data

    Even with the new user_info table, there is still a need for user data such as the "variables" provided by the old $user_var() function.  This data is often "sparse", in the sense that only a few variables may have data for most users.  It is also frequently used for managing the user interface, rather than representing any "personal" information about a user.

    In Caucus 5.0, this data is stored in a new table called user_data, which has only three columns:

    • userid
    • name (of data field)
    • value (always a string, any size up to 16MB)

    This data is accessed in a manner exactly parallel to the old "user variables", except that there is no cache and thus no $clear_user_data(), and there are no locking issues (no need to call $lock() when writing user data).

    $user_data(user vname)
    Evaluates to the value of userid user's variable called vname.

    $set_user_data(user vname value)        {protected}
    Sets userid user's variable vname to value.

    $list_user_data(user str)        {protected}
    Evaluates to a blank-separated list of user's variable names that begin with str.  If str is not supplied, lists all of user's variables.

  3. Finding a User

    $userids_byid(match) replaces the old $all_users(). 
    Evaluates to a list of all of the userids registered with Caucus that begin with the initial substring match.  If match is empty, evaluates to list of all of the Caucus userids.  (Even on a site with thousands of users, this function evaluates quickly.)

    $userids_byname(cnum names...) replaces the old $peo_names(). 
    Evaluates to a list of userids of people who match names.  A person matches if every word in names is an initial substring of some part of their name (including their userid as if it were part of their name).  If cnum is non-zero, matching people must also be a member of conference cnum.

    Implementation notes:

    1. Currently the cnum argument is ignored, pending conversion of the membership information into MySQL.

    2. 5.0 implements this function with a brute-force LIKE match and a set of JOINs of user_info against itself.  On a large site, this may be slow; if so, it can be reimplemented as a separate table, with one row per word in the users' names.