events_ccase

Operations and event records

Applicability

Product

Command type

VersionVault

general information

MultiSite

general information

Platform

UNIX®

Linux®

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 VersionVault, provided by user-name, or a combination of both

Full name information on a VersionVault client on Windows

Full name information is written into an event record created on a VersionVault client on UNIX, Linux, and Windows. On Windows, you need to set the full_name field on a domain controller. You can do this in two ways.

  • From the command line, enter the following command:

    net user user-name /fullname:″name-string″ /domain

    Where name-string is the name you want written into an event record. Here is an example:

    C:\> net user tdawson /fullname:"Terry Dawson" /domain

  • Open Active Directory Users and Computers. In the left pane, click Users. In the right pane, right-click user-name > Properties. In the Properties dialog box, click the General tab. Enter the name string in the Display name box.

The name string you entered is truncated at the first comma, semicolon, colon, open paren, open angle bracket, open bracket, or open brace. The leading and trailing blanks are removed. For example, if you enter this name string:

Terry Dawson (Senior Software Engineer)

VersionVault will extract ″Terry Dawson″ to use as the name in an event record.

You can disable this mechanism by setting the following registry key (of type REG_DWORD) to the value 1:

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Atria\ClearCase\CurrentVersion\
DisableGecos

If you disable this mechanism or enter an empty string in the domain controller's full_name field, VersionVault will record an empty string as the full name in any event records it writes to a VOB.

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
  • Policy
  • Rolemap
  • 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; VersionVault 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 1 lists event-causing base VersionVault 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 1 and Table 2.

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 1. Base VersionVault 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

chpolicy M T S C chpolicy mkpolicy -replace Element

chpool

M

S

C

chpool

Element

chrolemap M T S C chrolemap mkrolemap -replace 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

checkout, clearimport, relocate , mkelem

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

mkpolicy

T

mkpolicy

Policy

mkpool

mkpool

Storage pool object

mkreplica

mkreplica

Replica

mkrolemap

T

mkrolemap

Rolemap

mkslink

T

ln –s

clearimport, relocate

Directory version

mktrigger

M

T

S

mktrigger

relocate

Element

mktype

T

mk**type

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

mk**type –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)

rmpolicy

T S C

rmpolicy

VOB

rmpool

S

C

rmpool

VOB

rmrolemap

T S C

rmrolemap

VOB

rmtrigger

M

T

S

rmtrigger

Element

rmtype

T

S

C

rmtype

VOB

rmver

M

T

S

C

rmver

checkvob –fix

Element

setrolemap

T C

protect –chrolemap

VOB object, Rolemap, Policy, Element

unlock

T

S

unlock

(various)

Unlocked object

unreserve

M

T

unreserve

Checked-out version

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 2. UCM 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

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

setstream

T

S

mkview -stream, chview -stream

The stream that is being associated with the view

unsetstream

T

S

chview -stream, rmview

The stream that is associated with the view

setactivity

T

S

setactivity

The activity that is being set

setactivity_none

T

S

setactivity -none

The activity that is being unset

Operations and triggers

Each of the following superoperations represents a group of the event-causing operations listed in Table 1 and Table 2. For information about how to use the following keywords to write triggers for groups of operations, see mktrtype.

MODIFY_TYPE

MODIFY_DATA

MODIFY_ELEM

MODIFY_MD

Table 1 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 VersionVault commands in Table 1 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 VersionVault 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.