IBM Support

"Element is a member of another component" error when converting a VOB directory to a UCM component

Troubleshooting


Problem

This technote discusses why the error, []cleartool: Error: Element "@@" is a member of another component[], occurs when converting an existing IBM® Rational® ClearCase® VOB directory to a UCM component.

Symptom


Attempts to convert existing VOB directories into UCM components may result in the following error:

M:\dynamic_view\comp1\dir1>cleartool mkcomp -root . sub1@\PVOB


Processing subdirectory elements...
Done processing subdirectory elements.
Set Admin VOB for component "sub1"'s VOB
Created component "sub1".

M:\dynamic_view\comp1\dir1>cd ..\dir2

M:\dynamic_view\comp1\dir2>cleartool mkcomp -root . sub2@\PVOB
Processing subdirectory elements...
cleartool: Error: Element "M:\dynamic_view\comp1\dir2\foo.c@@" is a member of another component.
cleartool: Error: Unable to create component.

Cause


The problem occurs only if the following two conditions are met:

  1. You are creating directory level UCM components in an existing VOB and have already converted at least one directory to a component.

  2. The cleartool mv command, or equivalent operation, was run in the VOB at some point prior to its conversion to UCM components, which moved an element from the subtree under one component root to the subtree under a different component root. Review the ClearCase Command Reference Guide on the topic of mv (cleartool man mv ) for more information about mv restrictions in a UCM environment.

Why does this affect UCM?

The cleartool mv operation does not remove a file from old directory versions. Rather it creates a new version of the source directory without the file name, and a new version of the target directory with the file name.

In UCM, a ClearCase file or directory element can belong to only one UCM component.

When a directory element is made into the "root" of a UCM component, every version of every directory in the subtree under that "root" is searched for elements, and those elements are "claimed" for that new component.

An element that has been moved will reside in versions of the directory it was moved from, and in versions of the directory it was moved to; hence, both components will attempt to "claim" the element (during the respective mkcomp).

The first VOB directory to be made a component root (mkcomp) will claim the element successfully.
All subsequent mkcomp attempts will fail if they attempt to claim the same element.

The config spec of the view used for mkcomp does not affect this.

Notes:
* Drag and drop is the GUI equivalent functionality of cleartool mv.
* Creating a VOB hardlink running the cleartool ln command will cause the same problem.
* This architecture is the same reason that the cleartool mv, cleartool relocate and clearexport_ccase operations are not supported in UCM.

Resolving The Problem


Important Notes:

  • The following procedure is permanent (irreversible), and cannot be undone short of restoring from backup. It is advised that you take a complete backup of all VOBs that will be involved in this procedure before proceeding. There are procedures for restoring a VOB from backup (should the need arise). Review the ClearCase Administrator's Guide on the topic of Restoring Critical ClearCase Data for more information.

  • The following procedure cannot be used in a VOB that is replicated with ClearCase MultiSite. The VOB would have to be de-replicated, and re-replicated after the procedure. The alternative is to copy the data into a new VOB and componentize it there (option 3 below).

  • The procedure requires ClearCase administrative privileges.

  • For supervision or further assistance with this procedure, please contact IBM Rational Client Support

Resolution Overview

Conceptually, there are three basic approaches to resolving this conflict:
  1. Duplicate the element so it is in both components
    Or
  2. Remove all references to the element from one directory tree.
    Or
  3. This problem can be avoided by duplicating all the legacy data into a new VOB using clearexport_ccase and clearimport, and converting subdirectories of the new VOB into components instead. This new VOB will retain file element history but no directory history. A single version is created for each directory, matching the version from the legacy VOB which is visible in the view being used. No VOB hard links are created. The original VOB can be archived to use where directory history is necessary.

NOTE: To remove all references from the first directory tree (already a component) and keep the element in the second directory tree ( where rmcomp failed) you MUST first rmcomp the existing component. The component can be recreated after removing references, and it will not include the problem element.

The options further break down as follows:
1. Duplicate the element so it is in both components
  1. checkout the directory element in the second directory tree (the one where rmcomp failed) that contains the element.

  2. Copy the visible version of the file to a temporary file (UNIX example: cp foo.c foo.c.duplicate)

  3. cleartool rmname the original element.

  4. Rename the duplicate to its appropriate name (UNIX example: mv foo.c.duplicate foo.c)

  5. cleartool mkelem the view private copy to be a new element

  6. checkin the directory element

  7. merge the directory change to other branches as necessary

  8. Use cleartool rmname -nco to remove the file name from all other (older) versions of the directory. See the Tools below ("Remove the problematic hard links") rather than use "cleartool rmname" directly.
2. Remove all references to the element from one directory tree.

Note: Removing these references from directories could cause some historical builds to fail, which may require follow-up modifications to those scripts.
  1. Identify the directory element to remove the element from. (See Identifying the problem elements below)

  2. Use cleartool rmname -nco to remove the file name from all versions of the directory
    Note: To remove all references from the first directory tree (already a component) and keep the element in the second directory tree (where rmcomp failed) you MUST first rmcomp the existing component.

    rmname -nco will NOT remove the problem element from the component.
    See the Tools below ("Remove the problematic hard links") rather than use "cleartool rmname" directly.

Tools to make the job easier:

The error message identifies ONE file or directory element that has a component conflict.
The mkcomp operation fails at that point. There may be multiple problem elements.
The tools and procedures below will help to resolve the problem without having to repeatedly attempt mkcomp
Locate the Problematic Hard Links


To assist with locating the hard links in the VOB, IBM Rational Client Support has provided a utility named find_hlinks_lstfnd.
This tool identifies file and directory elements which are catalogued (hard linked) in at least one version of each of two distinct directory elements.

Note: This tool is strictly a read-only utility and will under no circumstances make any modifications to your database or source code.

The tool is operating system-specific and VOB schema version-specific. There are several pre-built versions represented below. If your operating system or schema version or both are not represented below, IBM Rational Client Support will need to build the tool for you. Use ESR to open a service request with IBM Rational Client Support requesting a version of the tool you require and referencing this technote.

Operating System
Schema 53
Schema 54

Windows®
find_hlinks_lstfnd_53.zip
find_hlinks_lstfnd_54.zip

AIX®
find_hlinks_lstfnd.aix4_power.53.gz
find_hlinks_lstfnd.aix4_power.54.gz

Solaris®
find_hlinks_lstfnd.sun5.53.gz
find_hlinks_lstfnd.sun5.54.gz

HP-UX®
find_hlinks_lstfnd.hp11_pa.53.gz
find_hlinks_lstfnd.hp11_pa.54.gz
Linux®
Red Hat®
& SUSE®
find_hlinks_lstfnd.linux_x86.53.gz
find_hlinks_lstfnd.linux_x86.54.gz

==============================================================================
Instructions:
  1. Copy the correct version of the utility to your VOB server host and decompress
  2. Lock the VOB
  3. Open a command prompt and cd to the VOB database (db) directory
  4. Execute the utility (no switches required).
Note: The output returns the file and directory elements by the database identifier - dbid.

Windows (schema 54 VOB) example:
C:\ClearCase_Storage\VOBs\test_vob.vbs\db>find_hlinks_lstfnd_54.exe        
Elem 59 catalogued in multiple directory elements (55, 47)
Elem 72 catalogued in multiple directory elements (44, 47)
Elem 66 catalogued in multiple directory elements (22, 31)
Elem 62 catalogued in multiple directory elements (47, 19)

5. Unlock the VOB
==============================================================================

Identify the problematic files, by name


To assist with resolving the hard links to pathnames in the VOB, IBM Rational Client Support has provided a utility named find_hardlinks_resolve_names.pl.
This tool takes the output of find_hlinks_lstfnd and cross references it in two ways.
  • by element pathname - showing all directory elements having a hard link for it in some version
  • by directory elements - showing all elements it contains, which also have a hard link in a version of some other directory

Notes: This tool is strictly a read-only utility and will under no circumstances make any modifications to your database or source code.

find_hardlinks_resolve_names.pl
==============================================================================
Instructions:
  1. Open a command prompt in a view context and cd to the VOB root directory.
  2. Run the tool as a Perl script. The only argument is the name of a file containing the output of find_hlinks_lstfnd
    For example:
    Perl find_hardlinks_resolve_names.pl find_hardlinks.out


Not all VOB hard links are causing the mkcomp command to fail.
An element is only problematic if it has at least two distinct parent directory elements which will NOT be under the same UCM Component Root Directory.
==============================================================================

Remove the problematic hard links


To assist with removing the element references from old directory versions, IBM Rational Client Support has provided a utility named rmname_from_all_versions.pl.
This tool searches all versions of a specified directory element for entries with a specified name or element dbid.
It then removes those entries using "cleartool rmelem -nco"

NOTE: This tool makes irreversible changes to your VOB.
Once an entry has been removed from a directory version, it can never be added back into that same version of the directory.

rmname_from_all_versions.pl
==============================================================================
Instructions:
  1. Open a command prompt in a view context and cd to the VOB root directory.
  2. Run the tool as a Perl script. The usage is
    <Perl-interpreter> rmname_from_all_versions.pl [-name <file/dir name> | -dbid <element-dbid>] -dir <directory element>
    For example:
    ccperl rmname_from_all_versions.pl -name  foo.c -dir \sources\src
==============================================================================


Example

First step is to run the find_hlinks_lstfnd utility.

#[17] %cd db
#[18] %./find_hlinks_lstfnd.sun5.54 > find_hlinks_lstfnd.txt
#[19] %head find_hlinks_lstfnd.txt
Elem 16624 catalogued in multiple directory elements (16615, 16621)
Elem 18513 catalogued in multiple directory elements (18270, 106056)
Elem 18517 catalogued in multiple directory elements (18270, 106056)
Elem 18665 catalogued in multiple directory elements (18270, 106056)
Elem 18669 catalogued in multiple directory elements (18270, 106056)
Elem 18681 catalogued in multiple directory elements (18270, 106056)
Elem 18685 catalogued in multiple directory elements (18270, 106056)
Elem 18865 catalogued in multiple directory elements (18270, 106056)
Elem 18869 catalogued in multiple directory elements (18270, 106056)
Elem 19009 catalogued in multiple directory elements (18270, 106056)
#[20] %

Next, set into a view and run the find_hardlinks_resolve_names.pl utility.

#[20] %ct setview default
#[1] %ct mount /vobs/legacy_comps
#[2] %cd /vobs/legacy_comps
#[3] %cp <save-path>/find_hardlinks_resolve_names.pl .
#[4] %cp <VOB_stg-path>/legacy_comps.vbs/db/find_hlinks_lstfnd.txt .
#[5] %Perl find_hardlinks_resolve_names.pl find_hlinks_lstfnd.txt > ambiguous_pathnames.txt


Comments on the output
#[6] %more ambiguous_pathnames.txt
1. By element: listing of multiple parent directories

Elem /vobs/legacy_comps/.@@/main/release/dave_initialversion/1/VersionTree.txt@@
        /vobs/legacy_comps/.@@
        /vobs/legacy_comps/Docs@@
Elem /vobs/legacy_comps/Common/Interface@@/main/10/MessagesServer.cpp@@
        /vobs/legacy_comps/Common/Interface@@
        /vobs/legacy_comps/Sources/Obsolete@@
Elem /vobs/legacy_comps/Common/Interface@@/main/15/MessagesServer.dfm@@
        /vobs/legacy_comps/Common/Interface@@
        /vobs/legacy_comps/Sources/Obsolete@@
Elem /vobs/legacy_comps/Common/Magic/Swap.cpp@@
        /vobs/legacy_comps/Common/Magic@@
        /vobs/legacy_comps/Common/Objects@@
Elem /vobs/legacy_comps/Common/Process/Event.cpp@@
        /vobs/legacy_comps/Common/Objects@@
        /vobs/legacy_comps/Common/Process@@
Elem /vobs/legacy_comps/Common/Process/Register.cpp@@
        /vobs/legacy_comps/Common/Objects@@
        /vobs/legacy_comps/Common/Process@@
Elem /vobs/legacy_comps/Common/Resources/ValidList.cpp@@
        /vobs/legacy_comps/Common/Resources@@
        /vobs/legacy_comps/Sources/Obsolete@@
Elem /vobs/legacy_comps/Common@@
        /vobs/legacy_comps/.@@
        /vobs/legacy_comps/Sources@@
Elem /vobs/legacy_comps/LIB@@
        /vobs/legacy_comps/.@@
        /vobs/legacy_comps/Sources@@
Elem /vobs/legacy_comps/MessageServer@@
        /vobs/legacy_comps/.@@
        /vobs/legacy_comps/Sources@@
Elem /vobs/legacy_comps/reports/Output/Build/Com_Light.dll@@
        /vobs/legacy_comps/Sources@@/main/6/Output/main/1/Build@@
        /vobs/legacy_comps/reports/Output/Build@@
Elem /vobs/legacy_comps/reports/Output/Build/Evaluator.dll@@
        /vobs/legacy_comps/reports@@
        /vobs/legacy_comps/Sources@@/main/6/Output/main/1/Build@@

In this output, the following ambiguities will NOT cause a problem, because both parent directories fall under the same component root (/vobs/legacy_comps/Common):
/vobs/legacy_comps/Common/Magic/Swap.cpp@@
/vobs/legacy_comps/Common/Process/Event.cpp@@
/vobs/legacy_comps/Common/Process/Register.cpp@@

The following will have a conflict if both "/vobs/legacy_comps/Common" and "/vobs/legacy_comps/Sources" are imported as component roots:
/vobs/legacy_comps/Common/Interface@@/main/10/MessagesServer.cpp@@
/vobs/legacy_comps/Common/Interface@@/main/15/MessagesServer.dfm@@
/vobs/legacy_comps/Common/Resources/ValidList.cpp@@

The following will have a conflict if both "/vobs/legacy_comps/reports" and "/vobs/legacy_comps/Sources" are imported as component roots:
/vobs/legacy_comps/reports/Output/Build/Com_Light.dll@@
/vobs/legacy_comps/reports/Output/Build/Evaluator.dll@@

In this case, several subdirectories of "/vobs/legacy_comps/Sources" have been moved up to the VOB root, so that they can become separate components.
The best solutions here are:
1. Completely break up "/vobs/legacy_comps/Sources" and do not make it a component root
OR
2. Remove all names from old versions of "/vobs/legacy_comps/Sources"

#[19] %ls -i .
     16624 Common                               108648 VersionTree.txt
     47169 Docs                                  34846 LIB                              
    134296 MessageServer                         26685 reports
    197917 Scripts                               16618 lost+found
     16621 Sources
#[20] %ls -i Sources@@/main/REL_2.0
     16624 Common                 32539 Icon1.ico             134296 MSV
     45676 CommonTests           318203 Libs                   26685 Reports
    124726 Evaluator             253941 Libs_src              106056 Obsolete
     34846 Ext

We can use rmname_from_all_versions.pl to clean up Sources:

#[21] %Perl /var/tmp/rmname_from_all_versions.pl -name Common -dir Sources
................................................
The following entries were found with name "Common"
  Elem_dbid     Directory Version
      16624     Sources@@/main/1
      16624     Sources@@/main/10
      16624     Sources@@/main/11
      16624     Sources@@/main/12
      16624     Sources@@/main/13
      16624     Sources@@/main/14
      16624     Sources@@/main/15
      16624     Sources@@/main/16
      16624     Sources@@/main/17
      16624     Sources@@/main/18
      16624     Sources@@/main/19
      16624     Sources@@/main/2
      16624     Sources@@/main/20
      16624     Sources@@/main/21
      16624     Sources@@/main/22
      16624     Sources@@/main/23
      16624     Sources@@/main/24
      16624     Sources@@/main/25
      16624     Sources@@/main/3
      16624     Sources@@/main/4
      16624     Sources@@/main/5
      16624     Sources@@/main/6
      16624     Sources@@/main/7
      16624     Sources@@/main/8
      16624     Sources@@/main/9
      16624     Sources@@/main/2007_v6_index/0
      16624     Sources@@/main/2007_v6_index/1
      16624     Sources@@/main/2007_v6_index/2
      16624     Sources@@/main/2007_v6_index/3
      16624     Sources@@/main/2007_v6_index/4
      16624     Sources@@/main/2007_v6_index/5
      16624     Sources@@/main/2007_v6_index/6
      16624     Sources@@/main/importucm/0
      16624     Sources@@/main/importucm/1
      16624     Sources@@/main/importucm/2
      16624     Sources@@/main/importucm/3
      16624     Sources@@/main/delphi/0
      16624     Sources@@/main/delphi/1
      16624     Sources@@/main/delphi/2
      16624     Sources@@/main/delphi/2007_v5_index/0
Continue and remove all the directory entries listed? [no] yes

Since it seems that the element "Reports" was changed to "reports" at some stage,
we'll do that one by "dbid":
#[22] %%Perl ~/calls/drobinson/rmname_from_all_versions.pl -dbid 26685 -dir Sources
................................................
The following entries were found for dbid 26685
"Sources@@/main/1/Reports"
"Sources@@/main/10/Reports"
"Sources@@/main/11/Reports"
"Sources@@/main/12/Reports"
"Sources@@/main/13/Reports"
"Sources@@/main/14/Reports"
"Sources@@/main/15/Reports"
"Sources@@/main/16/Reports"
"Sources@@/main/17/Reports"
"Sources@@/main/18/Reports"
"Sources@@/main/19/Reports"
"Sources@@/main/2/Reports"
"Sources@@/main/20/Reports"
"Sources@@/main/21/Reports"
"Sources@@/main/22/Reports"
"Sources@@/main/23/Reports"
"Sources@@/main/24/Reports"
"Sources@@/main/25/Reports"
"Sources@@/main/3/Reports"
"Sources@@/main/4/Reports"
"Sources@@/main/5/Reports"
"Sources@@/main/6/Reports"
"Sources@@/main/7/Reports"
"Sources@@/main/8/Reports"
"Sources@@/main/9/Reports"
"Sources@@/main/2007_v6_index/0/Reports"
"Sources@@/main/2007_v6_index/1/Reports"
"Sources@@/main/2007_v6_index/2/Reports"
"Sources@@/main/2007_v6_index/3/Reports"
"Sources@@/main/2007_v6_index/4/Reports"
"Sources@@/main/2007_v6_index/5/Reports"
"Sources@@/main/2007_v6_index/6/Reports"
"Sources@@/main/2007_v6/0/Reports"
"Sources@@/main/2007_v6/1/Reports"
"Sources@@/main/2007_v6/2/Reports"
"Sources@@/main/2007_v6/importucm/0/Reports"
"Sources@@/main/2007_v6/importucm/1/Reports"
"Sources@@/main/2007_v6/importucm/2/Reports"
"Sources@@/main/2007_v6/importucm/3/Reports"
"Sources@@/main/delphi/0/Reports"
"Sources@@/main/delphi/1/Reports"
"Sources@@/main/delphi/2/Reports"
"Sources@@/main/delphi/2007_v5_index/0/Reports"
Continue and remove all the directory entries listed? [no] yes
rcssun01[28] %


If "Sources" is to be imported as a component root, then all the individual conflicts under that path still have to be resolved.

The second part of the find_hardlinks_resolve_names.pl output just organizes the output by directory.
This may help process the data more quickly - where many elements have been moved out of one directory, it is easier to process them together instead of jumping from directory to directory.

Example output:

2. By directory: listing of problem elements

Directory /vobs/legacy_comps/.@@
        /vobs/legacy_comps/Common@@
        /vobs/legacy_comps/reports@@
        /vobs/legacy_comps/LIB@@
        /vobs/legacy_comps/.@@/main/release/dave_initialversion/1/VersionTree.txt@@
        /vobs/legacy_comps/MessageServer@@
        /vobs/legacy_comps/Sources/Libs@@
Directory /vobs/legacy_comps/Common/IT@@
        /vobs/legacy_comps/Sources/Obsolete/MigrationLSP.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/MigrationLSP.cpp@@
        /vobs/legacy_comps/Sources/Obsolete/TeamTime.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/TeamTime.cpp@@
Directory /vobs/legacy_comps/Common/Interface@@
        /vobs/legacy_comps/Sources/Obsolete/MigrationAVP.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/MigrationAVP.cpp@@
        /vobs/legacy_comps/Sources/Obsolete/MigrB.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/MigrB.cpp@@
        /vobs/legacy_comps/Sources/Obsolete/Pump.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/Pump.cpp@@
        /vobs/legacy_comps/Sources/Obsolete/TeamTimeAnalysis.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/TeamTimeAnalysis.cpp@@
        /vobs/legacy_comps/Sources/Obsolete/TeamTimeSynthesis.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/TeamTimeSynthesis.cpp@@
        /vobs/legacy_comps/Common/Interface@@/main/10/MessagesServer.cpp@@
        /vobs/legacy_comps/Common/Interface@@/main/15/MessagesServer.dfm@@
Directory /vobs/legacy_comps/Common/MagicMatrix@@
        /vobs/legacy_comps/Sources/Obsolete/Orders.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/Orders.cpp@@
        /vobs/legacy_comps/Sources/Obsolete/FluxView.dfm@@
        /vobs/legacy_comps/Sources/Obsolete/FluxView.cpp@@

After resolving identified conflicts, it is advisable to rerun the utilities and verify that everything problematic has been resolved.
Note again that it is not problematic when an element has two alternate pathnames that resolve through the same component root.

Further Information


Review the ClearCase Managing Software Project manual on the topic of Creating components for storing elements for more information on creating UCM components.

Documentation

[{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"UCM: Component","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF015","label":"IRIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"2003.06.00;2003.06.16;7.0;7.0.1;7.1;7.1.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"UCM: Component","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
16 June 2018

UID

swg21200838

Page Feedback