Administrator's Guide for Rational ClearCase MultiSite, Release 2002.05.00, All Platforms

3.2 multitool Use

The multitool program is very similar to the ClearCase cleartool program:

It has a set of subcommands that perform product functions, such as replica creation, synchronization, and management; mastership of objects stored in VOB databases; and failure recovery.

Some multitool subcommands are also available in cleartool.

Command options can always be abbreviated to three characters and sometimes fewer, as indicated in the reference pages.

You can use multitool in single-command mode. For example:

multitool rename replica:original boston_hub

Also in interactive mode:

multitool multitool> rename replica:original boston_hub multitool> quit

It has online help facilities. The help command displays syntax summaries, and the man command displays reference pages:

multitool man chreplica ...on Windows, Windows Help displays the reference page

chreplica ========== Changes the properties of a replica APPLICABILITY ...

multitool Subcommands

The following sections describe the different kinds of multitool subcommands. The tables in each section show whether the command has a cleartool equivalent and whether a view context is required when you invoke the command.

Commands Copied from ClearCase

These commands were copied from cleartool and are documented only in the Command Reference, except for apropos, which is also documented in this manual.

Table 5 multitool Subcommands Copied from ClearCase
Command	cleartool equivalent	View context required?	Description
apropos (UNIX)	Yes	No	Displays multitool command information
cd	Yes	No	Changes current working directory
describe	Yes	Yes (file-system objects)	Describes a replica's VOB database object
help	Yes	No	Displays multitool command syntax
man	Yes	No	Displays a MultiSite reference page
pwd	Yes	No	Prints working directory
quit	Yes	No	Ends interactive multitool session
rename	Yes	No	Renames a replica
shell	Yes	No	Creates subprocess to run shell or program

Replica Creation, Synchronization, and Management

multitool includes commands that set up new replicas of VOBs, change their characteristics, and change their contents by importing update packets.

Table 6 Replica Creation, Synchronization, and Management Commands
Command	cleartool equivalent	View context required?	Description
chreplica	No	No	Changes the properties of a replica
lspacket	No	No	Lists one or more packet files created by mkreplica or syncreplica
lsreplica	Yes	No	Lists one or more of a VOB's replicas
mkreplica	No	No	Creates a new VOB replica
rename	Yes	No	Renames a replica (command documented in the Command Reference)
rmreplica	No	No	Removes a replica
syncreplica	No	No	Synchronizes the current replica with one or more other replicas in its VOB family

Object Mastership

To prevent conflicting changes from occurring at different replicas of a VOB, certain VOB-database objects are assigned a master replica (master). The initial master of an object is the replica where the object is created. For more information on mastership, see Enabling Independent VOB Development: Mastership.

Table 7 Object Mastership Commands
Command	cleartool equivalent	View context required?	Description
chmaster	Yes	Yes (file-system objects)	Transfers mastership of a ClearCase object
lsmaster	Yes	Yes	Lists objects mastered by a replica
reqmaster	Yes	Yes	Requests mastership or set access controls for mastership requests

Failure Recovery

Each replica of a VOB uses an epoch number matrix to track its own state and the state of all other replicas. (Because replicas are always changing, a replica knows what changes have been made to itself; but it can have only an estimate of the states of other replicas.) Each time a replica sends an update packet, it updates its own epoch number matrix, under the assumption that the packet will be delivered to its destinations and applied to the appropriate replicas. For more information, see VOB Operations and the Oplog.

multitool includes the following failure-recovery commands, for use when this assumption of successful delivery does not hold true:

Table 8 Failure-Recovery Commands
Command	cleartool equivalent	View context required?	Description
chepoch	No	No	Changes a replica's epoch number matrix
lsepoch	No	No	Lists a replica's epoch number matrix
recoverpacket	No	No	Resets epoch number matrix so lost packets are resent (required when a packet is lost or unusable)
restorereplica	No	No	Restores VOB replica from backup. This command places a replica in a special state, in which it sends epoch number matrix corrections to other replicas. The replica cannot be used for normal development work until it receives special updates that inform it of the current states of other replicas.