Troubleshooting
Problem
This technote discusses why the error, []cleartool: Error: Element "
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:
- You are creating directory level UCM components in an existing VOB and have already converted at least one directory to a component.
- 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:
- Duplicate the element so it is in both components
Or - Remove all references to the element from one directory tree.
Or - 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
- checkout the directory element in the second directory tree (the one where rmcomp failed) that contains the element.
- Copy the visible version of the file to a temporary file (UNIX example: cp foo.c foo.c.duplicate)
- cleartool rmname the original element.
- Rename the duplicate to its appropriate name (UNIX example: mv foo.c.duplicate foo.c)
- cleartool mkelem the view private copy to be a new element
- checkin the directory element
- merge the directory change to other branches as necessary
- 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.
- Identify the directory element to remove the element from. (See Identifying the problem elements below)
- 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® | ||
AIX® | ||
Solaris® | ||
HP-UX® | ||
Linux® Red Hat® & SUSE® |
==============================================================================
Instructions:
- Copy the correct version of the utility to your VOB server host and decompress
- Lock the VOB
- Open a command prompt and cd to the VOB database (db) directory
- Execute the utility (no switches required).
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.
==============================================================================
Instructions:
- Open a command prompt in a view context and cd to the VOB root directory.
- 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.
==============================================================================
Instructions:
- Open a command prompt in a view context and cd to the VOB root directory.
- 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
- Hardcopy can be ordered from the IBM Publications Center.
- On-line documentation can be found:
About the ClearCase Information Center
Note: The on-line ClearCase version 7.x documentation can be found in the IBM Publication Center and has been organized for you in technote 1239261.
2003.06:
HTML
PDF LINKS
- Distributed Documentation
UNIX® and Linux®: /opt/rational/clearcase/doc/books
Microsoft® Windows®: C:\Program Files\Rational\ClearCase\doc\books
[{"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"}}]
Was this topic helpful?
Document Information
Modified date:
16 June 2018
UID
swg21200838