multitool

DevOps Code ClearCase® MultiSite user-level commands

Applicability

Product Command type
MultiSite MultiSite command
Platform
UNIX
Linux
Windows

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 Linux and the UNIX system, DevOps Code ClearCase MultiSite):
    multitool
    –ver/sion
  • Display version information for multitool and the libraries used by multitool (and on Linux and the UNIX system, DevOps Code ClearCase MultiSite):
    multitool
    –VerAll

Description

multitool is the principal program in DevOps Code ClearCase MultiSite. Typically, you also use DevOps Code ClearCase MultiSite extensions incorporated into cleartool subcommands in DevOps Code ClearCase.

The different multitool subcommands are described in "MultiSite command set" in ClearCase MultiSite Administrator's Guidethis guide.

Using interactive mode and status mode

With –e, multitool enters interactive mode. multitool 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 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)

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 DevOps Code ClearCase 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 quotation marks.
–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 Linux and the UNIX system, 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 DevOps Code ClearCase Command Reference.

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 (Linux and the UNIX system) 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 Linux and the UNIX system) 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 DevOps Code ClearCase Command Reference.