Event records and comments



Command type


general information






Each change to a VOB (checkin of new version, attaching of a version label, and so on) is recorded in an event record, which is created in the VOB database. Many commands allow you to annotate the event records that they create with a comment string. Commands that display event record information (describe, lscheckout, lshistory, lslock, lspool, lsreplica, and lstype) show the comments, as well. For a description of the report-writing facility built in to these commands, see the fmt_ccase reference page.

A comment string may not exceed 256 bytes per line. All commands that accept comment strings recognize the same options:

–c/omment comment-string
Specifies a comment for all the event records created by the command. The comment string must be a single command-line token; typically, you must quote it.
–cfi/le comment-file-pname
Specifies a text file whose contents are to be placed in all the event records created by this command.
Note: A final line-terminator in this file is included in the comment.
Prompts for one comment, to be placed in all the event records created by the command.
For each object processed by the command, prompts for a comment to be placed in the corresponding event record.
(No additional comment) For each object processed by the command, creates an event record with no user-supplied comment string.

The chevent command revises the comment string in an existing event record. For a detailed discussion of event records, see the events_ccase reference page.

Specifying comments interactively

A –cq or –cqe comment string can span several lines. To end a comment, enter an EOF character at the beginning of a line, typically by pressing Ctrl+D (UNIX® and Linux®) or Ctrl+Z and Return (Windows®), or by typing a period and pressing Return. For example:

cmd-context checkout main.c
Checkout comments for "main.c":
This is my comment
# the following line terminates the comment
Checked out "main.c" from version "\main\3"

cleartool can reuse a previously specified comment as the default comment. If the environment variable CLEARCASE_CMNT_PN specifies a file, that file is used as a comment cache:

  • When a cleartool subcommand prompts for a comment, it offers the current contents of the file $CLEARCASE_CMNT_PN (UNIX® and Linux®) or %CLEARCASE_CMNT_PN% (Windows®) as the default comment.

    Exception: If an element's checkout record includes a comment, that comment is the default for checkin, not the contents of the comment cache file.

  • When a user interactively specifies a comment string to a cleartool subcommand, cleartool updates the contents of CLEARCASE_CMNT_PN with the new comment. (The comment cache file is created if necessary.)
    Note: A comment specified noninteractively (for example, with the command cleartool mkdir –c "test files"), does not update the comment cache file.

The value of CLEARCASE_CMNT_PN can be any valid pathname. Using a simple file name (for example, .ccase_cmnt) can implement a comment cache for the current working directory; different directories then have different .ccase_cmnt files. Using the full pathname $HOME/.ccase_cmnt (UNIX® and Linux®) or %HOME%\.ccase_cmnt (Windows®) implements a cache of the individual user's comments, across all VOBs.

If environment variable CLEARCASE_CMNT_PN is not defined in a cleartool process, a default comment is supplied only in certain situations:

  • Any comment specified by the user when checking out an element becomes the default comment for checking in that same element.
  • When the user checks in a directory element, the default comment is a set of program-generated comments that describe the directory-level changes.

Customizing comment handling

Each command that accepts a comment string has a comment default, which takes effect if you enter the command without a comment option. For example, the comment default for the checkin command is –cqe, so you are prompted to enter a comment for each element being checked in. The comment default for the ln command is –nc: create the event record without a comment.

You can customize comment handling with a user profile file, .versionvault_profile, in your home directory. For example, you can establish –cqe as the comment default for the ln command. See the profile_ccase reference page for details.

See also

Reference pages for individual commands