Replaces missing operations in a replica that has been restored from backup


Product Command type
MultiSite multitool subcommand


[ –c/omment comment | –cfi/le comment-file-pname | –cq/uery | –cqe/ach | –nc/omment ] [ –f/orce ] [ –override ] [ –invob vob-selector | [ –rep/lace ] replica-selector ... ]


Warning: Proceeding with normal development at a restored replica before executing this command causes irreparable inconsistencies among the replicas in a family.

After you restore a replica from backup, the recommended procedure is to run checkvob against the restored VOB backup to check for and resolve any container issues and then execute the restorereplica command. After the restorereplica command has locked the VOB for restoration, you cannot interrupt the restorereplica process to make checkvob updates.

restorereplica replaces missing changes in a VOB replica that has been restored from backup, as follows:

  1. It causes the current replica to create special update packets that contain update requests to other replicas.
  2. It locks the current replica's VOB object and marks the replica as being in the process of restoration.
  3. It increments the recovery incarnation for the replica.
  4. It causes lsreplica –long to indicate which replicas must send restoration updates to the current replica.

The current replica remains in the restoration state until you have received and applied (using syncreplica–import) all the restoration updates needed to bring the replica up to date with the state of the family. Collectively, these updates include all the changes to the family since the backup was made, including changes made in the current replica before its failure.

You cannot recover changes that were made after the last synchronization export from your current replica. For example, if your replica was backed up on Wednesday at 12:30 p.m. and your last synchronization export was Thursday at 3:00 p.m., you can recover all changes made until Thursday at 3:00 p.m. All changes made after that time are lost.

During the process of restoration, the lsreplica –long command annotates its listing to indicate which replicas must send restoration updates to the replica.

For a description of the replica restoration procedure, see the Help.

Locking the replica

restorereplica locks the current replica's VOB object. Locking it ensures that while restoration proceeds through execution of syncreplica–exportand syncreplica –import commands, no other changes are made to the current replica.

When syncreplica applies the final required update, it displays a message indicating that the restoration process is complete. At this point, use the cleartool unlock vob: command to unlock the restored VOB replica, enabling normal development to proceed.

Optimizing the restoration process

By default, restorereplica requires that the replica receive restoration updates from all other replicas in its family (either directly or indirectly). Only after all the updates are imported does the syncreplica command display the message indicating that restoration is complete.

In some cases, you can relax this requirement without compromising the correctness of the restoration process. The replica will be brought up to date if it receives a restoration update from only one replica, the last one to which the replica sent an update before it was restored from the backup version. You can specify the name of that last-updated replica (or a list of replicas, one of which must be the last-updated one) to restorereplica. The syncreplica command displays the restoration-completed message after receiving restoration updates from all the specified replicas.

Important: If you use this optimization incorrectly, you can make the restored replica irreparably inconsistent with other replicas.


Identities: You must have one of the following identities:
  • VOB owner
  • root (Linux® and the UNIX® system)
  • Member of the VersionVault administrators group (Windows®)

Locks: No locks apply.

Mastership: No mastership restrictions.

Options and arguments

Event records and comments

Creates one or more event records, with commenting controlled by the standard VersionVault user profile (default: –cq). See Event records and comments in the multitool reference page. To edit a comment, use cleartool chevent.
–c/omment comment-string | –cfi/le comment-file-pname | –cq/uery | –cqe/ach | –nc/omment
Overrides the default with the specified comment option.

Suppressing interactive prompts

restorereplica prompts you for confirmation.
Suppresses the confirmation step.

Specifying the VOB family

Processes the replica that contains the current working directory.
–invob vob-selector
Processes the current replica in the specified family. Specify vob-selector in the form [vob:]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)

Reducing the number of required updates

The syncreplica command declares the replica to be restored completely only after updates are received from all other members of the VOB family and imported.
Warning: Incorrect use of these options allows new changes to be made to the replica before all missing changes are received from other replicas. This may place the entire family in an irreparably inconsistent state.
replica-selector ...
Specifies a subset of replicas from which updates are required before syncreplica declares the replica to be restored completely. Specify replica-selector in the form [replica:]replica-name[@vob-selector]
Name of the replica (displayed with lsreplica)
VOB family of the replica; can be omitted if the current working directory is within the VOB.

Specify vob-selector in the form [vob:]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)
–rep/lace replica-selector ...
Changes the subset of replicas from which restoration updates are required.
Overrides normal restoration processing and declares the VOB to be restored completely. The lsreplica –long command no longer annotates any replicas as needing to provide updates, and you can use cleartool unlock vob: to place the replica back in normal service.

When you specify this option, the command displays a list of replicas from which updates have not been received and prompts you to cancel the operation or continue.