MultiSite user-level commands
multitool subcommand [ options/args ]
multitool [ –e ]
multitool> subcommand [ options/args ] . . .
multitool> quit
multitool –status
multitool 1> subcommand [ options/args ] . . .
multitool 5> quit
multitool –ver·sion
multitool –VerAll
multitool is the principal program in MultiSite. Typically, you also use MultiSite extensions incorporated into cleartool subcommands in ClearCase.
The different multitool subcommands are described in Descriptions of Subcommands.
With –e, multitool enters interactive mode. It exits if an error is returned by a command.
With –status, multitool enters interactive mode and returns the status (0
or 1
) of each multitool subcommand executed.
If you exit multitool by entering a quit command in interactive mode, the exit status is 0
. The exit status from single-command mode depends on whether the command succeeded (zero exit status) or generated an error message (nonzero exit status).
In multitool commands, you specify non-file system VOB objects (types, pools, hyperlinks, and replicas) with object selectors.
Object selectors identify these VOB objects with a single string:
[prefix:]name[@vob-selector]
where
prefix
The kind of object. The prefix is optional if the context of the command implies the kind of object. For example, multitool lsreplica replica:buenosaires is equivalent to multitool lsreplica buenosaires.
If a context does not imply any particular kind of object, multitool assumes that a name argument with no prefix is a pathname. For example, the command multitool describe buenosaires describes a file system object named buenosaires, while multitool describe replica:buenosaires describes the buenosaires replica object.
name
The name of the object. See the Object Names section for the rules about composing names.
vob-selector
VOB pathname. If you omit vob-selector, the default is the current working directory unless the reference page specifies otherwise. Specify vob-selector in the form
[vob:]pname-in-vob (for some commands, the vob: prefix is required)
pname-in-vob
|
Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted)
|
In object-creation commands, you must compose the object name according to these rules:
Each change to a VOB is recorded in an event record in the VOB database. Many multitool commands include options you can use to include a comment string in the event record created by the command. Commands that display event record information (describe, lsepoch, lspacket, lsreplica, lstype) show the comments. See the fmt_ccase reference page in the Command Reference for a description of the report-writing facility built in to these commands.
Commands that accept comment strings recognize one or more of the following options:
–c·omment comment
Specifies a comment for all event records created by the command. The comment string must be a single command-line token; typically, you must enclose it in double quotes.
–cfi·le comment-file-pname
Specifies a text file whose contents are to be placed in all event records created by the command.
Note: A final line terminator in this file 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
For each object processed by this command, creates an event record with no 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, by typing a period character ( . ) and pressing ENTER, by typing CTRL+D on UNIX, or by typing CTRL+Z+ENTER on Windows. For example:
cleartool 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 cleartool chevent command revises the comment string in an existing event record. For more information about event records, see the events_ccase reference page in the Command Reference.
multitool can reuse a comment specified previously. If the environment variable CLEARCASE_CMNT_PN specifies a file, that file is used as a comment cache:
Note: A comment that is specified noninteractively (for example, with the command mkreplica –export –c "new replica for buenosaires") 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, .msite_cmnt) implements a comment cache for the current working directory; different directories can have different .msite_cmnt files. Using the full pathname %HOME%\.msite_cmnt (on Windows) or $HOME/.msite_cmnt (on UNIX) implements a cache of the individual user’s comments across all ClearCase VOBs.
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 restorereplica command’s comment default is –cqe, so you are prompted to enter a comment for each replica being restored. The rmreplica command’s comment default is –nc: remove the replica without prompting for a comment.
You can define a default comment option for each multitool command with a user profile file, .clearcase_profile, in your home directory. For example, you can establish –cqe as the comment default for the chmaster command. See the comments and profile_ccase reference pages in the Command Reference.