|
|
|
Soft - is your software and documentation |
ClearCase VOBs - “How do I” covers: (Last updated 12-Nov-09)
· Elements – identifying by oid, source container, etc...
· Triggers – copying, ACL’s, applying, etc...
· Types & Type manager – manually reconstruct cleartext, magic files, type manger, restoring elements, etc...
· Links - hard links, etc...
· VOB (Raima) database – Raima database errors.
· VOB database – 2GB database files limit, reducing the size of string file, etc...
· Storage - .(dot) identify file, renaming VOB storage, VOB tags, etc...
· Backup & restore – about file system snapshots, etc...
· ClearCase commands – rmname and checkouts, etc...
· Scripts & utilities – changing ownership of all objects in, listing locked, last time VOB accessed, etc...
· Limitations – of storage, etc...
· Problems & Issues – VOB symbolic link issue, etc...
· Addendums – to: mkvob –nremote_admin, etc
Table of Contents
ClearCase
VOBs - “How do I” covers: (Last updated 12-Nov-09)
2. How do I - determine the full pathname and version of
an element identified only by its oid
3. How do I - Identify elements by the source container
path
4. How do I – understand the Primary Group requirements
for element creation
5. How do I - Restore an element that has been rmnamed
6. How do I – understand what the History Mode element
means
7. How do I - List and count the number of elements in
VOB
9. How do I - determine the amount of elapsed time
ClearCase spends in trigger logic
10. How do I - create a preop checkin trigger that does
not fire on directories
11. How do I - copy a Trigger Type
12. How do I - use Access Control Lists with triggers to
restrict operations to specific groups
13. How do I – understand about deleted user accounts and
ClearCase performance
14. How do I - apply a trigger to the ClearCase move
operation
15. How do I – create a trigger to prevent unreserved
checkouts on UNIX and Linux
16. How do I – enforce a standard set of triggers from
windows to control mklbtype, rmlbtype, etc...
17. How do I - detect whether a checkin is part of an Add
to Source Control operation in a trigger
18. How do I - change element ownership when new elements
are added to the VOB
19. How do I - convert a base ClearCase VOB to a UCM
Component
20. How do I – understand about reserved and unreserved
checkouts
21. How do I - run JRE version 1.4.2_05 and higher within
a VOB context on Linux
22. How do I - convert a VOB to an AdminVOB
23. How do I - suppress the confirmation dialogue box that
displays VOBs that have been mounted
24. How do I – handle binary files in ClearCase
25. How do I - manually construct cleartext
26. How do I – understand the VOB server operation Create
Container failed issue
27. How do I – understand how ClearCase evaluates multiple
magic files
28. How do I – use the ClearCase Magic file
29. How do I – Add a new element type to the local
cc.magic file
30. How do I – understand how the file type of a new
element is determined
31. How do I – Change element types in a replicated VOB
32. How do I - restore an element from backup using
standard file copy
33. How do I – Knowledge Collection: Type manager <text_file_delta>
failed create_version operation
34. How do I – resolve a Type manager text_file_delta
failed create_version operation
36. How do I – understand about type managers and size
limitations
37. How do I – understand the file too large error
checking in a text file issue
38. How do I – understand the mkbrtype command
39. How do I – understand how file types are determined
when creating a new element
40. How do – use the new Merge Type Copy feature with
ClearCase version 7
41. How do I – resolve a definition of type in AdminVOB
would be eclipsed issue
42. How do I – understand the type manager text_file_delta
failed create_version operation issue
43. How do I - change the XML Diff/Merge Type Manager
44. How do I - identifying hard links within a VOB
45. How do I – understand the VOB hard link created due to
canceled checkout issue
46. How do I – understand about locating checkouts for VOB
symbolic links
47. How do I - create Symbolic Links (symlinks) from
command line
48. How do I - create Symbolic Links (symlinks) from the
GUI
49. How do I – manage symbolic links in ClearCase interop
50. How do I - remove Symbolic and Hard Links in ClearCase
51. How do I – understand the db_VISTA error 2 from
OpenFileMapping() of lockmgr_almd
52. How do I – understand the db_VISTA database error -4 -
invalid database
53. How do I – understand db_VISTA database error -5 -
invalid field name
54. How do I – understand VISTA error -6 – invalid
db_address
55. How do I – understand db_VISTA error -900 (errno ==
"No such file or directory")
56. How do I – understand db_VISTA database error -900 -
no more space on file
58. How do I – understand the shared memory version
changed on lock
62. How do I – understand db_VISTA database error -905 -
error opening file
64. How do I – understand db_VISTA database error -905 -
error opening file
65. How do I – understand db_VISTA error -907 (errno ==
"Resource temporarily unavailable")
66. How do I – understand db_VISTA error -907 (errno ==
"Resource temporarily unavailable")
67. How do I – understand db_VISTA database error -909 -
file record limit exceeded
68. How do I – understand db_VISTA error -912 (errno ==
"Invalid argument")
69. How do I – understand db_VISTA error -919 (errno ==
"Resource temporarily unavailable")
71. How do I – understand db_VISTA database -922: lockmgr
is busy
72. How do I – understand db_VISTA error -925 (errno ==
"Resource temporarily unavailable")
73. How do I - reduce the size of the string file for a
ClearCase VOB
74. How do I – understand about the 2 Gigabyte limitation
of VOB database files
75. How do I - remove all Derived Objects from a VOB
77. How do I - increase reformatvob performance
79. How do I – understand why a database must be dumped
before it can be loaded
80. How do I – understand the VOB database files that can
be regenerated or replaced
81. How do I – understand about ClearCase database vista.*
files
82. How do I – understand about ClearCase event records in
the VOB database
84. How do I – understand why ClearCase spawns hundreds of
db_server processes
85. How do I – understand about the lost+found directory
86. How do I - rename a ClearCase VOB (applies to renaming
a view as well)
88. How do I – resolve there are no generated data sources
available for storage dir issue
90. How do I – understand about cleartool mount options
91. How do I - recreate the cleartext storage pool
92. How do I – address the the chown_pool and
chown_container support issue on Linux
93. How do I – understand about the interaction between
ClearCase and file system snapshots
94. How do I - restore an element from backup using
clearexport_ccase
95. How do I – understand about cleartool rmname and
checkouts
97. How do I - list locked VOBs
98. How do I - change the ownership of all objects in a
VOB
99. How do I - determine the last time a VOB was modified
100. How do I - find all checkins in a VOB that occurred
since a particular date
101. How do I - automate uncheckout
102. How do I - list and count the number of elements in
VOB
103. How do I - show disk utilization per branch per
element using UNIX du command
104. How do I – understand the issue of hosting VOB Servers
on VMware
105. How do I – understand the limits on the number of VOBs
stored on a single VOB server
106. How do I – understand about the limits for
simultaneously mounting VOBs on a single host
107. How do I – understand that increasing the lockmgr
parameters can cause NFS deadlocks
108. How do I – understand the supplement to the Command
Reference Guide on mkvob -nremote_admin
109. How do I – understand the supplement to the Command
Reference Guide on comments
110. How do I – understand the supplement to the Command
Reference Guide on mktrtype
111. How do I – understand the issue unable to determine
version for VOB root directory element
113. How do I – understand why dbcheck crashes with
Unhandled exception in ClearCase 7.1
117. How do I – understand the failed to record hostname
issue in ClearCase
118. How do I – understand the “Unable to raise the VOB
Family Feature Level” issue
121. How do I – understand about VOBs mounted read-only and
checkouts of directory elements
123. How do I – understand the Warning: unable to scrub
Pool cdft below maximum size issue
124. How do I – understand the data to collect when there
are VOB issues
125. How do I – resolve error from VOB database and Trouble
opening VOB database
126. How do I - restore missing versions to a VOB from a
known data source
127. How do I – resolve a Cleartext is not in VOB issue
128. How do I - restore cleartext and derived object pools
130. How do I – understand eclipsed files and ClearCase
131. How do I – resolve an unable to add or remove a group
to the VOBs group list issue
132. How do I - run cleartool protectvob for VOBs stored on
NAS
133. How do I - change the VOBs initial creation comments
(You can’t)
134. How do I - change the name of the original creator of
an element (You can’t)
135. How do I – understand the checkout from VOB symbolic
link fails within a snapshot view issue
137. How do I – understand the VOB tags are still displayed
in the GUI after changing regions issue
138. How do I – understand the removed VOB still appears as
mounted to the MVFS issue
140. How do I – understand the unable to unlock versioned
object base error
141. How do I – understand the unable to move files into a
VOB on Linux issue
142. How do I – understand the invalid argument error
loading a file on Windows issue
Elements
1. How do I – understand using directory protections is not sufficient to protect the contained elements
Using VOB directory protections is not sufficient to protect the elements
that appear as children of the VOB directory when accessed through a ClearCase
view.
Using a directory protection scheme appears to work in most cases because a
view-resolved pathname will require the user to traverse through the protected
directory element. For example, if a user is using ClearCase Explorer, his view
context will force him to traverse through a VOB's directory structure before
reaching a file element. If the user does not have permission to access any of
the directory elements in the path, he will be indirectly blocked from
accessing the file element.
However, hard links (additional names for elements in another versioned
directory), direct access via a database identifier can make an element visible
and/or readable outside its original element pathname. In addition, the
element's source and cleartext containers in the VOB's storage pools are
protected only by the element's owner and group.
To protect an element from unwanted access, you need to set the owner, group,
and other control bits for the element itself. You cannot depend on the
protection of VOB directories to prevent unauthorized access to elements that
they contain.
2. How do I - determine the full pathname and version of an element identified only by its oid
UNIX/Linux:
%
cleartool dump foo.c@@/main/br2/1 | grep oid
oid=e752eb7a.f1084e91.b64f.39:d4:27:c1:e0:a4 dbid=241 (0x120)
Example: Dump the element of the file shows the
element oid:
Windows:
% cleartool dump foo.c@@ | findstr oid
oid=c1fd7075.b1eb11d4.a0da.00:01:80:cf:f3:54 dbid=161 (0xeb82ef)
The following information will help you
interpret the output of the cleartool describe -long command when run
against a version object identifier (oid).
Example:
1. Set in to a view and cd into the VOB.
2. Run cleartool
describe -long on the oid object:
$
cleartool describe -long oid:e752eb7a.f1084e91.b64f.39:d4:27:c1:e0:a4
version
"/vob/test/dir1@@/main/br1/br2/2/dir2/main/br2/4/dir3/main/br2/2/
dir4/main/br2/2/dir5/main/br2/2/foo.c@@/main/br2/1"
...
Note:
If the path looks long and confusing, the next step will help interpret.
Each directory element in the file
version path is listed by version as if seen from a version tree.
The above output by version would read as follows:
In the VOB named /vob/test is a versioned directory element named
dir1@@/main/br1/br2/2, which contains versioned directory element:
dir2@@/main/br2/4, which contains versioned directory element:
dir3@@/main/br2/2, which contains versioned directory element:
dir4@@/main/br2/2, which contains versioned directory element:
dir5@@/main/br2/2, which contains versioned file element:
foo.c@@/main/br2/1
Note: The full path to the actual element without the version extended
path is:
/vob/test/dir1/dir2/dir3/dir4/dir5/foo.c
3. How do I - Identify elements by the source container path
FINDING AN ELEMENT NAME FROM A SOURCE
CONTAINER
When an error message references a
source container path, it is difficult to determine which element the log is
referring to.
Example: "\\host1\ClearCase_storage\VOBs\DemoVOB.vbs\s\sdft\29\19\0-12227c71742f4ce99dd5100e96a0b54b-mg"
In order to determine the element name
within the VOB to which the path references, you will need to run the describe
command using pieces from the path above:
- The name of the VOB is needed.
source
cont="\\host1\ClearCase_storage\VOBs\DemoVOB.vbs\s\sdft\29\19\0-12227c71742f4ce99dd5100e96a0b54b-mg
- The file that contains the source is the last
part of the path to the source container:
source
cont="\\host1\ClearCase_storage\VOBs\DemoVOB.vbs\s\sdft\29\19\0-12227c71742f4ce99dd5100e96a0b54b-mg
- The part of this file name between the hyphens
is the oid (Object ID) which is needed:
0-12227c71742f4ce99dd5100e96a0b54b-mg
If you run "cleartool
describe -long oid:<oid>" on the oid while set in a view to the root
of the VOB to which the element resides (in our example DemoVOB), the output
will return an element name:
M:\default_view\DemoVOB>cleartool describe -long
oid:12227c71742f4ce99dd5100e96a0b54b
version
"M:\default_view\DemoVOB\tweedledee.txt@@\main\1"
created 27-Sep-04.14:21:23 by jdoe.Domain Users@host1
Element Protection:
User : DOMAIN_1\jdoe : r--
Group: DOMAIN_1\Domain Users : r--
Other: : r--
element type: text_file
predecessor version: \main\0
Hyperlinks:
Merge@125@\DemoVOB <- M:\default_view\DemoVOB\tweedledee.txt@@\main\testing\1
Note: Running the describe command outside of the VOB will NOT return an
element name:
C:\>cleartool
describe -long oid:12227c71742f4ce99dd5100e96a0b54b@\DemoVOB
version
"12227c71742f4ce99dd5100e96a0b54b@@\main\1"
created 27-Sep-04.14:21:23 by jdoe.Domain Users@host1
Element Protection:
User : DOMAIN_1\jdoe : r--
Group: DOMAIN_1\Domain Users : r--
Other: : r--
element type: text_file
predecessor version: \main\0
Hyperlinks:
cleartool:
Warning: Unable to determine view for
"oid:12227c71742f4ce99dd5100e96a0b54b@\DemoVOB".
cleartool:
Warning: Unable to determine view for
"oid:12227c71742f4ce99dd5100e96a0b54b@\DemoVOB".
Merge@125@\DemoVOB <- <object not available>
Note: Running the describe command (even in the VOB) with the VOB
designation (@<vobtag>) at the end of the oid will NOT return an element
name:
M:\default_view\DemoVOB>cleartool describe -long
oid:12227c71.742f4ce9.9dd5.10:0e:9
6:a0:b5:4b@\DemoVOB
version
"12227c71.742f4ce9.9dd5.10:0e:96:a0:b5:4b@@\main\1"
created 27-Sep-04.14:21:23 by host1.Domain Users@host1
Element Protection:
User : DOMAIN_1\host1 : r--
Group: DOMAIN_1\Domain Users : r--
Other: : r--
element type: text_file
predecessor version: \main\0
Hyperlinks:
Merge@125@\DemoVOB <-
M:\default_view\DemoVOB\tweedledee.txt@@\main\testing\1
FINDING THE SOURCE CONTAINER FROM AN
ELEMENT
The reverse technique may also be
helpful. Using the undocumented DUMP command will help to identify the source
container for a specific element:
M:\default_view\DemoVOB>cleartool dump tweedledee.txt
tweedledee.txt
(12227c71.742f4ce9.9dd5.10:0e:96:a0:b5:4b)
M:\default_view\DemoVOB\tweedledee.txt@@\main\1
oid=12227c71.742f4ce9.9dd5.10:0e:96:a0:b5:4b
dbid=124 (0x7c)
mtype=version
stored
fstat:
ino:
0; type: 1; mode: 01
usid:
NOBODY
gsid:
NOBODY
nlink:
0; size: 21
atime:
Wed Dec 31 19:00:00 1969
mtime:
Mon Sep 27 14:21:23 2004
ctime:
Mon Sep 27 14:21:23 2004
returned
fstat:
ino:
111; type: 1; mode: 0444
usid:
NT:S-1-5-21-141845252-1443263951-584457872-3387
gsid:
NT:S-1-5-21-141845252-1443263951-584457872-513
nlink:
1; size: 21
atime:
Mon Sep 27 14:21:23 2004
mtime:
Mon Sep 27 14:21:23 2004
ctime:
Mon Sep 27 14:21:23 2004
master
replica dbid=3
idstr="\main\1"
elem=111
branch=112 ver num=1
cont
dbid=536871176
container="29\19\0-12227c71742f4ce99dd5100e96a0b54b-mg"
source cont="\\host1\ClearCase_storage\VOBs\DemoVOB.vbs\s\sdft\29\19\0-12227c71742f4ce99dd5100e96a0b54b-mg"
clrtxt
cont="\\host1\ClearCase_storage\VOBs\DemoVOB.vbs\c\cdft\1f\3d\12227c71742f4ce99dd5100e96a0b54b"
hyperlinks
to object:
arrow=125
type=24
hlink vob=a50f450d.224f4a2e.ac15.3e:d7:1d:6f:d0:7d
hlink obj=7f10f560.ace54f3d.9a58.b1:80:b8:88:4e:97
from vob=a50f450d.224f4a2e.ac15.3e:d7:1d:6f:d0:7d
from obj=29a719c6.e9ba47be.900f.c3:52:61:29:02:bf
to vob=a50f450d.224f4a2e.ac15.3e:d7:1d:6f:d0:7d
to obj=12227c71.742f4ce9.9dd5.10:0e:96:a0:b5:4b
4. How do I – understand the Primary Group requirements for element creation
UNIX/Linux:
In order to create an element in a VOB, the user's Primary Group
must match a group in the VOB's group list.
WINDOWS:
As long as the user "is a member of" a group in the VOB's
group list and the parent directory where the element will be created is
owned by the group to which you are a member, that user will be able to create
elements in the VOB.
If, however, the user is a member of more than one of the VOB's groups, the
CLEARCASE_PRIMARY_GROUP will need to be set to one of these. See technote
1135509 for more information about the
CLEARCASE_PRIMARY_GROUP variable.
Below are examples showing this difference.
UNIX/Linux:
%> cleartool describe
vob:/vobs/protect
versioned object base
"/vobs/protect"
created
09-Jan-03.16:31:47 by vobadm (vobadm.group1@UNIX-host)
VOB family feature
level: 3
VOB storage
host:pathname "UNIX-host:/export/home/user1/vobstore/protect.vbs"
VOB storage global
pathname "/net/UNIX-host/export/home/user1/vobstore/protect.vbs"
database schema version:
54
VOB ownership:
owner atria.com/vobadm
group
atria.com/group2
Attributes:
FeatureLevel = 3
UNIX-host% id -a
uid=22319(user1) gid=20(group1) groups=20(group1),2(group2)
Note: User1 is a member of both group1 and group2, and the Primary Group
of user1 is set to group1. The VOB, however, is owned by group2.
%>/usr/atria/etc/utils/credmap
UNIX-host
Identity on local
system:
User: atria.com/user1
(UNIX:UID-22319)
Primary
group: atria.com/group1 (UNIX:GID-20)
Groups: (1)
atria.com/group2
(UNIX:GID-2)
Identity on host
"UNIX-host":
User SID: UNIX:UID-22319
Primary group SID:
UNIX:GID-20
Group SID list: (1)
UNIX:GID-2
%> cleartool mkelem -nc test.txt
cleartool: Error: Can't
create object with group (group1) that is not in the VOB's group list.
cleartool: Error: Unable
to create element "test.txt".
*******************************************************
*******************************************************
WINDOWS:
B:\protect>cleartool describe
vob:\protect
versioned object base
"\protect"
created
09-Jan-03.16:44:32 by user1.group1@WIN_HOST
VOB family feature
level: 3
VOB storage
host:pathname "WIN_HOST:C:\ClearCase_Storage\vobs\protect.vbs"
VOB storage global
pathname "\\WIN_HOST\ccstg_c\vobs\protect.vbs"
database schema version:
54
VOB ownership:
owner DOMAIN\vobadm
group
DOMAIN\clearuser
Attributes:
FeatureLevel = 3
B:\protect>creds
Login name:
DOMAIN\user1
USID:
NT:S-1-5-21-2025429265-1993962763-1957994488-1027
Primary
group: DOMAIN\group1 (NT:S-1-5-21-2025429265-1993962763-19579488-1026)
Groups: (8)
DOMAIN\None
(NT:S-1-5-21-2025429265-1993962763-1957994488-513)
Everyone (NT:S-1-1-0)
DOMAIN\clearuser
(NT:S-1-5-21-2025429265-1993962763-1957994488-1011)
BUILTIN\Administrators
(NT:S-1-5-32-544)
BUILTIN\Users
(NT:S-1-5-32-545)
LOCAL (NT:S-1-2-0)
NT AUTHORITY\INTERACTIVE
(NT:S-1-5-4)
NT
AUTHORITY\Authenticated Users (NT:S-1-5-11)
Note: User1 is a member of both group1 and clearuser, and the Primary
Group of user1 is set to group1. The VOB, however, is owned by clearuser.
B:\protect>cleartool mkelem
-nc test.txt
Created element
"test.txt" (type "text_file").
Checked out
"test.txt" from version "\main\0".
B:\protect>cleartool
ci -ident -nc test.txt
Checked in
"test.txt" version "\main\1".
B:\protect>cleartool
ci -nc .
Default:
Added file element
"test.txt".
Checked in "."
version "\main\1".
B:\protect>cleartool
describe test.txt
version
"test.txt@@\main\1"
created
09-Jan-03.16:48:00 by user1.group1@WIN_HOST
Element Protection:
User : DOMAIN\user1 :
r--
Group:
DOMAIN\clearuser : r--
Other:
: r--
element type: text_file
predecessor version:
\main\0
Note: The element is owned by the group clearuser.
5. How do I - Restore an element that has been rmnamed
A directory used to have a full compliment of file elements, and
along the way, some elements had the name removed from the directory using the cleartool rmname command.
Attempts to undo the rmname using a subtractive
merge from a previous version of the directory is performed, however, the
elements do not reappear. Why?
A cleartool rmname cannot
be undone with directory merging.
Note: The Delete operation
from within ClearCase Explorer also executes a cleartool rmname, not a cleartool rmelem or cleartool rmver. For example, from within your
view, right-click a file or directory element, select Delete, and read the details in the dialogue that
appears, then click Cancel.
Solution
There are two ways to get the element names back into the
directory in question.
Note: If files have been orphaned into the lost+found directory, review technote
1120317 for more information.
PREREQUISITES:
- Determine
which files are invisible. Here are three methods which can be used to
help determine the needed directory version for the next steps:
a.
On the branch that your view is set to use
cleartool find . -all
-nvisible -print
to list out all the versions that are not visible minus those that are visible.
b.
Within ClearCase Explorer, right click the directory where the
element is missing and select Compare with Previous Version.
Note: If you are unsure in which version of the directory the file was
rmnamed (deleted), you will need keep comparing different versions until you
find the file you are looking for.
The ClearDiff tool will show the missing element in the left pane of the
window. On top of that window you will see a path like:
M:\view\vob\directory@@\main\4
Note: You will need this path information after the version extended
syntax (@@) as this is to be used in the link command. From the example, @@\main\4 can be used to find the
missing element at the path .@@\main\4\<missing-element-name>
c.
Run the cleartool lshistory command or the History Browser
GUI on the directory to find which version of the directory the file was
rmnamed.
Note: You will need the previous version of the directory for the next
step. For example, say lshistory reports the following:
M:\view\my_test_vob>cleartool lshistory -d -since today
17-May.07:31 user1 create directory version ".@@\main\43"
"Uncataloged file element "cs.txt"."
You will need to use version \main\42 for the next steps.
- Checkout
the directory where the element is missing.
Use either of the following procedures to restore the element name back to the
LATEST version of the directory:
1.
Create a link using the cleartool ln operation for each
element. The procedure is documented in the "Undoing the rmname
Command" section of the cleartool
rmname man page, cleartool man rmname, or refer to the IBM
Rational ClearCase Command Reference.
For example, the missing element is called test.txt.
cleartool> ls
foo.c@@\main\13 Rule: \main\LATEST
cleartool> ln .@@\main\4\test.txt .\test.txt
Link created: ".\test.txt".
cleartool> ls
foo.c@@\main\13 Rule: \main\LATEST
test.txt@@\main\7 Rule: \main\LATEST
2.
Merge the directory graphically from the version tree browser:
A.
Start the version tree browser for the directory by right-clicking
on the file directory, then select Version Tree.
B.
After the version tree browser appears, right-click on a version
of the directory known to contain the missing file and select Merge to...
and select the current version of the directory in use.
C.
When the dialog box appears, select Yes, and also select
the option Merge the element graphically.
D.
Once the merge GUI appears, manually step through the differences
between the current version and the selected prior version with the files.
Note: If you need assistance, you can use the Help available from within
the Merge Manager tool.
E.
Undo the difference resolution for the removed element names and
then select the correct contributor you wish to use.
F.
Save the results, and close the graphical merge window.
G.
You may need to Refresh your view for the element names to
reappear in the directory version that they were just restored to.
H.
If the results are correct, then right-click the directory and
click Checkin.
For more information on the cleartool sub-commands used in this
technote refer to the IBM Rational ClearCase Command Reference, or run cleartool man <sub-command> from
command line.
6. How do I – understand what the History Mode element means
The term History Mode
element refers to an element whose history remains after the view
private checked out copy of that element was removed. Other versions of the
parent directory may still have references to the element; however, the version
of the parent directory from which the view private file was removed no longer
references the element.
This
may occur in a case where a you perform a checkout of an element from ClearCase
Explorer and then subsequently perform a delete on the checked out copy of that
element. This essentially does an rmname on this element, thus, making it a
history mode element.
7. How do I - List and count the number of elements in VOB
Using cleartool find
While set into a view with the default config spec, run the
following from the top level of the VOB:
- To
list out the elements in a VOB that are on a specific branch:
UNIX and Linux:
cleartool find -all -element 'brtype(main)' -print
Windows:
cleartool find -all -element "brtype(main)" -print
UNIX and Linux only:
- To
count all the elements that are on a specific branch:
cleartool find -all -element 'brtype(main)' -print |wc -l - This
is the command syntax for counting the number of elements in a VOB,
including elements in all directory versions on all branches that are not
shown in the current view.
You can use the cleartool find command with the wc (word count) command. This command counts the lines, words, and characters of all the input returned from the cleartool find.
1.
set a view
cleartool setview testview
2.
change directory (cd) to the VOB-tag
cd /vob2/testvob
3.
list out all the elements in the VOB
cleartool find -all -print
4.
list out and count the elements: (UNIX and Linux only)
cleartool find -all -print | wc -l
Note: There are no equivalent commands or utilities to count the
elements in a VOB on Windows.
For more information on using any of the cleartool sub-commands
used in this technote, refer to the IBM Rational ClearCase Command Reference,
or run cleartool man <sub-command>.
Using countdb
On Windows, UNIX and Linux, you can run the countdb utility
and check the output for line beginning with "ELEMENT" to get the
element count.
Example:
<...deleted output...for example only>
******************************************************
Record Distribution
******************************************************
TID_THE_USUAL
: 1
TID_DO_LINK_COUNTS
: 1
MASTER
:
1
SYSTEM
:
1
STRING_FREE
:
2
STRING
:
285
OBJECT
:
127
WELL_KNOWN_OBJECT_ENTRY
: 35
ELEMENT
:
10
The above output shows that the VOB has a total of 10 elements.
For more information on the
countdb utility refer to technote 1126456.
Using vob_sidwalk
This utility acts on the database directly to return a count of
all objects found in the VOB.
Syntax:
vob_sidwalk \<vobtag> <dumpfile>
Note: The dump file will contain a list of all:
- UIDs
and GIDs present in the VOB on UNIX and Linux
- User
and group SIDs present in the VOB on Windows
Example:
>vob_sidwalk \General_Test
.\dump.txt
VOB Tag: \General_Test (xxxxx:C:\CCSHARE\VOB\General_Test.vbs)
Meta-type "directory element" ... 6 object(s)
Meta-type "directory version" ... 16 object(s)
Meta-type "tree element" ... 0 object(s)
Meta-type "element type" ... 13 object(s)
Meta-type "file element" ... 15 object(s)
Meta-type "derived object" ... 0 object(s)
Meta-type "derived object version" ... 0
object(s)
Meta-type "version" ... 31 object(s)
Meta-type "symbolic link" ... 0 object(s)
Meta-type "hyperlink" ... 0 object(s)
Meta-type "branch" ... 21 object(s)
Meta-type "pool" ... 3 object(s)
Meta-type "branch type" ... 1 object(s)
Meta-type "attribute type" ... 4 object(s)
Meta-type "hyperlink type" ... 9 object(s)
Meta-type "trigger type" ... 0 object(s)
Meta-type "replica type" ... 1 object(s)
Meta-type "label type" ... 3 object(s)
Meta-type "replica" ... 2 object(s)
Meta-type "activity type" ... 0 object(s)
Meta-type "activity" ... 0 object(s)
Meta-type "state type" ... 0 object(s)
Meta-type "state" ... 0 object(s)
Meta-type "role" ... 0 object(s)
Meta-type "user" ... 0 object(s)
Meta-type "baseline" ... 0 object(s)
Meta-type "domain" ... 0 object(s)
Total number of objects found: 125
Successfully processed VOB
"\General_Test".
For more information on vob_sidwalk, refer to IBM
Rational ClearCase Command
8. How do I – understand the “db_obj_delete_V3: RPC: Unable to receive; errno = Connection reset by peer when running rmelem” issue
Attempting to remove an element from a VOB's lost+found directory
results in the following error:
% cleartool rmelem -for doc.967a2cb345da11d7ab8100306e2bcca1
db_obj_delete_V3: RPC: Unable to receive; errno = Connection reset
by peer
cleartool: Error: Trouble communicating with VOB database:
"/vobs/myvob".
Cause
There are dangling hyperlinks on the element that needs to be
deleted
Resolving the problem
Run a checkvob on the element.
Note: You need to use @@ signs
at the end of element name when running the checkvob.
The output will report problems with a broken hyperlink. Respond
Yes when prompted to "Delete it?".
Example:
cleartool checkvob -hlinks
doc.967a2cb345da11d7ab8100306e2bcca1@@
Unable to determine if the
following hyperlink is intact.
<hlink-id not available>
<object not available> ->
/vobs/myvob/lost+found/doc.967a2cb345da11d7ab8100306e2bcca1@@
Delete it? [no] yes
After removing the dangling hyperlinks, the cleartool rmelem command
will succeed.
Triggers
9. How do I - determine the amount of elapsed time ClearCase spends in trigger logic
What
environment variable can you set to assist in determining if an IBM® Rational®
ClearCase® trigger has fired and if so, the elapsed time spent in the trigger
logic?
Answer
You can set the CLEARCASE_TRACE_TRIGGERS
environment variable before performing the operation that is expected to
fire the trigger.
If there is a question about whether or not a trigger is actually
fired as expected when performing a specific operation, setting this
environment variable can provide that initial validation by indicating when the
trigger is firing (example: Firing pre-operation trigger type
"SLOW_DOWN_CO").
Refer to the IBM Rational ClearCase Command Reference Manual under
the topics of mktrtype
and mktrigger
for details about creating triggers.
Setting the CLEARCASE_TRACE_TRIGGERS environment as described
below causes exactly 2 lines to be printed:
- The start time
of trigger execution
- The end time of
the trigger execution
The main purpose of this environment variable is to time how long
one spends in the trigger logic.
For example:
%cleartool checkout -unr clearping
Checkout comments for "clearping":
.
>>> 04:38:44.048 (cleartool): Firing pre-operation
trigger type "SLOW_DOWN_CO"...
>>> 04:38:46.239 (cleartool): ... trigger type
"SLOW_DOWN_CO" done.
Checked out "clearping" from version
"/main/13".
From the above output, one can deduce that of the overall time that the
checkout command took, 2.191 seconds were spent in the trigger logic.
Setting the environment variable CLEARCASE_TRACE_TRIGGERS
UNIX®/Linux® example (for csh shell):
ENABLE:
setenv CLEARCASE_TRACE_TRIGGERS 1
DISABLE:
setenv CLEARCASE_TRACE_TRIGGERS 0
Note: The syntax to set the environment variable will differ depending
on the shell in use.
Microsoft® Windows® example:
ENABLE:
set CLEARCASE_TRACE_TRIGGERS=1
DISABLE:
set CLEARCASE_TRACE_TRIGGERS=0
Review the Rational
ClearCase Reference Guide on the topic of env_ccase (cleartool
man env_ccase) for a complete list of ClearCase variables.
Note: For even more detailed debugging information, modify your trigger
scripts to display information as it executes.
Below is a basic example of a post-op checkin trigger on Windows:
- Here are the
details of the trigger type:
M:\def1\test-vob>cleartool describe -l trtype:ci_trigger
trigger type "ci_trigger"
created
2009-07-14T13:16:38-04:00 by Denise (denise.user@MYHOST-I)
owner: DOMAIN1\denise
group: DOMAIN1\user
all element trigger
post-operation checkin
action: -exec
\\myhost-I\data\testscript.bat
- The trace
environment variable is set as following:
M:\def1\test-vob>set CLEARCASE_TRACE_TRIGGERS=1
- Perform the
checkout operation to fire the trigger
M:\def1\test-vob>cleartool checkin -nc zero.txt
>>>
13:37:26.36261790404838314 (cleartool): Firing post-operation trigger type
"ci_trigger"...
M:\def1\test-vob>creds
1>>\\MYHOST-I\data\log.txt
>>>
13:37:27.36261790404837549 (cleartool): ... trigger type "ci_trigger"
done.
Checked in "zero.txt"
version "\main\8".
Related information
About
using ClearCase triggers from the GUI
Measure
elapsed time spent in a ClearCase trigger
Overview
of triggers
10. How do I - create a preop checkin trigger that does not fire on directories
When creating the
trigger type you need to identify which element types the trigger will fire
against excluding the "directory" element type.
In the example below
we are creating a trigger type that should not fire when a directory element is
checked in.
Create the trigger
type as follows:
1. While set to a view
and cd'd into the VOB run:
cleartool lstype -kind eltype
This will list all the element types
in the VOB including the "directory" element type.
Create the trigger
type identifying the element types from the list above that you want the
trigger to fire on deliberately excluding the "directory" element
type from that list.
cleartool mktrtype -element -all -preop checkin -eltype <element
type list excluding the word directory> -exec "<trigger action or
script to run>" <trigger_name>
Example:
M:\dmm-view\dmm>cleartool
mktrtype -element -all -nc -preop checkin -eltype
html,file,text_file,xml,compressed_text_file -exec C:\temp\myscript.pl
pre-ci-trigger
Created trigger type
"pre-ci-trigger".
11. How do I - copy a Trigger Type
By design, trigger types must be created locally in each VOB.
Trigger types, unlike other metadata types (labels, attributes, branches,
elements, hyperlink), cannot be created as global resources in an
Administrative VOB because they cannot properly traverse hyperlinks; which is how
the Administrative VOBs connect to their client VOBs. You can however copy
triggers between VOBs using the following method:
cleartool cptype
trtype:NO_RMELEM@<source VOB tag> trtype:NO_RMELEM@<target VOB tag>
12. How do I - use Access Control Lists with triggers to restrict operations to specific groups
When setting up a ClearCase environment to allow all users to
read, but only certain groups to modify, the files, there are some
requirements.
1. All
elements must have their group reprotected to a common "ClearCase users
group". This can be accomplished using a postop mkelem trigger
to reset the group (and potentially the owner) on newly created elements to the
desired group.
2. The
permissions on those elements must provide this group with the ability to read
those files.
All ClearCase users must be a member of that group in addition to
any other groups.
Once this is accomplished, there are a few trigger-based ways to
accomplish the desired limitations.
1. Create
all -element (or all-ucmobject, or other) triggers that prevent the operation
from occurring, preventing the desired users from firing the trigger using the -nusers option.
For example:
cleartool
mktrtype -element -all -preop checkout -nusers user1,user2,user3 -exec
"ccperl -e die();" ONLY_SELECTED_CAN_CHECKOUT
The drawback to this option is that the user list in the -nusers parameter could get unwieldy and require a
great deal of maintenance.
2. Create
triggers that execute a script which checks the currently logged-in user
against a user list to see if the user has permission to do the operation. The
drawback to this is that the user list still needs maintenance.
3. Use the
VOB's group list as the list of groups the desired operations are restricted
to.
To do this, create a script that
a. Describes
the VOB and extracts the VOB's additional group list,
b. Runs the
"creds" command to get the users group credentials.
c. Runs the
necessary comparisons to see if the user is in one of the desired groups.
4. In an
environment consisting entirely of Microsoft® Windows® hosts, you can create
"no-operation" trigger scripts and set the NTFS access control list
of that script to allow ONLY the groups that will be permitted to perform the
operation to read or execute the file. This option takes advantage of a feature
of trigger script security. If the user executing the trigger does not have
execute permissions for the trigger script, the trigger fails. As a result, for
a pre-operation trigger, the operation being attempted will be blocked if the
user attempting the operation does not have access to the script the trigger
fires.
The steps are:
a. Create a
"No operation" script. In Windows, an empty batch file will suffice.
b. Set the
NTFS permissions by:
i.
Open the parent directory in the Windows explorer
ii.
Right-click on the trigger script. Select Properties.
iii.
Go to the Security tab
iv.
Set the restrictions however you need to prevent undesired users
from executing the trigger script.
v.
Click OK to close the dialog box.
c.
Create the trigger by executing a command similar to the
following:
cleartool mktrtype -element -all
-preop checkout -exec
"\\server\triggershare\directory\no-op-script.cmd" NOCO_1
At
this point, any attempt by an unauthorized user will cause the trigger to fire,
and when the trigger script fails to execute due to the restricted access
control list, the trigger failure will block the operation (in this case, the
checkout operation).
13. How do I – understand about deleted user accounts and ClearCase performance
The -nusers switch is available for cleartool subcommands, such as lock and mktrype, to create an exception list for objects in
a Rational ClearCase VOB.
A username that is included on an exception list is granted rights
to modify the object, while users that are not on the list cannot modify the
object.
When the object is changed, ClearCase checks the authenticity of
the user running the operation as well as all other users that are specified in
the -nusers list, even accounts that have been deleted in the
environment.
Deleted user account
When a user account is removed from the environment without first
being explicitly removed from the exception list of an object, then it remains
on the list. There is no update sent to or captured by ClearCase to remove the
account from exception list.
In this situation, though the username is no longer valid, it
still requires authentication when the VOB object is modified.
As expected, the lookup attempt for an invalid account is
unsuccessful, but the remote procedure call (RPC) takes several moments longer
to return than if the account was still available in the environment. Hence,
this will increase the time it takes for the ClearCase operation to complete.
Since ClearCase does not cache negative failures (or failed lookup
attempts), each time an operation is performed against the VOB object, the
lookup will occur for any deleted account in the -nusers list.
Note: The delay will vary from environment to environment due to unique
configurations, and in some cases, the operation can fail as seen in some of
the below examples
Cause
Defect APAR PK35018 has been submitted to investigate this
scenario
Resolving the problem
The defect has been closed as ClearCase is working as designed. If
the user account is removed but still associated with locked metadata,
ClearCase will not perform optimally because it will continue to try and authenticate
the user.
Recommendations
- When possible,
it is best to just disable a user account, rather than delete it from the
environment. However, if the user account must be removed, then see the
below suggestions to help with administration of an exception list.
- The -nusers
option should be used with discretion to help minimize (and possibly
prevent) any performance degradation as detailed above when a user account
is deleted.
- Track user
accounts that are added to an exception list for an object, that way,
should the account need to be deleted, it can first be removed from the -nusers
list. Review the next section to see how to check
for invalid accounts.
List usernames in -nusers list
You can display the list of users included in an exception list of
either a lock or a trigger type using the following command syntax:
(Windows syntax example)
cleartool lslock -l -obs -all
vob:<vob-tag> | find "Locked except"
cleartool lstype -l -obs -kind
trtype -invob <vob-tag> | find "excluded users"
Check for all user accounts mentioned in the output whether they are still
defined in your domain (see below).
If not, then either define and or disable them, or change the exception list on
the trigger type or the lock to remove the undefined user account.
Note: Obsoleted trigger types can cause the problem.
Use creds to check account
The ClearCase credentials utility, creds, can be used to determine if a username in an
exception list is no longer valid in the environment.
Here is an example of the output that will get returned by creds
utility for an invalid account:
Note: This utility will work for any user account whether it is used
for ClearCase or not.
>creds user1
Windows NT user info (on local system):
*** LookupAccountName((null),user1) - No mapping between account
names and security IDs was done.
ClearCase user info:
*** Can't get user info for "user1"
For more information on creds, refer to technote 1221403.
Examples
These are all situations where a non-existent username in the
exception list had to be removed to resolve the problem.
1.
A user account that no longer exists, but is still listed in the
-nusers option for cleartool lock of a branch can cause a checkout, checkin and
merge to fail like:
error checking out M:/testvu/lib32/test/test_fan/app.
error from vob database lib32.
trouble finding the global definition for local type"???".
unable to checkout
M:/testvu/lib32/test/test_fan/app.
2.
Long delays can occur when listing the available label types when
trying to apply a label to a version from the ClearCase Version Tree Browser.
The delay has been reported to extend from 1 to 5 minutes.
3.
When attempting to join a UCM project, the operation fails with:
Error Creating the Stream 'dev1_stream'
Error from VOB database:
"\pvob1".
Trouble finding the global
definition for Local Type "???".
4.
In a multiple domain environment, the delay can grow exponentially
for the lookup of a deleted username to complete.
For example, if the current domain has trusts with other domains then the
lookup for the non-existent username must occur in the other domains also. This
can take a long time, as the lookup timeout must occur in each trusted domain
before returning -2 "nobody", which allows the process to continue.
Triggers that are configured to run for specific individuals can
be problematic if not managed properly.
Note: Even when the trigger is locked obsolete, the problem can still
persist.
14. How do I - apply a trigger to the ClearCase move operation
The move operation is not listed in the Operational Keywords for creating
triggers.
Unlike other ClearCase commands or menu options, the movement of ClearCase
elements involves the removal of an element name (cleartool rmname) from the
current directory element it is being cataloged in, and the linking of the
element name (cleartool ln) into the new
directory it is to be cataloged in.
The move (cleartool mv) operation is really
two individual operations needed to complete to element move.
To determine what operation is firing for an element move, the ClearCase
trigger environment variable CLEARCASE_POP_KIND should
be used.
It is suggested that the trigger be applied to the removal of the element name
(operation keyword "rmname"), as this is the first operation to
occur.
The trigger script's logic should include the assessment of the above variables
value being "rmname" of the process.
15. How do I – create a trigger to prevent unreserved checkouts on UNIX and Linux
An unreserved checkout does not
guarantee the right to create the successor version.
If several views have unreserved
checkouts, the first view to check in the element creates the successor;
developers working in other views must merge the checked-in changes into their
own work before they can check in.
The following trigger can be used to
prevent unreserved checkouts:
cleartool mktrtype -element -all -preop
checkout -nuser root -nc -execunix 'perl -e "die ( ) unless (
\$ENV{CLEARCASE_RESERVED} == 1 )"' TRIGGERNAME
16. How do I – enforce a standard set of triggers from windows to control mklbtype, rmlbtype, etc...
Create
an install.bat file containing the following, which you should then run from
the root of the VOB:
Rem
Define who can make new label types
cleartool
rmtype -rmall trtype:no_new_labels
cleartool
mktrtype -type -preop mktype -lbtype -all -nusers samecs -exec
"clearprompt proceed -prompt \"Only <SYSTEM NAME>
Administrators or designated personnel can create label types\" -mask
abort -default abort -prefer_gui" -c "Only <SYSTEM NAME> Administrators /CRMs can create label types"
no_new_labels
Rem
Define who can make new branch types
cleartool
rmtype -rmall trtype:no_new_branches
cleartool
mktrtype -type -preop mktype -brtype -all -nusers samecs -exec
"clearprompt proceed -prompt \"Only <SYSTEM NAME> Administrators or designated personnel can
create branch types\" -mask abort -default abort -prefer_gui" -c
"Only <SYSTEM NAME>
Administrators/CRMs can create branch types" no_new_branches
Rem
Define who can make new attribute types
cleartool
rmtype -rmall trtype:no_new_attributes
cleartool
mktrtype -type -preop mktype -attype -all -nusers samecs -exec
"clearprompt proceed -prompt \"Only <SYSTEM NAME>
Administrators can create attribute types\" -mask abort -default abort
-prefer_gui" -c "Only <SYSTEM NAME> Administrators can create attribute
types" no_new_attributes
Rem
Define who can remove label types
cleartool
rmtype -rmall trtype:no_remove_lbtypes
cleartool
mktrtype -type -preop rmtype -lbtype -all -nusers samecs -exec
"clearprompt proceed -prompt \"Only <SYSTEM NAME> Administrators or designated personnel can
remove label types\" -mask abort -default abort -prefer_gui" -c
"Only <SYSTEM NAME>
Administrators/CRMs can remove label types" no_remove_lbtypes
Rem
Define who can remove branch types
cleartool
rmtype -rmall trtype:no_remove_brtypes
cleartool
mktrtype -type -preop rmtype -brtype -all -nusers samecs -exec
"clearprompt proceed -prompt \"Only <SYSTEM NAME> Administrators or designated personnel can
remove branch types\" -mask abort -default abort -prefer_gui" -c
"Only <SYSTEM NAME>
Administrators/CRMs can remove branch types" no_remove_brtypes
Rem
Define who can remove attribute types
cleartool
rmtype -rmall trtype:no_remove_attypes
cleartool
mktrtype -type -preop rmtype -attype -all -exec "clearprompt proceed
-prompt \"WARNING: Removing attribute types can be very damaging, therefore,
on the <SYSTEM NAME> system, it is desabled for everyone\" -mask
abort -default abort -prefer_gui" -c "Removal of attributes is
disabled" no_remove_attypes
Rem
Define who can remove versions
cleartool
rmtype -rmall trtype:no_rmver
cleartool
mktrtype -element -all -preop rmver -nusers samecs -exec "clearprompt
proceed -prompt \"Only <SYSTEM NAME> Administrators can remove
verstions\" -mask abort -default abort -prefer_gui" -c "Only
admins can remove " no_rmver
Rem
Define who can remove attributes
cleartool
rmtype -rmall trtype:no_rmattr
cleartool
mktrtype -element -all -preop rmattr -nusers samecs -exec "clearprompt
proceed -prompt \"Only <SYSTEM NAME> Administrators can remove attributes\"
-mask abort -default abort -prefer_gui" -c "Only <SYSTEM NAME>
Administrators can remove attributes" no_rmattr
Rem
Define who can remove elements
cleartool
rmtype -rmall trtype:no_rmelem
cleartool
mktrtype -element -all -preop rmelem -nusers samecs -exec "clearprompt
proceed -prompt \"Please use the cleartool rmname command instaed or
contact the SYSTEM Administrators if
youi really need to remove all version of an element\" -mask abort
-default abort -prefer_gui" -c "Only <SYSTEM NAME>
Administrators can remove elements" no_rmelem
Rem
Define who can remove triggers
cleartool
rmtype -rmall trtype:no_rmtrigger
cleartool
mktrtype -element -all -preop rmtrigger -trtype -all -nusers samecs -exec
"clearprompt proceed -prompt \"Only <SYSTEM NAME>
Administrators can remove triggers\" -mask abort -default abort
-prefer_gui" -c "Only admins can remove triggers" no_rmtrigger
17. How do I - detect whether a checkin is part of an Add to Source Control operation in a trigger
In environments where a -preop checkin trigger is used to
ensure files are associated with defect record id, the standard GUI Add to
Source Control processes can yield unexpected results when the check-in
phase of the operation is aborted by the trigger.
When the GUI Add to Source Control or the cleartool
mkelem -ci commands are run, the trigger environment does not flag the
check-in as part of the mkelem process.
Change request (RFE) RATLC01023447 has be submitted to request the
check-in phase of the Add to Source Control GUI operation set the
CLEARCASE_POP_KIND trigger environment variable.
Review the ClearCase Command Reference Guide on the topic
of mktrtype (cleartool man mktrtype) for
more information about trigger environment variables.
WORKAROUND:
The below Perl code will walk the predecessor versions of the
checked-out file and determine whether the checked-out version is descended
from /main/0. This
is one of the checks needed to verify that the check-in is part of an Add to
Source Control operation.
Note: This code can be used to modify the trigger to detect (and
potentially allow) this type of checkin.
DISCLAIMER:
All source code and/or
binaries attached to this document are referred to here as "the
Program". IBM is not providing program services of any kind for the
Program. IBM is providing the Program on an "AS IS" basis without
warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL,
INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES
(INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
--------------------------------
#!/usr/bin/Perl -w
# Preload recursive call using raw
pathname.
# Why? Because the xpn in a preop
checkin trigger contains
# the FUTURE version extended-name.
my $fname = $ENV{CLEARCASE_PN};
my $verpart;
#
# Get initial predecessor version.
#
$cmd = "cleartool desc -fmt
\"%PVn\" $fname";
$verpart = `$cmd`;
use Config;
my $arch = $^O ? $^O :
$main::Config{archname};
$CFG::NT = (($arch =~ /^MSWin32/)
|| ($arch eq 'i386-win32')) ? 1 : 0;
$CFG::UNIX = ($CFG::NT ? 0 : 1);
# If the predecessor is /main/0, no
call is needed. Simply fall out.
#
if (($verpart ne
"/main/0")&&($verpart ne "\\main\\0"))
{isnewelem($fname, $verpart, $CFG::UNIX);}
#
# Recursively walk the predecessor
version of each found version
# If we get all the way to /main/0,
simply fall out. If we find
# a non-zero version number
somewhere in the list, exit the script
# with error 1.
#
sub isnewelem
{
my $fname = shift;
my $verpath = shift;
my $isunix = shift;
my @vname;
my $predname;
my $cmd;
$cmd = "cleartool desc -fmt
\"%PVn\" $fname\@\@$verpath";
$predname = `$cmd`;
if ($isunix)
{
@vname = split(/\//,$predname);
}
else
{
@vname = split(/\\/,$predname);
}
if (@vname[$#vname] ne
"0")
{
exit 1;
}
else
{
if (@vname[$#vname-1] ne
"main")
{
isnewelem($fname, $predname,
$isunix);
}
}
return 0;
}
Other checks that may be desired are:
- Determine
whether the versions found in this walk of the version tree are the only
versions in the version tree, and
- Determine
if the parent directory is currently checked out.
These checks are currently beyond the scope of this note, but can be
implemented by extending the above sample script.
18. How do I - change element ownership when new elements are added to the VOB
The cleartool mktrtype must be run with the correct syntax
arguments depending on which OS the trigger is created from. See the below
examples for UNIX and Windows, respectively.
UNIX/Linux example:
1.
Set into a view ($ /usr/atria/bin/cleartool setview java_vu)
2.
Mount a VOB ($ /usr/atria/bin/cleartool mount /vobs/java)
3.
Set into a VOB ($ cd /vobs/java/)
4.
Run the following command:
/usr/atria/bin/cleartool mktrtype
(-replace) -element -all -postop mkelem -eltype -all -execunix
'/usr/atria/bin/cleartool protect -chmod g+rwx -chown vobadm $CLEARCASE_PN'
-execwin 'cleartool protect -chmod g+rwx -chown vobadm %CLEARCASE_PN%' -nc
CHOWN_CHGR
Trigger execution example:
$ /usr/atria/bin/cleartool mkelem
-nc ann.c
Changed protection on
"/vobs/java/./ann.c".
Created element
"ann.c" (type "text_file").
Checked out
"ann.c" from version "/main/0".
Windows example:
1.
Start a view, (cleartool startview java_vu)
2.
Mount a VOB (cleartool mount \java)
3.
Change to the view/VOB context (cd M:\java_vu\java)
4.
Run the following command:
cleartool
mktrtype (-replace) -element -all -postop mkelem -eltype -all -execunix
"cleartool protect -chmod g+rwx -chown vobadm $CLEARCASE_PN" -execwin
"cleartool protect -chmod g+rwx -chown vobadm %CLEARCASE_PN%" -nc
CHOWN_CHGR
Trigger
execution example:
M:\java_vu\java>cleartool mkelem
-nco -nc ann.c
Changed protection on "M:\base_dmhnt_view\Support\.\ann.c".
Created element "ann.c"
(type "text_file").
Methodology
19. How do I - convert a base ClearCase VOB to a UCM Component
Scenario:
The existing project is using a base ClearCase VOB. However, as the project
requirements have changed, the project is being moved to a UCM environment in
order to use the features UCM provides.
Is it possible to create a new PVOB and import this base VOB as a component
without losing any versions and data?
Yes, the following steps can be used to convert a base ClearCase
VOB to a UCM component.
Refer to the IBM
Rational ClearCase Command Reference Manual for details regarding the
command line syntax used in the steps below.
1.
Create a UCM project VOB
M:\>cleartool mkvob -tag \eric5_pvob -ucmproject -stgloc vob
Comments for "C:\cc_storage\vob\eric5_pvob.vbs":
Project VOB.
.
Created versioned object base.
Host-local path: mylaptop:C:\cc_storage\vob\eric5_pvob.vbs
Global path: \\mylaptop\cc_storage\vob\eric5_pvob.vbs
VOB ownership:
owner DOMAIN1\patrick
group DOMAIN1\user
VOBs have special data backup considerations. For more information on how to
back up your VOB properly, see the documentation for administering ClearCase.
If the backups aren't done properly, you are putting your data at risk!
2.
Create a UCM project
M:\>cleartool mkproject -in RootFolder@\eric5_pvob
project:Project_1@\eric5_pvob
Created project "Project_1".
3.
Attach version labels to latest versions of all elements in the
Base VOB to be imported as a component.
Example:
M:\dview\basevob1>
cleartool mklbtype –nc LABEL1
Created label type "LABEL1".
M:\dview\basevob1>cleartool
checkin -nc .
Checked in "."
version "\main\5".
M:\dview\basevob1>cleartool
mklabel -r LABEL1 .
Created label
"LABEL1" on "." version "\main\4".
Created label
"LABEL1" on ".\aj.txt" version "\main\1".
Created label
"LABEL1" on ".\b.txt" version "\main\1".
Created label "LABEL1"
on ".\f.txt" version "\main\1".
Created label
"LABEL1" on ".\lost+found" version "\main\0".
Created label
"LABEL1" on ".\new folder" version "\main\1".
Attempted to apply labels to 6
versions.
6
newly applied
0
moved
0
already in place
0
failed
4.
Import VOB as component in ClearCase Project Explorer:
a.
Right click Component in Project Explorer
b.
Select Import
c.
Select VOB as Component
d.
Select the VOB to be imported
e.
Click Add
f.
Click Import
5.
Import the label as a baseline
a.
Right click the base vob listed under Component (basevob1 in the
example below)
b.
Select Import Label
c.
Select the label to import.
d.
Click OK
Example:
6.
Change the configuration of the stream
a.
Right Click an Integration stream
b.
Select properties -> configuration tab -> add ->
Component (basevob1) -> change -> all streams
c.
Select the label to be imported (LABEL1_basevob1_IMPORT in this
example)
d.
Click OK -> Rebase Stream preview: to complete the rebase
e.
Click OK -> complete -> OK -> close
7.
Recommend baselines and then rebase
a.
Right click the Integration stream -> recommend baselines ->
b.
Select the baseline (LABEL1_basevob1_IMPORT in this example)
c.
Right click the development stream
8.
Select Rebase Stream
20. How do I – understand about reserved and unreserved checkouts
Difference between reserved and
unreserved
A version can have at most one reserved
checkout and any number of unreserved checkouts.
Performing a reserved checkout (without
using the –version option) guarantees you the right to create a successor to
the version you checked out.
If several users perform unreserved
checkouts, any one of those users (and only one) can create a successor version.
You can change the default checkout
behavior for all VOBs from reserved to unreserved on any ClearCase client by
making one or both of the following changes.
·
Set the CLEARCASE_PROFILE environmental
variable to affect the command line operations.
For Microsoft® Windows®, UNIX® and Linux®
Review the ClearCase Command Reference Guide on the topic of env_ccase
(cleartool
man env_ccase) for a list of the environment
variables (including CLEARCASE_PROFILE) used with ClearCase.
Also review the ClearCase Command Reference Guide on the topic of profile_ccase
(cleartool
man profile_ccase) for more details about the ClearCase
profile file .clearcase_profile.
Review technote 1142599 to understand why this variable while set will not
affect ClearCase GUIs.
Example:
1. Define the CLEARCASE_PROFILE environment variable according to
the operating instructions and set the fully qualified path and file name for a
profile to override the checkout settings.
CLEARCASE_PROFILE=c:\.clearcase_profile
2. Create the .clearcase_profile
file in the path that you specified in the above step.
Note: This file contains your ClearCase or ClearCase LT user
profile, which includes rules that determine the comment option default for one
or more cleartool and multitool commands.
3. Edit the contents of the file and add the following line:
checkout
-unreserved
4. Checkout the file to see the new
default in action.
Example:
M:\dynamic_view\test_vob>set
CLEARCASE_PROFILE=C:\.clearcase_profile
M:\dynamic_view\test_vob>cleartool co -nc .
Checked out "." from version "\main\2".
M:\dynamic_view\test_vob>cleartool describe .
directory version ".@@\main\CHECKEDOUT" from \main\2 (unreserved)
<...snipped...>
·
Change the User Preferences to
affect the GUI operations.
For Windows only
1.
Open ClearCase Home Base (Start
> Run type clearhomebase)
2.
Select the Options tab
3.
Click User Preferences
4.
To make checkouts unreserved by
default, uncheck the Reserved box under the Check Out section and click
OK.
You
can change the default checkout behavior for particular VOBs from reserved to
unreserved by creating the following trigger in your VOB.
UNIX and Linux:
cleartool mktrtype -element -all -post checkout -exec '/opt/rational/clearcase/bin/cleartool
unreserve -nc $CLEARCASE_PN' <Tigger_Name>
Microsoft Windows:
cleartool mktrtype -element -all -post checkout -exec "cleartool unreserve
-nc \"%CLEARCASE_PN%\"" <Tigger_Name>
Example:
%>
cleartool co -nc junk.c
Changed
checkout to unreserved for "/net/host/vobs/vob_tag/junk.c" branch
"/main".
Checked
out "junk.c" from version "/main/2".
%> cleartool lsco
--03-22T11:03
user checkout version "junk.c" from /main/2
(unreserved)
Note: The trigger will fail if the trigger is a "preop
checkout" trigger. This is because the file is not checkedout first. You
will see a message similar to the one below if the trigger is a preop trigger.
cleartool:
Error: No branch of element is checked out to view
"hostname:/home/user/user_view.vws".
cleartool:
Error: Unable to find checked out version for
"/net/host/vobs/vob_tag/junk.c".
cleartool:
Warning: Trigger "co_unr_trig" has refused to let checkout proceed.
cleartool:
Error: Unable to check out "junk.c".
How to change the reserve status of a
checkout
For Windows, UNIX and Linux
To verify the status of an element checkout as reserved or unreserved, use
the cleartool describe command
Example:
%>cleartool describe foo
directory version "foo@@\main\CHECKEDOUT" from \main\2 (unreserved)
<...snipped...>
%>cleartool describe bar
directory version "bar@@\main\CHECKEDOUT" from \main\2 (reserved)
<...snipped...>
- Use the unreserve command to change the
checkout from reserved to unreserved. See related information below for
examples.
·
Use the reserve command to change the
checkout from unreserved to reserved.
Review the ClearCase Command
Reference Guide on the topics of reserve (cleartool man reserve) and unreserve (cleartool man unreserve) for more information.
21. How do I - run JRE version 1.4.2_05 and higher within a VOB context on Linux
Attempts to run a Java on Linux from within a VOB and dynamic view
context results in the following error:
Error: could not find libjava.so
Error: could not find
Java 2 Runtime Environment.
In versions 1.4.2_05 and higher, Sun modified the system call that Java runs
during a routine to determine its current working directory. On Linux
platforms, Java uses /proc/self/exe, which
within a dynamic view context is returning the cleartext container instead of
the /vob/vobname/...
virtualized pathname as expected.
On Linux, /proc
functions differently than on UNIX®, so this issue only applies to Linux
clients attempting to run Java from inside a VOB.
Sun tracks this issue as Bug 6189256.
Solution
At this time, Rational is proposing a two-pronged solution:
1.
Long term: Through
the Linux Technology Center, Rational is moving towards making a change to the Linux
kernel which will allow file mapping capabilities similar to what is currently
available on UNIX platforms.
2.
Short term:
Rational has created an interposing library which should allow the Linux client
to find the correct path.
DISCLAIMER:
All source code and/or
binaries attached to this document are referred to here as "the
Program". IBM is not providing program services of any kind for the
Program. IBM is providing the Program on an "AS IS" basis without
warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL,
INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES
(INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Steps to install the interposer library:
1.
Download the attached library to a location on your Linux host
2.
export LD_PRELOAD=<path/to/libreadlink_interpose.so>
3.
export LD_LIBRARY_PATH=<path to JRE libraries within the
VOB>
|
|
Example:
$ cleartool setview testview
$
/vobs/java/j2re1.4.2_05/bin/java -version
Error: could not find
libjava.so
Error: could not find Java 2
Runtime Environment.
$ export
LD_PRELOAD=/tmp/libreadlink_interpose.so
$ export LD_LIBRARY_PATH=/vobs/java/j2re1.4.2_05/lib/i386
$
/vobs/java/j2re1.4.2_05/bin/java -version
java version "1.4.2_05"
Java(TM) 2 Runtime Environment,
Standard Edition (build 1.4.2_05-b04)
Java HotSpot(TM) Client VM (build
1.4.2_05-b04, mixed mode)
22. How do I - convert a VOB to an AdminVOB
To change a base ClearCase VOB into an
Administrative VOB, you must create an AdminVOB hyperlink from a client VOB to
the VOB that you want to act as the AdminVOB.
Note:
This can be used to change a newly created VOB or a VOB that was previously an
AdminVOB into an AdminVOB.
Example:
There are presently 3 standard VOBs:
/vobs/dev1
/vobs/dev2
/vobs/dev3
To make /vobs/dev3 into an AdminVOB for /vobs/dev1 and /vobs/dev2:
1. Make sure all 3 VOBs are mounted and accessible.
2. Log in as the VOB owner.
3. Set a view and change directory (cd) into
/vobs/dev1
%>
cleartool setview view1
%> cd /vobs/dev1
4. Make the AdminVOB hyperlink:
%>
cleartool mkhlink -c "link to AdminVOB /vobs/dev3" AdminVOB
vob:/vobs/dev1 vob:/vobs/dev3
Created hyperlink "AdminVOB@40@/vobs/dev1".
5. A describe of the VOB, /vobs/dev1, will now show the hyperlink:
%>
cleartool describe -long vob:/vobs/dev1
versioned object base "/vobs/dev1"
created 05-Mar-02.11:43:16 by John Doe(jdoe.user@host1)
VOB family feature level: 3
VOB storage host:pathname
"host1:/export/home/jdoe/store/dev1.vbs"
VOB storage global pathname
"/net/host1/export/home/jdoe/store/dev1.vbs"
database schema version: 53
VOB ownership:
owner jdoe
group user
Additional groups:
group2
Attributes:
FeatureLevel = 3
Hyperlinks:
AdminVOB@40@/vobs/dev1 ->
vob:/vobs/dev3
Repeat the same steps for each client
VOB you want to associate with the AdminVOB.
23. How do I - suppress the confirmation dialogue box that displays VOBs that have been mounted
The confirmation dialogue box that
displays VOBs that have been mounted after logging into a Windows client can be
suppressed so that it does not display.
Follow the below steps to turn this
option in ClearCase off.
1. Open the ClearCase Control Panel applet (Start
> Run type cc.cpl)
2. Choose the "Options" tab.
3.
Clear the check mark in the option Display
confirmation message after remounting persistent VOBs
Next time you log onto a ClearCase
client, the confirmation dialogue box that shows what VOBs have been mounted
will not display again.
This will need to be performed for each
ClearCase client that does not want this confirmation dialogue box to appear.
Types and Type manager
24. How do I – handle binary files in ClearCase
Binary
files are handled in UCM the same way they are handled in base ClearCase; they
cannot be merged.
ClearCase
can only merge text files; therefore a different strategy must be deployed in
order to manage change related to binary content.
In order to effectively manage binary files in ClearCase, new element types must
be defined to handle these file types. The following options are available:
- Configure element type to be never
considered for merging. ClearCase will not attempt to merge elements
with a never merge type. These elements will be left unchanged during a deliver
or rebase operation and you will not be prompted to merge them.
- Only available in ClearCase 7.0:
Configure element type to copy. For elements with a copy type,
ClearCase will in a merge replace the target version with the source
version without user interaction. See technote 1240740 for more information.
Note: The following instructions are taken from
the point of view of the Microsoft® Windows® operating system. The steps may
differ on UNIX® and Linux®, but the concepts apply exactly.
Instructions
for non-replicated VOBs
Note: The element type can be created from
command line or the GUI.
1. Reuse an
existing element type or Create a new one from the command line or GUI. See step
2 if the element type already exists.
Review the ClearCase Reference Guide on the topic of mkeltype (cleartool man mkeltype) for more details.
GUI example > Create:
·
Open Type Explorer GUI for the VOB (Start > Programs
> Rational ClearCase> Type Explorer)
·
Select the VOB where binary files exist.
·
Open the element type folder
·
Right-click and create a new element type.
·
Give the element type a name (for example NEVER_MERGE or COPY or
any name of your choosing).
·
Click OK
Example: NEVER_MERGE
Example: COPY
2. From the
Type Manager tab in the element type's Properties dialog box, enable the option
to
Never consider elements of this type for merging
or
Always copy elements of this type (ClearCase 7.0 or later)
3. For the
binary elements that already exist in the VOB, use cleartool chtype to
change these types to the new element type.
Review the ClearCase Reference Guide on the topic of chtype (cleartool man chtype) for more details.
4. For the
binary files that do not yet reside in the VOB, the magic file can be edited to
call the new element type for elements with a certain extension. Upon element
creation these files will use the new type you have defined to manage those
file elements.
Review the ClearCase Reference Guide on the topic of cc.magic, default.magic (cleartool man cc.magic) for more details.
Instructions for
replicated VOBs
The same
steps are required as above; however, the element types need to be created from
the command line in a replicated environment .
Review
the following technotes for additional information about working with element
types in a replicated VOB.
- Changing unused element types in a
replicated VOB (1148740)
- Changing used element types in a
replicated VOB (1257979)
Example:
Never Merge Example:
M:\view\vob>cleartool
mkeltype -supertype file -mergetype never -nc FILE_NEVER_MERGE
Created
element type "FILE_NEVER_MERGE".
Copy
Example:
M:\view\vob>cleartool
mkeltype -supertype compressed_file -mergetype copy -nc
COMPRESSED_FILE_COPY_MERGE
Created element type
"COMPRESSED_FILE_COPY_MERGE".
The definitions for
trivial and manual merging
Trivial: The base and the destination versions of the element are the
same.
This means the element can simply be copied from the source to the destination
view. A trivial merge is automatically determined by merge or findmerge and
thus will be taken care of for you.
Manual: The source and destination versions of the element contain one
or more conflicts that you must resolve. A manual merge thus requires that you:
1. Check
out the destination version.
2. Copy the
data from the source version to the destination version.
3. Checkin
the destination version.
4. Manually
draw the merge arrow in a version tree GUI or you can run the 'cleartool merge'
command with a -ndata switch to manually establish the merge arrow between the
source and destination versions.
25. How do I - manually construct cleartext
Using
the type manager to manually extract a version from a source container can be a
valuable step in troubleshooting cleartext construction problems.
UNIX and
LINUX
The
syntax for using any individual type manager manually is:
<CCHOME>/lib/mgrs/<type_manager>/construct_version
<source_cont> <output_file> <version_oid>
<CCHOME> in 2002.05.00 and previous: /usr/atria
<CCHOME>
in 2003.06.00 and later: /usr/rational/clearcase
Step-by-step example:
Reconstruct foo.c@@/main/Branch1/4
1. Obtain
version OID and source container for foo.c@@/main/Branch1/4
% cleartool dump foo.c@@/main/Branch1/4 | grep oid
oid=c1fd7075.b1eb11d4.a0da.00:01:80:cf:f3:54
dbid=337 (0x151)
% cleartool dump
foo.c@@/main/Branch1/4 | grep "source cont"
source
cont="/net/host/files/ccstg/vobs/sol.vbs/s/sdft/19/3c/0-c1fd7075b1eb11d4a0da000180cff354-2m"
2. Determine
which element type foo is using:
% cleartool describe foo.c@@/main/Branch1/4 | grep
"element type"
element type: text_file
3. Determine
the type manager used to manage that element type:
% cleartool describe eltype:text_file | grep "type
manager"
type manager: text_file_delta
4. Reconstruct
version by executing the type manager:
/usr/atria/lib/mgrs/text_file_delta/construct_version
/net/trinity/files/ccstg/vobs/sol.vbs/s/sdft/19/3c/0-c1fd7075b1eb11d4a0da000180cff354-2m
/tmp/foo.c c1fd7075.b1eb11d4.a0da.00:01:80:cf:f3:54
Note: The version foo.c@@/main/Branch1/4 will be
written out to /tmp/foo.c
5. Insert
the regenerated cleartext into the actual location in the cleartext pool:
cleartool dump foo.c@@/main/Branch1/4 | grep
"cleartext cont" cleartext cont="/net/host/files/ccstg/vobs/sol.vbs/c/cdft/19/3c/0-c1fd7075b1eb11d4a0da000180cff354-2m
then
copy /tmp/foo.c to
/net/host/files/ccstg/vobs/sol.vbs/c/cdft/19/3c/0-c1fd7075b1eb11d4a0da000180cff354-2m
WINDOWS
The invoke_mgr.exe utility is used to build cleartext manually on
Windows.
This
tool resides in the C:\Program Files\Rational\ClearCase\etc\utils directory.
The
syntax for using any individual type manager manually is:
C:\Program Files\Rational\ClearCase\etc\utils\invoke_mgr
<mgr name> <op name> <mgr args> ...
WHERE
·
mgr name = type manager name (e.g. text_file_delta)
- op name =
construct_version
·
mgr args = <path_to_source_container> <output_file>
<version_oid>
Example:
invoke_mgr text_file_delta construct_version
\\host1\share\vob.vbs\s\sdft\1\3a\0-c1fd7075b1eb11d4a0da000180cff354-2m
C:\tmp\construct.txt c1fd7075.b1eb11d4.a0da.00:01:80:cf:f3:54
Step-by-step example:
To construct foo.c@@/main/Branch1/4
1. Obtain
version OID and source container for foo.c@@/main/Branch1/4
M:\main\sol>cleartool dump foo.c@@/main/Branch1/4 |
findstr oid
oid=c1fd7075.b1eb11d4.a0da.00:01:80:cf:f3:54
dbid=337 (0x151)
M:\main\sol>cleartool
dump foo.c@@/main/Branch1/4 | grep "source cont"
source
cont="\\host1\files\ccstg\vobs\sol.vbs\s\sdft\19/3c/0-c1fd7075b1eb11d4a0da000180cff354-2m"
2. Determine
which element type foo is using:
M:\main\sol>cleartool describe foo.c@@/main/Branch1/4
| findstr "element type"
element type: text_file
3. Determine
the type manager used to manage that element type:
M:\main\sol>cleartool desc eltype:text_file | grep
"type manager"
type manager:
text_file_delta
4. Reconstruct
the version by executing the type manager:
M:\main\sol>"C:\Program
Files\Rational\ClearCase\etc\utils\invoke_mgr" text_file_delta
construct_version
\\host1\files\ccstg\vobs\sol.vbs\s\sdft\19\3c\0-c1fd7075b1eb11d4a0da000180cff354-2m
c:\foo.c c1fd7075.b1eb11d4.a0da.00:01:80:cf:f3:54
Note: The version foo.c@@/main/Branch1/4 will be written out to c:\foo.c
5. Insert the
regenerated cleartext into the actual location in the cleartext pool:
cleartool dump foo.c@@/main/Branch1/4 | findstr
"cleartext cont" cleartext
cont="\\host1\files\ccstg\vobs\sol.vbs\s\sdft\19\3c\0-c1fd7075b1eb11d4a0da000180cff354-2m
then copy foo.c to
\\host1\files\ccstg\vobs\sol.vbs\s\sdft\19\3c\0-c1fd7075b1eb11d4a0da000180cff354-2m
26. How do I – understand the VOB server operation Create Container failed issue
Attempts to add a
new object to source control in a UNIX VOB from Windows results in the
following error:
V:\user_wx\testvob2\source>cleartool
mkelem file.txt
Creation comments for
"file.txt":
mkelem comment
.
cleartool: Error: Vob server
operation "Create Container" failed.
Additional information may be
available in the vob_log on host "VOB_server"
cleartool: Error: Unable to
create directory "\\VOB_server\vobstore\testvob2.vbs\s\sdft\1a":
operation not permitted.
cleartool: Error: Unable to
create element "file.txt".
Errors in vob_log on
the UNIX/Linux server:
12/23/02 13:27:29
vob_server(20995): Error: unable to set ownership of file s/sdft/16/28: Not
owner
12/23/02 13:27:29
vob_server(20995): Error: Unable to create container
/vobstore/testvob2.vbs/s/sdft/1a: Not owner
cleartool describe
-long of the VOB from Windows:
H:\>cleartool desc
-l vob:\testvob2
versioned object base
"\testvob2"
created 02-Jan-03.11:53:46 by
ClearCase Administrator (vobadm.tesas@VOB_server) "Created using
create_vob(8s)."
VOB family feature level: 3
VOB storage host:pathname
"VOB_server.domain.com:/4clearcase//vobadm/vobstore/testvob2.vbs"
VOB storage global pathname
"\\VOB_server.domain.com\home\vobadm\vobstore\testvob2.vbs"
database schema version: 54
VOB ownership:
owner nobody
group nobody
Additional groups:
group nobody
group domain\group1
credmap for logged
in user from Windows:
C:\Rational\ClearCase\etc\utils>credmap
VOB_server.domain.com
Identity on local system:
User: domain\user_wx
(NT:S-1-5-21-2025429....)
Primary group: domain\group1
(NT:S-1-5-21-2025429....)
The primary group, domain\group1, of the user account is in the VOB's Additional
Group list, but the cleartool describe for the VOB shows nobody as the group owner on
Windows.
Note: A describe of the same VOB from the UNIX/Linux side
shows the correct group ownership.
Cause
The group that owns
the VOB exist on UNIX/Linux, but it does not exist on Windows.
Nobody (or -2)
reported as the group owner on the VOB is preventing the vob_server process
from setting the group ownership on the data storage container, /testvob.vbs/s/sdft/1a.
Resolving the
problem
You will need to do
one of the following:
1. Use protectvob to
set the VOB group ownership to a group on UNIX (or Linux) that has an identical
group on Windows:
cleartool protectvob -chgrp <group_name> \\Hostname\share\MyVOB.vbs
Review the ClearCase Command Reference Guide on the topic of protectvob
(cleartool man
protectvob) for more
information.
Create a group on
Windows that matches the current VOB group owner on UNIX or Linux.
Consult your system administrator or operating system manuals for assistance.
Note: The VOB's group owner does not have to be the same as the user's
primary group.
27. How do I – understand how ClearCase evaluates multiple magic files
How does IBM® Rational® ClearCase® looks for a magic file and what
happens if there are multiple copies on a host.
Only ONE magic file can be used per host.
The first magic file discovered by ClearCase is the one that will be used.
So what happens when there are multiple magic files on the host?
How does ClearCase choose which one to use?
1. ClearCase
searches for magic files in specific locations in a specific order
2. ClearCase
selects the magic file based on its filename.
SEARCH ORDER
1. Magic
files are first searched for in the location specified by the
environment variable MAGIC_PATH. This
variable overrides the search path described below.
2. If the MAGIC_PATH variable is not set, ClearCase
next searches for a magic file in your HOME directory, (as defined by
the environment variable HOME) for a .magic
file.
3. If there
is no magic file in your HOME directory, ClearCase next searches in the
ClearCase install directory (often defined by the environment variable CLEARCASEHOME). There is a config
directory and a magic directory. The default magic file (default.magic)
is located here; however, any other file ending in .magic will be examined by ClearCase as well.
Example:
Microsoft® Windows®: C:\Program
Files\Rational\ClearCase\config\magic
UNIX® and Linux®:
/opt/rational/clearcase/config/magic
MAGIC FILE EVALUATION
Within a given directory, all files with a .magic suffix are read in
ASCII alphabetical order. This means for example that Z comes after
W but before A.
So when more than one magic file exists in the defined or default Magic Path
location, the various magic files are evaluated first by filename.
Example:
If the following 3 magic files are found by ClearCase, only one will be
evaluated for use. Which one?
c.magic
b.magic
a.magic
Answer: a.magic. This is because the filename a.magic is
alphabetically first in the ClearCase search order.
Scenario:
The default magic file name on Windows and UNIX is default.magic.
If this magic file was to be modified, good practice dictates that
a back-up copy of the file be created before proceeding. If you name the backup
copy of the magic file to copy.default.magic (for example) and you keep
it stored in the same location as the default.magic file, the changes in the
default.magic file would not be evaluated. Why?
Answer: The changes made to the default.magic file would
not be evaluated as ClearCase will first evaluate the filename copy.default.magic
(as C comes before D).
The following solution will help to avoid conflict or confusion
with respect to multiple magic files:
1.
Store only one copy of the "active" magic file in one of
the designated magic paths (identified above).
2.
Make sure the naming convention used for your magic files is such
that the "active" copy you need to use has its name evaluated first
(alphabetically).
28. How do I – use the ClearCase Magic file
The purpose of the magic file is to have ClearCase 'type' the
element correctly based on the contents of a given file. By 'type' we mean
select a specific ClearCase Type Manager to manage the asset.
Below is an excerpt from a default.magic file:
frame_document document file:
-magic 0, "<MakerFile" ;
This line is interpreted as:
file-type-list: selection-expression
·
The first entry ("frame_document" and
"document" in this example) can be any name that is chosen to
describe the type or function of the file. Depending on the file type
situation, each name on the list could match either an element type defined in
a VOB or an icon name specified in an icon file.
·
The final name in the file-type-list, in this case
"file", should always be a valid element type that exists in your
VOBs.
Note: The cleartool lstype -kind eltype -long command
will list all the element types that are defined in a VOB.
Here is an example:
%cleartool lstype -kind eltype -long
element type "compressed_file"
05-May-94.12:37:10 by
USER (user.email)
"Predefined element
type used to represent a file in compressed format."
type manager:
z_whole_copy
supertype: file
meta-type of element:
file element
element type "compressed_text_file"
05-May-94.12:37:10 by
USER (user.email)
"Predefined element
type used to represent a text file in compressed format."
type manager:
z_text_file_delta
supertype: text_file
meta-type of element:
file element
element type "directory"
05-May-94.12:37:10 by
USER (user.email)
"Predefined element
type used to represent a directory."
supertype: file_system
_object
meta-type of element:
directory element
element type "file"
05-May-94.12:37:10 by
USER (user.email)
"Predefined element
type used to represent a file."
type manager: whole_copy
supertype: file_system
_object
meta-type of element:
file element
element type "file_system
_object"
05-May-94.12:37:10 by
USER (user.email)
"Predefined element
type used to represent a file system object."
SCENARIO 1: Adding a file to source control using the -eltype switch.
Example:
%cleartool mkelem -eltype frame_document my_frame_doc
ClearCase will try to find the frame_document type in the VOBs list of types
and will fail if this type has not been defined.
SCENARIO 2: Adding a file to source control without
using the -eltype switch.
%cleartool mkelem my_frame_doc
ClearCase will try to guess what type the file needs by using the default.magic
file to perform the file typing.
·
If there is a local magic file in the default install directory
for (/usr/atria/config/magic on UNIX or C:\Program
Files\Rational\ClearCase\config\magic on Windows) ClearCase will search there
first by default.
·
If the MAGIC_PATH variable is not set, the default search path is:
$HOME/.magic:${ATRIAHOME:-/usr/atria}/config/magic
On Windows, the path is: %clearcase_home%\config\magic
·
If MAGIC_PATH is set to a list of directories, ClearCase will
search for files with a .magic suffix in these directories. It will not search
the /usr/atria/config/magic/default.magic, it effectively overrides this file.
If an element type is not specified on the command line, mkelem
tries to determine a type automatically by using "magic" files to
perform file-typing. This involves a pattern-match on the new element's
extension (and perhaps an examination of the file itself).
For the above selection of a Frame file, here is an excerpt from the magic file
and an example of what will happen:
magic file:
-----------
frame_document document file: -magic 0, "<MakerFile" ;
1. No file type is listed with the mkelem so use selection-expression
2. Open the file and use "-magic 0, "<MakerFile" to
determine the file type.
3. OK -- found "<MakerFile" in the files contents
4. OK -- use the first valid type that is found in the file-type-list. In this
case "file".
Note: File is the only valid type in the VOB type list above.
PERSONAL MAGIC FILE: To use a personal magic file
and have ClearCase type the file as one of your own defined types, without
using '-eltype', perform the following:
EXAMPLE:
1a. Create a .magic directory in the user's home directory and
create a file with .magic extension (UNIX only)
% cd ~user
% mkdir .magic
% cd .magic
% touch my.magic
% ls
my.magic
1b. Create a cc.magic file (in the same directory as the default.magic file) or
edit the default.magic file itself (WINDOWS only)
2. Create the element type in the VOB
%cleartool
mkeltype -supertype compressed_file frame
element type
"frame"
12-Sep-95.16:20:57 by
User (user.group@host)
"new file type for
frame docs"
type manager:
z_whole_copy (inherited from type "compressed_file")
supertype:
compressed_file
meta-type of element:
file element
3. Edit the personal magic file or default.magic file and add the new line.
Example for Frame
#
Check Magic Numbers
frame_document document
frame: -magic 0, "<MakerFile" ;
4. Use cleartool file to verify the correct type used when
creating a new element of this type:
%cleartool file template2.doc
template2.doc: frame
5. Perform cleartool
mkelem with the new type.
%cleartool mkelem template2.doc
Created element
"template2.doc" (type "frame").
Checked out
"template2.doc" from version "/main/0".
Note: This element type must be defined in all VOBs that need to use
it.
Remember, if the default.magic file is changed directly, the next time an
upgrade is performed, a new default.magic file will be created. It is better to
create a personal magic file and set the MAGIC_PATH variable instead.
29. How do I – Add a new element type to the local cc.magic file
This is a walkthrough of the steps required for creating a new
element type and adding it to the local ClearCase magic file, default.magic.
Note: There are other methods for managing magic files, refer to technote 1122471 for more
details.
The screenshots used in the below example are from Windows,
however, the cleartool command line syntax can be found in IBM Rational
ClearCase Command Reference, or run cleartool man
<sub-command>; for example, cleartool man cc.magic.
Note: The GUI can only be used in non-replicated VOBs only; if
MultiSite® is enabled, then you will not be able to remove an element type or
change the definition of an element type from the Type Explorer, and the
command line syntax must be used.
Create a new element type (cleartool mkeltype)
For this example the new type is NEVER_MERGE, see technote 1123371 for details on
how this type is used in the ClearCase UCM context:
- Go
to the Windows Start menu, traverse to Rational
Software > Rational ClearCase > Type Explorer:
- When
it opens, you are prompted to select a VOB:
- After
selecting a VOB, click OK > double-click element types:
- Right-click
an empty space > select Create... > enter a name > click OK:
- Element
Properties dialogue will open > select Type manager tab > change the
Merge type to Never consider elements of this type for merging:
- If
the VOB is replicated, then the following error will appear:
- Otherwise,
in a non-replicated VOB, the new element type will get created and be made
available in the element type list:
Update the cc.magic file with the new type
1.
This file, default.magic, is located in the config directory under
the ClearCase installation, by default the path is:
·
UNIX and Linux: /usr/atria/config/magic
·
Windows: C:\Program
Files\Rational\ClearCase\config\magic
Make a copy of the default.magic file to another directory as a
backup; for example, C:\Program
Files\Rational\ClearCase\config\magic\backup\default.magic.
Open the default.magic file using Notepad (or another platform
specific editor)
An entry must be added for the new type, NEVER_MERGE
There are plenty of entries for binary and compressed_file, so the
new element type can most likely be based off an existing entry.
Example:
visio_template visio compressed_file : !-printable & -name
"*.[vV][sS][tT]" ;
To replace an existing entry, just add a '#' to the beginning of
the line and add the new entry below it.
Example:
existing entry --->
# visio_template visio
compressed_file : !-printable & -name "*.[vV][sS][tT]" ;
new entry ---->
visio_template NEVER_MERGE
compressed_file : !-printable & -name "*.[vV][sS][tT]" ;
Note: This entry, visio_template, may be located in different
sections of the magic file, be sure to search for the entries and make the
change under each section.
Repeat the above steps for all types that you want to be
associated with the NEVER_MERGE element type, then Save and Close
the magic file
To confirm the change worked as expected, use cleartool file
<filname>. The output will display what file type a visio file will
be added as under source control in ClearCase.
Example:
Y:\material>cleartool file
test.vst
test.vst: NEVER_MERGE
30. How do I – understand how the file type of a new element is determined
The element type feature in Rational ClearCase is a
methodology for cataloguing file objects in a VOB and assigning them the
correct type manager.
The file type is a ClearCase declaration that does not
impact (or change) the file as it is interpreted or stored on the local file
system .
The magic file is parsed to type a new file element. This
file consist of a map that dictates how an element's type is determined. There
is a local magic file on each Rational ClearCase host, but in some environments
a global magic file is administered, refer to technote 1122471 for more details
on the magic file.
Each file type is associated with a particular type manager,
which will ultimately determine how the element's source container is stored in
the VOB database. Type managers process a file based on its data format. Refer
to technote 1127322 for more details
on type managers and their size limitations.
Note: There are restrictions for merging element types that are not text
as detailed in technote 1149498.
Making a new element
Adding a new element to ClearCase source control requires the
execution of cleartool mkelem.
From command line, cleartool mkelem -eltype is used to
specify the file type of the new file element.
Only an element type that already exist in the VOB can be
specified in the command syntax. There are predefined element types that exist
in a VOB after creation, however, see technote 1146356 for directions
on creating a new element type and adding it to the magic file.
Note: For information about predefined element types, see the mkeltype
reference page; cleartool man mkeltype.
The creation of a new element can occur by simply entering some
arbitrary filename in the cleartool mkelem syntax or by converting an existing
view-private file:
·
If the filename does not exist as a view-private object in the
view, then only the filename is considered when typing the file in ClearCase.
·
However, when converting a view-private file to a new element,
then both the name and the contents of the file are evaluated to type the file.
Hence, a filename that is commonly used for text files will be typed as a
binary (or compressed) file if it contains non-ASCII characters.
The type of an element can be changed after is has been added to
source control using cleartool chtype <file type> <filename>:
M:\admin_vu\multivob>ct
chtype -force text_file foo.txt
Changed type of element
"foo.txt" to "text_file".
Match by name only
To force ClearCase to type a specific file by name only (and
ignore its contents), you can add a file-typing rule to the magic file in the Match
by name without examining data section.
Note: This is the first section in the default.magic file.
Example:
#
Match by name without examining data
core file : -name
"core" ;
compressed_file : -name
"*.[nN][eE][wW]";
Note: The new file-typing rule that you add must come before the
following line in the magic file:
text_file : -printable ;
compressed_file :
!-printable ;
31. How do I – Change element types in a replicated VOB
It is a challenge to make changes to existing element types in an
IBM® Rational® ClearCase MultiSite® replicated VOB.
There are some cases where an element type needs to be modified:
- Change
the merge rules
- Change
the type manager
In a replicated VOB modifying an element type is prohibited in order to
avoid divergence issues.
The only alternative is to create a new element type that has the
features you wish to utilize.
This process can be complicated and very time consuming as the work involved
requires multiple steps. It is far easier just to keep the existing element
type name; however, since you cannot create an object where the name already
exists, you must remove the <old> element type first.
Herein lies the second problem.
The ClearCase MultiSite Administrator's Guide and the ClearCase
Reference Guide on the topic of rmtype (cleartool
man rmtype) document that the removal of element types in a replicated VOB
is prohibited in order to avoid divergence.
WORKAROUND:
The following workaround can be used to create a new element type in a
replicated VOB using the same name of an existing element type.
1.
Rename (cleartool rename) the
<old> element type
2.
Lock -obsolete the element type
3.
Create the new element type with the same name
4.
Replicate to ALL sites in the family
32. How do I - restore an element from backup using standard file copy
This is an alternate method for restoring an IBM® Rational®
ClearCase® element from backup when a container has become corrupted using the
standard file copy command. This procedure will only work so long as the
element was not removed using rmelem nor any versions (rmver) or branches
(rmbranch) were removed.
Solution
The below procedure describes restoring an element from backup
using a standard file copy as opposed to the relocate utility as described in
the ClearCase Administrator's Guide.
This procedure will not work if the element has been removed using
rmelem or if any versions have been removed on any branches. The reason is the
container needs to be in sync with the database otherwise the information
restored that the database has removed will remain inaccessible!
Note: This procedure will work in UCM environments.
Instructions:
To restore a single element from backup, you will need to take the following
steps:
1. Restore
a copy of the VOB from backup onto another registry server.
Note: Restoring a live VOB onto a production registry server where the
VOB is already registered in any region can cause possible corruption. Use a
different registry server.
2. Find the
element's old source container from the backup VOB.
3. Place
the old source container in the current VOB's storage area, using a special
name.
4. Run cleartool
checkvob to bring the VOB database in line with the old container.
Note: Since the container restored from backup will not be as current as
the corrupted container, it will be missing some versions. The cleartool
checkvob will bring the VOB's database in line with the older container.
The following example uses an element called file.txt, a VOB called /vobs/myvob,
and a storage area called /vobstore/myvob.vbs are used.
Note: The examples are taken from UNIX® (or Linux®), but are the same
for Microsoft® Windows®.
EXAMPLE:
Note: It is recommended you scrub all the cleartext in the VOB
before proceeding with the following steps. Review the Rational
ClearCase Reference Guide on the topic of scrubber (cleartool man scrubber) for more information.
1. Find the
element's source container.
·
Run cleartool dump file.txt
·
Look for the line that references the
source container.
Example line in output:
source cont="/net/server/vobstore/myvob.vbs/s/
sdft/16/2e/0-41fbe138ed0511d2b552000180k679de-k5"
Search for the containers in the VOB storage area. Make a note of
the source container name from the dump output; it will be needed in later
steps.
Run ls -l on
UNIX/Linux
Example output:
/net/server/vobstore/myvob.vbs/s/
sdft/16/2e/0-41fbe138ed0511d2b5520001808679de-k5
Note: If the container exists, remove it using standard
operating system remove commands.
IMPORTANT: You will at this stage need to remove all the cleartext for
each version ever constructed of the element before proceeding if you have not
scrubbed all the cleartext in the VOB. This entails running the cleartool dump
command on each version of the element. To obtain each version of the element,
run cleartool lsvtree -all <file>. Once
each version is identified, you will need to run cleartool dump <file version>. For
example cleartool dump file.txt@@/main/1. Do this for every version and
remove the specific cleartext containers if they exist prior to proceeding with
the next step.
Restore the VOB from a backup using normal backup and restore
procedures.
Note: These procedures are described in the Rational ClearCase
Administrator's Guide.
This example will assume that the VOB storage area was restored to server_two
at /vobstore/myvob_restore.vbs
Register and tag the VOB:
·
Run cleartool register -vob /vobstore/myvob_restore.vbs
·
Run cleartool mktag -vob -tag /vobs/myvob_restore
/vobstore/myvob_restore.vbs
·
Run mkdir /vobs/myvob_restore
·
Run cleartool mount /vobs/myvob_restore
Find the source container of the file.txt element in this
restored VOB:
·
Run cleartool dump file.txt
Look for the line that mentioned the source container.
For example:
source
cont="/net/server_two/vobstore/myvob_restore.vbs/s/
sdft/16/2e/0-202080579b2411d6ae3b000180f0f492-kx"
Move the restored source container for file.txt to the
production VOB source container path, adding .1 to the end of the container name.
Note: The .1 suffix
signifies to the cleartool checkvob command that the source container is
a backup container and should therefore alter the VOB database accordingly.
Example:
%cp
/net/server_two/vobstore/myvob_restore.vbs/s/
sdft/16/2e/0-202080579b2411d6ae3b000180f0f492-kx
/net/server/vobstore/myvob.vbs/s/
sdft/16/2e/0-41fbe138ed0511d2b5520001808679de-k5.1