Home

How do I

Soft - is your software and documentation
Asset - is something that must be protected
Management - is what we do
Enterprise - is the capability
Computing - is the power
Services - are what we provide


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) 1

Table of Contents. 1

Elements. 5

1.       How do I – understand using directory protections is not sufficient to protect the contained elements. 5

2.       How do I - determine the full pathname and version of an element identified only by its oid. 5

3.       How do I - Identify elements by the source container path. 6

4.       How do I – understand the Primary Group requirements for element creation. 8

5.       How do I - Restore an element that has been rmnamed. 9

6.       How do I – understand what the History Mode element means. 11

7.       How do I - List and count the number of elements in VOB. 11

8.       How do I – understand the “db_obj_delete_V3: RPC: Unable to receive; errno = Connection reset by peer when running rmelem” issue  13

Triggers. 13

9.       How do I - determine the amount of elapsed time ClearCase spends in trigger logic. 13

10.     How do I - create a preop checkin trigger that does not fire on directories. 15

11.     How do I - copy a Trigger Type. 15

12.     How do I - use Access Control Lists with triggers to restrict operations to specific groups. 15

13.     How do I – understand about deleted user accounts and ClearCase performance. 16

14.     How do I - apply a trigger to the ClearCase move operation. 18

15.     How do I – create a trigger to prevent unreserved checkouts on UNIX and Linux. 19

16.     How do I – enforce a standard set of triggers from windows to control mklbtype, rmlbtype, etc... 19

17.     How do I - detect whether a checkin is part of an Add to Source Control operation in a trigger 20

18.     How do I - change element ownership when new elements are added to the VOB. 22

Methodology. 22

19.     How do I - convert a base ClearCase VOB to a UCM Component 22

20.     How do I – understand about reserved and unreserved checkouts. 26

21.     How do I - run JRE version 1.4.2_05 and higher within a VOB context on Linux. 29

22.     How do I - convert a VOB to an AdminVOB. 30

23.     How do I - suppress the confirmation dialogue box that displays VOBs that have been mounted. 30

Types and Type manager. 31

24.     How do I – handle binary files in ClearCase. 31

25.     How do I - manually construct cleartext 34

26.     How do I – understand the VOB server operation Create Container failed issue. 36

27.     How do I – understand how ClearCase evaluates multiple magic files. 37

28.     How do I – use the ClearCase Magic file. 38

29.     How do I – Add a new element type to the local cc.magic file. 40

30.     How do I – understand how the file type of a new element is determined. 42

31.     How do I – Change element types in a replicated VOB. 43

32.     How do I - restore an element from backup using standard file copy. 44

33.     How do I – Knowledge Collection: Type manager <text_file_delta> failed create_version operation. 46

34.     How do I – resolve a Type manager text_file_delta failed create_version operation. 46

35.     do I – understand the text_file_delta: Error: "foo.c" is not a 'text file': it contains a line exceeding 8000 bytes  48

36.     How do I – understand about type managers and size limitations. 49

37.     How do I – understand the file too large error checking in a text file issue. 49

38.     How do I – understand the mkbrtype command. 51

39.     How do I – understand how file types are determined when creating a new element 52

40.     How do – use the new Merge Type Copy feature with ClearCase version 7. 53

41.     How do I – resolve a definition of type in AdminVOB would be eclipsed issue. 53

42.     How do I – understand the type manager text_file_delta failed create_version operation issue. 55

43.     How do I - change the XML Diff/Merge Type Manager 56

Links. 64

44.     How do I - identifying hard links within a VOB. 64

45.     How do I – understand the VOB hard link created due to canceled checkout issue. 65

46.     How do I – understand about locating checkouts for VOB symbolic links. 66

47.     How do I - create Symbolic Links (symlinks) from command line. 67

48.     How do I - create Symbolic Links (symlinks) from the GUI 68

49.     How do I – manage symbolic links in ClearCase interop. 70

50.     How do I - remove Symbolic and Hard Links in ClearCase. 71

VOB (Raima) database. 73

51.     How do I – understand the db_VISTA error 2 from OpenFileMapping() of lockmgr_almd. 73

52.     How do I – understand the db_VISTA database error -4 - invalid database. 73

53.     How do I – understand db_VISTA database error -5 - invalid field name. 74

54.     How do I – understand VISTA error -6 – invalid db_address. 76

55.     How do I – understand db_VISTA error -900 (errno == "No such file or directory") 78

56.     How do I – understand db_VISTA database error -900 - no more space on file. 78

57.     How do I – understand db_VISTA error -901 (errno == "Resource temporarily unavailable") Error: Shared memory version changed on lock. 79

58.     How do I – understand the shared memory version changed on lock. 80

59.     How do I – understand db_VISTA database error -901 - system error - vobrpc_server- About the interaction between ClearCase and file system snapshots. 81

60.     How do I understand about db_VISTA error -901 (errno == "Permission denied") -901 (errno == "Permission denied"). 81

61.     How do I - understand db_VISTA database error -901 - system error - db_server - Shared-memory version not set, but there are live logged-in users. 82

62.     How do I – understand db_VISTA database error -905 - error opening file. 82

63.     How do I – understand db_VISTA database error -904 - unable to allocate sufficient memory SCENARIO: 83

64.     How do I – understand db_VISTA database error -905 - error opening file. 83

65.     How do I – understand db_VISTA error -907 (errno == "Resource temporarily unavailable") 84

66.     How do I – understand db_VISTA error -907 (errno == "Resource temporarily unavailable") 85

67.     How do I – understand db_VISTA database error -909 - file record limit exceeded. 86

68.     How do I – understand db_VISTA error -912 (errno == "Invalid argument") 87

69.     How do I – understand db_VISTA error -919 (errno == "Resource temporarily unavailable") 88

70.     How do I – understand db_VISTA database error -920 - no lock manager is & db_VISTA error 2 from OpenFileMapping() of lockmgr_almd. 88

71.     How do I – understand db_VISTA database -922: lockmgr is busy. 90

72.     How do I – understand db_VISTA error -925 (errno == "Resource temporarily unavailable") 90

73.     How do I - reduce the size of the string file for a ClearCase VOB. 91

74.     How do I – understand about the 2 Gigabyte limitation of VOB database files. 92

75.     How do I - remove all Derived Objects from a VOB. 94

VOB database. 95

76.     How do I – the issue reformatvob does not set the VOB replicated attribute entry of a replicated VOB. 95

77.     How do I - increase reformatvob performance. 96

78.     How do I - manually reformat VOB database using db_dumper and db_loader, when reformatvob does not  work  97

79.     How do I – understand why a database must be dumped before it can be loaded. 99

80.     How do I – understand the VOB database files that can be regenerated or replaced. 101

81.     How do I – understand about ClearCase database vista.* files. 102

82.     How do I – understand about ClearCase event records in the VOB database. 103

83.     How do I – understand the “Lock manager unable to recover from "User Table full" condition which may cause VOBs to become inaccessible” issue. 104

84.     How do I – understand why ClearCase spawns hundreds of db_server processes. 105

Storage. 105

85.     How do I – understand about the lost+found directory. 105

86.     How do I - rename a ClearCase VOB (applies to renaming a view as well) 111

87.     How do I – understand the additional groups in .identity directory not preserved after moving a VOB issue  111

88.     How do I – resolve there are no generated data sources available for storage dir issue. 112

89.     How do I – understand the permission to mount the VOB tag requires ownership of the VOB storage directory issue  112

90.     How do I – understand about cleartool mount options. 113

91.     How do I - recreate the cleartext storage pool 113

92.     How do I – address the the chown_pool and chown_container support issue on Linux. 114

Backup and restore. 114

93.     How do I – understand about the interaction between ClearCase and file system snapshots. 114

94.     How do I - restore an element from backup using clearexport_ccase. 115

ClearCase commands. 116

95.     How do I – understand about cleartool rmname and checkouts. 116

96.     How do I – understand why locking an element with the -obsolete option does not hide it from view.. 117

Scripts and utilities. 117

97.     How do I - list locked VOBs. 117

98.     How do I - change the ownership of all objects in a VOB. 118

99.     How do I - determine the last time a VOB was modified. 118

100.        How do I - find all checkins in a VOB that occurred since a particular date. 119

101.        How do I - automate uncheckout 119

102.        How do I - list and count the number of elements in VOB. 119

103.        How do I - show disk utilization per branch per element using UNIX du command. 121

Limitations. 122

104.        How do I – understand the issue of hosting VOB Servers on VMware. 122

105.        How do I – understand the limits on the number of VOBs stored on a single VOB server 122

106.        How do I – understand about the limits for simultaneously mounting VOBs on a single host 122

107.        How do I – understand that increasing the lockmgr parameters can cause NFS deadlocks. 123

Addendums. 124

108.        How do I – understand the supplement to the Command Reference Guide on mkvob -nremote_admin  124

109.        How do I – understand the supplement to the Command Reference Guide on comments. 124

110.        How do I – understand the supplement to the Command Reference Guide on mktrtype. 124

Problems and Issues. 125

111.        How do I – understand the issue unable to determine version for VOB root directory element 125

112.        How do I – understand why a ClearCase administrative user is able to move a version map label without warning  126

113.        How do I – understand why dbcheck crashes with Unhandled exception in ClearCase 7.1. 127

114.        How do I – understand why after restarting the ClearCase host the CM server does not automatically restart 129

115.        How do I – understand the error Operation "ver_unformat_cltxt" failed: ClearCase object not found. 129

116.        How do I – understand the serious performance degradation possible on Solaris 9.0 VOB servers with more than 2GB of memory hosting large VOBs. 130

117.        How do I – understand the failed to record hostname issue in ClearCase. 130

118.        How do I – understand the “Unable to raise the VOB Family Feature Level” issue. 136

119.        How do I – understand the VOB pool scrubbing errors "db_cr_delete_strands_V3: RPC: Unable to receive; errno = Connection reset by peer" problem.. 138

120.        How do I – understand about the error Checked out version, but could not copy data to <some-file.txt> in view   139

121.        How do I – understand about VOBs mounted read-only and checkouts of directory elements. 140

122.        How do I – understand why problems that occur if the ClearCase Administrator group owns the VOB or VOB objects  141

123.        How do I – understand the Warning: unable to scrub Pool cdft below maximum size issue. 143

124.        How do I – understand the data to collect when there are VOB issues. 144

125.        How do I – resolve error from VOB database and Trouble opening VOB database. 145

126.        How do I - restore missing versions to a VOB from a known data source. 145

127.        How do I – resolve a Cleartext is not in VOB issue. 146

128.        How do I - restore cleartext and derived object pools. 148

129.        How do I – resolve a cleartool protect -chgrp fails with a group name but succeeds with group id issue  149

130.        How do I – understand eclipsed files and ClearCase. 149

131.        How do I – resolve an unable to add or remove a group to the VOBs group list issue. 150

132.        How do I - run cleartool protectvob for VOBs stored on NAS. 151

133.        How do I - change the VOBs initial creation comments (You can’t) 151

134.        How do I - change the name of the original creator of an element (You can’t) 152

135.        How do I – understand the checkout from VOB symbolic link fails within a snapshot view issue. 152

136.        How do I – understand the directory modified stamp does not reset after cancelling the checkout of a version issue  153

137.        How do I – understand the VOB tags are still displayed in the GUI after changing regions issue. 156

138.        How do I – understand the removed VOB still appears as mounted to the MVFS issue. 158

139.        How do I – understand the unable to unlock versioned object base after moving a VOB to a new server host issue  159

140.        How do I – understand the unable to unlock versioned object base error 160

141.        How do I – understand the unable to move files into a VOB on Linux issue. 161

142.        How do I – understand the invalid argument error loading a file on Windows issue. 161

143.        How do I – understand that changing the case of a checked out version causes Checked Out but Removed error 162

144.        How do I – understand the shared-memory version not set, but there are live logged-in users error 166

145.        How do I – understand about problems that occur if the ClearCase Administrator group owns the VOB or VOB objects  167

 

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:

source cont="\\host1\ClearCase_storage\VOBs\DemoVOB.vbs\s\sdft\29\19\0-12227c71742f4ce99dd5100e96a0b54b-mg

source cont="\\host1\ClearCase_storage\VOBs\DemoVOB.vbs\s\sdft\29\19\0-12227c71742f4ce99dd5100e96a0b54b-mg

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>

http://www.ibm.com/i/v14/icons/u_bold.gif

Back to top


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:

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.


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:


UNIX and Linux only:

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:


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

barryma@us.ibm.com.

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 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:

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

>>> 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

Check for an invalid account

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:


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.

http://www-1.ibm.com/support/docview.wss?uid=swg21135939&aid=1

 

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 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>

libreadlink_interpose.so

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:

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.


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)

·         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:

 

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:


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

                Once the source container has been copied to the production VOB, the restored VOB can be removed with the cleartool rmvob /vobs/myvob_restore command.

                On the production server, run checkvob -fix file.txt.

Example output:
[viewname: /vobs/myvob]% cleartool checkvob -fix file.txt
The session's log directory is 'checkvob.12-Apr-99.12:18:23'.
Processing element "/vobs/myvob/file.txt@@".
The element is now locked.