IPnom Home • Manuals • ClearCase

 Rational ClearCase Commands Reference

ClearCase Stuff:ClearCase LinksClearCase BooksClearCase Commands ReferenceClearCase ForumsClearCase News
Keyword Live Search (10 results max):
 Type in part of a ClearCase command in the search box.
Commands Index:


Operations and event records


ProductCommand type
ClearCasegeneral information
ClearCase LTgeneral information
MultiSitegeneral information



Nearly every operation that modifies the VOB creates an event record in the VOB database. For example, when you create a new element, attach a version label, or lock the VOB, an event record marks the change.

Event records are attached to specific objects in VOB databases. Thus, each object (including the VOB object itself) accumulates a chronological event history, which you can display with the lshistory command.

In addition, you can do the following:

  • Customize event history reports with lshistory –fmt; see the fmt_ccase reference page.
  • Scrub minor event records from the VOB database to save space; see the vob_scrubber reference page.
  • Assign triggers to many event-causing operations (mkelem, checkout, and mklabel, for example); see the mktrtype reference page.
  • Change the comment stored with an event; see the chevent reference page.

Contents of an Event Record

An event record stores information for various operations:

obj-name The objects affected
obj-kind The kind of object (file element, branch, or label type, for example)
user-name The user who changed the VOB database
host-name The client host from which the VOB database was changed
operation The operation that caused the event (usually a cleartool command like checkout or mklabel)
date-time When the operation occurred (reported relative to the local time zone)
event-kind A description of the event, derived from a combination of the operation and obj-kind fields
comment A text string that is generated by ClearCase or ClearCase LT, provided by user-name, or a combination of both

VOB Objects and Event Histories

The following kinds of VOB-database objects have event histories, which you can display with lshistory:

  • VOB
  • VOB storage pool
  • Element
  • Branch
  • Version
  • VOB symbolic link
  • Hyperlink
  • Derived Object (no creation event)
  • Replica
  • Type
    • Attribute type
    • Branch type
    • Element type
    • Hyperlink type
    • Label type
    • Trigger type
  • UCM Objects
    • Project
    • Stream
    • Folder
    • Activity
    • Component

Each time an object from any of these categories is created, it begins its own event history with a creation event. (Derived objects are an exception; ClearCase stores a DO's creation time in its config record, not in an event record.) As time passes, some objects—VOBs and elements, in particular—can accumulate lengthy event histories.

Do not confuse type objects (created with mkattype, mkbrtype, mkeltype, mkhltype, mklbtype, and mktrtype) with the instances of those types (created with mkattr, mkbranch, mkelem, mkhlink, mklabel, and mktrigger). The type objects are VOB-database objects, with their own event histories. Individual branches, elements, and hyperlinks are also VOB-database objects. However, individual attributes, labels, and triggers are not VOB-database objects and, therefore, do not have their own event histories. Their create and delete events (mkattr/rmattr, mklabel/rmlabel, and mktrigger/rmtrigger) are recorded on the objects to which these metadata items are attached.

Operations That Cause Event Records to Be Written

The following kinds of operations cause event records to be written to the VOB database:

  • Create or import a new object.
  • Destroy (remove) an object.
  • Check out a branch.
  • Modify or delete version data.
  • Modify a directory version's list of names.
  • Attach or remove an attribute, label, hyperlink, or trigger.
  • Lock or unlock an object.
  • Change the name or definition of a type or storage pool.
  • Change a branch or element's type.
  • Change an element's storage pool.
  • Change the protections for an element or derived object.

If UCM is in use, the following kinds of operations cause event records to be written to the UCM Project VOB (PVOB) database.

  • Start, cancel, or complete a deliver or rebase operation.
  • Create, change, or remove a project, stream, baseline, or activity.

Table 2 lists event-causing base ClearCase operations as you may see them in lshistory output that has been formatted with the –fmt option's %o (operation) specifier. Note that most operations correspond exactly to cleartool subcommands.

Key to Table 2 and Table 3.

MCauses a minor event (see lshistory –minor)
TCan have a trigger (see mktrtype)
SResulting event records can be scrubbed (see vob_scrubber)
CGenerates a comment (see the comments reference page)

Table 2. Base ClearCase Operations That Generate Event Records

Operation that generates the event recordNotes (see key above)Commands that always cause the operationCommands that may cause the operationObject to which event record is attached
checkin T  checkin, mkelem, mkbranch clearimport, relocate Newly created version
checkout T  checkout clearimport, findmerge, mkelem, mkbranch, relocate Checked-out branch (event deleted automatically at checkin or uncheckout)
chmaster T Cchmaster, reqmaster (reqmaster is not triggerable) Object whose mastership was changed
chpoolM SCchpool  Element
chtypeMTSCchtype  Element or branch
exportsync   Csyncreplica –export  Replica
import     clearimport Imported element or type
importsync   Csyncreplica –import  Replica
lnnameMTSCln, ln –s, mkelem, mkdir, mv relocate Directory version
lock TSClock (Various)Locked object (type, pool, VOB, element, or branch)
mkattrMTSCmkattr clearimport, mkhlink, relocate Element, branch, version, hlink, or VOB symlink
mkbranch T  mkbranch, mkelem checkout, clearimport, relocate New branch
mkelem T Cmkelem, mkdir clearimport, relocate New element
mkhlinkMTSCmkhlink clearimport, findmerge, merge, relocate Hyperlink object and from-object, and for bidirectional hyperlinks, to-object (unless cross-VOB hyperlink)
mklabelMTSCmklabel clearimport, relocate Version
mkpool    mkpool  Storage pool object
mkreplica    mkreplica  Replica
mkslink T  ln –s clearimport, relocate Directory version
mktriggerMTS mktrigger relocate Element
mktype T  mk**type clearimport, relocate Newly created type object
mkvob    mkvob (causes numerous creation events), mkreplica –import  VOB
modpoolM SCmkpool –update  Storage pool
modtypeM SCmk**type –replace  Type object
protectM SCprotect  Element or DO
reconstructM S  checkvob –fix Element
reformatvob    reformatvob  VOB
rename (pool)M  Crename  Storage pool
rename (type)MT Crename  Type object
reserveMT  reserve  Checked-out version
rmattrMTS rmattr  (See mkattr)
rmbranch TSCrmbranch  Parent branch
rmelem TSCrmelem relocate VOB
rmhlinkMTSCrmhlink, rmmerge  From-object, to-object (unless cross-VOB, unidirectional), VOB
rmlabelMTS rmlabel  Version
rmnameMTSCrmname, rmelem, mv  Directory version(s)
rmpool  SCrmpool  VOB
rmtriggerMTS rmtrigger  Element
rmtype TSCrmtype  VOB
rmverMTSCrmver checkvob –fix Element
unlock TS unlock (various)Unlocked object
unreserveMT  unreserve  Checked-out version

Table 3 lists event-causing UCM operations as you may see them in lshistory output that has been formatted with the –fmt option's %o (operation) specifier. These events are generated only in a PVOB.

Table 3. UCM Operations That Generate Event Records

Operation that generates the event recordNotes (see key above)Commands that always cause the operationCommands that may cause the operationObject to which event record is attached
deliver_start  TS deliver Target (integration) stream
deliver_cancel TS deliver Target (integration) stream
deliver_complete TS deliver Target (integration) stream
rebase_start  TS rebase  Target (development) stream
rebase_cancel TS rebase Target (development) stream
rebase_complete  TS rebase  Target (development) stream
mkactivity TS mkactivity Stream that is to contain the activity
chactivity TS chactivity Activity being changed
rmactivity TS rmactivity Activity being removed
setactivity TS setactivity Activity being set
mkstream TS mkstream Project that is to contain the stream
chstream TS chstream Stream being changed
rmstream TS rmstream Stream being removed
mkbl TS mkbl Component that is to contain the baseline
chbl TS chbl Component that contains the baseline
rmbl TS rmbl Component that contains the baseline
mkproject TS mkproject The entire project VOB
chproject TS chproject Project being changed
rmproject TS rmproject Project being removed
mkcomp  TS mkcomp  The entire project VOB
rmcomp TS rmcomp The entire project VOB
mkfolder TS mkfolder Folder that is to contain the folder
chfolder TS chfolder Folder that contains the folder
rmfolder  TS rmfolder  Folder that contains the folder

Operations and Triggers

Each of the following superoperations represents a group of the event-causing operations listed in Table 2 and Table 3. See mktrtype for information on how to use the following keywords to write triggers for groups of operations.


Table 2 omits the triggerable operations uncheckout and chevent; as these operations do not cause event records to be stored in the VOB database.

Event Visibility

This section describes where, directly or indirectly, you may encounter event record contents. The following commands include event history information in their output, which can be formatted with the –fmt option:

describe lshistory
lsactivity lslock
lsbl lspool
lscheckout lsproject
lscomp lsreplica
lsdo lsstream
lsfolder lstype –long

Comments and Event Records

The set of ClearCase and ClearCase LT commands in Table 2 matches almost exactly the set of commands that accept user comments as input. (reformatvob, which takes no comment, is the only exception.) When you supply comments to a ClearCase or ClearCase LT command, your comment becomes part of an event record.

Some cleartool commands create a comment even if you do not provide one. These generated comments describe the operation in general terms, such as “modify metadata” or “create directory element.” User comments, if any, are appended to generated comments. For a complete description of comment-related command options and comment processing, see the comments reference page.



ClearCase Links • ClearCase Books • ClearCase Commands Reference • ClearCase Forums • ClearCase News