CML Reference Guide

Chapter 4.13:  Items and Responses

 [TOP] [UP] [PREV] [NEXT]

In Caucus 5.1, one "gets" most item and response information via direct SQL queries.  "Setting", creating, or changing items or responses is, on the other hand, usually done through CML "service" functions, since the required data changes may cover many tables.

Conferences are referred to by their key number, typically called "cnum".  Items, on the other hand, are referred to by either their unique key number (typically "id"), or their label, aka item number, depending on context.  An item number is a "dotted" concatentation of (up to) 6 levels.  For example:

Each "breakout" or "thread" is its own standalone item, with a linear thread of responses attached to it, in sequential order.  But new breakout items or threads may split off from any response, and get their own new item number. 

Internally (in the item-related database tables), each item has its own unique key, called item_id.  This key never changes.  Item numbers (labels) may change, i.e. it is possible to renumber an item, move it up and down in the breakout hierarchy, or even "share" the same item in multiple conferences.

Responses have a two-part key: the item_id (for the item the response "belongs to"), and the response number (rnum).  The response number is also used as the label, which tells you where the response appears within an item.  Response numbers (and keys) never change.

The rest of this document describes the item and response CML service functions.

$item_add (cnum iparent rparent userid title...)
Creates a new item in conference cnum.  If iparent is zero, the new item is assigned the next top-level item number in that conference.  Otherwise, the new item becomes the next breakout item under item id iparent, and is attached to response number rparent.

The item's author is set to userid, and is given title title.  Note that this creates an empty item, with a title but no text.  Use $resp_add() to add the text of response 0, i.e. the item text proper.

Evaluates to the new item's id, or to a negative error code if the item could not be created.

$item_del (cnum item_id)
Delete item item_id in conference cnum.  This permanently deletes the item and all of its responses, and all of its subitems(!).  Thus deleting item (with label) 1 also deletes items labelled 1.1, 1.2, 1.1.1, etc., and all of their responses.

Exception: if an item is shared across multiple conferences, deleting it from a conference only removes it from that conference -- it still exists in the other conferences.  When the last conference deletes it, only then will the item completely disappear.

$item_id (cnum inum)
Evaluates to the item id (items.id) value of an item in conference cnum, with item label inum.

$item_parse (cnum text)
Parses text into a triplet-list of conference number, item id, and response number.  Text may be:
  • An item label, with an optional ":" followed by a response number.  An item label may use one or more '*' wildcards, e.g. 5.* is items 5.1, 5.2, etc.  5.*.2:1 is response 1 to items 5.1.2, 5.2.2, etc.
  • A string of words in the title of one or more items.

If there is an error, it will evaluate to a single negative number.  If there are no matches, the result will be empty.

$item_label (cnum item_id)
Evaluates to the item label of an item item_id in conference cnum.

%item_lastresp (item_id)
Evaluates to the number of the last response to item_id.

Note: this is a macro! Eventually it should probably be (part of) a service function.

$item_tuplet (i0 i1 i2 i3 i4 i5)
In the database, the item level (breakout) numbers are actually represented as 6 integer fields, item0 through item 5.  (Which means that 6 levels is as deep as breakouts can go.)  Occasionally it is necessary to translate from this set of (up to) 6 integers into the "dotted" item number format.

So this function evaluates to the dotted form of this list of (up to) 6 space-separated integers, e.g. "$item_tuplet(1 4 3)" evaluates to 1.4.3.

$item_set (cnum item_id property value)
Sets the property of the specified item_id to value, as below:
    property  value
    hidden 1 (true), 0 (false)
    retired 1, 0
    frozen 1, 0
    userid new owner userid

$item_set_seen (cnum item_id userid respseen)
Marks response respseen in conference cnum, item item_id, as "seen" by user userid.  A respseen value of -1 marks the item as completely new, a value of -2 marks the item as "forgotten".

$resp_add (cnum item_id userid property bits reserved text..)
Adds a response to cnum, item_id, with author userid, text type property, and options bits.  (See property values for a description of the property and bits values.)  Reserved is reserved for future expansion; for now, set it to 0.  And text is the actual text of the new response.

Evaluates to the new response number in the item.

$resp_set (item_id rnum field value)
Sets (changes) the value of some field for response item_id, rnum.  The field/value pairs are:
    Field   Value
    time  Date/time stamp of response, as "YYYY-MM-DD HH:MM:SS".
    userid  Userid of owner of response.
    text  Text of response.
    prop  Text property (type) number

$resp_del (cnum item_id rnum)
Deletes response cnum, item_id, rnum.

 

These are the old, 4.x item-related CML functions.  They are here for reference, and for conversion tools that map 4.x data into 5.1 data.  Eventually they will disappear all together.

$it_member(cnum)
Evaluates to "1" if the current user has a participation record in the conference (that which tracks items seen vs new).  A person may be a member of a conference (in the sense that there is a 'grouprules' table rule that grants them access to the conference) but not (yet) have a participation record. 

The name is a historical accident due to how membership was handled in Caucus 4.

$it_last(cnum)
Evaluates to the number of the last item in a conference, i.e., the number of items.

$it_inew(cnum)
Evaluates to the number of new (and undeleted) items in a conference.

$it_wnew(cnum)
Evaluates to the number of items that have 1 or more new responses.

$it_iunseen(cnum)
Evaluates to the number of unseen items.

$it_listrnew(cnum)
Evaluates to a "triplet" list of the new responses in a conference.  The response number in a triplet is the first new response in the relevant item.

$it_listiunseen(cnum)
Evaluates to a "triplet" list of the unseen items in a conference.  The response number is always 0.

$it_exists(cnum inum)
Evaluates to "1" if the item exists and the user is a member of the conference, and "0" otherwise.

$it_visib(cnum inum)
Evaluates to "1" if the item is visible to the user, i.e. has not been deleted, not "forgotten", and not "hidden".  Otherwise "0".

$it_new(cnum inum)
Evaluates to "1" if the item is new to this user, i.e. it has a higher number than the highest item the user has seen.  Otherwise "0".

$it_unseen(cnum inum)
Evalutates to "1" if this item is not new but has not been seen by the user.  Otherwise "0".

$it_resps(cnum inum)
Evaluates to the number of responses.  If the item does not exist (or was deleted), evaluates to -1.  An item without any responses evaluates to "0".

$it_lastresp(cnum inum)
Evaluates to the number of the last (undeleted) response to the item.  If the item does not exist (or was deleted), evaluates to -1. 

$it_newr(cnum inum)
Evaluates to the number of the first response on this item that is new to this user.  If no responses are new, evaluates to the number of responses + 1.

$it_frozen(cnum inum)
Evaluates to "1" if the item is frozen, and "0" otherwise.

$it_howmuch(cnum inum userid)
Evaluates to the number of responses seen by user userid to item inum in conference cnum.  A value of -1 means the item is new to that user; -2 means the user has forgotten that item.

$it_parse(cnum text)
Evaluates to a triplet list of item/response numbers in conference cnum that match, in some form, text.  Text may contain a variety of forms of listing items, separated by commas, including the example shown below.  The result is an "or" match, i.e. all the items that match all the entries in text. 
  5
  7-20
  key words in an item title
  "words in one item title", "words in another item title"
  author "charles roth"
  since 5/23/95
  since -4

$it_pack(cnum comma triplet(s))
Acts as the inverse of $it_parse(), i.e. it converts a triplet list of items into text representing item ranges.  Items in triplets that are not in conference cnum are ignored.  A comma value of 1 means add a comma and a space between items or item ranges; 0 means just use a space.

Example: $it_pack (3 1   3 12 0   3 13 0  3 14 0   2 5 1   3 1 5)
produces "1, 12-14".

$it_hidden(cnum inum)
Is conference cnum item inum hidden?  Evaluates to 1 if hidden, 2, if "retired", or 0 if not hidden or does not exist, not accessible, etc.

Note: to ease the writing (and reading) of CML pages, all of the $it_ functions that take two arguments (such as it_visib(), it_resps(), and it_newr()) may be written with no arguments.  This means "re-use the exact same arguments as in a previous instance of one of these functions".  Warning: results may be unpredictable if other $it_...() functions (those with more than two arguments) are called in between.