comments

Event records and comments

APPLICABILITY

DESCRIPTION

Each change to a VOB (checkin of new version, attaching of a version label, and so on) is accompanied by the creation of an event record in the VOB database. Many commands allow you to annotate the event records 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. See the fmt_ccase reference page for a description of the report-writing facility built into these commands.

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.

In Attache, the text file must be on the local host. Specifying a relative pathname for comment-file-pname begins from Attache's startup directory, not the working directory, so a full local pathname is recommended. For a file in DOS format, any final line-terminator is included in the comment.

-cq·uery

Prompts for one comment, to be placed in all the event records created by the command.

-cqe·ach

For each object processed by the command, prompts for a comment to be placed in the corresponding event record.

-nc·omment

(no additional comment) For each object processed by the command, creates an event record with no user-supplied comment string.

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) or CTRL-Z and RETURN (Windows), or 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"

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

Specifying Comments Interactively

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) 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, it 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) 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 describing 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 any comment option. For example, the checkin command's comment default is -cqe, so you are prompted to enter a comment for each element being checked in. The ln command's comment default is -nc: create the event record without a comment.

You can customize comment handling with a user profile file, .clearcase_profile, in your home directory (in Attache, on your helper host). 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