relocate

You must have one of the following identities:

• VOB owner (for both VOBs)
• root (UNIX and Linux)
• Member of the VersionVault administrators group (VersionVault on Windows)

An error occurs if one or more of these objects are locked in the source VOB: VOB, element. An error occurs if one or more of these objects are locked in the target VOB: VOB, element, branch type, element type, label type, hyperlink type, attribute type.

(Replicated VOBs only) Your current replica must master any element to be relocated.

Because relocate normally locks the elements on which it operates, users cannot access them while they are being relocated. If the elements must remain in use during the relocation, you can use relocate's update mode (relocate –update). You can also use update mode to update the target VOB incrementally with changes that have occurred since relocate was last run. However, we recommend that you use update mode sparingly.

You cannot switch from using update mode to not using it. We recommend you not use update mode if you plan to leave some elements in the original VOB. (If you do use it in this situation, you must clean up the original elements and create symbolic links manually.)

When you use update mode incrementally, relocate rescans all elements and updates the ones that have changed. In regular mode, relocate determines where it left off and continues, assuming that elements it has already relocated do not need further processing. In update mode, relocate does not make this assumption: because update mode is used incrementally and no locks are put on the original elements, the elements could have changed since relocate –update was last run.

There are certain changes (usually deletions of objects) that cause relocate to fail when updating existing elements. If you perform rmver, rmbranch, or rmelem operations on the original elements, these changes are not reflected in the target VOB.

In addition, a deletion combined with a replacement creation can cause an error. For example, if a branch named foo is removed in the original VOB and a new branch named foo is created to replace it, relocate fails when it tries to update the target element. Because relocate did not remove the old branch, it cannot create the new one. To work around this problem, remove the target element; on the next run of relocate, the element is re-created.

The following restrictions apply:

• relocate cannot be used when pname or target-dir-pname is part of UCM component.
• relocate cannot move checked-out elements. It fails during the selection phase if it finds any checked-out files among the ones it is going to move.
• relocate may fail if there are restrictive triggers on checkout, checkin, and rmelem commands. Because relocate runs these commands, triggers on these operations are also executed. If these triggers cause relocate to fail, you must disable the triggers or remove them from those operations and run relocate again.