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 utilities “How do I” covers: (Last updated 5-Oct-09)

Ř  licensing - Clearlicense & lsclient, etc

Ř  ClearCase doctor – disabling, etc...

Ř  Export and Import tools – clearfsimport, CCImportWizard, Perforce, subversion and SourceGear migration, etc...

Ř  Database Utilities - dbcheck, countdb, string_report, vista_errors, rgy_upgrade, etc...

Ř  Permissions - issue resolution, fixprot, etc...

Ř  xclearcase - issues – setup, view executed commands, etc...

Ř  Report Builder – Using, etc...

Ř  Scheduler – notify utility, recreating, creds, credmap, etc...

Ř  Server processes – using albd_list, etc....

Ř  Merge tool – functionality, etc...

Ř  CtCmd module – 64-bit usage, etc...

Ř  Troubleshooting – using wireshark to resolve problems, etc...

Ř  General – utility scripts, etc...

 

Table of contents

ClearCase utilities “How do I” covers: (Last updated 5-Oct-09) 1

Table of contents. 1

Licensing.. 3

1.       How do I – understand clearlicense -release. 3

2.       How do I – stop a ClearCase license being pulled each time I logon to Windows. 3

3.       How do I - revoke a ClearCase license. 5

4.       How do I – set the licensing priorities in ClearCase. 6

5.       How do I - deny users from pulling a ClearCase license. 7

6.       How do I – understand ClearLicense reporting a user priority of none. 7

7.       How do I - Identify unidentified users using credmap, clearlicense and lsclient 8

ClearCase Doctor. 9

8.       How do I - disable the ClearCase Doctor from executing at logon. 9

9.       How do I – understand why the ClearCase Doctor incorrectly reports that the option "Can have local VOBs and/or views" is available on a "client only" installation. 9

Export & Import. 10

10.     How do I – understand why files come across as checked out but removed when using IBM® Rational® ClearCase® to perform a clearfsimport operation. 10

11.     How do I – understand about exporting data from other SCM tools into ClearCase and installation requirements  11

12.     How do I – understand about importing flat files to a branch with clearfsimport 12

13.     How do I -  stop and restart the clearfsimport command. 13

14.     How do I – understand the issue clearfsimport is not preserving element creation date. 14

15.     How do I – understand about importing flat files to a branch with clearfsimport 16

16.     How do I – resolve the unable to determine VOB for pathname "." during clearimport issue. 17

17.     How do I – resolve the locks on metadata types can cause clearimport to fail issue. 17

18.     How do I – use the CCImportWizard. 17

19.     How do I – understand why Clearfsimport -rmname may not detect removed directories if wildcards are used to specify source directories. 20

20.     How do I - Migrating from Perforce to ClearCase. 20

21.     How do I – understand about converting from SourceGear Vault version control to ClearCase. 21

22.     How do I - migrating data from Subversion to ClearCase. 21

23.     How do I - import files with spaces using clearfsimport 21

24.     How do I – understand the clearfsimport -recurse -rmname causes source directory to be skipped when view-private file exists in target directory issue. 22

25.     How do I – understand the ClearCase 7.0 fails to export PVCS files issue. 24

Database utilities. 24

26.     How do I – understand why Dbcheck crashes with Unhandled exception in ClearCase 7.1. 24

27.     How do I - increase the performance for ClearCase Database utilities. 25

28.     How do I – use dbcheck. 25

29.     How do I – understand  the issue dbcheck: "record is deleted but not on the delete chain". 27

30.     How do I – understand the errors in logs as a result of running dbcheck. 28

31.     How do I – define the maximum value for dbcheck -p option. 28

32.     How do I – run the ClearCase dbcheck utility. 28

Note: The dbcheck utility is run against a single VOB. All references to VOB in the instructions below refer to the VOB you wish to run dbcheck against.. 28

33.     How do I – run the dbcheck on a read-only filesystem.. 30

34.     How do I – understand the db_VISTA database error -4 - invalid database. 30

35.     How do I – understand the requirements for running the database dumper in stand alone mode for ClearCase 7.0  31

36.     How do I – use the countdb utilities. 32

37.     How do I – understand about string_report 32

38.     How do I – understand about rgy_upgrade. 35

39.     How do I – understand about keybuild. 35

40.     How do I - reprotect elements and metadata using vob_sidwalk on Windows. 36

1.1.         How do I - List and count the number of elements in VOB. 38

Permissions. 39

41.     How do I – understand the protection commands and utilities used with ClearCase. 39

42.     How do I – use the Fix_prot utility. 41

43.     How do I – understand about the creds utility. 42

1.2.         How do I – understand why "NT" -type SID is not supported by credmap_server 45

xclearcase. 46

44.     How do I - change the font size of xclearcase. 46

45.     How do I - view the commands that were executed by xclearcase. 47

46.     How do I - specify colours for xclearcase. 47

47.     How do I – understand about clearvobadmin, cleardescribe and cleargetlog on UNIX and Linux. 47

Report Builder. 48

48.     How do I - run the report builder from the command line. 48

49.     How do I - display all elements that have not been delivered for a particular project 49

Scheduler. 52

50.     How do I - Recreating the scheduler database. 52

51.     How do I – use the ClearCase notify utility. 53

Server processes. 54

52.     How do I – use albd_list 54

53.     How do I - determine network connectivity to a remote ClearCase server using albd_list 55

Merge tools. 55

54.     How do I – understand the ClearCase compare and merge functionality is for text files only issue. 55

CtCmd module. 56

55.     How do I – understand why CtCmd fails to compile on ClearCase 7.x hosts. 56

56.     How do I – understand about CtCmd on a 64bit Linux platforms. 57

57.     How do I – understand about CtCmd and screen formatting. 57

58.     How do I - get started with CtCmd the Perl extension for ClearCase. 58

59.     How do I – understand the Must Gather requirement for : CtCmd. 59

60.     How do I – understand why CtCmd fails to compile on ClearCase 7.x hosts. 60

Troubleshooting.. 61

61.     How do I - configure Wireshark to troubleshoot ClearCase performance issues. 61

62.     Stop client names from appearing in the ClearCase Administration Console. 61

63.     How do I - run the ClearCase ALBD service in debug mode. 62

General. 64

64.     How do I – understand the Rational Change Management (CM) Server Administration utility - new in 7.1.0.2  64

65.       CM Server ClearQuest Options tab - Configures the attributes in the MBean CqServerFactoryMBean. This MBean governs the ClearQuest Managed Connection Factory that starts the backend cqrpc processes.  65

66.     How do I - deploy the ClearCase and ClearQuest Help systems on an intranet server 65

67.     How do I – get a sorted path name for VOBs (UNIX) 70

Licensing

1.    How do I – understand clearlicense -release

If you have 20 ClearCase licenses and 10 ClearCase MultiSite® licenses, you could use clearlicense -release 40 times per day on the ClearCase licenses and 24 times per day on the ClearCase MultiSite licenses.

Note: This limit is counted for each individual ClearCase product associated with a single license server.

Once the limit is reached, running clearlicense -release will result in the following error:

clearlicense: Error: Exceeded per day release limits.  User jdoe not released.


Rationale

"To discourage license battles among users, albd_server prevents this option from being used an excessive number of times during any single day." The limit is 24 times per day, or twice the number of user accounts for that license per day, whichever is greater.

 

There is no means by which this limit can be modified.

2.    How do I – stop a ClearCase license being pulled each time I logon to Windows

After logon to a Windows host, as user1, running clearlicense will show that a license has been pulled for that user id:


C:\>clearlicense
Licensing information for ClearCase.
License server on host "CC_LICENSE_HOST".
Running since Wednesday 02/20/02 16:06:04.

LICENSES:
Max-Users  Expires       Password [status]
100          none      

Maximum active users allowed: 100
Current active users: 2
Available licenses: 98

ACTIVE users:
User         Priority    Time-out in
user1        none       59 minutes (at 13:20:42)
user2        none       37 minutes (at 13:18:12)

 

There are a couple reasons this will occur:

1. ClearCase Doctor running in the background at logon will pull a license. This status tool runs by default after installing ClearCase. Following the system reboot, ClearCase Doctor prompts you to either:


Note:
A license is pulled by ClearCase Doctor when it is set to Always Run at Logon or Run In Background at Logon, and either of these selections becomes the default for each subsequent logon to the Windows host.

1.     Views starting a logon will also cause a license to be pulled. When starting a view, there is an option to Connect to drive. By selecting none, the view will be accessible from the MVFS drive, which by default is M:\. If you choose to map the view to a drive, then the radio button for Restart at Logon is enabled. If it is left checked, the view will startup after you logon to the Windows host.

Note: VOBs set to mount at logon, or persistent VOBs, do not cause a license to get pulled.

 

Solution

A ClearCase license is taken when you run a ClearCase client utility, such as cleartool or a GUI program.

When a license is pulled, then you keep it for an extended period, which by default is 60 minutes.

Entering any ClearCase command renews the license and the Time-out period. If you do not enter a ClearCase command for a substantial period, prior to the 60 minutes expiring, then the license is released and another user can pull that license.

For more information About Rational ClearCase Atria Licensing refer to technote 1128958.

 

To stop licenses from being issued at logon:

ClearCase Doctor:

Review technote 1148854 for instructions on how to disable ClearCase Doctor from running at logon.

Views starting at logon:

Review technote 1122505 in the section Mapped Network Drives for Views for instructions on how to disconnect the views.

When you restart the views from the ClearCase GUI, be sure the Restart at Logon is unchecked to ensure the mapped drives disconnect when you log off or restart.


ClearCase Start View
undefined

When you restart the views from the Windows GUI, be sure the Reconnect at logon is unchecked to ensure the mapped drives disconnect when you log off or restart.

Windows Explorer
undefined

 

3.    How do I - revoke a ClearCase license

These steps detail how to temporarily revoke a license from a ClearCase user:

1.     Determine which users have a license by examining clearlicense output (Run cleartool man clearlicense for more details on this utility):

C:\>clearlicense
Licensing information for ClearCase.
License server on host "CC_LICENSE_HOST".
Running since Wednesday 02/20/02 16:06:04.

LICENSES:
Max-Users  Expires       Password [status]
100          none      

Maximum active users allowed: 100
Current active users: 9
Available licenses: 91

ACTIVE users:
User      Priority    Time-out in
dple       none       59 minutes (at 13:20:42)
mfia       none       57 minutes (at 13:18:12)
pmcro      none       53 minutes (at 13:14:05)
edein      none       51 minutes (at 13:12:14)
dmcno      none       50 minutes (at 13:11:35)
jrat       none       39 minutes (at 13:00:34)
ateso      none       38 minutes (at 12:59:18)
kwart      none       38 minutes (at 12:58:57)
dhip       none       29 minutes (at 12:50:13)

License Usage Statistics:
2 licenses revoked since start of period 02/20/02.
0 license requests denied.
0 active users bumped by preferred user.

2.     To release a license from a user, run clearlicense -release <username>:

C:\>clearlicense -release dple
ClearCase license for user dple has been released.
clearlicense: Error: There are no valid licenses in the NT registry for ClearCase_view_only.
clearlicense: Warning: User dple is not licensed for MultiSite.
clearlicense: Warning: User dple is not licensed for Attache.
clearlicense: Warning: User dple is not licensed for Attache-MultiSite.
clearlicense: Error: There are no valid licenses in the NT registry for ClearTrack_C.
clearlicense: Error: There are no valid licenses in the NT registry for ClearTrack.
clearlicense: Warning: User dple is not licensed for ClearGuide.
clearlicense: Error: There are no valid licenses in the NT registry for PDDTS.

Note:
Any error messages can be safely ignored, as they indicate that the user was not using any of the licenses for which errors appear upon execution of the clearlicense -release command. The clearlicense -release command attempts to release licenses for all licenses on the license server in use by the specified user.

The ClearCase license has now been relinquished. To confirm this, you can repeat step #1.

Note: There is a limit for the number of times that
clearlicense -release can be used in a 24 hour period, refer to technote 1149757 for details.

4.    How do I – set the licensing priorities in ClearCase

This functionality will ensure that the priority users will pull a license even when no licenses are available in the ClearCase environment. The lowest priority user will get bumped first by a priority user. However, a lower priority user cannot bump a user of a higher priority.

Note: To determine who currently has a license and how many are still available, run clearlicense from command line. Refer to the IBM Rational ClearCase Command Reference for more details or run cleartool man clearlicense.

To set the licensing priorities, you must modify the license database file, license.db, and use the -user option:


The license database can contain any number of -user lines, each of which specifies one or more users (by name or by numeric ID). All these lines are effectively concatenated into a single license priority list. The first user on the list has the highest priority; each successive user has a lower priority. Users not listed at all can still use the product, but they all share the lowest priority.

Example:
The following lines define licenses that assign User adm the highest priority, smith the next highest, then akp and kjones the next highest, respectively. The priority is assigned by the order that the users are specified in the license database. These users will automatically pull a license from another user of a lower priority if there are no licenses currently available in the ClearCase environment.

Note: All other users not defined, share the lowest priority and will only be able to pull any available license that is not in use already. These users are not granted a priority that allows them to pull a license from another user, and in those instances will be denied a license until one becomes available.


-license ClearCase ATRIA *.10 19961116 2adde977.1360cb11.02
-user adm
-user smith akp kjone
s

 

When the -user switch is used, the clearlicense output will update to show the priority of each user that is specified in the licensing priority:


clearlicense output:
ACTIVE users:
User    Priority    Time-out in
adm         1       28 minutes (at 13:56:11)
ccuser1     none    27 minutes (at 13:54:46)
ccuser2     none    25 minutes (at 13:53:00)
ccuser9     none    23 minutes (at 13:51:00)
kjones      2       19 minutes (at 13:46:47)


Notes:

5.    How do I - deny users from pulling a ClearCase license

Denying users can be done in the license database file, license.db, using the -nuser switch.

The license file can contain any number of –nuser lines, each of which specifies one or more users (by name or by numeric ID). The specified users cannot obtain a license and thus cannot use the product.

Note: The –user and –nuser lines can be intermixed. If a user is named in both kinds of line, the first entry is used.

1.     Go to Start > (Settings >) Control Panel > double-click the ClearCase icon > select the Licensing tab

2.     Enter -nuser Domain/user_name after the -license declarations


Note: All lines in the license.db file must be terminated with a new line character (or Enter).

1.     Edit the license.db in var/adm/atria or var/adm/rational/clearcase, depending on your ClearCase version.

2.     Enter -nuser user_name after the -license declarations.

Note: All lines in the license.db file must be terminated with a new line character (or Enter).

 

Example (applicable to all operating systems):


-license ClearCase ATRIA *.1 NONE 1235678.12345678.02
-nuser user1

 

 

6.    How do I – understand ClearLicense reporting a user priority of none

Why does the IBM® Rational® ClearCase® clearlicense utility report the user priority of none for users that have been granted a priority in the license database.

 

Users have a priority of none in a clearlicense output even though they are listed in the -user switch of the license.db file:


-license <ClearCase>
-license <MultiSite>
-audit
-timeout 30
-user ccone cctwo ccthree ccfour ccfive ccsix ccseven cceight ccnine ccten cceleven cctwelve ccthirteen ccfourteen

 

The license.db output above shows that there are multiples lines for all the users to be granted a licensing priority, however, only the first line begins with -user. This causes some of the users to have the correct priority, while others are still listed with none in the clearlicense output:


ACTIVE users:
User    Priority    Time-out in
ccone       1       28 minutes (at 13:56:11)
ccnine      none    27 minutes (at 13:54:46)
ccten       none    25 minutes (at 13:53:00)
ccthirteen  none    23 minutes (at 13:51:00)
cctwo       2       19 minutes (at 13:46:49)
ccfour      3       19 minutes (at 13:46:47)


Note: The only users that should appear with a priority of none, are those that are not defined in the licensing priority.

 

Solution

When the priority switch (-user) has a list of users that continues (or wraps) to multiple lines, then each new line must start with the -user switch to ensure that all specified users will be granted a priority, and not just the users in the first line.

Add the -user switch to the second line before the ccnine user, then all users will have a priority number as seen in the below clearlicense output:


ACTIVE users:
User   Priority    Time-out in
ccone       1       28 minutes (at 13:56:11)
ccnine      4       27 minutes (at 13:54:46)
ccten       5       25 minutes (at 13:53:00)
ccthirteen  6       23 minutes (at 13:51:00)
cctwo       2       19 minutes (at 13:46:49)
ccfour      3       19 minutes (at 13:46:47)


Notes:

·         The user priority pertains only to users that have currently pulled a ClearCase license. Thus, ccnine, has a priority of 4 rather than 9.

·         If a user of a higher priority, such as, ccthree were to login, then the list will reset the priority of any currently logged in users that have a lesser priority.

·         If all the priority users were logged in, then the list would be sequential for all specified users in the license database.

7.    How do I - Identify unidentified users using credmap, clearlicense and lsclient

From time-to-time when running clearlicense you will see a user take a license that does not get reflected as a sid but as a long SID 3.000…… string of characters. This will be a windows user who is taking a license who cannot be authenticated by your systems License server host. You may be able to identify this user if you run the following credmap command from a command prompt window:

 

            …/etc/utils/credmap –c  3.000……. <windows domain>

 

If this does not work you may be able to track down the user using a combination of clearlicense and cleartool lsclient. First run clearlicense and from the entry for the unidentified user get the time at the end of the line that the license will be given up. From this time deduct the –timeout that is set in your license.db file (UNIX) or under the Licensing tab or the ClearCase icon in the windows control panel (Windows). By default the period is 60 minutes but can be reduced to a minimum of 30 minutes by adding

-timeout 30. Once you have this amended time, run the following command to create and output file of client information:

 

            cleartool lsclient –l –host <ClearCase License server host> > <output file>

           

            cleartool lsclient –l –host samecs.com> /net/samecs/utilities/output.txt

 

Open the output file in a suitable text editor and then search this file for the amended time and look up the client name which should be 7 lines earlier in the output file.

 

Note: It is possible that one or more clients may take a license at the same time, therefore, check for more than one entry.

ClearCase Doctor

8.    How do I - disable the ClearCase Doctor from executing at logon

To prevent the ClearCase Doctor Analysis from launching at logon, check to ensure the following steps are applied:

Ensure that "Never at Logon" is selected within the Options toolbar menu within ClearCase Doctor.

undefined

Review the Help options in ClearCase Doctor for more information about the logon options.


Note:
This solution contains information about modifying the system registry. Before making any modifications to the Microsoft® Registry Editor, it is strongly recommended that you make a backup of the existing registry. For more information describing how to back up the registry, refer to the Microsoft Knowledge Base article
256986.

If ClearCase Doctor continues to start at logon, check the following registry keys:

1. HKEY_LOCAL_MACHINE\Software\Atria\ClearCase\CurrentVersion\CCDoctorLogons

 

2. HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run

If the NetworkSetup key is present, and pointing to ccdoctor.exe, removing ccdoctor.exe from the data value will prevent ClearCase Doctor from running at logon.

9.    How do I – understand why the ClearCase Doctor incorrectly reports that the option "Can have local VOBs and/or views" is available on a "client only" installation

 

This technote provides information about a defect that can occur after installing IBM Rational ClearCase (CC) 7.1 where ClearCase Doctor is incorrectly reporting the option, Can have local VOBs and/or views, is available although it was not selected during the installation.

 

Symptom

When you perform a "client only" installation of ClearCase and do not select Local Vobs and Views, ClearCase doctor incorrectly reports that this option is available to the users.

In ClearCase Doctor, you see these options that are not needed with client only installations:

1.     The albd service is installed

This issue has been identified as a product defect, APAR PK78380. Refer to
technote 1358768 for further information about this issue.

2.     It clearly states that this machine "Can have local VOBs and/or views."

Cause

This is not expected behavior. These options are appearing This issue has been identified as a product defect, APAR PK78557.

 

Resolving the problem

There is currently no resolution or workaround for this defect.

 

 

 

 

Export & Import

10.  How do I – understand why files come across as checked out but removed when using IBM® Rational® ClearCase® to perform a clearfsimport operation.

After running a clearfsimport operation listing file elements reports them as checkedout but removed.


Example:
cleartool> ls -l
version                Rhapsody_dat.txt@@\main\CHECKEDOUT from \main\0 [checkedout but removed]

Cause


Most likely the files that are checked out but removed contain binary data. As the type_manager tries to use a certain manager for the file, it notices that the file is not what was expected.

Diagnosing the problem


cleartool describe on the element that is checked in:

version "foo@@/main/1"                                          
"created by clearfsimport"                                      
Element Protection:                                              
User : eric : r-x                                              
Group: bldgrp : r-x                                                
Other:  : r-x                                                    
element type: file
predecessor version: /main/0                                    

Element that is checked out but removed:

version "9,9@@/main/CHECKEDOUT" from /main/0 (reserved)
by view: eric_view                                    
("vws_eric:/view_storage/eric/eric_view.view")    
"created by clearfsimport"                            
Element Protection:                                    
User : eric : r-x                                    
Group: bldgrp : r-x                                      
Other:  : r-x                                          
element type: text_file
predecessor version: /main/0

Resolving the problem

Remove the binary data from the files.

Refer to
technote 1222072 Type manager text_file_delta failed create_version operation for information about removing the binary data.
Or

Change the default behavior for elements.

For information about how to change the default behavior for elements refer to the
cc.magic, default.magic section of the IBM Rational ClearCase Command Reference Manual.

11.  How do I – understand about exporting data from other SCM tools into ClearCase and installation requirements

When exporting data from other SCM tools into IBM® Rational® ClearCase® (CC), does the exporting application have to be installed on the ClearCase host?

 

Cause

A user wants to migrate data from another (non-ClearCase) SCM tool, for this example, CVS. The CVS repository is placed on the ClearCase VOB server and an attempt is made to import but it fails. What needs to be done to successfully import this data into ClearCase?

 

Answer

The exporting application needs to be installed on the same system as ClearCase.

For all the exporter utilities (clearexport_cvs, clearexport_pvcs, clearexport_rcs, clearexport_sccs, clearexport_ssafe) the native application needs to be on the same system as ClearCase. This is because the clearexport_xxx utilities will make calls, such as get in the case of CVS, in order to access the files within the repository. Then the cvt_data file can be created and the clearimport process can then be called.


Refer to these technotes for related information:


For further information about a specific export utility, refer to the
ClearCase Information Center appropriate for your product version and search for the export utility name (clearexport_cvs, clearexport_pvcs, clearexport_rcs, clearexport_sccs or clearexport_ssafe).

Note: As documented in version 7.1 of the IBM Rational ClearCase Command Reference Manual, clearexport_sccs is supported on UNIX and Linux platforms (not Windows) which was a change from previous versions.

12.  How do I – understand about importing flat files to a branch with clearfsimport

ClearCase version 2002.05 and earlier had an importing tool called clearexport_ffile which utilized a -branch option to specify a branch name into which the flat files were imported.


ClearCase Version 2003.06.00 and later superseded the use of
clearexport_ffile with clearfsimport in order to import flat files into a VOB. Since clearfsimport has no -branch option, the information below provides a simple example of how to import flat files onto a branch.

Note: Clearfsimport is only available from command line, and there is no GUI equivalent functionality for this utility.

Example Scenario:

1. Locate the files to be imported.


Example:

c:\temp\exp\exported.txt

c:\temp\exp\test.txt

 

2. Set into a view and change your directory into the target VOB directory.

Example:

cd M:\myview\myvob\sub

 

3. Modify the views config spec.


Example:

cleartool edcs -tag myview

 

Note: BR in the sample config spec below refers to the target branch name.

----
element * CHECKEDOUT
element * .../BR/LATEST
element * /main/LATEST -mkbranch BR

----

 

4. Run 'clearfsimport'

M:\myview\myvob>clearfsimport -r c:\temp\exp M:\myview\myvob
      ^^^
Creating element "M:\myview\myvob\exp\exported.txt".
Created branch "BR" from "M:\myview\myvob\exp\exported.txt" ver
sion "\main\0".
    version "\main\BR\1".

      ^^^

Note: The above syntax causes a new subdirectory to get created in the target path. If you only want to copy the contents of the source location, refer to technote 1121938 for more details.


5. Verify the branch was created.

M:\myview\myvob>cleartool ls -l
exported.txt@@\main\BR\1    Rule: element * ...\BR\LATEST
test.txt@@\main\BR\1        Rule: element * ...\BR\LATEST

 

13.  How do I -  stop and restart the clearfsimport command

The clearfsimport command can be interrupted, stopped or restarted without duplicating work, but only if the -nsetevent option is not used.

The following is an example (performed on UNIX®) of the clearfsimport command being stopped and restarted.

CONFIG SPEC OF THE VIEW

% cleartool catcs
element * CHECKEDOUT
element * /main/bugs/LATEST
element * /main/LATEST -mkbranch bugs


TARGET DIRECTORY
% pwd
/view1/vob1/DIR1

SOURCE DIRECTORY LISTING
% ls -l /net/host/export/home/jdoe/tags/mystuff
total 80
-r-xr-xr-x   1 jdoe  user         246 May 15 12:49 cat.c
-r-xr-xr-x   1 jdoe  user         542 Dec 13  2000 data.txt
-r-xr-xr-x   1 jdoe  user       31887 Jun 26 16:53 foo.jsp
-r--r--r--   1 jdoe  user          29 Feb  8  2002 hardlink
-r--r--r--   1 jdoe  user          29 Jun 13 14:03 junk.c
drwxr-xr-x   4 jdoe  user         187 Jul  3 14:14 junkdir
-r--r--r--   1 jdoe  user          29 Jun 13 14:01 myfile.c
-r--r--r--   1 jdoe  user          52 Jan 29  2002 seeme.txt


RUN THE COMMAND
% clearfsimport /net/host/export/home/jdoe/tags/mystuff/* .
Validating directory ".".
Creating element "./cat.c".
^C  
(STOPPED THE COMMAND Ctrl-C)

% pwd
/view1/vob1/DIR1

% ls -l
total 0
-r-xr-xr-x   1 jdoe  user           0 Aug 14 13:13 cat.c
% cleartool lsvtree -all cat.c
cat.c@@/main
cat.c@@/main/0


RESTART THE COMMAND

% clearfsimport /net/phosphate/export/home/jdoe/tags/mystuff /* .
Validating directory ".".
clearfsimport: Warning: Using existing checkout of directory ".".
Validating element "./cat.c".
Skipping element "./cat.c", because version in VOB is newer.
Creating element "./data.txt".
Created branch "bugs" from "./data.txt" version "/main/0".
version "/main/bugs/1".
Creating element "./foo.jsp".
Created branch "bugs" from "./foo.jsp" version "/main/0".
version "/main/bugs/1".
Creating element "./hardlink".
Created branch "bugs" from "./hardlink" version "/main/0".
version "/main/bugs/1".
Creating element "./junk.c".
Created branch "bugs" from "./junk.c" version "/main/0".
version "/main/bugs/1".
Creating directory "./junkdir".
Created branch "bugs" from "./junkdir" version "/main/0".
Creating element "./myfile.c".
Created branch "bugs" from "./myfile.c" version "/main/0".
version "/main/bugs/1".
Creating element "./seeme.txt".
Created branch "bugs" from "./seeme.txt" version "/main/0".
version "/main/bugs/1".
Closing directories.
Checked in version "/main/bugs/1" of directory "./junkdir/TESTDIR"
Checked in version "/main/bugs/1" of directory "./junkdir"
Checked in version "/main/bugs/2" of directory "."

% pwd
/view1/vob1/DIR1


% ls -l
total 79
-r-xr-xr-x   1 jdoe  user           0 Aug 14 13:13 cat.c
-r-xr-xr-x   1 jdoe  user         542 Dec 13  2000 data.txt
-r-xr-xr-x   1 jdoe  user       31887 Jun 26 16:53 foo.jsp
-r--r--r--   1 jdoe  user          29 Feb  8  2002 hardlink
-r--r--r--   1 jdoe  user          29 Jun 13 14:03 junk.c
drwxr-xr-x   4 jdoe  user         187 Aug 14 13:14 junkdir
-r--r--r--   1 jdoe  user          29 Jun 13 14:01 myfile.c
-r--r--r--   1 jdoe  user          52 Jan 29  2002 seeme.txt

14.  How do I – understand the issue clearfsimport is not preserving element creation date

After modifying the date of files to be older and then importing data to the VOB using the command clearfsimport -nset -r everything is imported correctly.

Then if create a new directory, with the non-modified date, and try to import without the "-nset" option, the directory whose date has never been modified gets imported in the vob with an older date.

Here is the error reproduction transcript along with comments:

Using a test vob ind_test2, and user ccuser is its owner. Checking the behavior of the clearfsimport "-nset" option.

1.     First explicitly modify the date of test file to be older than the rest (to 'Oct 11 2006' in my test):

[ccadm tmp]$ mkdir pip4
[ccadm tmp]$ cd pip4
[ccadm pip4]$ mkdir foo
[ccadm pip4]$ echo foo>foo/foo.txt
[ccadm pip4]$ touch -d 'Oct 11 2006' foo/foo.txt
[ccadm pip4]$ ll foo
total 12
drwxr-xr-x    2 ccadm nolscc       4096 Jan 10 16:07 .
drwxr-xr-x    3 ccadm nolscc       4096 Jan 10 16:07 ..              
-rw-r--r--    1 ccadm nolscc          4 Oct 11  2006 foo.txt

2.     Then import data to the vob as an ordinary user (not a vob owner), using the clearfsimport command with the "-nset" option:

[ccadm pip4]$ clearfsimport -nset -r . /vob/ind_test2
Validating directory "/vob/ind_test2".
Creating directory "/vob/ind_test2/pip4".
Created branch "cif" from "/vob/ind_test2/pip4" version "/main/0".
Creating directory "/vob/ind_test2/pip4/foo".
Created branch "cif" from "/vob/ind_test2/pip4/foo" version "/main/0".
Creating element "/vob/ind_test2/pip4/foo/foo.txt".
Created branch "cif" from "/vob/ind_test2/pip4/foo/foo.txt" version
"/main/0".
   version "/main/cif/1".
Closing directories.                                                    
Checked in version "/main/cif/1" of directory "/vob/ind_test2/pip4/foo"
Checked in version "/main/cif/1" of directory "/vob/ind_test2/pip4"
Checked in version "/main/cif/4" of directory "/vob/ind_test2"

[ccadm pip4]$ ll /vob/ind_test2/pip4/foo
total 6
drwxr-xr-x    2 ccadm nolscc         27 Jan 10 16:08 .
drwxr-xr-x    3 ccadm nolscc         23 Jan 10 16:08 ..
-r--r--r--    1 ccadm nolscc          4 Jan 10 16:08 foo.txt

Everything is imported correctly.

 

Then create a new directory, with the non-modified date, and try to import it to the vob as the vob owner, without "-nset" option:

[ccadm pip4]$ mkdir foo1
[ccadm pip4]$ ll
total 876
drwxr-xr-x    4 ccadm nolscc       4096 Jan 10 16:08 .
drwxrwxrwt   19 root     root       880640 Jan 10 16:08 ..
drwxr-xr-x    2 ccadm nolscc       4096 Jan 10 16:07 foo
drwxr-xr-x    2 ccadm nolscc       4096 Jan 10 16:08 foo1

[ccadm pip4]$ su shpichko
[ccuser pip4]$ ct setview shpichko_dv
[ccuser pip4]$ clearfsimport -r . /vob/ind_test2
Validating directory "/vob/ind_test2".
Validating directory "/vob/ind_test2/pip4".
Validating directory "/vob/ind_test2/pip4/foo".
Validating element "/vob/ind_test2/pip4/foo/foo.txt".                  
   Skipping element "/vob/ind_test2/pip4/foo/foo.txt", because version in VOB is newer.
Creating directory "/vob/ind_test2/pip4/foo1".
Created branch "cif" from "/vob/ind_test2/pip4/foo1" version "/main/0".
Closing directories.
Checked in version "/main/cif/1" of directory "/vob/ind_test2/pip4/foo1"
No change in version "/main/cif/1" of directory
"/vob/ind_test2/pip4/foo"
Checked in version "/main/cif/2" of directory "/vob/ind_test2/pip4"
No change in version "/main/cif/4" of directory "/vob/ind_test2"

[ccuser pip4]$ ll /vob/ind_test2/pip4 total 8
drwxr-xr-x    4 ccadm nolscc         47 Jan 10 16:09 .
drwxr-xr-x    7 ccuser nolscc        265 Jan 10 16:08 ..
drwxr-xr-x    2 ccadm nolscc         27 Jan 10 16:08 foo            
drwxr-xr-x    2 ccuser nolscc          0 Oct 11  2006 foo1


The
/vob/ind_test2/pip4/foo/foo.txt is skipped correctly, as its date (Oct 11 2006) is really older than the one in the vob.

However, the foo1 directory, whose date has always been 'Jan 10' (had never been modified) gets imported in the vob and in the vob it dates as of Oct 11 2006.

 

Cause

This issue has been identified as a product defect under APAR PK65040.

 

Resolving the problem

There is currently no fix for the defect.

WORKAROUND:

Use the -nset flag for all subsequent imports to prevent this issue.

15.  How do I – understand about importing flat files to a branch with clearfsimport

ClearCase version 2002.05 and earlier had an importing tool called clearexport_ffile which utilized a -branch option to specify a branch name into which the flat files were imported.


ClearCase Version 2003.06.00 and later superseded the use of
clearexport_ffile with clearfsimport in order to import flat files into a VOB. Since clearfsimport has no -branch option, the information below provides a simple example of how to import flat files onto a branch.

Note: Clearfsimport is only available from command line, and there is no GUI equivalent functionality for this utility.

Example Scenario:

1. Locate the files to be imported.


Example:

c:\temp\exp\exported.txt

c:\temp\exp\test.txt

 

2. Set into a view and change your directory into the target VOB directory.


Example:

cd M:\myview\myvob\sub

 

3. Modify the views config spec.


Example:

cleartool edcs -tag myview

 


Note: BR in the sample config spec below refers to the target branch name.

----
element * CHECKEDOUT
element * .../BR/LATEST
element * /main/LATEST -mkbranch BR

----

 

4. Run 'clearfsimport'

M:\myview\myvob>clearfsimport -r c:\temp\exp M:\myview\myvob
      ^^^
Creating element "M:\myview\myvob\exp\exported.txt".
Created branch "BR" from "M:\myview\myvob\exp\exported.txt" ver
sion "\main\0".
    version "\main\BR\1".

      ^^^

Note: The above syntax causes a new subdirectoy to get created in the target path. If you only want to copy the contents of the source location, refer to technote 1121938 for more details.

 


5. Verify the branch was created.

M:\myview\myvob>cleartool ls -l
exported.txt@@\main\BR\1    Rule: element * ...\BR\LATEST
test.txt@@\main\BR\1        Rule: element * ...\BR\LATEST


Review the ClearCase Command Reference Guide on the topic of
clearfsimport (cleartool man clearfsimport) for more information.

16.  How do I – resolve the unable to determine VOB for pathname "." during clearimport issue

Attempts to use the clearimport command result in the following error:

Unable to determine VOB for pathname "."

 

The clearimport command was not executed using the proper ClearCase view context.

Example:

C:\>clearimport M:\view1\VOB1 C:\cvt_data
clearimport: Error: Unable to determine VOB for pathname ".".


If the
clearimport command is not executed within the context of a ClearCase view/VOB, then the -directory option must be used.

 

Solution

Option #1:
Execute clearimport in a View/VOB context:

1.     Mount the destination VOB

2.     Start a View

3.     Set into the View and cd to the root of the VOB (or the directory to which the import will run).

4.     Execute the clearimport command

Example:

M:\view1\VOB1\dir1>clearimport c:\temp\cvt_data


Option #2:

Execute clearimport using the -directory option outside a View/VOB context:

1.     Mount the destination VOB

2.     Start a View

3.     Set into the View

4.     Execute the clearimport command using the -directory option where the directory path is the VOB path to the destination location.

Example:

C:\>clearimport -directory M:\view1\VOB1\dir1 c:\temp\cvt_data

 

 

 

17.  How do I – resolve the locks on metadata types can cause clearimport to fail issue

Attempts to import files into a VOB using the clearimport utility results in the following error:

clearimport: Error: Label type " <label name>" is locked in import VOB
clearimport: Error: Trouble while reading type information from datafile.

The clearimport utility cannot recreate an element with its associated metadata if the metadata is locked.

Note: The message Trouble while reading type information from datafile is a bit misleading. What the message really means is that while validating the type object (branch, label, element etc...), clearimport discovers that one of the "target" metadata types is locked and thus that type can not be used to make metadata type instances in the VOB. Since clearimport requires the metadata to complete the import, the import fails.

 

Solution

Unlock the metadata type in the target VOB and run the clearimport command again.

18.  How do I – use the CCImportWizard

The CCImportWizard is a GUI that combines some of the functionality of the command line export and import tools such as:
clearfsimport -- ordinary files
clearexport_pvcs -- PVCS Version Manager
clearexport_rcs -- RCS
clearexport_sccs -- MKS Source Integrity
clearexport_ssafe -- Visual SourceSafe
Note: The clearexport_cvs and clearexport_ccase are not included in the tools capability.

Any feature that is not included in the GUI tool (such as applying a label or downcasing files) to which you require will need to be executed from the command line utility.

The following example uses the CCImportWizard to import a flat file (ordinary file) into a VOB.

1. Open the CCImportWizard (Start > Run type
ccimportwizard)

Note: The CCImportWizard does not have a shortcut by default. The binary resides in the ClearCase bin directory.

2. Click Next
undefined

3. Chose the file type to import and click Next


4. In this window you select the files you wish to import. The left pane displays the source that is found on the local host operating system and the right pane displays the VOBs. Locate the file or directory you wish to import into a VOB. The choose the VOB and its location you wish to store the file.

Note: In this example the file eclipse.exe was selected as the source and the root directory of the \import VOB was selected as the destination.

Click Import to ClearCase to verify options.


5. You have the following options at this point:

·         Click Remove to change currently selection.

·         Click a new file or folder and select a VOB path and click Import to ClearCase for more imports.

·         Click Next to proceed with import

Note: In this example, click Next.

6. Preview the results to ensure accuracy. Highlight any entry and click Remove if unsatisfied; otherwise click Next.


7. The import will process the files.

Note: If lots of files are being imported (more than 100), it is recommended you use the command line export/import method for performance reasons.



8. Confirm success and click Next



9. Click Close to finish.
undefined

19.  How do I – understand why Clearfsimport -rmname may not detect removed directories if wildcards are used to specify source directories

When running clearfsimport with the -rmname option to import multiple directories using wildcards, if a directory in the root of the source area is removed, clearfsimport will not remove the matching directory from the destination directory:

For example:

If the "c:\sourcedir" directory contains the following items:
12/19/2008  04:34 PM    <DIR>          OPIE
09/23/2008  01:28 PM    <DIR>          WFI

And a clearfsimport is run with these options:
     clearfsimport -recurse -rmname c:\sourcedir\* m:\testview\testvob1

The above 2 directories will be created. If the "OPIE" directory is then removed, and the SAME import command run, the "OPIE" directory will NOT be rmnamed.

 

Cause

This behavior is working as designed.

 

Resolving the problem

Using a wildcard in the clearfsimport command line as above is processed as if you are specifying multiple directories. So, in this example, the first clearfsimport is processed as if you had typed:

clearfsimport -recurse -rmname c:\sourcedir\OPIE c:\sourcedir\WFI m:\testview\testvob1

And the second import is processed as if you had typed:

clearfsimport -recurse -rmname c:\sourcedir\WFI m:\testview\testvob1

Thus, clearfsimport will appear to ignore the removal of the directory in the "C:\sourcedir" directory. Clearfsimport does not consider the "c:\sourcedir" directory the import source, it is considering EACH child directory matching the wildcard as a SEPARATE source directory.

Note: Files removed (in this example) from the "WFI" or "OPIE" directories would be rmnamed when the -rmname option is used since they are within the "source" directories of the import.

If you need the "sourcedir" subdirectories to be removed when clearfsimport -rmname is used, you need to specify "c:\sourcedir" without the wildcards as the source directory. To workaround the creation of the same-named directory in the import destination, you can use symlinks to point to the desired directories in the destination directory.

20.  How do I - Migrating from Perforce to ClearCase

The perforce database format is proprietary and the perforce API does not give any direct way to access or manipulate the Perforce depot file structure directly. Therefore:

 

WORKAROUND:
Converting Perforce data considerations:

·         Text files are in RCS format, which can be converted to ClearCase using clearexport_rcs.

·         Binary files are stored as compressed (zipped) files in a subdirectory whose name is the same name as the file. The actual zip file contained in that directory has a name of "1.1" or some like construct, which cannot be converted using clearexport_rcs.

·         Metadata, such as labels, cannot be preserved with the RCS converter.

Conversion of the archive will be a multiple step process:

a).  Convert non-binary data from RCS format to ClearCase

b).  Convert binary data from its format to ClearCase

c).  Convert metadata

·         You could use clearfsimport to export version by version from Perforce to ClearCase
or

·          Use Perforce to CVS converter and then load that into ClearCase using clearexport_cvs

21.  How do I – understand about converting from SourceGear Vault version control to ClearCase

How can I export data from SourceGear Vault version control system and import into an IBM® Rational® ClearCase® VOB?

 

There is currently no export utility to directly export from SourceGear Vault version control to ClearCase.

You can attempt the following options to convert from SourceGear Vault version control to ClearCase.

1.     If you're able to export the data in SourceGear Vault to a flat file system directory, then you could use the ClearCase clearfsimport utility to import the data in the directory structure into a ClearCase VOB.

Note: This method would only import a single version of the current file; however, with additional effort, clearfsimport can be used to iteratively recreate version trees, if exporting each subsequent directory version (and associated files) from the 3rd party repository and re-clearfsimporting them. You can test this method by reading the clearfsimport manual page, and then testing this on flat files and a non-production VOB, as well as try the
-preview switch.

2.     Another option is to find a converter from SourceGear Vault to another 3rd party product for which we do offer a converter, for example SourceGear to CVS, then clearexport_cvs to ClearCase.

Review the ClearCase Command Reference Guide on the topics of
Importing assets from other configuration management systems for more information about the available conversion utilities.

Finally, you can try to search the user forums on IBM Rational developerWorks for solutions posted by ClearCase Admins:
http://www-128.ibm.com/developerworks/forums/dw_rforums.jsp
http://www.ibm.com/developerworks/forums/dw_forum.jsp?forum=333&cat=24&hideBody=true

22.  How do I - migrating data from Subversion to ClearCase

ClearCase does not provide a tool to import from Subversion to maintain version history.

If you are not interested in maintaining version history and merely wish to start from the latest version or a preselected configuration, you can use the clearfsimport command. Review the ClearCase Command Reference Guide on the topic of clearfsimport (cleartool man clearfsimport) for more information.

If you require version history, you may want to evaluate the open source tool svn2cc.

WORKAROUNDS:

1.     It is possible to create views in Subversion representing certain milestones in your development stream. From there you can import the versions from each view sequentially using the aforementioned command clearfsimport. The clearfsimport command in this scenario will create a new version of the element each time it is run applying a label to the imported versions automatically.

You can try using clearexport_cvs, as the Subversion repository is very similar to that of CVS (Concurrent Versions System), see IBM Rational ClearCase Command Reference for more details on this export utility.

23.  How do I - import files with spaces using clearfsimport

 The following information explains what the proper clearfsimport syntax is for importing directories or flat files that have spaces in the filename.


ClearCase 7.0

When importing directories or files using the ClearCase 7.0 clearfsimport utility, it is necessary to use double quotes around the directory or file if it has spaces in the name.

Example:

M:view\my_vob>clearfsimport -r "C:\Test Directory" .
Validating directory ".".
Creating directory ".\Test Directory".
Creating element ".\Test Directory\This is a test.txt".
   version "\main\1".
Closing directories.
Checked in version "\main\1" of directory ".\Test Directory"
Checked in version "\main\1" of directory "."

Note: Attempts to use single quotes results in an error:

Example:

Single quotes (' '):

M:view\my_vob>clearfsimport -r 'C:\Test Directory' .
Validating directory ".".
clearfsimport: Error: Could not access "C:\Test".
clearfsimport: Error: Could not access "Directory".
Closing directories.
No change in version "\main\0" of directory "."

Note: Attempts to use wildcards (\*) and double quotes results in the following error:

M:view\my_vob>clearfsimport -r "C:\Test Directory\*" .
clearfsimport: Error: Trouble expanding command line: "C:\Test Directory\*".

This issue has been reported as defect APAR PK24845.

WORKAROUND:
The following syntax change is required if you are exporting from a directory with spaces in the path. For example, C:\Docs and Stuff\

Rather than set into the target (view and VOB) and import from the source, set into the source and import into the target.

Example:
C:\Docs and Stuff\Templates>clearfsimport -r -preview .\* M:\view\test_vob
M:\view\test_vob\amipro.sam new element
M:\view\test_vob\excel.xls new element
M:\view\test_vob\excel4.xls new element
M:\view\test_vob\lotus.wk4 new element
M:\view\test_vob\powerpnt.ppt new element
M:\view\test_vob\winword.doc new element

 

ClearCase 2003.06.00

For ClearCase version 2003.06.00 with no patches applied, single quotes must be used to import data with embedded spaces in the name.

For ClearCase 2003.06.14 (Service Release 4) and later, double quotes must be used to import data with embedded whitespace.

 

ClearCase 2002.05.00

For ClearCase version 2002.05.00 with no patches applied and earlier, double quotes must be used to import data with embedded spaces in the name.

For ClearCase 2002.05.00 with patch 22, single quotes must be used to import data with embedded whitespace.

24.  How do I – understand the clearfsimport -recurse -rmname causes source directory to be skipped when view-private file exists in target directory issue

Attempts to run clearfsimport -recurse -rmname results in the source directory being skipped if any view-private files are present in the destination directory.


Example:

Importing the icons directory and a single file into the root of the VOB (test_vob).


M:\dynamic_view\test_vob>clearfsimport -recurse -rmname C:\icons .
Validating directory ".".
Creating directory ".\icons".
Creating element ".\icons\icons.bmp".
    version "\main\1".
Closing directories.
Checked in version "\main\1" of directory ".\icons"
Checked in version "\main\2" of directory "."


M:\dynamic_view\test_vob>cleartool ls
DownloadDirector@@\main\1       Rule: \main\LATEST
icons@@\main\1                  Rule: \main\LATEST
lost+found@@\main\0             Rule: \main\LATEST


M:\dynamic_view\test_vob\icons>cleartool ls
icons.bmp@@\main\1              Rule: \main\LATEST

M:\dynamic_view\test_vob>clearfsimport -recurse -rmname -identical -preview C:\icons
.\icons\icon.txt  new element
.\icons\icons.bmp  element unchanged
.\icons  new directory version
.  directory unchanged

Note: A new file icon.txt has been added to C:\icons and clearfsimport has detected that file to be added as a new element.


M:\dynamic_view\test_vob\icons>cleartool ls
file.txt
icons.bmp@@\main\1              Rule: \main\LATEST

M:\dynamic_view\test_vob>clearfsimport -recurse -rmname -identical -preview C:\icons .
.\icons  directory unchanged
.  directory unchanged


Note: Now clearfsimport reports no change even though there clearly is a new file that needs to be imported.

This issue has been reported as defect APAR PK30744.

 

WORKAROUND:

Remove the view-private files from the destination directory and clearfsimport will process the directory as expected.

Example:


M:\dynamic_view\test_vob\icons>cleartool ls
file.txt
icons.bmp@@\main\1              Rule: \main\LATEST


M:\dynamic_view\test_vob\icons>del file.txt


M:\dynamic_view\test_vob\icons>cleartool ls
icons.bmp@@\main\1              Rule: \main\LATEST


M:\dynamic_view\test_vob>clearfsimport -recurse -rmname -identical -preview C:\icons .
.\icons\icon.txt  new element
.\icons\icons.bmp  element unchanged
.\icons  new directory version
.  directory unchanged

Note: Be sure to preview the import from the parent directory of destination directory

25.  How do I – understand the ClearCase 7.0 fails to export PVCS files issue

There is a defect where attempts to export PVCS files using version 7.0 or later of the IBM® Rational® ClearCase® clearexport_pvcs utility results in only the directories being imported into the VOB.

 

Cause

Scenario:

On the PVCS host, install ClearCase 7.x.

Run the clearexport_pvcs utility to export the PVCS files, then import the files into a ClearCase VOB using clearimport.

Note: There are no errors, and all will seem successful.

Attempts to set into a view, mount and cd into the VOB to view the files results in only the directory structure being imported. There are file elements in the directories.

Solution
Defect APAR PK30708 has been submitted to investigate this behavior.

There is currently no solution available for this defect.

WORKAROUND:

Use the clearexport_pvcs utility from an earlier version of ClearCase 2003.06.16 (Service Release 6) or previous. The executable is located under ...\ClearCase\bin.

You can then import into a ClearCase 7.x VOB server.

Database utilities

26.  How do I – understand why Dbcheck crashes with Unhandled exception in ClearCase 7.1

An attempt to run Dbcheck on ClearCase version 7.1 crashes with an Unhandled exception. This issue occurs on all Windows architectures (32 and 64 bit).

Cause

This issue has been identified as a product defect under APAR PK78046.

Resolving the problem

There is currently no resolution for this issue.

WORKAROUND

Either of the following procedures can be used to workaround this issue.

 

Refer to the following technotes for further information about the dbcheck utility:

Technote 1203130 About the ClearCase database utility dbcheck

Technote 1122748 Running the ClearCase dbcheck utility

 

27.  How do I - increase the performance for ClearCase Database utilities

Tools that access the ClearCase database can be configured to use more memory and thus gain a speed boost.

Note: This is only available on ClearCase 2003.06.13 (Service Release 3) and higher.

The speed boost is gained by setting the following environment variable on the host running the database utility to 32766 (32k).

Note: This allocates more memory pages for the program to use.


CCASE_VIEW_LDR_CACHE = 32766

This variable can increase the performance of any tool that accesses the ClearCase database, with one exception. The dbcheck utility does not require the environment variable to be set in order to gain additional speed. This utility is has its own command option to improve performance (-p option). Review technote 1121988 for more details about this option.

IMPORTANT: The value for the environment variable (and the dbcheck parameter) cannot be larger than 32766 (32k). Values larger than that will be ignored and no speed boost will be visible as the default amount of memory pages will be used during execution.

28.  How do I – use dbcheck

The dbcheck utility is a Raima level database utility located in the etc > utils directory of your ClearCase installation path. This tool checks the integrity of the files in the database directory of your VOB storage - specifically the vob_db.d0* and vob_db.k0* files.

The dbcheck utility is not aware of ClearCase at all. It can be run on a machine that doesn't have ClearCase installed, as long as the 7 Raima database files (and the vob_db.dbd file) are copied to it. The dbcheck tool reads only those 7 files looking for inconsistencies between the key files (vob_db.k0*) and the data files (vob_db.d0*), and no more. It doesn't care about branches, versions, elements, triggers, permissions, etc... It only cares about whether or not each individual database record looks healthy.

The dbcheck tool will report false error conditions if the database is changing underneath it. For example, if a checkin occurs during run time of the dbcheck tool, there may be an indication of that checkin in the .d01 file but not in the .k01 file - and dbcheck reports a problem. This only happens if any database files are being modified during the dbcheck run. If the VOB is locked for all users that means no write operations can occur in the VOB (other than unlocking it). This ensures that the database won't change, and thus that the dbcheck run is valid. If the VOB is unlocked during the dbcheck, or the VOB is not locked for a specific user who modifies the database, the dbcheck is invalid.

Read operations on the database can still occur when the VOB is locked. Constructing cleartext is a read operation from a database point of view - the cleartext container may be written but dbcheck never looks outside the db directory - as long as those 7 files never change dbcheck is fine.

In order to see usage statement and a definition of the syntax type dbcheck with no options from the command line.

EXAMPLE:
>dbcheck

db_VISTA Version 3.20
Database Consistency Check Utility
Copyright (C) 1985-1990 Raima Corporation, All Rights Reserved
usage: dbcheck [-options] dbname [dbfile(s)]
options: [-s] [-k] [-dk] [-kd] [-a] [-ts] [-r#] [-p#] [-f#] [-t] [-c]

-s = Perform complete set consistency check
-k = Perform key file structure consistency check
-dk = Perform key access consistency check from data files
-kd = Perform key data consistency check from key files
-ts = Perform time stamp checks for records and sets
-a = Does -s -dk -kd -ts
-r# = Report every # percent to stderr
-p# = Number of pages for vista to allocate to its page cache
-f# = Number of open files vista is allowed to have
-t = Print a traceback of the b-tree at the first sign of disorder
-c = Print counts of objects scanned in the check

 

Example:

1. Log on to the VOB server as Administrator (on Windows) or root (on UNIX)
2. Lock the VOB

Note: You can reduce the time the VOB needs to be locked by locking the VOB, making a copy of the db directory, unlocking the VOB, and running dbcheck on the copy of the database.

IMPORTANT: If there are errors locking the VOB, copy the database to another location and run the dbcheck. Be sure you inform Support if the dbcheck was run on a unlocked VOB.

3. Open a command prompt and cd to the db sub-directory in the storage location of the VOB

Example:
E:\ClearCase_Storage\VOBs\test.vbs\db
4. Run dbcheck (from within the db directory of the VOB).

<CCHOME>\etc\utils\dbcheck -r1 -a -k -p8192 vob_db > c:\tmp\dbcheck.txt

<CCHOME>/etc/utils/dbcheck -r1 -a -k -p8192 vob_db > /tmp/dbcheck.txt

Note: The string vob_db is not an abbreviation, and should be entered literally. Make sure the dbcheck.txt output file indicates processing of each of the 7 database files.

UNIX/Linux Note: Be sure to run the correct version of dbcheck if running the utility from a Link-Only installation as there are different versions for different database schemas. View technote 1122278 for more information.

5. Unlock the VOB

The output you want to see is 0 errors were encountered in 0 records/nodes
Anything else should be reported to Support.

Example Output:

db_VISTA Version 3.20
Database Consistency Check Utility
Copyright (C) 1985-1990 Raima Corporation, All Rights Reserved
-------------------------------------------------------------------
Processing key file: vob_db.k01(1), total of 650 nodes
-------------------------------------------------------------------
Processing key file: vob_db.k02(2), total of 1472 nodes
-------------------------------------------------------------------
Processing key file: vob_db.k03(5), total of 1 node
-------------------------------------------------------------------
Processing key file: vob_db.k04(6), total of 1 node
-------------------------------------------------------------------
Processing data file: vob_db.d01(0), total of 50901 records
-------------------------------------------------------------------
Processing data file: vob_db.d02(3), total of 28109 records
-------------------------------------------------------------------
Processing data file: vob_db.d03(4), total of 5 records

Database consistency check completed
0 errors were encountered in 0 records/nodes

This technote explains what the maximum value is for the IBM® Rational® ClearCase® dbcheck -p argument and how setting this value too might worsen performance.

The dbcheck "-p" argument is the number of pages for vista to allocate to its page cache. It allows you to specify the number of 4 kilobyte pages to cache, or in other words it allows you to allocate more memory than dbcheck uses by default.

 

This can positively impact performance as dbcheck processes a potentially multi-gigabyte database.

Omitting the -p argument results in dbcheck defaulting to 64 pages (as in dbcheck -p 64).

The maximum value usable for -p is 32k minus 1 (32767).

Specifying 32768 or higher will cause dbcheck to ignore the setting, in effect making it "0" which potentially puts performance behind what one would observe by omitting the -p altogether.

29.  How do I – understand  the issue dbcheck: "record is deleted but not on the delete chain"

 This technote explains why the warning record is deleted but not on the delete chain may appear while running the IBM® Rational® ClearCase® dbcheck utility.

 

Symptom

One or more of the following warnings are reported during dbcheck execution:

"processing data file...

vob db.d01 (2) problems at record <record_id>

record is deleted but not on the delete chain"

 

Cause

This warning means that the record space will not be reused unless the VOB is reformatted. Reformatting the VOB will free up the space for use again.

 

Resolving the problem

If there are only a few of these warnings, you may decide to just leave things as they are; however, if there are several or many of these warnings you may want to reclaim the space by running the cleartool reformatvob command.

Example: cleartool reformatvob <full path to .vbs directory>

Review the IBM Rational ClearCase Command Reference Guide on the topic of reformatvob (cleartool man reformatvob) for more information.

 

30.  How do I – understand the errors in logs as a result of running dbcheck

The following errors appear in the ClearCase logs after running dbcheck:

 

Cause

This issue has been identified as a product defect under APAR IC43659.

 

Resolving the problem

This defect has been closed as a permanent restriction. Review the Problem Conclusion section of the APAR for a detailed explanation.

Note: This issue does not impact functionality of dbcheck or the database in anyway; you may safely ignore the messages.

Be sure to report any other errors that are reported in the dbcheck output, refer to technote 1122748 for more details.

 

31.  How do I – define the maximum value for dbcheck -p option

The dbcheck -p option is the number of pages for vista to allocate to its page cache. It allows you to specify the number of 4 kilobyte pages to cache, or in other words it allows you to allocate more memory than dbcheck uses by default.

This can positively impact performance as dbcheck processes a potentially multi-gigabyte database.

Omitting the -p argument results in dbcheck defaulting to 64 pages (as in dbcheck -p 64).

The maximum value usable for -p is 32k minus 1 (32767).

Specifying 32768 or higher will cause dbcheck to ignore the setting, in effect making it "0" which potentially puts performance behind what one would observe by omitting the -p altogether.

32.  How do I – run the ClearCase dbcheck utility

Note: The dbcheck utility is run against a single VOB. All references to VOB in the instructions below refer to the VOB you wish to run dbcheck against.

1.     Log on to the VOB server as VOB owner, Administrator (on Windows) or root (on Linux/UNIX)

2.     Lock the VOB

Note: You can reduce the time the VOB needs to be locked by locking the VOB, making a copy of the db directory, unlocking the VOB, and running dbcheck on the copy of the database.

IMPORTANT: If there are errors locking the VOB, copy the database to another location and run the dbcheck. Be sure you inform Support if the dbcheck was run on a unlocked VOB.

3.     Open a command prompt and cd to the db sub-directory in the storage location of the VOB

Example:
E:\ClearCase_Storage\VOBs\test.vbs\db

4.     Run dbcheck (from within the db directory of the VOB).

·         On Windows:
<CCHOME>\etc\utils\dbcheck -r1 -a -k -p8192 vob_db > c:\tmp\dbcheck.tx

·         On UNIX ond Linux:
<CCHOME>/etc/utils/dbcheck -r1 -a -k -p8192 vob_db > /tmp/dbcheck.txt

Note: The string vob_db is not an abbreviation, and should be entered literally. Make sure the dbcheck.txt output file indicates processing of each of the 7 database files.

UNIX/Linux Note: Be sure to run the correct version of dbcheck if running the utility from a Link-Only installation as there are different versions for different database schemas. View
technote 1122278 for more information.

5.     Unlock the VOB


The output you want to see is 0 errors were encountered in 0 records/nodes
Anything else should be reported to Support.


Example Output:

db_VISTA Version 3.20
Database Consistency Check Utility
Copyright (C) 1985-1990 Raima Corporation, All Rights Reserved
------------------------------------------------------------------------
Processing key file: vob_db.k01(1), total of 3 nodes
Processing delete chain:  0 nodes on delete chain.
Processing nodes:
++100%
------------------------------------------------------------------------
Processing key file: vob_db.k02(2), total of 3 nodes
Processing delete chain:  0 nodes on delete chain.
Processing nodes:
++100%
------------------------------------------------------------------------
Processing key file: vob_db.k03(5), total of 1 node
Processing delete chain:  0 nodes on delete chain.
Processing nodes:
100%
------------------------------------------------------------------------
Processing key file: vob_db.k04(6), total of 1 node
Processing delete chain:  0 nodes on delete chain.
Processing nodes:
100%
------------------------------------------------------------------------
Processing data file: vob_db.d01(0), total of 153 records
Processing delete chain:  0 records on delete chain.
Processing records:
+++++++++10%+++++++++20%+++++++++30%+++++++++40%+++++++++50%+++++++++
60%+++++++++70%+++++++++80%+++++++++90%+++++++++100%

------------------------------------------------------------------------
Processing data file: vob_db.d02(3), total of 133 records
Processing delete chain:  0 records on delete chain.
Processing records:
+++++++++10%+++++++++20%+++++++++30%+++++++++40%+++++++++50%+++++++++
60%+++++++++70%+++++++++80%+++++++++90%+++++++++100%

------------------------------------------------------------------------
Processing data file: vob_db.d03(4), total of 1 record
Processing delete chain:  0 records on delete chain.
Processing records:
100%
Database consistency check completed
0 errors were encountered in 0 records/nodes

33.  How do I – run the dbcheck on a read-only filesystem

Historically dbcheck could not be run on read-only files systems.

One example of where this has been problematic is when a VOB is stored on a NAS device using the snapshot or flash backup features. The snapshot of the disk can be taken instantaneously, but it is a read-only version of the disk at that time. Running dbcheck on a read-only volume will yield the following error:

db_VISTA Version 3.20
Database Consistency Check Utility
Copyright (C) 1985-1990 Raima Corporation, All Rights Reserved

*** db_VISTA database error -4 - invalid database

Database consistency check prematurely terminated
   Last db_status = -4

1 error was encountered in 0 records/nodes

 

Solution

There is a new undocumented switch for use with dbcheck.


The -R switch will allow the dbcheck utility to run against a read-only file system.

Note: this is a capital "R", the lowercase "r" has a different meaning.

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

The following invalid database messages occurs after running dbcheck:

db_VISTA Version 3.20
Database Consistency Check Utility
Copyright (C) 1985-1990 Raima Corporation, All Rights Reserved

*** db_VISTA database error -4 - invalid database

Database consistency check prematurely terminated
Last db_status = -4

1 error was encountered in 0 records/nodes


This error DOES NOT MEAN there is VOB database corruption.

This error indicates that the dbcheck utility was unable to collect the information it needed for one reason or another.

Solution

The following list contains steps to verify if dbcheck was run correctly.

One of these problems is causing the error.

1.     Make sure the correct directory is set; this error may appear if the db directory is not set when the command is run.

2.     Make sure the dbcheck utility was run as the correct user:

·         On UNIX and Linux the dbcheck utility needs to run as root or VOB owner.

·         On Windows the dbcheck utility needs to run as VOB owner or Administrator.

3.     Log in to and run the dbcheck utility on the host where the VOB storage physically resides.

4.     Make sure that the system to which the database resides is not read only. Raima will need to temporarily open the database for read/write for checking the internal timestamp.

5.     Make sure the string "vob_db" in the command:

           dbcheck -a -k vob_db 2>&1 dbcheck.out

This string is not an abbreviation, and should be typed literally.

6.     Ensure that ALL the database files are available. If the database directory has been recently backed up, compare the files in the db directory to a newly created or reliable (live) database's db directory. The following database files that dbcheck is looking for should be present in the db directory:

vob_db.d01
vob_db.d02
vob_db.d03
vob_db.dbd
vob_db.k01
vob_db.k02
vob_db.k03
vob_db.k04
vob_db.str_file
vob_db_schema_version

For specific directions on how to run the dbcheck utility, refer to technote 1122748.

35.  How do I – understand the requirements for running the database dumper in stand alone mode for ClearCase 7.0

Attempts to run the database dumper on a copy of the VOB database results in the following error:


db_dumper.54: Error: Unable to open file "./replica_uuid": No such file or directory.
db_dumper.54: Error: Cannot open database in './db': db_dumper.54: Error: Error from libdb (1)


The dumper's database open code was modified to verify that the VOB's registry entry is correct before actually opening the database, thus the VOB's replica UUID is required to search the ClearCase vob_object registry.

This was done to prevent possible problems when the replica is registered on 2 registry servers and the different registries have different VOB servers assigned to the same VOB.

Since this information cannot be obtained from the database without opening it, the replica_uuid file in the VOB storage directory is referenced instead. When that file does not exist, such as when looking at a copy from a VOB snapshot, the above error occurs.

 

Solution

WORKAROUND:

Do both of the following:

1.     Use the full path the VOB storage area when running the database dumper in stand alone mode. This can be done by using the following command on Unix/Linux:

/opt/rational/clearcase/etc/dumpers/db_dumper.{schema version} `pwd`

On Windows, the following commands can be used in a batch file:

for /f "delims==" %%x in ('cd') do set PWD=%%x
"c:\program files\rational\clearcase\bin\dumpers\db_dumper.{schema ver}" %PWD%

2.     Create a file named replica_uuid in the parent directory of the VOB copy that is holding the database you are working on.

Add a
dummy uuid line in this file, for example:

11111111.22222222.3333.44:55:66:77:88:99

The dumper will then run successfully in stand alone, though you will get with this warning:

db_dumper.54: Warning: Database not found in local registry for cmd: "".  Using client path ./db

36.  How do I – use the countdb utilities

Introduction to countdb
The countdb utility is a read only tool that reports the count of the various objects and records in the VOB database.

The countdb utility is useful for analyzing VOB databases to determine how space is being used within it. The countdb utility is sometimes used in conjunction with the string_report utility.

The output will show how full a database is and what needs to be scrubbed if it is reaching the disk maximum capacity, or the maximum number of database records (schema 53 VOBs only).

Depending on what is filling up the database, there are various actions that can be taken to make space.
Examples:

·         High number of OPLOG_ENTRY or EVENT records:
** Run the vob_scrubber with appropriate vob_scrubber_params file settings.

·         High number of DERIVED_OBJECT/CONFIG_REC_DERIVED_OBJECT/STRING objects:
** Remove derived objects and run scrubber -e

High number of VERSION_LABEL_LINK / NAMESPACE_DIR_VERSION records:
** Remove instances of this item. (rmlabel / delete directory versions)

 

Location of countdb

The countdb utility comes installed with ClearCase and was introduced in release 4.1 patch 7. The countdb utility is stored in the etc-utils directory.

UNIX and Linux:

2003.06 and later:

/var/adm/rational/clearcase/etc/utils

2002.05.00 and earlier

/var/adm/atria/etc/utils

Windows

C:\Program Files\Rational\ClearCase\etc\utils

 

Instructions
1. Change to the db directory of the VOB to be checked.
2. Run the command
 countdb vob_db

37.  How do I – understand about string_report

The string_report utility is a read only tool that reports the count of the various records in the VOB database string file.

The string file contains records such as

 

Other objects stored in the string file depending on its size:


Note: This is not a complete list of where ClearCase uses string objects or directly stores information in the string file.

The string_report utility is useful for analyzing the VOB database string file to determine how space is being used within it. The string_report utility is often used in conjunction with the countdb utility.

The output is really useful for schema 53 VOBs which have a limitation imposed on the maximum string file length (2GB).

Depending on what is filling up the database, there are various actions you can take to make space.
Examples:

Location of string_report

The string_report utility comes installed with ClearCase. The string_report utility is stored in the etc utils directory.

UNIX® and Linux®:

2003.06 and later:

/var/adm/rational/clearcase/etc/utils

2002.05.00 and earlier

/var/adm/atria/etc/utils

Microsoft® Windows®

C:\Program Files\Rational\ClearCase\etc\utils

 

Instructions

Note: You must be logged in as root, administrator or ClearCase privileged from within the db directory.
1. Change to the db directory of the VOB to be checked.
2. Run the command string_report.

Example:

UNIX (schema 53 VOB):
/vobstore/myvob-vob.vbs:-> cd db
/vobstore/myvob-vob.vbs/db:-> /usr/atria/etc/utils/string_report

String File Statistics
======================================================
record type             # records    string file bytes
--------------------    ---------    -----------------
STRING (no overflow)          444                    0
STRING (overflow)             245                26571
CONFIG_REC                      2                    2
------------------------------------------------------
Bytes in use                                     26571
STR_FREE                       10                   75
------------------------------------------------------
Total string file size (DB)                      26646
Total string file size (OS)                      29871
------------------------------------------------------
Max possible string file size               2147483647
Longest free string length                  2147457001

Note the string file size and length cannot exceed 2GB with Schema 53.

Windows (schema 54 VOB):

C:\ClearCase_Storage\VOBs\test_vob.vbs\db>string_report
***WARNING: No CONFIG_REC records found!!

String File Statistics
======================================================
record type             # records    string file bytes
--------------------    ---------    -----------------
STRING (no overflow)          122                    0
STRING (overflow)               4                   61
CONFIG_REC                      0                    0
------------------------------------------------------
Bytes in use                                        61
STR_FREE                        0                    0
------------------------------------------------------
Total string file size (DB)                         61
Total string file size (OS)                        969
------------------------------------------------------
Max possible string file size      9223372036854775807
Longest free string length         9223372036854775746

Note the increased string file size and length is over 2GB with Schema 54.

About string_report output

The string_report output reports the output for particular sections in the string file:

STRING (no overflow)

String records that are stored in the VOB database files vob_db.d0*

STRING (overflow)

Strings that are stored in the string file (vob_db.str_file) and their size in bytes.

CONFIG_REC

The number of configuration records (created from clearmake, omake or clearaudit) and their related size in bytes stored in the string file (vob_db.str_file).

Bytes in use

The amount of space in bytes that is in use and not on the free list (STR_FREE) as represented in the database.

STR_FREE

The amount of free space or gaps in the *CURRENT* string size as represented in the database.

Total string file size (DB)

The size of the string file (sum of the Bytes in use and STR_FREE) as represented by the VOB database

Total string file size (OS)

The size of the string file (vob_db.str_file) in bytes as represented by the operating system.

Max possible string file size

The maximum possible size (in bytes) the string file (vob_db.str_file) can grow:

  • Schema 53: 2GB
  • Schema 54: >2GB (in terabytes)

Longest free string length

The maximum size a single string length can be recorded in the string file:

  • Schema 53: 2GB
  • Schema 54: >2GB (in terabytes)

 

 

STR_FREE

The STR_FREE value represents the open gaps in the string file that can be filled with data before the file becomes full; much the same way disk fragmentation is represented. As the STR_FREE value reaches 0, it will create a larger string as needed.

The following example output shows there are 491 records on the STR_FREE list with gaps that can be filled up to 3897720 bytes of space.

record type             # records    string file bytes
--------------------    ---------    -----------------
STRING (no overflow)       645291                    0
STRING (overflow)          155794            337278641
CONFIG_REC                 153517           1828301489
------------------------------------------------------
Bytes in use                                2165580130
STR_FREE                      491              3897720
------------------------------------------------------
Total string file size (DB)                 2169477850
Total string file size (OS)                 2169490634
------------------------------------------------------
Max possible string file size      9223372036854775807
Longest free string length         9223372034685285173

When the STR_FREE value reaches 0, the string file will become larger (as needed).

Note: In some cases the string file can grow before the STR_FREE value becomes 0. This can occur where the free gaps on the STR_FREE list are smaller than the information needing to be written to the string file.

Warnings & Errors

Below is a list of known warnings or errors that may be encountered either within the output or when executing the string_report utility.


***WARNING: No CONFIG_REC records found!!

The output of string_report may produce a waning that reports No CONFIG_REC records found (as seen in the example above). This warning is merely stating there are no config records found in the string file. Config records are only stored in the string file as a result of clearmake, omake or clearaudit builds.

If you are not using these utilities, there will never be config records stored in your string file, this the warning can be ignored.

If you are using one or more of these utilities

*** Can't find schema version file! ***

Attempts to run the string_report utility results in the error:

C:\ClearCase_Storage\VOBs\test_vob.vbs>string_report
*** Can't find schema version file! ***

This error occurs because the utility was not executed from within the db directory of the VOB.

Make sure you are set into the db directory of the VOB

38.  How do I – understand about rgy_upgrade

The utility rgy_upgrade is automatically run during an upgrade to 2003.06.14 or later to configure the ClearCase registry and VOB servers to support the new MultiSite synchronization manager and the MultiSite Administration WEB Console functionality.

Note: This utility will be available after installing
Service Release 4 (2003.06.14) or later on Windows® or patches multisite_p2003.06.00-6 or multisite_p2003.06.10-6 or later on UNIX® or Linux®.

When the rgy_upgrade utility is run on a registry and or VOB server the following actions are taken:

1.     If the host is a ClearCase Registry server and the MultiSite Administration WEB Console site name setting has not been set, rgy_upgrade sets the site name to <hostname>_site

If the host is a VOB server, for each VOB local to this host that does not already have a "replicated" attribute, it checks to see if the VOB is replicated and if so, the replicated attribute is set in the VOB object.

 

 

 

39.  How do I – understand about keybuild

The VOB's database is made up primarily of two main sets of files.

Keybuild is a tool that can be used to fix corruption in the key files if the data files are healthy. Running keybuild will completely re-create from scratch the key files based on the information in the data files.

As long as the data files are healthy, bad key files can be re-generated at any time by running keybuild. If it turns out that the data files also have a problem, running keybuild will cause damage to the key files as they will be rebuilt based on incorrect data. Further, the keybuild process may not be able to complete, also leaving the key files much worse off than they were before.

Note: Keybuild is related to reformatvob, in that some minor database corruptions can be fixed by running reformatvob, however sometimes the corruption actually blocks reformatvob from dumping the database. In these cases, running keybuild first will construct a minimal set of database keys that will allow the dump phase of reformatvob to proceed.

Keybuild should only be run when specified by a ClearCase Technical Support Engineer.

Keybuild is most often run based on errors from a dbcheck output. However, there is almost no dbcheck output that will guarantee a keybuild will fix a corrupt database. Determining if a keybuild should be run requires an understanding of the database structure and understanding of what the presented errors mean in order to make a judgment that a keybuild will likely fix a given problem.

KEYBUILD INSTRUCTIONS:

DISCLAIMER:

If keybuild is run inappropriately your VOB can be rendered unusable or irretrievably damaged; therefore, it is critical that a good back up the VOB is performed prior to following these steps.  Keybuild is NOT a preventive maintenance tool.  It is only run when something is very wrong with the database indexes and should only be run when instructed to do so by Rational Support.

It is important to understand that it is not possible for Rational to ensure that this will fix your corruption. Therefore, these instructions must be followed carefully so that you may recover if this fails.

1.     Stop ClearCase. If ClearCase must be running during the keybuild, you can untag and unregister the VOB, stop ClearCase and then start ClearCase.

2.     Copy the db directory. Make a copy of the db directory so that if the keybuild fails or does not work, we can revert to this copied version. This new copy is our backup. In the remaining steps, db directory refers to the original, not the new copy of the db.

Caution! This step is critical! If you run keybuild without making a backup and the issue is not resolved by the keybuild, a restore from backup tape (or mkreplica if using MultiSite) will be the only course of action as the database will now been damaged beyond repair.

Note: On Windows® for this step you will need to make sure that you copy the files in a way that will preserve the permissions of the files. We recommend using ccopy which can be found in
<clearcase-install>\etc\utils directory. A drag and drop from the GUI, or a DOS copy will not work.

3.     Copy the keybuild utility to the VOB db directory. This tool can be found in the <clearcase-install>\etc\utils directory (by default C:\Program Files\Rational\ClearCase\etc\utils).

4.     Run the keybuild utility. Open a command prompt and cd into the db directory. Run the following command:

keybuild vob_db

Note: The vob_db section is a literal string and should not be replaced. This command may take a while to run, do not attempt to access the VOB or run any other db commands.

5.     Start ClearCase. If you untagged and unregistered the VOB in step 1, you should register and tag it now.

6.     Reformat the VOB. Run the following command:

cleartool reformatvob <path-to-vbs>


If these steps are completed successfully and without errors, your VOB is now healthy.

If they did not complete or you received errors, restore the VOB from backup and report the problem to your Rational Technical Support immediately.

RESTORE INSTRUCTIONS:

1.     Stop ClearCase

2.     Move the existing db directory in the .vbs directory to a new location

3.     Copy the backed-up version from step 2 back into the .vbs directory
Note: Again on Windows, you will need to use ccopy or similar utility.

Start ClearCase.

40.  How do I - reprotect elements and metadata using vob_sidwalk on Windows

How to reprotect all associated IBM® Rational® ClearCase® objects in a VOB on Microsoft® Windows® where those objects were created by a wrong user and or group without the use of the cleartool protect command.

 

Cause

Under certain circumstances it may be necessary to reprotect several objects in a VOB at the same time and the running individual cleartool protect commands can be tedious, impractical or both.

Some of these situations could include (but are not limited to):

Reprotecting metadata type definitions and instances

 

Solution

In the event where all elements and metadata (labels, branches, attributes etc...) in a VOB is misprotected and needs to change to a different user and group in the same domain, the below procedure can be used:

Note: Use of the vob_sidwalk tool requires the VOB database schema be at 54.

1.     Lock the VOB

2.     Generate a SID file that lists the names of users and groups associated with objects in the VOB \libpub. Run vob_siddump as shown in the following example to generate a SID file in comma-separated-value (CSV) format:

C:\Program Files\Rational\ClearCase\etc\utils\vob_siddump \libpub C:\ClearCaseStorage\VOBs\libpub.vbs\libpub.csv

Hint: Create the SID file in the VOB storage directory so that it will be available on the new VOB host after the storage directory has been moved as you will need it for this procedure.

3.     Create a map file. Open the SID file you generated in Step number 2 of this procedure (\\ccsvr-new\vobstg\libpub.vbs\libpub.csv). Editing this file may be simplified if you use a spreadsheet program that can read the comma-separated-value format. This example shows one line of such a file. We've added a header row for clarity and truncated the SID string to save space.

For each line in the file, replace the string IGNORE in the New-name field with a string made up of the new domain name and the user name from the Old-name field; then delete the last three fields (Type, New-SID, and Count). In this example, old domain's name is OLD and the new domain's name is NEW, so the line would change as shown here:

OLD\akp,USER,NT:S-1-2-21-532...,NEW\akp

Although this example shows a user name that is the same in the old and new domains, the procedure can also be used to map a user or group name from the old domain to a different user or group name in the new domain. After you have edited all the rows of the SID file, save it as a comma-separated-value file and use it as the mapping file required when you run vob_sidwalk -map. Each line of the mapping file must have exactly four fields, separated by commas.

Note: You may reassign ownership of any object in a VOB to the VOB owner by placing the string DELETE in the New-name field. You may also reassign ownership of all objects in a VOB to the VOB owner without creating a mapping file. See Reassigning Ownership to the VOB in the ClearCase Administrators manual.

4.     Test the map file. Run vob_sidwalk without the -execute option. (The list of mappings prescribed by the map file libpub-map.csv is written to the SID file (libpub-test.csv in this example), but no changes are made to the VOB.)

C:\Program Files\Rational\ClearCase\etc\utils\vob_sidwalk -map \\ccsvr-new\vobstg\libpub.vbs\libpub-map.csv \libpub libpub-test.csv

5.     Unlock the VOB

6.     Update user and group identities stored in the VOB. When you are satisfied that the map file is correct, run vob_sidwalk as shown in the following example, where libpub-map.csv is the map file you created in step number 3 of this procedure:

C:\Program Files\Rational\ClearCase\etc\utils\vob_sidwalk -execute -map \\ccsvr-new\vobstg\libpub.vbs\libpub-map.csv \libpub libpub-exec.csv

vob_sidwalk remaps ownership as specified in the map file and records the
changes that were made in libpub-exec.csv.

 

Review the related information section on how this procedure impacts a ClearCase MultiSite environment.

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

Permissions

41.  How do I – understand the protection commands and utilities used with ClearCase

 

Utilities for Finding and Fixing Protection Problems

Rational ClearCase includes three utility programs for finding and fixing VOB and view storage directory protection problems:

fix_prot (utility, located in <clearcase home>/etc/utils)
This utility affects the file system objects (for example the source containers) of a view or VOB. The fix_prot utility actually adjusts the Microsoft® Windows® permissions (ACL's) and the UNIX® or Linux® permissions to the .vbs directory in a way that ClearCase can understand.

More information can be found in the IBM Rational ClearCase Administrator's Guide in the Troubleshooting section.


Example syntax can be seen in
technote 1142606.

vob_sidwalk (utility, located in the <clearcase home>/etc/utils directory)
This utility fixes storage directory protections for schema version 54 VOBs. It can also be used to change ownership on VOB objects.

Review the ClearCase Command Reference Guide on the topic of vob_sidwalk (
cleartool man vob_sidwalk) for more information.


Example syntax can be seen in
technote 1256390.

lsacl (utility, located in the <clearcase home>/etc/utils directory)
This utility (Windows only) displays NTFS ACLs for file system objects.

More information can be found in the Administrator's Guide in the Troubleshooting section.

Cleartool Commands for Fixing Protection Problems

The ClearCase cleartool command includes three subcommands fixing VOB storage and VOB object protection problems:
protectvob (cleartool subcommand, run as "cleartool protectvob")
The protectvob command manages the ownership and group membership of the files and directories in a VOB, by changing the OS-level permissions on files and directories within the VOB storage area.

Review the ClearCase Command Reference Guide on the topic of protectvob (
cleartool man protectvob) for more information.

protect (cleartool subcommand, run as "cleartool protect")
The protect command sets the owner, group, or permissions for elements, shared derived objects, or VOB objects which are maintained in the VOB database.

The main use of protect is to control access by standard programs to an element or object's data. For example, you can make some elements readable by anyone and make others readable by only their group members.

Review the ClearCase Command Reference Guide on the topic of protect (
cleartool man protect) for more information.


checkvob (cleartool subcommand, run as "cleartool checkvob")
The checkvob command looks for inconsistencies within and between VOBs. It can find and fix problems with storage pools, hyperlinks, and global types in an administrative VOB hierarchy. Checkvob can also find and fix inconsistencies between PVOBs, components, and an optional ClearQuest database in a UCM environment.

Review the ClearCase Command Reference Guide on the topic of checkvob (
cleartool man checkvob) for more information.

Common scenarios: Checking the condition of a VOB on a server that crashed; double-checking after restoring a VOB from backup.

42.  How do I – use the Fix_prot utility

This technote explains how to run the IBM® Rational® ClearCase® utility fix_prot to reprotect Windows® ACLs on VOB and view storage as well as adjust file and group ownership on VOB and view storage on UNIX®.

 

Usage: fix_prot [-force]
{ -root [-r[ecurse]]
[{-recover | -chown login-name -chgrp group-name}]
| -replace[_server_process_group]
| [-r[ecurse] [-type { d | f }]]
[-chown login-name] [-chgrp group-name] [-chmod permissions]
} pname ...

For more information on fix_prot and its usage, refer to the IBM Rational ClearCase Administrators Guide.

Note: It is recommended that ClearCase services on Windows be shut down prior to running the fix_prot utility. This will ensure that no files are held open by ClearCase processes which otherwise could be skipped during the execution of the utility.

The proper syntax and process for running fix_prot is as follows:

1.     Open a command prompt.

2.     Change directory to the <CCHOME>\etc\utils and issue the following commands in order indicating the appropriate pathnames for the operating system on which you are running the command.

(Where: <CCHOME> is the home directory where ClearCase is installed.

UNIX and Linux: /usr/atria/ or /opt/rational/clearcase

Windows: C:\Program Files\Rational\ClearCase

Note: The fix_prot command will need to be executed twice if the -chmod option and the -root options need to be run.

·         %> fix_prot -r -chown <owner name> -chgrp <primary group> -chmod 775 <Path to VOB/View storage>

·         %> fix_prot -root -chown <owner name> -chgrp <primary group> <Path to VOB/View storage>

 

Note: If not using the -chmod switch, run the fix_prot command with both the -r and -root options as indicated below:

Note: If only using one of the switches (-chown, -chgrp, -chmod), then you must run the fix_prot command with only the -r or the -root options as indicated below:

 

Note: Windows Only. If the ClearCase administrators group name has changed or you have moved a view to a new domain that has a different SID for this group, then the -replace_server_process switch is required.

Note: Windows Only. Fix_prot can be run on schema 53 and 54 VOBs with one exception. The -recover switch can only be used on schema 53 VOBs. The functionality of this Windows only switch restores correct file system ACLs in a VOB or view storage directory based on the information in the identity.sd and groups.sd files. It is not applicable to schema version 54 VOBs because vob_sidwalk –recover_filesystem performs this function.

Note: There are unknown problems that can occur when changing ACLs on a file system remotely, so it is recommended that you run the fix_prot utility directly from the VOB/View server itself and not through a remote connection.

43.  How do I – understand about the creds utility

About the creds utility

The ClearCase creds utility displays user and group information for the currently logged-in user account on the local Windows host. This utility is generally used to determine credentials with regard to ClearCase use and troubleshooting permission related problems.

Note: The creds utility is located, by default, in C:\Program Files\Rational\ClearCase\etc\utils. This path is not included in the system PATH environment variable. You can add the path to the system PATH EV, or you will need to change directory (cd) into the directory where creds is located.

The available options for creds usage can be listed out using creds -h.

Usage

Description

creds [-w]

Display current user's SID credentials.

creds {-a|-A}

Display all information in current user's access token.

creds -u [-w]

Display current user's UNIX style credentials.

creds -r

Display current user's credentials in raw SID form.

creds {-p|-P} <pid>

Display all information in the target process's access token.

creds [-u|-r] <user>

Display information about specified user; user can be given as a name, integer UID, NT SID ("S-..."), or ClearCase SID ("NT:S-...","UNIX:10...","SID:01..."). Optional machine name causes lookup to be done on the specified machine.

creds [-u|-r] -g <group>

Display information about specified group; group can be given as a name, integer GID, NT SID ("S-..."), or ClearCase SID ("NT:S-...","UNIX:10...","SID:01..."). Optional machine name causes lookup to be done on the specified machine.

creds -s <pid>

Set the primary group in the target process's access token based on CLEARCASE_PRIMARY_GROUP.

creds -t

Update and print the cached trusted POSIX offset table.

creds -e

Display standard SIDs.

creds -d <host>

Display whether named host is in same domain as current host.

creds -x <ID>

Convert the ID, which can be a SID or an integer UID/GID to an integer
UID/GID or SID (i.e., the other kind of ID) without regard to the validity of the ID.

creds -c <user>

Display credentials of specified user; user can be given as a fully-qualified name.

creds -D

Dump the cached pwd/grp tables.


Example of most basic creds output used for troubleshooting a user account:

>creds
Login name:    DOMAIN\User1
USID:          NT:S-1-5-21-14...
Primary group: DOMAIN\CC_USERS_GROUP (NT:S-1-5-21-14...)
Groups: (10)
    Everyone (NT:S-1...)
    BUILTIN\Administrators (NT:S-1...)
    BUILTIN\Remote Desktop Users (NT:S-1...)
    BUILTIN\Users (NT:S-1...)
    NT AUTHORITY\REMOTE INTERACTIVE LOGON (NT:S-1...)
    NT AUTHORITY\INTERACTIVE (NT:S-1...)
    NT AUTHORITY\Authenticated Users (NT:S-1...)
    LOCAL (NT:S-1...)
    DOMAIN\Domain Users (NT:S-1-5-21-14...)
    DOMAIN\clearcase (NT:S-1-5-21-14...)


You have ClearCase administrative privileges.


For more information on the creds utility, from command line, use
cleartool man creds, or see the IBM Rational ClearCase Command Reference.

 

Creds output showing group names twice

Sometimes creds output lists the domain groups twice with separate SID's.

*************************
C:\Rational\clearcase\etc\utils>creds
Login name:    DOMAIN1\xjrb7751
USID:          NT:S-1-5-21-2025429265-1303643608-1417001333-20032
Primary group: DOMAIN1\cmccs (NT:S-1-5-21-2091331072-1406801349-277364198-33363)
Groups: (32)
DOMAIN1\clearusers (NT:S-1-5-21-2091331072-1406801349-277364198-32837)
DOMAIN1\clearusers (NT:S-1-5-21-2025429265-1303643608-1417001333-1275)
DOMAIN1\SMS_CDG_TechSup (NT:S-1-5-21-2025429265-1303643608-1417001333-2182)
DOMAIN1\CMU (NT:S-1-5-21-2025429265-1303643608-1417001333-1283)
DOMAIN1\S3USER (NT:S-1-5-21-2025429265-1303643608-1417001333-2163)
DOMAIN1\S3USER (NT:S-1-5-21-2091331072-1406801349-277364198-1558)
DOMAIN1\SMS_CDG_TechSup (NT:S-1-5-21-2091331072-1406801349-277364198-32804)
DOMAIN1\CMU (NT:S-1-5-21-2091331072-1406801349-277364198-36480)
...

You have ClearCase administrative privileges.
****************************

This means your site is in the process of migrating groups from an NT domain to an Active Directory domain.

If the migrated accounts include SID history, user accounts in the Active Directory domain include twice as many group memberships as they have in the Windows NT domain. Each user's group list includes groups from both domains. Users who are members of multiple groups in a Windows NT domain may find that their group list includes more than 32 groups after migration. Review
technote 1124574 for more information about the CLEARCASE_GROUPS environment variable.

Refer to the ClearCase Administrators Guide for additional information on Active Directory Migration.

Note: As of version 2003.06.00, the OLD Domain entry will have a leading asterisk:

Login name:    DOM1\user1
USID:          NT:S-1-5-21-827945181-191126496-1124750213-4883
Primary group: DOM1\CC_Users (NT:S-1-5-21-827945181-191126496-1124750213-4962)
Groups: (25)
    DOM1\Domain Users (NT:S-1-5-21-827945181-191126496-1124750213-513)
    Everyone (NT:S-1-1-0)
    WREN\PD Developers (NT:S-1-5-21-436374069-507921405-839522115-1007)
    WREN\PD Team (NT:S-1-5-21-436374069-507921405-839522115-1004)
    BUILTIN\Administrators (NT:S-1-5-32-544)
    BUILTIN\Users (NT:S-1-5-32-545)
    NT AUTHORITY\INTERACTIVE (NT:S-1-5-4)
    NT AUTHORITY\Authenticated Users (NT:S-1-5-11)
    LOCAL (NT:S-1-2-0)
    DOM1\Product Development (NT:S-1-5-21-827945181-191126496-1124750213-5007)
    DOM1\Clear Case Admins (NT:S-1-5-21-827945181-191126496-1124750213-4963)
    DOM1\CMDS Associates (NT:S-1-5-21-827945181-191126496-1124750213-4965)
    DOM1\All CMDSers (NT:S-1-5-21-827945181-191126496-1124750213-4321)
    DOM1\Development-2 (NT:S-1-5-21-827945181-191126496-1124750213-4331)
    DOM1\TE Prog (NT:S-1-5-21-827945181-191126496-1124750213-4174)
    DOM1\HFD-Tech Staff (NT:S-1-5-21-827945181-191126496-1124750213-3899)
    DOM1\CC_Users (NT:S-1-5-21-2109960903-705956611-641664369-2902)
* DOM1\user1 (NT:S-1-5-21-2109960903-705956611-641664369-3172)
 DOM1\Clear Case Admins (NT:S-1-5-21-2109960903-705956611-641664369-2207)
    DOM1\Product Development (NT:S-1-5-21-2109960903-705956611-641664369-1252)
    DOM1\CMDS Associates (NT:S-1-5-21-2109960903-705956611-641664369-1018)
    DOM1\DOM1 Associates (NT:S-1-5-21-827945181-191126496-1124750213-4986)
    DOM1\PD - Local (NT:S-1-5-21-827945181-191126496-1124750213-4997)
    DOM1\DOM1 Associates (NT:S-1-5-21-2109960903-705956611-641664369-2841)
    DOM1\PD - Local (NT:S-1-5-21-2109960903-705956611-641664369-2861)

You have ClearCase administrative privileges.
You are logged onto Administrative-mode Terminal Server (Console).

 

How to use creds -t to determine if a domain is trusted
The creds -t output is specific to the domain to which the workstation resides. Log in to any available domain and the output will be the same per workstation because it can only belong to one domain.

Example of a one way trust, where Domain1 trusts Domain2, but Domain2 does not trust Domain1:


C:\Program Files\Rational\ClearCase\etc\utils>creds -t
Name             Offset       SID
LAB              0x01900000  S-1-5-21-1518097302-
DOMAIN2        0x01100000  S-1-5-21-1453292567-
NT01            0x01f00000  S-1-5-21-1186989896-
ATRIA           0x00f00000  S-1-5-21-108034363-
XERRA           0x02500000  S-1-5-21-1055335994-
CCSUPPT          0x01b00000  S-1-5-21-101735466-
TEST_DOMAIN      0x02600000  S-1-5-21-790525478-
WORKDOMAIN      0x02b00000  S-1-5-21-1644491937-

Note: DOMAIN 2 appears in the output because DOMAIN 1 trusts DOMAIN 2.


C:\Program Files\Rational\ClearCase\etc\utils>creds -t
Name             Offset       SID
DISOCOVERY        0x01500000  S-1-5-21-1776094891-57206
COOP              0x00b00000  S-1-5-21-1581937804-37220
ATRIA           0x01700000  S-1-5-21-108034363-981813

Note: DOMAIN 1 does not appear in the output because DOMAIN 2 does not trust DOMAIN 1.

 

How to use creds -D to view cached data

The ClearCase creds command maintains a cache in memory that has a list of mappings that map, for example, a SID to a UID, or a UID to the information stored in the domain controller.

Here is a list of the specific mappings creds maintains:

1.     UID  ->  Passwd info

2.     User name  ->  Passwd info

3.     SID  ->  Passwd info

4.     GID  ->  Group info

5.     Group name  ->  Group info

6.     SID  ->  Group info

7.     Account name  ->  SID

8.     Account name  ->  SID

9.     SID  ->  UID

10.  Domain group SID map

11.  SID  ->  TPO

12.  TPO  ->  SID

Sometimes groups changes are made but are not picked up by the creds command. Why? For example, the current logged on user is added to ClearCase Administrator group, but creds still shows that the user does not have ClearCase administrative privilege. This has to do with the cache. The current login session still keeps the old creds information until the user has logged off or the host is restarted.

From the usage output,
creds -D will dump the cached password and group tables for accounts logged onto the local system for ClearCase use. This output cannot be scaled down by account, which means the output will include, at least, information for your user account and the clearcase_albd account.

Since this information is cached, if your SID or other information changes, such as your account is added to a new group, then this cache needs to be refreshed also to reflect the change. This can be done manually using
phash -f global and phash -f private (which is an undocumented utility) or creds will automatically check the cache for stale entries the next time it is run.

usage: phash {-s | -f [global | private]}

        -s : to display cache hit/usage statistics
        -f : to flush the cache (default private)

Note: The phash utility is located, by default, in
C:\Program Files\Rational\ClearCase\etc\utils.

1.2.       How do I – understand why "NT" -type SID is not supported by credmap_server

Users may experience one or more of the following symptoms:

1.     At the time of the operation (checkout, deliver, etc.) the view log reports errors like the following:

Error checking out 'Z:\myvob\source\code\index.html'.
"NT" -type SID is not supported by credmap_server
"NT" -type SID is not supported by credmap_server
"NT" -type SID is not supported by credmap_server
"NT" -type SID is not supported by credmap_server
No permission to perform operation "checkout".
Must be one of: member of element group, element owner, VOB owner, member of ClearCase® group.
Unable to check out "Z:\myvob\source\code\index.html".

2.     A cleartool describe -long of the element from the Windows side displays the Owner or Group in SID format rather than a Domain qualified account or group.

Example:
Z:\mac>cleartool describe -l xyz.txt
version "xyz.txt@@\main\4"
 created 15-Oct-03.15:23:26 by user1.user@myhost
 Element Protection:
   User :  NT:S-1-5-21-141845252-1443263951-584457872-2202 : r--
   Group: DOMAIN\user : r--
   Other:          : r--
 element type: text_file
 predecessor version: \main\3

3.     A cleartool dump -long of the element from the Windows side includes the error message among the data it displays

4.     A cleartool describe -long of the element from the Unix or Linux side shows the element owner or group either as Unknown or in raw sid format of the corresponding Windows account/group.

Example:
3.010500000000000500000015569x7c1762146bd12175403300003d89

A vob_siddump of the VOB from the Unix or Linux side lists an account or group as unknown and displays the raw SID of the corresponding Windows user account/group.

Example:
Account Unknown,USER,SID:3.010500000000000500000015569x7c1762146bd12175403300003d89,IGNORE,,,60

 

Cause

This error typically occurs in an interop environment when one or more elements or pieces of metadata are owned by a Unix or Linux account(s) that no longer exists.

 

Resolving the problem

First ensure that the cross-platform product (NFS/SMB) that you are using is properly configured for ClearCase.
Review the ClearCase Administrators Guide on the topic of
Configuring cross-platform file-system access for further information.

Then run a cleartool describe on the element (for example, cleartool describe <element-name>) to see if the element owner is showing a valid user. If the output is showing a Windows domain SID value rather than a valid userid, try changing the elements protections to a valid userid (eg. cleartool protect -chown <newuser> <element-name>) and then retry the checkout.

The above resolution will help resolve the issue for one element, however, if the Unknown account or group owns other elements or metadata, the error will eventually occur again.

To avoid further occurrences, run vob_siddump to get a listing of the objects that may be impacted. Then you can run vob_sidwalk to change the owner/group to a valid entry.


Refer to
technote 1256390 Supplement to the Command Reference Guide on vob_sidwalk and vob_siddump for more information.

xclearcase

44.  How do I - change the font size of xclearcase

The ClearCase graphical user interface (GUI), xclearcase, works as a standard Xwindows mechanism; therefore, you can control its appearance by setting the Xwindows properties through your .Xdefaults file on UNIX or the .Xresources file Linux both located in your HOME directory.

For example, you can add the following line to the .Xdefaults/.Xresources file to change the font size within xclearcase:

xclearcase*fontList: 9x15

As the .Xdefaults/.Xresources file is read each time an Xwindows application is launched, changes made to the file are immediately applied when you run the command xclearcase.

Note: If the change does not take affect, restart Xwindows.

From a ClearCase user's point of view, the above solution is the most simple and quickest one, but will only apply to this particular user.

Your ClearCase administrator should be aware of ClearCase Schemes, which enables you to make general appearance changes within the ClearCase GUI applications.

The Scheme files are collections of Xwindows system resource settings that control the geometry, colors, and fonts used by GUI applications. By default, ClearCase and ClearCase LT® do not enable schemes. Instead, the GUI applications use the settings that your Common Desktop Environment (CDE) specifies. However, you can enable schemes and use the ClearCase and ClearCase LT schemes mechanism by adding the following resource to your .Xdefaults/.Xresources file:

*useSchemes: all


Refer to the ClearCase Reference Guide schemes entry for more detailed information by running the cleartool man schemes command.

45.  How do I - view the commands that were executed by xclearcase

In order to see a transcript of the commands xclearcase executes when buttons are pushed or menu items are selected, you must set the CLEARCASE_DBG_GRP environment variable to something other than 0 (1 for instance will suffice).

Then start the GUI.

Note: You may have to turn on the transcript window in xclearcase (File > Show Transcript) and scroll back in the transcript window to see the command lines. The rest of the output refers to the pname (path name) of the actual script which was executed.

 

Example:

Set the environment variable according to your shell syntax.
In this example, the BASH shell is used.

% env | grep SHELL
% SHELL=/bin/bash
 
% CLEARCASE_DBG_GRP=1

% export CLEARCASE_DBG_GRP

Note: You may have to turn on the transcript window in xclearcase (File > Show Transcript) and scroll back in the transcript window to see the command lines. The rest of the output refers to the pname (path name) of the actual script which was executed

46.  How do I - specify colours for xclearcase

This technote explains how to specify colors within the IBM® Rational® ClearCase® xclearcase GUI on UNIX® and Linux®.

 

To specify colors xclearcase takes the following arguments:

-bg = background colors

-fg = foreground colors.

The colors can be specified by name or by RGB values, as explained in the man pages for X:

black             rgb:0/0/0
red               rgb:ffff/0/0
green             rgb:0/ffff/0
blue              rgb:0/0/ffff
yellow            rgb:ffff/ffff/0
magenta           rgb:ffff/0/ffff
cyan              rgb:0/ffff/ffff
white             rgb:ffff/ffff/ffff

Example:

$ xclearcase -bg wheat -fg black

47.  How do I – understand about clearvobadmin, cleardescribe and cleargetlog on UNIX and Linux

The clearvobadmin, cleardescribe and cleargetlog GUIs have been deprecated on UNIX and Linux due their dependencies on third party libraries, such as Galaxy, which IBM Rational is no longer authorized to ship (with Rational ClearCase) as of ClearCase version 7.0.

Note: ClearCase 2003.06.00 for Linux on IBM S/390 also has the clearvobadmin, cleardescribe and cleargetlog GUIs removed.

 

Review the IBM Rational ClearCase and ClearCase MultiSite Release Notes, 7.0, Windows, UNIX, Linux (GI11-6367-00) for more information on the additional commands that have been obsoleted in the 7.0 release.

Report Builder

48.  How do I - run the report builder from the command line

Any report can be run from the command line.


The reports are generated using ccperl scripts, thus the scripts can be called from the command line using ccperl syntax.

The report scripts are stored in the following location:

C:\Program Files\Rational\ClearCase\reports\scripts

The first step is to run the report with the -i option to obtain the necessary parameters. Invoking the scripts using the -i option tells the report to "dump its command line interface".

Example: Running the Elements Created by User report

C:\>ccperl "C:\Program Files\Rational\ClearCase\reports\scripts\elements\Elements_Created_
by_User.prl" -i
description : "Elements Created by User"
id : 2016
helpfile :
parameters : LOOKIN USER
rightclick : Properties_of_Element(single) sep Version_Tree(single) History(single)
fields : "Element Path"(element_xpn, sort 2, rightclick) "Creating User"(user, sort 1)

Note: It is important to invoke the script with its path as some code can strip the path off. To shorten the command, you could define an environment variable:

set mypath=C:\Program Files\Rational\ClearCase\reports\scripts
ccperl "%mypath%\Elements_Created_by_User.prl" -i


IMPORTANT: Quotes are not used in the set command but they are used in the ccperl command.

This will report that two arguments: LOOKIN and USER must be supplied.

The output for Elements_Created_by_User.prl looks like this:

description : "Elements Created by User"
id : 2016
helpfile :
parameters : LOOKIN USER
rightclick : Properties_of_Element(single) sep Version_Tree(single) History(single)
fields : "Element Path"(element_xpn, sort 2, rightclick) "Creating User"(user, sort 1)


In this example, the LOOKIN and USER parameters are specified.

Note: These are the two arguments that the Report Builder GUI would prompt for.


To continue with this example, LOOKIN wants a VOB directory path, and USER wants a username for the Elements_Created_by_User.prl report.

It is important to understand what the script needs to complete and provide that information when prompted.


HINT:
Run the Report from the GUI to see what the report wants as input.


Once the parameters are obtained and defined, run the report as follows:

C:\>ccperl "C:\Program Files\Rational\ClearCase\reports\scripts\elements\Elements_Created_
by_User.prl" LOOKIN=\"m:\dynamic_view\\test_vob\";USER=jdoe

Note: The -i switch is no longer used as the arguments are fed directly in the command.


Considerations:

 

Once executed, the ccperl script report will run, and dump out the result fields to the standard output.

Example:

C:\>ccperl "C:\Program Files\Rational\ClearCase\reports\scripts\elements\Elements_Created_
by_User.prl" LOOKIN=\"m:\dynamic_view\\test_vob\";USER=jdoe
m:\dynamic_view\\test_vob;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\autorun.inf;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\banner.bmp;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\dlmgr.pro;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\doc;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\libatriagu.dll;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\mfc42.dll;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\miniBom.xml;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\resdll;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\SETUP;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\setup.exe;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\SITEPREP;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\siteprep.exe;jdoe;
m:\dynamic_view\\test_vob\DownloadDirector\suite.ico;jdoe;
m:\dynamic_view\\test_vob\file.txt;jdoe;
m:\dynamic_view\\test_vob\foo.doc;jdoe;
m:\dynamic_view\\test_vob\Foo.doc;jdoe;

The fields will be separated by semicolons.

Note: The fields were defined in the -i output above.


This method of running reports can be added into a batch job (*.BAT file) where parameters can be passed.

The output can also be redirected into a file.


You can also review the save_results.prl script located in

C:\Program Files\Rational\ClearCase\reports\script_tools.


This is the script used by the GUI to write out results to either HTML or CSV.

Finally if you have any issues and want to terminate a session, hit <Ctrl C>.

 

Example:

</