14.2 Element Relocation Illustrated

The following series of figures illustrates several variants of a comparatively simple relocate operation and emphasizes how the various versions of affected directories catalog elements after the move. The figures assume these conditions:

• The view used for the relocate operation selects \main\LATEST for all elements being relocated. This approach is recommended because it is least likely to generate confusing results for VOB users and administrators. (You can use a different branch, as long as the config spec selects the latest version on that branch.)

• The target VOB was created to accommodate the relocated elements. This approach is not mandatory, but we recommend it. It minimizes the chances of name collision between an existing element and a relocated one and of encountering locked type objects in the target VOB.

NOTE: All figures use the following shorthand notation for directory versions:

dir1\1 = dir1@@\main\1

Figure 23 shows the source and target VOBs, \bigdir and \new, before relocating one directory element (dir1) and four file elements (three contained by dir1, plus the single element f4). This is the applicable relocate command sequence:

c:\> net use v: \\view\main (view selects \main\LATEST in source and target VOBs)
c:\> v:
v:\> cd \bigdir
v:\bigdir> cleartool relocate dir1 f4 \new

Figure 23 Elements Cataloged by Directory Versions Before Relocate Operation

The relocate command defines a selection set that includes dir1, f1, f2, f3, and f4.

Figure 24 shows the VOBs after relocate runs.

Figure 24 Directory Version Cataloging After Relocate Operation

Cataloging in the Source VOB

In the source VOB, after relocate completes, preexisting parent directory versions (bigdir@@\main\1 and bigdir@@\main\2 in Figure 24) include symbolic links to the moved elements. These links provide stability for historical views, which can continue to view the VOB as it existed before the relocate operation.

relocate checks in a new version of each relocated element's containing directory (bigdir@@\main\3 in Figure 24). The new directory version created by relocate does not catalog any relocated elements. In general, this result is desirable; it forces you to address any anomalies in your active development environment that may have resulted from the relocate operation. A guiding principle is that as many views, scripts, and so on, as possible find relocated elements at their new locations, rather than through VOB symbolic links left behind in the original VOB. See Symbolic Links for some reasons to avoid relying too heavily on VOB symbolic links. See Updating Directory Versions Manually for information on adding symbolic links to relocated elements where circumstances warrant it.

Cataloging in the Target VOB

In the destination VOB, only the latest version of the target directory catalogs relocated elements. Figure 24 illustrates the common, recommended scenario involving a new destination VOB. However, even if the new directory has many versions, only the version created automatically by relocate-on the target directory branch selected by the current config spec-catalogs the moved elements. Figure 25 shows the destination VOB from Figure 24, expanded to include multiple versions of the target directory.

Figure 25 Destination VOB That Includes Multiple Versions

See Updating Directory Versions Manually for information on adding symbolic links to relocated elements where circumstances warrant it.

Relocating Borderline Elements

Figure 26 illustrates the relocate operation shown in Figure 23 and Figure 24, but this time the source VOB includes a borderline element (f3). This element is cataloged both in a version of a directory in the selection set and in some version of a directory outside the selection set (in a directory that stays behind). (See key in Figure 23 here.)

Figure 26 Source VOB That Includes a Borderline Element

File element f3 is cataloged in both dir1 and dir2. dir1 is in the selection set, but dir2 is not. Assume for now that the config spec for the administrator's working view includes a \main\LATEST rule that makes f3 visible as \bigdir\dir1\f3. Because f3 is visible to the working view, relocate moves it by default, as shown in Figure 27.

Figure 27 Source and Destination VOBs with Borderline Element Relocated

Element f3 is relocated, and the directory version in the source VOB that referenced it (dir2@@\main\1) is updated with a VOB symbolic link to its new location.

Figure 28 shows borderline element f3 left behind in the source VOB. These different scenarios may yield this result:

• The -qall option to relocate is used. In this case, each borderline element triggers the relocate this element or not? prompt.

• At relocate time, if the working view selects no version of f3, it stays behind by default. (In this case, using -qall yields an opportunity to relocate f3 anyway.)

Figure 28 Source and Destination VOBs with Borderline Element Not Relocated

The next section follows on these examples to examine the administrator's role in a relocate operation.