relocate

Moves elements and directory trees from one VOB to another

APPLICABILITY

ClearCase (cleartool subcommand), Attache (command)

SYNOPSIS

relocate [ -f·orce ] [ -qal·l ] [ -log log-pname ] [ -upd·ate ]

pname [ pname ... ] target-dir-pname

DESCRIPTION

The relocate command moves elements, including directory trees, from one VOB to another. All related VOB database entries and data containers are moved to the target VOB. relocate preserves the "move from" VOB's namespace by substituting VOB symbolic links for moved elements.

NOTE: In Attache, after moving elements from one VOB to another, relocate does not move the corresponding elements in the workspace.

The more common use of relocate involves splitting a piece from one VOB and moving it to a newly created VOB. However, you can move an arbitrary collection of elements from one VOB to a location in any other VOB. You cannot use relocate to move an element to a new location in the same VOB. Use cleartool mv for this purpose.

For a dynamic view, view-private files and nonversioned DOs are not relocated. If a relocated directory contains view-private files, they are stranded; DOs are removed. See also Relocating Derived Objects and Using recoverview -sync to Recover View-Private Objects and DO Data Files.

WARNING: The relocate command makes irreversible changes to at least two VOBs and their event histories. We recommend that you not use it frivolously or routinely for minor adjustments. Furthermore, you are advised to stop VOB update activity before and during a relocate operation.

Overview of a Relocate Operation

Primary relocate processing phases:

• Select/checkout from source VOB

• Copy elements to target VOB
• Catalog elements in target VOB
• Update hyperlinks
• Remove elements from source VOB

When moving elements from one VOB to another, relocate does the following:

1. Locks all elements in the relocate set. (These locks are held until relocate removes the elements from the source VOB, or until you abort relocate and release them manually.)
2. Checks out source files and directories, and checks out the target directory.
3. Copies all elements into the target directory, creating a temporary, flat directory of OID-prefixed element names.
4. Copies metadata types to target VOB (label, attribute, element, attribute, trigger, and hyperlink type objects).

   Name collisions result in new type names of the form type-name.n (label type REL3.1, or branch type r2_bugfix.1, for example).

5. Converts flat target directory to directory tree by cataloging elements in their containing directories.
6. For borderline elements being relocated (these, by definition, are cataloged in at least one nonrelocated directory): replaces original catalog entries in source VOB directory versions with VOB symbolic links. Each link's text is a relative pathname. For example: ..\..\newhome
7. Rebuilds event history for all elements.
8. Applies nonhyperlink metadata to target VOB elements (labels, attributes, and triggers).
9. Adjusts hyperlinks. Preserves all bidirectional hyperlinks, including merge links. (relocate does not preserve unidirectional hyperlinks whose targets are relocated.) See also mkhlink.

   Adds hyperlink of type RelocationVOB to the target VOB. (catcr uses such hyperlinks to resolve references to relocated objects.)

10. Removes elements from source VOB.
11. Checks in target directory, and checks in source directories from which elements were relocated.

Invoking relocate

Because relocate performs checkouts, creates new elements, and removes elements, invoke it from a view configured to perform these actions on the source and target VOBs. In particular, make sure your config spec can check out the elements to be relocated. For example, a view or config spec without a CHECKEDOUT rule is inappropriate for the purposes of relocate. See the config_spec reference page for more information on view configuration.

WARNING: Do not run multiple relocate commands in the same view in the same directory. Because relocate checks out and checks in files in the directory, simultaneous commands will interfere with each other. To ensure no interference, we recommend that you run only one relocate command at a time in a VOB.

Perform a relocate operation in the same view, or with the same config spec, that you will use to adjust makefiles, rebuild libraries, reset config specs, modify development tools, or complete any other work that may accompany the relocation task. See also AFTER RELOCATION.

If you are using ClearCase MultiSite, see Relocating Elements from Replicated VOBs.

Selecting Elements to Relocate

The term selection set refers to the complete collection of file and directory elements implied by your pname arguments to relocate, irrespective of your view. For example, the command relocate file1 dir2 \newhome yields a selection set that includes file1, dir2, and all files and directories cataloged in all versions of dir2 and its subdirectories. (Note that this means the selection set can include elements for which your current config spec does not select any version.) relocate scans the selection set and extracts a subset, the relocate set, which it moves to the target VOB.

Often, the selection set and relocate set are identical. By default, relocate scans the selection set and adds these elements to the relocate set:

• Each element visible in the current view
• Each element cataloged only by a directory in the selection set

In other words, relocate leaves behind any element that is not visible in the current view and is cataloged in a directory outside the selection set. For example, suppose you relocate directory element lib2, which catalogs file element file.c (that is, at least one version of lib2 catalogs file.c). Your view does not select any version of file.c. Directory element lib4, which you are not relocating, does catalog file.c. By default, file.c stays behind.

The -qall option permits you to interactively confirm or override relocate's default handling of each borderline element: it does not query on all elements in the selection set. A borderline element is one that is cataloged both in a directory being relocated and in a directory not being relocated. relocate's default handling of a borderline element depends on whether the element is visible to your current view: a visible element (config spec selects a version) moves by default. An invisible element (config spec selects no version) does not.

Running relocate in Update Mode

Because relocate locks elements to be moved, relocating elements from a production VOB prevents users from working on them. If the elements to be moved 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.)

CAUTION: If you use update mode, you must not make any changes to the relocated elements in the target VOB until you have stopped using the originals.

In update mode, relocate works as follows:

• Does not create symbolic links in the source VOB to replace existing catalogs; it leaves the catalogs in place
• Allows you to relocate the VOB root and lost+found directories
• Does not stop relocation when it encounters a nonlocally mastered element; it relocates the element
• Does not remove the elements from the source VOB
• Does not check out or modify the source directory
• Does not lock the elements in the relocate set

When you use update mode incrementally, relocate rescans all elements to update them with any changes. 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 may have changed since the last time relocate -update was 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 destination VOB. relocate creates objects; it does not remove them.

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 destination element. Because relocate did not remove the old branch, it cannot create the new one. To work around this problem, remove the destination element; on the next run of relocate, the element is re-created.

Relocating Derived Objects

NOTE: Derived objects are created only in dynamic views.

You can relocate checked-in derived objects as you do any element. Configuration records (CRs) for these DOs move to the target VOB's database.

All nonversioned DOs (shared and view-private)-and their config records-are deleted when relocate removes their containing directory from the source VOB. That is, DO and config record objects are deleted from the VOB database (not moved) with the equivalent of rmdo operations. See also Using recoverview -sync to Recover View-Private Objects and DO Data Files.

Relocating Elements to an Existing VOB

When moving elements to a VOB that is not currently empty (new), be careful to avoid the following problems:

• Target VOB locks on branches, types, or elements (use lock -replace -nuser to work around this problem)
• Name collisions

Relocating Elements from Replicated VOBs

When relocating elements from one replica of a replicated VOB to another VOB, observe the following rules and guidelines:

• You must be an element's master to relocate it.
• You must replicate the target VOB at each site that includes the source VOB. Relocate elements from VOB1 replica to VOB2 at local site; then replicate VOB2 at each VOB1 replica site.

  After a relocate operation at site A, cross-VOB hyperlinks will "dangle" at site B's replica if either site B does not include a replica of the target VOB used at site A, or site B has not been updated by a syncreplica operation since the relocate operation at site A.

• You must coordinate the relocate operation with the administrators of all of the VOB's replicas. For example, if replica A is locked for relocate, and a checkin happens at replica B in the meantime, that checkin is lost to replica A.
• You may need to adjust mastership for metadata type objects. When relocate copies them to the target VOB, it creates them with local mastership.

Relocation and Event History

For each relocated element, two events record the relocate event:

• In the source VOB, a remove element event on the VOB object
• In the target VOB, a relocate event on the relocated element

Relocated element event histories are otherwise preserved nearly intact. (Some minor events are lost.)

Relocate Log File

By default, relocate creates a log file in the current directory with the name relocate.log.date-time. You can use -log to send log output to another location.

Interrupting and Restarting relocate

In general, you can interrupt and restart relocate operation, if you take these precautions:

• Do not release locks that relocate sets in the source VOB.
• Do not modify elements in the selection set (check them in, apply labels to them, and so on).
• Record your answers to -qall queries the first time through.

If restarted with an identical command line, relocate can determine where to resume processing.

The final phase in a relocate operation, removing elements from the source VOB, is not restartable. The relocate log file records the OIDs of elements to be removed. If you interrupt relocate during this phase, you must use the logged OIDs to remove elements manually (rmelem accepts arguments of the form oid:oid).

AFTER RELOCATION

Modifying Views/Config Specs to Find Relocated Elements

In some cases, config specs for existing views may require changes to find elements that have been relocated. In source VOB directory versions that catalog relocated elements, relocate replaces the original catalog entry for a relocated element with a VOB symbolic link. Each link's text is a relative pathname, ..\..\newhome, for example . Views left to access elements via symbolic links may run into problems. For example, you cannot check out a VOB symbolic link, even if it points to an element. There are several ways around this limitation, providing a view with a more direct path to elements in the target VOB:

• Reset views to use pathnames to the new VOB.
• Add labels to relocated versions, and configure the view to select these elements with a label-based rule.
• Apply a particular branch type to relocated elements, and configure the view to select this branch.

Similarly, you will want to examine your build scripts, triggers, and other tools that may need adjustments to accommodate relocated elements.

NOTE: In the source VOB, relocate completes its operation by checking in the parent directories of all relocated elements. Unlike all preceding directory versions, this last checked-in directory version does not include symbolic links to relocated elements. Presumably, the view in which you ran relocate selects this version, and to this view, relocated elements appear simply removed. Working in this view affords an opportunity to track tools, builds, and other potentially "broken" references to the relocated elements.

Fixing Incorrect Symbolic Links

After relocating some elements, the corresponding symbolic links are not always correct for all views in which they may appear. To help resolve such problems, the HyperSlink hyperlink type links symbolic links to their objects. Use describe to get information on the problematic symbolic link; the HyperSlink makes evident how to fix the link.

Using recoverview -sync to Recover View-Private Objects and DO Data Files

relocate does not move view-private objects when it relocates their containing directories. If you do not move or back up these objects, they are effectively lost. However, you can use recoverview -sync view-tag to move view-private files to the dynamic view's lost+found directory, under names like OID_file3.c.

relocate deletes all nonversioned DOs (both shared and view-private)-and their config records-when it relocates their containing directories. A stranded DO data file (its status as a VOB object is now gone, along with its corresponding VOB database entries) can be recovered by a view that still references it with recoverview -sync view-tag. This command moves all view-private files and referenced DOs to the dynamic view's lost+found directory.

Cataloging Relocated Elements in Multiple Versions of the Target Directory

relocate checks out the target VOB directory, relocates elements, and checks in the target directory. This means that relocated elements are cataloged only in the latest version of the target directory, giving these elements a sense of newness that may not be desirable. For example, if the target VOB has been in existence for some time, you may want previous target directory versions to catalog the relocated elements. In this case, you can use the cleartool or Attache ln -nco to add VOB symbolic links to non-LATEST directory versions-cataloging relocated elements in previous versions of target-dir-pname.

If you want relocated elements to be cataloged in the latest versions of target-dir-pname on multiple branches:

1. Set your config spec to select a branch of target-dir-pname, /main/relocate_work, for example.
2. Run relocate.
3. Perform directory merge operations from /main/relocate_work to other branches.

Moving a Relocated Element

If you move a relocated element with mv, a VOB symbolic link to the element from the source VOB is not updated. Instead, the link is left pointing at a nonexistent target (thereby making the link invisible to directory listings and other file-system read operations).

Figure 21 Moving Relocated Element Does Not Update Symbolic Link from Source VOB

RESTRICTIONS

Permissions Checking: You must be the VOB owner (for both VOBs) or a member of the ClearCase group to execute this command.

Locks: relocate first locks all elements to be moved from the source VOB. Then, it creates elements, element types, branch types, and so on in the destination VOB, as required to re-create all moved elements and their metadata. Therefore, relocate returns an error if any of the following objects are locked in the source VOB: VOB, element. It returns an error if any of the following objects are locked in the destination VOB: VOB, element, branch type, element type, label type, hyperlink type, attribute type. See the permissions reference page.

Other Restrictions: 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.

Also, 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.

OPTIONS AND ARGUMENTS

SUPPRESSING THE CONFIRMATION QUERY. Default: After displaying the relocate set, relocate asks you to confirm that these are the elements you want to relocate.

-f·orce

Suppresses the confirmation step.

CONTROLLING SPECIAL CASE HANDLING.   Default: relocate filters the selection set as described above in the subsection Selecting Elements to Relocate.

-qal·l

Prompts user to affirm or reject relocate's handling of each borderline element-one that is cataloged both in a directory being relocated and in a directory not being relocated. The default answer in an individual case depends on the element's visibility in the current view: yes if the view selects some version of the element; no otherwise.

If you reject these defaults, the result is nonfunctional links that you must repair. If a version of an element is visible in the current view and you indicate it is not to be relocated, the result is a bad link in the target VOB. If a version of an element is not visible in the view and you indicate that it is to be relocated, the result is a bad link in the source VOB.

WRITING A LOG FILE. Default: relocate creates a log file in the current directory with the name
relocate.log.date-time.

-log log-pname

Creates a relocate log file at location log-pname.

RELOCATING IN UPDATE MODE. Default: relocate proceeds as described in Overview of a Relocate Operation.

-upd·ate

relocate runs in update mode, as described in Running relocate in Update Mode.

SPECIFYING WHICH FILES TO RELOCATE.   Default: None. You must specify one or more elements to relocate, the selection set. relocate filters the selection set to construct a relocate set as described earlier in Selecting Elements to Relocate.

pname ...

Specifies the elements to be relocated. A pname can be a file element, directory element, or VOB symbolic link.

SPECIFYING A TARGET VOB AND DIRECTORY.   Default: None. You must supply a target directory in a second VOB.

target-dir-pname

Specifies the directory in the target, or destination, VOB that will store the relocated elements. relocate checks out and modifies the version of this directory that is selected by your current view. The target directory must be in the same view as the source pathname (that is, you cannot specify a view-extended pathname for target-dir-pname). This pathname must be drive-relative (non-drive-specific):

EXAMPLES

Examples including wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the command interpreter prompt. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt. In Attache, cmd-context represents the workspace prompt.

• Move subdirectory glib (and its one file, file.c) from \vob_lib to the newly created VOB \vob_gui. Query on borderline elements. To illustrate how relocate replaces element names with symbolic links in the source VOB, the example uses a relative pathname to specify the target VOB.

  After relocating glib, examine the RelocationVOB hyperlink added to \vob_gui.

> cd \vob_lib

cmd-context setcs -default

cmd-context relocate -qall .\glib_src ..\vob_gui
Logfile is "relocate.log.09-Apr-99.14.11.37".
Selected "glib".
Selected "glib\file.c".
Do you want to relocate these objects? [no] yes
Checked out "." from version "\main\3".
Checked out "\vob_gui" from version "\main\0".
Locking selected objects
Locked "glib"
Locked "glib\file.c"
Recreating selected objects
Created "glib"
updated branch "\main"
   updated version "\main\0"
       created version "\main\1"
       Created "glib\file.c"
   updated branch "\main"
       updated version "\main\0"
       created version "\main\1"
Cataloging new objects
   cataloged symbolic link "\vob_lib\glib\.@@\main\2\glib" -> "..\vob_gui\glib"
   cataloged symbolic link "\vob_lib\glib\.@@\main\3\glib" -> "..\vob_gui\glib"
   cataloged "\vob_lib\.@@\main\CHECKEDOUT.32\glib"
   cataloged symbolic link "\vob_lib\glib\.@@\main\1\file.c" -> "..\vob_gui\glib\file.c"
   cataloged symbolic link "\vob_lib\glib\.@@\main\2\file.c" -> "..\vob_gui\glib\file.c"
   cataloged "\vob_gui\glib@@\main\1\file.c"
Removing original objects
   removed "glib\file.c"
   removed "glib"
Checked in "\vob_lib\." version "\main\4".
Checked in "\vob_gui\." version "\main\1".

cmd-context describe vob:\vob_gui
versioned object base "\vob_gui"
  created 09-Apr-99.13:50:16 by clearadm.adm@propane
  "relocate target for former directory \vob_lib"
  VOB storage host:pathname "propane:\vobstore\gui.vbs"
  VOB storage global pathname "\\propane\vobstore\gui.vbs"
  VOB ownership:
    owner clearadm
    group sys
  Hyperlinks:
    RelocationVOB@33@\vob_gui vob:\vob_gui -> vob:\vob_lib

FILES

relocate.log.date-time

SEE ALSO

ln, mkvob, mv