events_ccase

Operations and event records

APPLICABILITY

Product	Command type
ClearCase	general information
ClearCase LT	general information
MultiSite	general information

Platform
UNIX
Windows

DESCRIPTION

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.

Symbol	Meaning
M	Causes a minor event (see lshistory –minor)
T	Can have a trigger (see mktrtype)
S	Resulting event records can be scrubbed (see vob_scrubber)
C	Generates a comment (see the comments reference page)

Table 2. Base ClearCase Operations That Generate Event Records

Operation that generates the event record	Notes (see key above)				Commands that always cause the operation	Commands that may cause the operation	Object 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		C	chmaster, reqmaster (reqmaster is not triggerable)		Object whose mastership was changed
chpool	M		S	C	chpool		Element
chtype	M	T	S	C	chtype		Element or branch
exportsync				C	syncreplica –export		Replica
import						clearimport	Imported element or type
importsync				C	syncreplica –import		Replica
lnname	M	T	S	C	ln, ln –s, mkelem, mkdir, mv	relocate	Directory version
lock		T	S	C	lock	(Various)	Locked object (type, pool, VOB, element, or branch)
mkattr	M	T	S	C	mkattr	clearimport, mkhlink, relocate	Element, branch, version, hlink, or VOB symlink
mkbranch		T			mkbranch, mkelem	checkout, clearimport, relocate	New branch
mkelem		T		C	mkelem, mkdir	clearimport, relocate	New element
mkhlink	M	T	S	C	mkhlink	clearimport, findmerge, merge, relocate	Hyperlink object and from-object, and for bidirectional hyperlinks, to-object (unless cross-VOB hyperlink)
mklabel	M	T	S	C	mklabel	clearimport, relocate	Version
mkpool					mkpool		Storage pool object
mkreplica					mkreplica		Replica
mkslink		T			ln –s	clearimport, relocate	Directory version
mktrigger	M	T	S		mktrigger	relocate	Element
mktype		T			mktype**	clearimport, relocate	Newly created type object
mkvob					mkvob (causes numerous creation events), mkreplica –import		VOB
modpool	M		S	C	mkpool –update		Storage pool
modtype	M		S	C	mktype –replace**		Type object
protect	M		S	C	protect		Element or DO
reconstruct	M		S			checkvob –fix	Element
reformatvob					reformatvob		VOB
rename (pool)	M			C	rename		Storage pool
rename (type)	M	T		C	rename		Type object
reserve	M	T			reserve		Checked-out version
rmattr	M	T	S		rmattr		(See mkattr)
rmbranch		T	S	C	rmbranch		Parent branch
rmelem		T	S	C	rmelem	relocate	VOB
rmhlink	M	T	S	C	rmhlink, rmmerge		From-object, to-object (unless cross-VOB, unidirectional), VOB
rmlabel	M	T	S		rmlabel		Version
rmname	M	T	S	C	rmname, rmelem, mv		Directory version(s)
rmpool			S	C	rmpool		VOB
rmtrigger	M	T	S		rmtrigger		Element
rmtype		T	S	C	rmtype		VOB
rmver	M	T	S	C	rmver	checkvob –fix	Element
unlock		T	S		unlock	(various)	Unlocked object
unreserve	M	T			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 record			Commands that always cause the operation	Object to which event record is attached
deliver_start	T	S	deliver	Target (integration) stream
deliver_cancel	T	S	deliver	Target (integration) stream
deliver_complete	T	S	deliver	Target (integration) stream
rebase_start	T	S	rebase	Target (development) stream
rebase_cancel	T	S	rebase	Target (development) stream
rebase_complete	T	S	rebase	Target (development) stream
mkactivity	T	S	mkactivity	Stream that is to contain the activity
chactivity	T	S	chactivity	Activity being changed
rmactivity	T	S	rmactivity	Activity being removed
setactivity	T	S	setactivity	Activity being set
mkstream	T	S	mkstream	Project that is to contain the stream
chstream	T	S	chstream	Stream being changed
rmstream	T	S	rmstream	Stream being removed
mkbl	T	S	mkbl	Component that is to contain the baseline
chbl	T	S	chbl	Component that contains the baseline
rmbl	T	S	rmbl	Component that contains the baseline
mkproject	T	S	mkproject	The entire project VOB
chproject	T	S	chproject	Project being changed
rmproject	T	S	rmproject	Project being removed
mkcomp	T	S	mkcomp	The entire project VOB
rmcomp	T	S	rmcomp	The entire project VOB
mkfolder	T	S	mkfolder	Folder that is to contain the folder
chfolder	T	S	chfolder	Folder that contains the folder
rmfolder	T	S	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.

MODIFY_TYPE	MODIFY_DATA
MODIFY_ELEM	MODIFY_MD

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.