multitool

MultiSite user-level commands

APPLICABILITY

SYNOPSIS

• Single-command mode:

multitool subcommand [ options/args ]

• Interactive mode:

multitool [ -e ]

multitool> subcommand [ options/args ]
. . .

multitool> quit

• Status mode:

multitool -status

multitool 1> subcommand [ options/args ]
. . .

multitool 5> quit

• Display version information for multitool (and on UNIX, MultiSite):

multitool -ver·sion

• Display version information for multitool and the libraries used by multitool (and on UNIX, MultiSite):

multitool -VerAll

DESCRIPTION

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 multitool Subcommands.

USING INTERACTIVE MODE AND STATUS MODE

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).

SPECIFYING OBJECTS WITH OBJECT SELECTORS

In multitool commands, you specify non-file-system VOB objects (types, pools, hyperlinks, and replicas) with object selectors.

Object selectors identify non-file-system 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)

Object Names

In object-creation commands, you must compose the object name according to these rules:

• It must contain only letters, digits, and the special characters underscore (_), period (.), and hyphen (-). A hyphen cannot be used as the first character of a name.

• It must not be a valid integer or real number. (Be careful with names that begin with "0x", "0X", or "0", the standard prefixes for hexadecimal and octal integers.)

• It must not be one of the special names " . ", " .. ", or " ... ".

EVENT RECORDS AND COMMENTS

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.

All commands that accept comment strings recognize the same 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

(No additional comment) 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. See the events_ccase reference page in the Command Reference for more information about event records.

Specifying Comments Interactively

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:

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

• When you specify a comment string interactively, the multitool subcommand updates the contents of CLEARCASE_CMNT_PN with the new comment. (The comment cache file is created if necessary.)

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.

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 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 for details.