Relocating elements to another VOB

The cleartool relocate command moves elements to another VOB.

When you relocate a file element, you relocate all of the element's data and metadata. When you relocate a directory element, you relocate all the file and directory elements it contains. A relocate operation is appropriate when you need to reorganize VOB contents to reflect changes in system architecture or organizational structure or when you need to move groups of elements out of a VOB to reduce its size, or provide better load balancing across VOB servers.

Note: You cannot use relocate in a UCM component VOB or PVOB. Before you perform any relocate operation, read the relocate reference page.

How the relocate command works

The relocate command moves elements from one VOB (the source VOB) to another VOB (the target VOB). In many cases, the target VOB is created for this purpose. The relocate command normally does all of the following:

Moves elements from one VOB to another. Both VOBs must be in the same registry region. For each element, the following data and metadata are moved:
- The element’s data containers
- The element’s event history (some minor events are lost)
- Bidirectional hyperlinks attached to the element
- Related VOB database records
- The config records associated with versioned derived objects

Preserves the source VOB’s namespace by creating appropriate symbolic links to the target VOB.
Copies metadata types associated with moved elements to the target VOB, as necessary (label, attribute, element, trigger, and hyperlink types).
Creates relocation event history for each relocated element—a remove element event in the source VOB, and a relocate event in the target VOB.
Deletes nonversioned DOs and config records for DOs contained in relocated directories.
Creates a log of its activities—by default, in the file relocate.logdate-time in the directory where you run relocate.

The relocate command does not do any of the following:

Relocate elements when either the source or the target VOB is a UCM component VOB or PVOB.
Move view-private files and nonversioned DOs stored in relocated directories.
Move elements to a new location in the same VOB. (Use cleartool mv for this purpose.)

Steps to take before relocating elements
To ensure that a relocate operation succeeds, you must take some preliminary steps.
Special considerations for replicated VOBs
Handling borderline elements
When an element is cataloged in more than one VOB directory, relocate classifies it as a borderline element if any directory in which it is catalogued is not displayed in the set of elements selected by the view in which you run relocate.
Handling errors during a relocate operation
When the relocate command encounters a problem, you can usually fix it and restart relocate with the same command line; the operation continues from the point of the error.
After elements are relocated
Verify that the relocated elements are visible in the views that need to use them.
Using update mode
The relocate command has an update mode that preserves the source elements while creating the targets. This mode can be useful in certain cases, but should be used with care.

Parent topic: Moving VOBs and relocating VOB data