---

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 UCM “How do I” covers: (Last updated 11-Nov-09)

Ø Projects - adding components to, etc...

Ø Components – creating rootles components, copy between, removing, etc...

Ø Baselines – creating identical, removing member baseline, etc...

Ø Activities – determining dependent, dependencies, tec...

Ø Steams – issues, prevent user creating, etc...

Ø Derived Objects – UCM and , etc...

Ø Techniques – removing object, elements, etc

Ø Troubleshooting – template, ucmutil, etc...

Table of Contents

ClearCase UCM “How do I” covers: (Last updated 11-Nov-09) 1

Table of Contents. 1

Projects. 2

1. How do I - add a component to a UCM project 2

2. How do I - change Mastership for a UCM Project 6

3. How do I - convert an AdminVOB to a UCM Project VOB.. 7

4. How do I - rename a UCM project from CLI or GUI 7

Components. 11

5. How do I - copy elements between UCM components. 11

7. How do I - create a Rootless Component from Command Line. 12

8. How do I - remove components from a Project after the VOB has been removed. 13

9. How do I – understand why the root of a Multi-Component VOB is read-only in a UCM view.. 13

10. How do I - create a component in a VOB.. 14

11. How do I - import an existing subdirectory as a UCM component 17

12. How do I – understand why the root of a Multi-Component VOB is read-only in a UCM view.. 18

13. How do I – understand about the number of modifiable components and performance. 19

14. How do I – understand why th component root directory in a Multiple Component VOB cannot be renamed 19

Baselines. 20

15. How do I - remove and recreate UCM baselines. 20

16. How do I - create an identical baseline in UCM... 21

17. How do I - remove a member baseline of a composite baseline. 22

18. How do I – understand symbol definitions of -> and >> when diffing UCM baselines. 24

19. How do I – understand about No version to label 24

20. How do I – understand the cannot rebase a non-modifiable component after creating a new baseline with the -identical option issue. 24

21. How do I – gather the recommended baselines of all ClearCase UCM projects. 25

22. How do I – understand the “Not able to recommend baselines after enabling UCM policies” issue. 26

23. How do I – understand about UCM baseline types. 26

24. How do I – understand who has rebased to the new baseline. 27

Activities. 28

25. How do I - determin dependent UCM activities in ClearCase. 28

26. How do I – understand why UCM selects activities as dependencies that are not related to the current deliver operation 29

27. How do I – list the contributing activities in the change set of a baseline or an integration activity. 29

28. How do I – resolve the unable to perform operation change activity in replica issue. 32

29. How do I - move a UCM version in a change set from one activity to another. 33

30. How do I - determine the view association of a UCM Activity from the command line. 35

31. How do I - list which activity your view is currently set to when using ClearCase and ClearQuest 36

32. How do I – understand the Version from the activity is missing from the required version list issue. 36

Activity is already set in view... 37

Streams. 38

33. How do I – understand the cannot set default deliver target of a non-integration stream issue. 38

34. How do I - prevent users from creating a new UCM stream.. 38

35. How do I – understand the do not allow deliver to proceed with checkouts in the stream issue. 38

36. How do I – understand that after renaming an UCM stream, the old name still appears in the ClearQuest record 39

37. How do I - Rebase a UCM stream from ClearCase Explorer may not use the currently-selected view.. 39

38. How do I – resolve streams not appearing in the component for the baseline browser. 40

39. How do I – understand deliver operation already in progress on stream.. 40

Derived Objects.. 41

40. How do I – understand about site wide settings for shareable derived objects and UCM Integration views 41

Techniques. 43

41. How do I – remove objects in UCM environments. 43

42. How do I - remove an entire UCM environment 45

43. How do I - remove elements in UCM... 46

44. How do I – renaming UCM Objects. 46

45. How do I - trac ing the UCM integration with ClearQuest on UNIX or Linux. 47

46. How do I - complete a posted UCM deliver. 47

47. How do I - initiate a UCM Delivery from the ClearCase Explorer. 48

48. How do I - find UCM posted deliveries. 48

49. How do I - determine which projects are associated with a specific UCM component 50

50. How do I - display the record ID from the command line when using the UCM or Base ClearCase and ClearQuest integration 51

51. How do I - avoid ClearQuest Change Request/Activity prompts during file import in UCM using clearfsimport 52

52. How do I – understand about UCM Config Specs. 54

Troubleshooting.. 55

53. How do I – use the ClearCase UCM troubleshooting template. 55

54. How do I – understand about ucmutil 56

55. How do I – understand why a Deliver or Rebase fails while merging file elements. 58

56. How do I – understand the Unable to resolve VOB symlink issue. 58

57. How do I – understand why a rebase fails when trying to remove a component from the integration stream configuration 59

58. How do I – understand the explanation of .contrib files left for every version just delivered in UCM... 60

Projects

1. How do I - add a component to a UCM project

Over the duration of a Project's Lifecycle, it is expected that the scope of your project typically broadens, and you may need to add components.

Note: There is no predefined limit to the number of components that can be added to a single UCM project.

The steps for adding a component to a UCM Project:

1. Add the component to the integration stream's configuration

2. (Optionally) Make the component modifiable. By default, the component is added to the project as read-only, which is ideal for shared resources, such as libraries.

3. Synchronize the integration view with the stream’s new configuration

4. Recommend a Baseline for the new Component and Rebase the child stream, see below for details

5. Synchronize child streams with the project’s new set of modifiable components

6. Synchronize the child stream’s view with the stream’s new configuration

7. Update the snapshot view load rules to include the component that you added to the stream, if applicable

These instructions are in IBM Rational ClearCase Managing Software Projects > Managing the Project > Adding Components.

Note: The directions for recommending a baseline and rebasing a child stream have been documented below; follow the sequence of steps for this procedure as numbered above.

Recommend a Baseline for the new Component

You can recommend a baseline for the new component that is in the current stream or its foundation.

To manage the baseline that the child streams rebase to, it is advised to recommend a baseline. In the case where a new component is added to a project, the recommended baseline will usually be the baseline that was added to the integration stream's foundation. However, if a new baseline is created in this project, after the component is added, then that baseline should be recommended; such as if data is imported into the component after it is added to the project.

1. From Project Explorer > right-click the integration stream > select Recommend Baselines... and the following dialogue will open:



2. Click Add > select the Component > select the baseline to Recommend > click OK:



3. The Recommend Baselines window will update with the new baseline > click OK:



3. After recommending the new baseline, you can now proceed to Rebase the Child Stream.

The directions for adding a baseline to the list of baselines that are recommended in the project are detailed in IBM Rational ClearCase Managing Software Projects > Managing the Project > Recommending the Baseline.

Rebase the Child Stream
Note: These directions are assuming that the rebase will only detect the recommended baseline for the new component. If other changes are included in the rebase, then you may want to use the Advanced button to only select the recommended baseline for the new component.

1. To rebase a child stream to the new baseline , from Project Explorer > right-click the stream > select Rebase Stream, and the following dialogue will open, click OK:



2. You will be prompted with an informational dialogue, you can just click OK:



3. You will be prompted to complete the Rebase, be sure to click Complete:



4. When the child stream rebases, it will pick up the recommended baseline for the new component, which will update it's configuration. After the rebase is completed, you will then need to continue with the steps as outlined above:

• Synchronize child streams with the project’s new set of modifiable components
• Synchronize the child stream’s view with the stream’s new configuration
• Update the snapshot view load rules to include the component that you added to the stream, if applicable

The directions for rebasing a stream are found in IBM Rational ClearCase Developing Software > Starting the Rebase Operation.

Removing a UCM Component

• Currently, there is no functionality that will allow you to remove a component after it has been in use in a UCM Project, refer to technote 1178234 for more details.

If a component has never been used (it is empty), then it can be removed, refer to IBM Rational ClearCase Managing Software Projects > Managing the Project > Removing Unused Objects.

2. How do I - change Mastership for a UCM Project

How do I change mastership of an IBM® Rational® ClearCase® UCM project that is replicated from one site to another using MultiSite®?

To change the mastership of a UCM Project from one site to another, the following objects needs to have mastership transferred:

PROJECT

Change mastership of the Project:

Example :
multitool chmaster dest_replica project:project_name@\pvob

STREAM

Change mastership of any stream objects used at the remote site:

Example:
multitool chmaster -stream dest_replica stream:stream_name@\pvob

Note: Changing mastership of the Stream objects will not change the mastership of the Baseline hyperlinks associated with those streams.

HYPERLINK
Change mastership of the UseBaseline hyperlink:

Example:
multitool chmaster siteB@/vobs/pvob hlink:UseBaseline@19@/vobs/pvob

IMPORTANT: There is no automated way to completely transfer the mastership of all the branch types when you change mastership of the stream.

Note: You can get the UseBaseline hyperlink and Branch type information by performing a cleartool describe -long on each stream.

BRANCH TYPE
Change mastership of the branch type associated with the stream.

Example:
multitool chmaster dest-replica brtype:branch1

RATIONAL CLEARQUEST®
Please review technote 1237806 for information about changes to project mastership. ClearCase does not automatically change mastership of the project in Rational ClearQuest when ClearCase ClearQuest UCM and MultiSite are integrated.

3. How do I - convert an AdminVOB to a UCM Project VOB

It is not possible to convert an existing Admin VOB to a UCM Project VOB.

This is expected behavior.

An Admin VOB in base ClearCase is a normal VOB containing only the lost+found directory.

A UCM Project VOB is a special VOB containing the lost+found directory as well as a processes directory. It is this directory that contains the UCM data files.

Since the directory structure is created differently, it is impossible to convert.

WORKAROUND:

Create a new UCM Project VOB and use the existing Admin VOB as the Administrative VOB for the Project VOB.

Example:

Admin VOB --->  Project VOB  ---> Component

4. How do I - rename a UCM project from CLI or GUI

A ClearCase UCM stream can be renamed using CLI or GUI functionality.

Note: If ClearCase MultiSite is in use, then the local site must have mastership to rename the project, and the change must be synched to propagate to the other replicas.

CLI:

1. Open a command prompt (click Start > Run and type cmd).

2. It is not required to set to a view context to execute the following command syntax successfully:

cleartool rename project:<project selector>@\PVOB project:<new project name>@\PVOB

Example:

C:\>cleartool rename project:project1@\pvob1 project:proj1@\pvob1
Renamed project from "project" to "proj1".

Notes:

· If you specify the wrong stream name or do not use the correct case in the name, the following error will occur:

C:\>cleartool rename project:Project1@\pvob1 project:prj1@\pvob1
cleartool: Error: stream not found: "Project1".

· You will receive the following error if a name with a space is used or if the command syntax is not used explicitly as shown above:

C:\>cleartool rename project:project1@\pvob1 proj1@\pvob1
cleartool: Error: The name has illegal characters.

For more information on the cleartool rename command, refer to IBM Rational ClearCase Command Reference, or run cleartool man rename.


GUI:

1. Open ClearCase Project Explorer (Exploring ClearCase Projects) from the Rational ClearCase Start menu options, or click Start > Run and type clearprojexp.

2. Right-click the UCM project to be renamed > select Properties:

3. Rename the stream by changing the Name field to the desired name > click OK to apply the changes and exit the Properties dialogue:



Note: An error will occur if a name with a space is used:

4. ClearCase Project Explorer should dynamically update with the change, however, if it does not, then use F5 to refresh the window:

Components

5. How do I - copy elements between UCM components

This procedure requires that you copy the elements out of UCM into a base ClearCase (or non-UCM) VOB, then convert that VOB into a UCM component.

The UCM metadata, such as change set membership and baseline labels, cannot transition from one component to another. After this procedure is completed, all the metadata will be new and unrelated to the metadata that was attached prior to the copy.

Note: There is no utility available to move or copy all elements and element versions from one UCM component to another.

ClearCase Export Utility

The utility used for copying elements between components is clearexport_ccase. This utility plays a central role in cross-VOB maintenance by copying VOB objects from one VOB to another, specifically:

• Elements
• All the elements and links cataloged within a directory
• A hierarchy of directories, file elements, and VOB symbolic links

Copying data between VOBs

There are other utilities available for moving and copying ClearCase elements between VOBs, however, they are limited when working in UCM:

1. cleartool mv - This utility allows you to move or rename an element or VOB link. However, the following restrictions apply:

· The mv command should not be used in a UCM VOB.

· The mv command should not be used to rename a UCM component whose root directory is one level beneath the VOB's root directory.

Note: The cleartool mv command itself will run in a UCM environment; however, it should not be used becuase the results may cause merge problems during the next rebase or deliver.

relocate - This utility moves elements and directory trees from one VOB to another. However, the following restriction applies:

· The relocate command cannot be used in a UCM VOB.

clearfsimport - This is a flat-file conversion tool that is generally used to convert file system objects to element versions. This can be used to copy elements between UCM components. However, the following restriction applies:

· The clearfsimport utility can only copy a single version of the element, and it cannot copy the entire version tree.

For more information on ClearCase converters, refer to IBM Rational ClearCase Command Reference, or run cleartool man <converter>.

Copy data from one UCM component to another

1. Use clearexport_ccase to create an export file from the original component:

Example:
M:\prj1_int_vu\multivob\comp1>clearexport_ccase -r
VOB directory element ".".
Converting element "foo.txt" ...
Extracting element history ...
......
Completed.
Converting element ...
Creating element ...
Element "foo.txt" completed.
clearexport_ccase: Error: Unable resolve pathname "foo.txt.contrib@@".
clearexport_ccase: Error: Unable resolve pathname "foo.txt.contrib.1@@".
Creating script file cvt_data ...

2. Use clearimport to import the data into a new base ClearCase VOB:

Example:
M:\admin_vu\vob1>clearimport m:\prj1_int_vu\multivob\comp1\cvt_data m:\admin_vu\vob1
Validating element types.
Validating label types.
Validating branch types.
Validating element types.
Validating directories and symbolic links.
Validating elements.
Validating element ".\foo.txt".
   update version "\main\0"
   update version "\main\prj1_dev\0"
   create version "\main\prj1_dev\1"
   create version "\main\prj1_dev\2"
   update version "\main\prj1_int\0"
   create version "\main\prj1_int\1"
Closing directories.
   Labeling directory ".".


Note: The import must be completed from a non-UCM view to a non-UCM view. If you attempt the import in a UCM view, you will get an error, clearimport: Error: Importing to a UCM view is not allowed.

Import the base ClearCase VOB into UCM to convert it into a new component, refer to IBM Rational ClearCase Managing Software Projects under Setting Up the Project traverse to Making components from existing VOBs (or Making a VOB into a Component).

6.

7. How do I - create a Rootless Component from Command Line

Unlike Creating Components for Storing Elements, creating a rootless component does not require you to create a VOB first.

Note: Rootless Components can only store composite (project) baselines, it cannot store files or directories.

Command Syntax:

cleartool mkcomp -nroot <component-name>@\<pvob-tag>

Example:

M:\repro_dev\ucmcvob\reprocomp>cleartool mkcomp -nroot rootlesscomp@\ucmpvob
Created component "rootlesscomp".

More information on creating Components without a VOB root for storing Project Baselines is available in IBM Rational ClearCase Managing Software Projects, such as:

• Creating a Component for Storing the Project Baseline
• To create a component without a VOB root directory (GUI Instructions)
• To create a composite baseline (GUI Instructions)

8. How do I - remove components from a Project after the VOB has been removed

how to remove the IBM® Rational® ClearCase® UCM Component reference from a Project VOB (PVOB) that has a bad Component which is keeping users from delivering, rebasing or joining a Project.

Cause

The VOB to which the UCM Component references was removed using the cleartool rmvob command (or was manually removed).

Solution

Restore the VOB to which the Component references from backup.

Then execute the cleartool rmcomp command and remove the Component and all related objects manually.

Note: If there is no VOB available to be restored, please contact IBM Rational ClearCase Support and have the below information ready. A tool will be required to remove the dangling hyperlinks in the PVOB.

Collect the following information from the command line:

1. cleartool lsvob

2. cleartool describe -long vob:<pvob_tag>

3. cleartool describe -long project:project_name

4. cleartool dump project:project_name

5. cleartool describe -long component:<comp_name>@<pvob_tag>

6. Is the Component a member of a composite baseline?

7. Collect the system information outputs as detailed in either technote 1131335 for Windows® or technote 1208895 for UNIX® and Linux®.

Related information

Removed a Composite member baseline
ClearCase UCM Troubleshooting Template
Removal of a UCM project
Removing an entire UCM environment
Removing objects in UCM environments

9. How do I – understand why the root of a Multi-Component VOB is read-only in a UCM view

When working in ClearCase UCM, checking out the root of a Multiple Component VOB fails with:

Command Line
M:\proj1_int_vu\multivob>cleartool co -nc .
cleartool: Error: Config spec indicates that checkouts are not allowed for element ".".
cleartool: Error: Unable to check out ".".


GUI


Since the root directory of the Multi-Component VOB cannot be checked out, the cleartool mkelem from the CLI and add to source control from the GUI are prevented:

• From command line, since the root directory of the Multi-Component VOB must be checked out first, it fails with the same error as above.
• From ClearCase Explorer, the Add to source control fails with:

This is the expected behavior for the commands and operations used above.

Solution

When using a Multiple Component VOB to store UCM components, the root directory of the VOB is read-only from any UCM view.

To better understand the functionality available for creating new components in a Multiple Component VOB, refer to the following technotes:

• 1243311 - About Creating a component in a VOB
• 1240724 - About Importing an existing subdirectory as a UCM component

For more information on using Multiple Component VOBs in your UCM environment, refer to IBM Rational ClearCase Managing Projects > Planning the project.

10. How do I - create a component in a VOB

It is possible to create a new component in a VOB using GUI functionality in Project Explorer or from command line using cleartool mkcomp.

Creating a sub-directory in a VOB and adding it to source control for it to act as the component root directory is not required when creating a new component in a VOB.

This feature will create both the component root directory and the UCM component with a single operation or command.

Component Root Directory
The creation of a new component root directory (crd) is not dependent on the existence of a directory element in the Multi-Component VOB.

The component root directory that gets created is not from an existing subdirectory in the VOB, even if a subdirectory already exist in the VOB with the same name.

The crd that is created is a new directory element that is visble from within a UCM view for the purpose of working in a UCM project. Hence, the new directory element will not appear in a non-UCM view as a subdirectory in the Multi-Component VOB.

Note: If you want to use an existing sub-directory as a UCM component, then use the option for importing a VOB directory as a component, which will create a ComponentRootDir hyperlink in the existing directory. This option will not create a new directory element, refer to technote 1240724 for more details.

To avoid confusion, it is advised to manage your UCM environment in a manner where sub-directories in the Multi-Component VOB do not have identical names as UCM components.

If you are unsure as to whether a directory element is in fact serving as a root directory for a UCM component, refer to technote 1147165 for directions on how to determine if the sub-directory is in fact the root of a component.

Create a Component in a VOB
Here is an illustration of creating a new component in a VOB using either GUI or CLI functionality.

Note: Prior to Rational ClearCase 7.0, the VOB must be mounted for this operation to complete successfully. Otherwise, Error Creating Component, will appear and cause the operation to fail.

GUI

1. In Project Explorer right-click Components > New > Component in a VOB ...

2. After filling in the required fields click OK, and you are prompted to enter a view to use:

Note: The operation can only be completed within a view context, but you can use either a UCM or non-UCM view.

3. Select a view from the drop-down list click OK, and the new component will appear under the Components folder in Project Explorer:

4. The new component's Properties will show the root directory as VOB\dir, but is only visible in a UCM view and intended for use when working in a UCM project:

CLI

1. Open a Command Prompt (cmd) and execute the following command:

M:\proj1_int_vu\multivob>cleartool mkcomp -root my_new_comp my_new_comp@\pvob1
Created component "my_new_comp".

The new component's Properties will show the root directory as VOB\dir, but is only visible within a UCM view and is intended for use when working in a UCM project:

M:\proj1_int_vu\multivob>cleartool lscomp -long component:my_new_comp@\pvob1
"my_new_comp"
2006-08-04T10:49:35-04 by jdoe.group@host
 root directory: "\multivob\my_new_comp"
 owner: jdoe
 group: group

11. How do I - import an existing subdirectory as a UCM component

It is possible to convert an existing VOB subdirectory into a UCM component by importing the directory as a component.

The VOB subdirectory must already be a directory element for this operation to succeed.

When you use this option, the existing directory element is catalogued as a UCM object and a ComponentRootDir hyperlink is created in it.

A UCM component that is created from a subdirectory in a VOB is a sub-VOB component.

The base ClearCase VOB that is used to store sub-VOB components is a Multiple Component VOB.

Note: Converting an existing directory element into a UCM component is useful if the directory element already exist, however, if the subdirectory does not already exist, you should use the option for creating a component in a VOB as detailed in technote 1243311.

Convert a subdirectory to a UCM Component

GUI

1. From Project Explorer > right-click Components > select Import > VOB Directory as Component ...



Note: This operation requires a base ClearCase view.

2. After entering the required fields click OK and the new component will appear under the Components folder in Project Explorer:

CLI

Open a Command Prompt (cmd) > set into a base ClearCase view > change directory (cd) into the Multi-Component VOB > execute the following command:

M:\admin_vu\multivob>cleartool mkcomp -root .\new_comp2 new_comp2@\pvob1
Processing subdirectory elements...
Done processing subdirectory elements.
Created component "new_comp2".

Note: If the above command is executed from a UCM view, then it will create a new component in the VOB as detailed in technote 1243311.

12. How do I – understand why the root of a Multi-Component VOB is read-only in a UCM view

Why do attempts to checkout the root directory of a Multiple Component VOB from an IBM® Rational® ClearCase® UCM view result in the error cleartool: Error: Config spec indicates that checkouts are not allowed for element "."..

Cause

When working in ClearCase UCM, checking out the root of a Multiple Component VOB fails with the following error:

Note: You would also see this error while attempting to check-out the root directory of a rootless component.

Command Line
M:\proj1_int_vu\multivob>cleartool co -nc .
cleartool: Error: Config spec indicates that checkouts are not allowed for element ".".
cleartool: Error: Unable to check out ".".


GUI



Since the root directory of the Multi-Component VOB cannot be checked out, the cleartool mkelem from the CLI and add to source control from the GUI are prevented:

• From command line, since the root directory of the Multi-Component VOB must be checked out first, it fails with the same error as above.
• From ClearCase Explorer, the Add to source control fails with:

This is the expected behavior for the commands and operations used above.

Solution

When using a Multiple Component VOB to store UCM components, the root directory of the VOB is read-only from any UCM view.

To better understand the functionality available for creating new components in a Multiple Component VOB, refer to the following technotes:

• 1243311 - About Creating a component in a VOB
• 1240724 - About Importing an existing subdirectory as a UCM component

For more information on using Multiple Component VOBs in your UCM environment, refer to IBM Rational ClearCase Managing Projects > Planning the project.

13. How do I – understand about the number of modifiable components and performance

Deliver and rebase operations attempt to check all the components in a project to see which files have been modified.

• The more streams you have accessing a project, the more deliver and rebase operations you can run.
• The more modifiable components there are in the project, the longer the verification process can take.

These operations (rebase and deliver) in a configuration with lots of modifiable components can significantly tax the performance.

Note: If you can minimize the number of streams you have per project, you can alleviate some of the performance issues.

The following whitepaper on component scaling provides some information on how the increasing number of components affect performance:

14. How do I – understand why th component root directory in a Multiple Component VOB cannot be renamed

A Multiple Component (multi-component) VOB is a base ClearCase VOB that is used to store multiple UCM components.

Note: Components that are created in a Multiple Component VOB are also referred to as sub-VOB components.

Presently, there is no functionality to rename a component root directory when it is in a multi-component VOB.

Expected Behavior

If you attempt to rename the component root directory from a UCM view, an error like the following will occur, because the parent directory cannot be checked out. Hence, the cleartool move command cannot be executed on the component root directory:

CLI

M:\proj1_dev_vu\multivob>ct mv comp1 comp
cleartool: Error: Can't modify directory "." because it is not checked out.

GUI

[Rational ClearCase Explorer]
Config spec indicates that checkouts are not allowed for element "M:\proj1_dev_vu\multivob\." .
Unable to check out "M:\proj1_dev_vu\multivob\." .

Renaming a Component Root Directory

Only UCM views should be used to select and operate on UCM objects, which are catalogued in the project VOB (PVOB).

From a non-UCM view the directory element (that is serving as a VOB root for a UCM component) can be renamed because the action is against the VOB object, and not the UCM object.

However, after renaming the directory element from a non-UCM view, the UCM view will still show the component root directory with its original name. This behavior is illustrated in the Example below.

Change Request

Change request (RFE) RATLC00684340 has been submitted to allow the root directory of sub-VOB components to be renamed using cleartool move and from within ClearCase Explorer; however, the decision was made by Product Management to exclude the resolution of this feature from future upgrades and releases due to the significant architectural changes required to implement the solution.

Note: The root directory of a Single Component VOB can be renamed, see technote 1144219 for directions.

Baselines

15. How do I - remove and recreate UCM baselines

how to undo (remove and recreate) an IBM® Rational® ClearCase® UCM baseline that may have been created inadvertently or if it is found to be unstable after testing.

Solution

To undo a baseline, the baseline must be removed and then a new one can be created.

Here are some considerations before proceeding:

1. The baseline cannot have already been modified in any UCM stream of any project, or removing the baseline will fail. You will not be able to remove the baseline, but rather, you will need to make any necessary changes to correct the baseline, then make a new baseline, recommend it, and rebase all streams.

2. If the component is read-only in the project, but there is an error that changes have already been made in the stream, then refer to technote 1150870 to address that error.

3. An error will occur if the baseline has been rebased to any development or child streams. To remove the baseline from the foundation of a UCM stream, using cleartool rebase -dbaseline baseline@\ProjectVOB. This must be run against each stream reported in the error to remove the baseline from the foundation of the stream.

4. If this is a recommended baseline, then you should first remove it from the recommended list:

· Reset the recommended baseline list by specifying all the baselines, except the one you are going to remove:

cleartool chstream -recommended BL1@\ProjectVOB,BL2@\ProjectVOB stream:stream-name@\ProjectVOB

OR

· Clear all the recommended baselines that are currently set for the stream:

cleartool chstream -nc -nrecommended stream:stream-name@\ProjectVOB

Note: If you are seeing errors because you have removed a recommended baseline refer to technote 1226431.

Removing the UCM Baseline:

The baseline can only be removed from the command line interface (CLI), see the below example:

1. Find the baseline, cleartool lsbl -component component_name@\ProjectVOB

C:\>cleartool lsbl -component chowchow@\BigDog
....
08-Jan-03.13:42:31  Cust_Test_01_08_03  UserName   "Cust_Test_01_08_03"
stream: Cust_Test_Integration@\BigDog
component: chowchow@\BigDog
....

2. Remove the baseline, cleartool rmbl baseline_name\@ProjectVOB
Note: After removing the baseline, all the activities that were in this baseline will be available to be added in a new baseline.

C:\>cleartool rmbl Cust_Test_01_08_03@\BigDog
Remove baseline "Cust_Test_01_08_03@\BigDog"?  [no] y
cleartool: Warning: Searching PVOB "\BigDog" for baselines that depend upon baseline "Cust
_Test_01_08_03".  This may take a few minutes...

Removed baseline "Cust_Test_01_08_03@\BigDog".
C:\>

3. Make a new baseline,

• CLI: cleartool mkbl -view integration_view activity_name

C:\>cleartool mkbl -view UserName_Cust_Test_integration Cust_Test_01_08_03
No changes in component "removecomp" since last baseline; no baseline created.
No changes in component "disappear" since last baseline; no baseline created.
No changes in component "smalltalk" since last baseline; no baseline created.
Created baseline "Cust_Test_01_08_03" in component "chowchow".
Begin incrementally labeling baseline "Cust_Test_01_08_03".
Done incrementally labeling baseline "Cust_Test_01_08_03".
C:\>

Note: By default this will pick up all the activities to be baselined. There are additional options for use with the cleartool mkbl command, see the IBM Rational ClearCase Command Reference, or run cleartool man mkbl.

• GUI:

1. Start Project Explorer

2. Rright-click the integration stream

3. Select Make Baseline.

Note: There is a Help button on the Make Baseline applet for additional information.

16. How do I - create an identical baseline in UCM

There is fundtionality available for creating identical baselines in ClearCase UCM, but this should be used with discretion against read-only components as per the following technotes:

• 1150870 - Unable to remove a non-modifiable component from a stream's configuration
• 1145335 - Cannot rebase a non-modifiable component after creating a new baseline with the -identical option

A more appropriate option may be to Remove and recreate UCM baselines. Review technote 1147318 for more information.

Solution

Creating Identical Baselines

Creating a duplicate (identical) baseline can be achieved by using cleartool mkbl -identical.

The new baseline will contain all the same change set versions as the previous baseline, but you can supply a new baseline name.

A new baseline can be applied across one or more components depending on the switches you use with the mkbl command.

Note: After creating a new baseline, you need to rebase your streams to the newly created baseline.

Option 1

To create a baseline with a custom name across all components in a stream, use the following command syntax:

• To Create an Incremental Baseline:
  
  cleartool mkbl -identical <baseline-name>
• To Create a Full Baseline:
  
  cleartool mkbl -identical -full <baseline-name>

Example:
M:\repro_dev\ucmcvob\reprocomp>cleartool mkbl -identical new_baseline_name
Created baseline "new_baseline_name.202" in component "ucmcomp_b".
Created baseline "new_baseline_name.9093" in component "reprocomp".
Created baseline "new_baseline_name" in component "ucmcomp".
Begin incrementally labeling baseline "new_baseline_name.9093".
Done incrementally labeling baseline "new_baseline_name.9093".
Begin incrementally labeling baseline "new_baseline_name".
Done incrementally labeling baseline "new_baseline_name".

Note: Each baseline created under a single PVOB requires a unique name, regardless of which component it is attached to. With this command, UCM will append a random string of numbers to the end of the baseline name; see technote 1193780 for more details.

Option 2

To create a baseline with a custom name across one component in a stream, use the following command:

• To Create an Incremental Baseline:
  
  cleartool mkbl -component component:<component-name>@\<pvob-tag> -identical <baseline-name>
• To Create a Full Baseline:
  
  cleartool mkbl -component component:<component-name>@\<pvob-tag> -identical -full <baseline-name>

Example:

M:\repro_dev\ucmcvob\reprocomp>cleartool mkbl -component component:ucmcomp@\ucmpvob -identical single_baseline_name
Created baseline "single_baseline_name" in component "ucmcomp".
Begin incrementally labeling baseline "single_baseline_name".
Done incrementally labeling baseline "single_baseline_name".

17. How do I - remove a member baseline of a composite baseline

Deleting a member baseline using cleartool rmbl in a composite baseline results in an error:

Error retrieving recommended baselines of parent stream.

Non-existent baseline: oid:9caad4e5.40664583.8a56.55:ed:36:6b:2c@\XMLEdge
Unable to get member baseline of composite baseline "Snoopy_03_12_02"
Unable to enter member baselines of composite baseline "Snoopy_03_12_02" into foundation.

Attempting cleartool dump -long of the object in question yields the following:

cleartool dump -long oid:9caad4e5.40664583.8a56.55:ed:36:6b:2c@\XMLEdge
cleartool: Error: Invalid object id:  "9caad4e5.40664583.8a56.55:ed:36:6b:2c".

Note: The same type of errors occur if the member baseline is removed using cleartool rmcomp.

A composite baseline is a collection of baselines that are from multiple components. Removing a baseline from this set or removing a component containing this baseline information can yield errors when attempting to list the composite baseline or attempting to rebase to this composite baseline.

The removal of the baseline should be blocked since it is a member of a composite baseline. This was investigated and resolved in ClearCase 2002.05 for cleartool rmbl in defect, RATLC00588714. The fix prevents the direct removal of a baseline using cleartool rmbl. There is a check performed, and if the baseline is part of a composite baseline, then the removal fails with an error message indicating that it's part of a composite baseline.

However, the indirect removal of a baseline using cleartool rmcomp was still allowed. Hence, removing a component, which contains a baseline that is a member in a composite baseline would result in the reported errors.

There was also a regression reported in ClearCase 2003.06 that allowed the baseline to be removed using cleartool rmbl even if it is was a member of a composite baseline.

Both of the latter issues have been addressed in defect, APAR IC46307. The code was updated to prevent the removal of a member baseline using either cleartool rmbl or cleartool rmcomp.

Note: If the VOB root has been removed for a UCM component that contains a member baseline of a composite baseline or if a component VOB is corrupt (and there is no backup), then these are situations that special cleartool rmcomp procedures must be used to remove the component. Please contact IBM Rational Customer Support to work with a member of the ClearCase UCM Team for assistance.

The fix for defect, RATLC00588714, was made available in a patch for ClearCase 2002.05.

UNIX	Windows
ClearCase clearcase_p2002.05.00-10	ClearCase clearcase_p2002.05.00.NT-9
ClearCase LT clearcase_lt_p2002.05.00-5	ClearCase LT <no patch required>

---

The fix for detect, APAR IC46307, will be made available in a future release of ClearCase. It is not slated to be back patched in any currently available versions due to the extent and complexity of the code changes that were involved.

WORKAROUNDS:

1. Try running cleartool checkvob -ucm -fix baseline:BL_NAME@PVOB, and if that does not work, then proceed with workaround #2.

2. If you are experiencing this error, you can use the attached utility, fix_bl_members. This utility is ClearCase version and operating system specific, and is only available for Windows and Solaris. The Windows utility can be used on any edition of Windows that is supported for use with ClearCase, which is also true for any supported version of Solaris, reference technote 1136950 for the supported platforms and versions.

Note: The utility is currently only available for ClearCase version 2002.05 on Windows and Solaris, and for ClearCase 2003.06 on Windows. You should contact IBM Rational Customer Support to work with a member of the ClearCase UCM Team if you need the utility for ClearCase 2003.06 on Solaris.

The utility will cleanup any remaining references to a removed baseline, which will also stop any related errors from being generated. Running this command against the problematic composite baseline (and all other component baselines that exhibit similar problems or contain the now defunct baseline) will correct the issue.

Note: Running the utility on a composite baseline that does not report these errors will not have any adverse effect; its use in that condition is benign. The utility will only address errors as the result of a member baseline being removed from a composite baseline.

Here is the usage for fix_bl_members:

fix_bl_members.exe <baseline-selector>

Example:

fix_bl_members.exe CompositeBL_089@/vobs/pvob1

If using this utility does not resolve the errors or for help using the utility, you should contact IBM Rational Customer Support to work with a member of the ClearCase UCM Team for additional assistance.

18. How do I – understand symbol definitions of -> and >> when diffing UCM baselines

The cleartool diffbl command compares the contents of two baselines or streams and displays any differences it finds.

To properly interpret and understand the output, you need to know what the different symbols ( -> and <- and >> and <<) mean.

Example:

%> cleartool diffbl stream:Integration1 stream:Deliver1
-> change_dir "change_dir"
>> change_dir_2 "change_dir_2"
>> test36 "test36_2"

The following symbols are used to describe the results of a comparison:

Symbol	Meaning
<<	The item is present only in baseline-selector1 or stream-selector1.
>>	The item is present only in baseline-selector2 or stream-selector2.
<-	The activity is present in both of the items being compared and is newer in baseline-selector1 or stream-selector1.
->	The activity is present in both of the items being compared and is newer in baseline-selector2 or stream-selector2.
none	There are no differences between the objects being compared.

19. How do I – understand about No version to label

The line label status: No Versions to Label means that the baseline that is being listed is a composite baseline:

%>cleartool lsbl
baseline "comp_bl"
22-May-05.10:53:14 by user.group@host
 stream: composite_Integration@\pvob
 owner: user
 group: group
 component: noroot@\pvob
label status: No Versions to Label
 change sets:
 promotion level: INITIAL
 depends on:
   comp1_INITIAL@\pvob (comp1@\pvob)

A composite baseline is made up of other baselines, and as such, does not have a label associated with it.

20. How do I – understand the cannot rebase a non-modifiable component after creating a new baseline with the -identical option issue

Changing the baseline of a non-modifiable component in that project results in the following error:

---------------------------
Baseline Validation
---------------------------
"Can't switch to baseline {baseline name} of component because the stream has made changes based upon the current baseline."
---------------------------
OK  
---------------------------

The -identical option caused a baseline to get applied across all the components in the project, modifiable and non-modifiable.

Solution

This is expected functionality as the -identical option is used to create a new baseline for all components, regardless of whether they have actually been modified.

If you need to continue using the -identical option when making a baseline, then you should exclude the non-modifiable components. Otherwise, you can use composite baselines to prevent the problem with rebasing a non-modifiable component. See the workarounds detailed below.

WORKAROUNDS:

1. Exclude the read-only components when making an identical baseline:

cleartool mkbl -identical -component mod_a,mod_b,mod_c ...

Notes:

· Review technote 1125223 for more details on using cleartool mkbl -identical.

· With a large number of modifiable components this can become cumbersome. Use %[mod_comps]p in a script.

Composite baselines can prevent this problem, but they do not fix the problem with current projects. In a new project, use a composite baseline for the stream. The stream will be able to create a composite baseline, for which the modifiable components with modifications will get new baselines created in the stream, while the non-modifiable ones (and the unmodified modifiable ones) will be recorded with the foundation baselines. However, there will not be any conflict if you try to change the baseline of a non-modifiable component.

21. How do I – gather the recommended baselines of all ClearCase UCM projects

The following command line will list all the recommended baselines in a given PVOB.

for /f %v in ('cleartool lsproj -short -invob \<your-pvob-tag>') do cleartool describe -fmt "%n: %[rec_bls]p\n" project:%v@\<your-pvob-tag>

Example:

C:\>for /f %v in ('cleartool lsproj -s -invob \PVOB') do cleartool describe -fmt "%n: %[rec_bls]p\n" project:%v@\PVOB

EXAMPLE OUTPUT:

Note: \350pvob is the project VOB.
M:\Pats_int\350pvob>for /f %v in ('cleartool lsproj -short -invob \350pvob') do cleartool describe -fmt "%n: %[rec_bls]p\n" project:%v@\350pvob

Running the above command produces the following output:
M:\Pats_int\350pvob>cleartool describe -fmt "%n: %[rec_bls]p\n" project:350_Heads@\350pvob
350_Heads: docs_INITIAL heads_INITIAL help_INITIAL

M:\Pats_int\350pvob>cleartool describe -fmt "%n: %[rec_bls]p\n" project:Pats@\350pvob
Pats: compressed_down

M:\Pats_int\350pvob>cleartool describe -fmt "%n: %[rec_bls]p\n" project:mentor_proj@\350pvob
mentor_proj: docs_INITIAL

You can extend this method to list all PVOBs with the following line inserted into a batch file (in the example called ucmvobs.bat):

@cleartool lsvob | find "ucmvob"

The new for command with the extended functionality is as follows:

for /f %x in ('ucmvobs.bat') do @for /f %v in ('cleartool lsproj -short -invob %x') do @cleartool describe -fmt "Project: %Xn: %[rec_bls]p\n" project:%v@%x

Code in the ucmvobs.bat file:

@cleartool lsvob | find "ucmvob"

EXAMPLE OUTPUT:
C:\>for /f %x in ('ucmvobs.bat') do @for /f %v in ('cleartool lsproj -short -invob %x') do @cleartool describe -fmt "Project: %Xn: %[rec_bls]p\n" project:%v@%x


Running the above command produces the following output:
Project: project:350_Heads@\350pvob: docs_INITIAL heads_INITIAL help_INITIAL
Project: project:Pats@\350pvob: compressed_down
Project: project:mentor_proj@\350pvob: docs_INITIAL
Project: project:mikes_ms@\mikesPvob: mikesCvob_INITIAL
Project: project:patsProblem@\pleaseWork:

The nested for command above will list all the projects, in all PVOBs, with their recommended baselines. The recommended baseline list is space-delimited.

References:
Microsoft Windows Help on the FOR command -- for /?
ClearCase Command Reference on fmt_ccase -- cleartool man fmt_ccase

22. How do I – understand the “Not able to recommend baselines after enabling UCM policies” issue

After enabling both POLICY_CHPROJECT_UNRESTRICTED and POLICY_CHSTREAM_UNRESTRICTED, any user in the group that owns the project should be allowed to recommend a baseline in the project.

Note: These policies were made available in a patch for Rational ClearCase 2002.05, refer to technote 1131790 for more details.

However, the following error still occurs:

G:\clearCase\mbilling123_PGNG-UNIX_Construction>cleartool chstream -recommended PGNG-UNIX_Construction_10_09_02 PGNG-UNIX_Construction_integration@\PGNG_Proj
cleartool: Error: No permission to perform operation "change activity".
cleartool: Error: Must be one of: object owner, VOB owner, member of ClearCase group
cleartool: Error: Unable to set the recommended baselines for stream "PGNG-UNIX_Construction_integration".
cleartool: Error: Unable to change all streams.

Cause

In an interop environment, the credentials check for recommending a baseline will fail when the users' username on Microsoft® Windows® is not identical to the users' username on UNIX® (or Linux™).

For example, dbilling123 on Windows is mapped to dbilling on UNIX (or Linux).

Environment

This is an unsupported interop environment because the usernames do not match between UNIX (or Linux) and Windows.

Resolving the problem

Change the usernames on either UNIX (or Linux) to match Windows or vice-versa, refer to technote 1146784 for more details.

23. How do I – understand about UCM baseline types

UCM Baselines can be one of three types: checkpoint, incremental, or full.

• A full baseline is a baseline that you create by recording all versions of all elements below the component's root directory. A full baseline has a corresponding ClearCase label that is applied to one version of every element in the component. This type of baseline takes the longest to create but is the most functionally complete.
• An incremental baseline is a baseline that you create by recording the last full baseline and those versions of elements that have changed since the last full baseline was created. It has a corresponding ClearCase label that is applied to only those versions that have changed since the last full baseline. Incremental baselines are faster to create (unless every element in the VOB was modified ) and can be used for all UCM operations

A checkpoint baseline can be a fully labeled, incrementally labeled or unlabeled baseline. Checkpoint baselines cannot be used as foundation baselines, nor can they be used in rebase operations. Checkpoint baselines can be converted to incremental baselines and incremental baselines can be converted to full baselines.

Additional information about baselines can be reviewed in the IBM Rational ClearCase Managing Software Project Guide.

24. How do I – understand who has rebased to the new baseline

After creating a new baseline and promoting it as the recommended baseline, how can you determine who has rebased to the new baseline and who has not?

Command Line:

The easiest way is to use the cleartool lscomp command with the -tree parameter.

This command will list all baselines for a given component and show which streams are attached to each baseline.

Example:

Latest Baseline = V4.0.BL5_XYZ_BASE.118

Previous Baseline = V4.0.BL4_ABCD_BASE.118

</vobs/projects>cleartool lscomp -tree xy_comp | more xy_comp
xy_comp_INITIAL.118                baseline  (initial)
V4.0.BL3_XYZ_BASE.118              baseline  
ucm_4.0.bl4_int.old            stream    
stream990413.114838            stream    
hud_4.0.bl4                    stream    
V4.0.BL3_XYZ_BASE_990420.118       baseline  
V4.0.BL4_XYZ_BASE_990712.118       baseline  
V4.0.BL4_ABCD_BASE.118             baseline  
jtk_ABCD_1.0                  stream    
V4.0.BL5_XYZ_BASE.118              baseline  
stream990908.143751              stream    
lennon_4.0.bl5                   stream    
bjm_bl5_dev                      stream    
stream990824.130617              stream    
lennon_perf.bl5                  stream    
stream990812.170024              stream    
stream990811.113244              stream    
curreri_xyz_4.0.bl5              stream    
stream990816.162930              stream    
hui_xyz_4.0.bl5                  stream    
tblSUNWspro5                     stream    

For instance, the V4.0.BL4_ABCD_BASE.118 baseline still has one developer stream (jtk_ABCD_1.0) working on it, while most developers have moved to, or are working off of, the new V4.0.BL5_XYZ_BASE.118 baseline.

Project Explorer:

You can also use the ClearCase Project Explorer.

1. Open the Project Explorer

2. Select a project

3. Select the integration stream

4. Select File > Properties...

5. Select the "Baselines" tab in the property sheet

6. Select a component

7. Select a baseline from the available list for that integration

8. Click the Properties button

9. Select the Streams tab

10. The list shows streams that are "off of" the selected baseline

Note: The resulting list is particular to that one selected baseline and will not show you the scope that the lscomponent -tree option does.

Activities

25. How do I - determin dependent UCM activities in ClearCase

How can I determine which activities are dependent on other activities when delivering in an IBM® Rational® ClearCase® UCM project?

Answer

For any given element in an activity's change set, all versions are delivered from a given stream in the range between the version in the change set and either the version most recently delivered or the version in the stream's foundation baseline (whichever is later).




Notice that because version 3 of prog.c was delivered in a previous deliver operation, the dependencies between Activities B and C, which contain versions of prog.c, are as follows:

1. You can deliver Activity B without delivering Activity C.

2. To deliver Activity C, which contains version 6, users must also deliver Activity B, which contains the versions between 6 and the most recent delivery of prog.c.

3. Because Activity B also contains versions of lib.c, users may be required to deliver other activities to satisfy dependencies for lib.c.

For example, if Activity D (not shown in the above diagram) contained an undelivered version 6 of lib.c, delivering Activity B would require user to deliver Activity D as well.

For more information on delivering activities, refer to the Rational ClearCase Developing Software Guide.

With that said, a dependency between activities can arise from the fact that they contain versions of the same element, or because they are included in the same baseline.

There is no direct and reliable method to verify if an activity is required to be delivered with another due to a change set dependency.

The best way to determine if two activities need to be delivered together is to attempt a deliver of one activity by itself. If there are dependencies, a message will appear during the deliver notifying you of the dependency.

Review the content in the related information section below for more details.

Related information

Delivered activities still listed for deliver
APAR IC39512
Knowledge Collection: UCM Activity Dependencies
Workaround for activity dependencies during UCM deliver

26. How do I – understand why UCM selects activities as dependencies that are not related to the current deliver operation

When executing a deliver, and selecting only a subset of activities from a stream, an activity is selected as a dependency that seemingly has no

relation to the other activities. How is this possible?

The UCM deliver operation could complain about dependencies even when there may be no overlap in the change sets of activities in a stream. The classic cases of dependencies from non-overlapping change sets are the result of baselines in the source stream. These baselines could have been created explicitly by a user, or more likely implicitly by previous deliver operations.

Whichever the case, if there are baselines in the source stream, then activities included in those baselines are dependent.

Example:
In a development stream, a developer works on activity A.
In the same development stream, another developer works on activity B (and there is no overlap in the change sets of activities A & B).
Developer delivers only activity A to the integration stream (which will create a baseline in the development stream).
The second developer now wants to do an alternate target delivery of only activity B to a different stream.

The second delivery will not be possible without also delivering activity A (due to the existence of the baseline in the development stream created by the first delivery).

This is expected behavior within UCM. In general, any deliver operation will only allow selective deliver activities in the stream that have not been included in any previous baseline in that stream.

27. How do I – list the contributing activities in the change set of a baseline or an integration activity

How to view the contributing activities included in a baseline or an integration activity from the graphical user interface or command line when using IBM® Rational® ClearCase® UCM.

BASELINES

Baselines are used to mark a set of versions as a stable configuration or a bench mark, and can span multiple components in a project.

For more information on Baselines and their uses, see IBM Rational ClearCase Managing Software Projects.

You can view the contributing activities in a baseline from GUI or CLI as follows:

GUI - ClearCase Component Tree Browser

1. From Project Explorer, right-click a component and select Browse Baselines:

2. Right-click the baseline and select Properties > Activites tab:

CLI - cleartool describe

Command syntax:

cleartool describe baseline:<baseline>@\PVOB

Example:
C:\>cleartool des baseline:proj1_new_baseline@\pvob1
baseline "proj1_new_baseline"
  created 2006-07-17T21:38:48-04 by admin.ccusers@IBM-D15F3483123
  owner: IBM-D15F3483123\admin
  group: IBM-D15F3483123\ccusers
  stream: project1_int@\pvob1
  component: comp1@\pvob1
  label status: Fully Labeled
change sets:
    deliver.admin_proj1_dev2.20060717.213815@\pvob1
  promotion level: INITIAL
  depends on:
  Attributes:
    PromotionLevel = "INITIAL"
  Hyperlinks:
    BaselineLbtype -> lbtype:proj1_7_17_2006@\multivob
    UseBaseline <- stream:admin_proj1@\pvob1
    UseBaseline <- stream:admin_project1@\pvob1

INTEGRATION ACTIVITY

Integration activities track work completed as a result of a deliver or rebase operation, and they are named accordingly with a prefix of either deliver or rebase to help distinguish them from user created activities.

For more information About activities, see IBM Rational ClearCase Developing Software.

You can view the contributing activities in an integration activity from GUI or CLI as follows:

GUI - ClearCase Project Explorer

Note: The screen capture is from Microsoft® Windows®, but this feature is available on UNIX® and Linux® also.

1. Start Project Explorer, select a stream in the left-hand pane, and the integration activities will appear in the right-hand pane:

Note: Integration activities only exist in a stream as the result of a deliver or rebase operation.

2. Right-click the activity and select Show Contributing Activities:

CLI - cleartool lsactivity -contrib

Command Syntax:

cleartool lsactivity -contrib <deliver baseline>@\pvob

Note: You can list the intergration activities in a stream using cleartool describe stream:<stream>@\PVOB.

Example:

>cleartool lsactivity -contrib deliver.admin_proj1_dev2.20060717.213815@\pvob1
new_file

For more information on cleartool lsactivity, see IBM Rational ClearCase Command Reference, or run cleartool man lsactivity

28. How do I – resolve the unable to perform operation change activity in replica issue

Attempts to complete a rebase operation results in the following error:

$ cleartool rebase -complete
Rebase in progress on stream  "nightly_build".
Started by "jdoe" at 01/31/05  12:08:32.
Merging files...
Checking in files...
Loading  "vobs/src/dir1/file.txt" (88213 bytes).                                                                 Making  dir "vobs/product/src/readme".
Clearing integration  activity...
Updating stream's configuration...
cleartool: Error: Unable to  perform operation "change activity" in replica "pvob_replica1" of VOB  "/vobs/pvob".
cleartool: Error: Master replica of activity  "timeline050128.140320" is "pvob_replica2".
cleartool: Error:  Unable to create hlink of type "Foundation" from "cr_1_28_2005_pips.8891", to  "timeline050128.140320".
cleartool: Error: Can't update stream's  configuration.
cleartool: Error: Unable to update config.
cleartool:  Error: Unable to complete integration.
cleartool: Error: Can't update  stream's configuration.
cleartool: Error: Unable to resume  rebase.

Note: A similar error occurs during a deliver operation as well as a make baseline (mkbl) operation.

The error happens because the mastership of the timeline activity has not been temporarily transferred for the rebase to complete successfully.

This is not expected behavior as the mastership change should be transparent to the end user.

This will occur if there was a problem with exporting or importing syncreplica update packets.

Cause 2

This problem has also been known to occur when change mastership of the stream has been executed without using the -stream switch with the multitool chmaster command:

chmaster <replica> stream:<stream-obj>

All the required parts do not have their mastership transferred, such as the timeline activity, when the above command is used.

Solution

Make sure all the syncreplica packets have been exported and imported, respectively. If the rebase error still persist, then the mastership of the timeline activity must be transferred manually prior to completing the rebase:

cleartool chmaster new_mastering_replica anyactivity:timelinexx.xx@\PVOB

Note: In some cases, there may be multiple timeline activities to change the mastership of before completing the rebase. After correcting one activity, try to the rebase again, and another error will report a different timeline activity that needs the mastership changed.

Change Timeline Activity Mastership:

1. Cancel the rebase that is in progress: cleartool rebase -cancel

2. Change mastership of the timeline activity from the current error:

cleartool chmaster vobs_pvob_sirius.vcs.fw anyactivity:timeline050128.140321@/vobs/pvob_sirius

3. Sync the replicas to update them with the mastership change

4. Try the rebase again

Note: If the same error occurs again, check the name of the timeline activity, it may have changed. In that case, repeat the above steps for that activity also (and any others as necessary) until the rebase completes.


Changing Stream Mastership

The correct syntax for transferring mastership of a UCM stream is:

cleartool chmaster -stream <replica> stream:<obj>

This command will ensure that all parts of the UCM stream will have their mastership transferred.

29. How do I - move a UCM version in a change set from one activity to another

How to move an IBM® Rational® ClearCase® version in one UCM activity's change set to a different activity

Solution

From the ClearCase Project Explorer:

1. Highlight the stream and select the activity from which you want to move the versions.

2. Right-click to bring up the properties of the activity.

3. Select the Change Set tab, select the Change Set and right-click on it to bring up a context menu.

4. Select "Move to Activity...".

5. From the available list of activities choose an existing one or choose to create a new activity by selecting the "New" button and creating the new activity.

6. Highlight the activity to which you want to move the versions to and click OK.

7. Click OK again.

From the command line:

1. Change directory (cd) to the view that is associated with the stream which contains the change set and activity to be moved.

2. M:\test_proj1>cleartool lsact -long new
activity "new"
13-Jul-01.13:10:47 by username.cc_users@username_ntw
owner: username
group: CC_USERS
stream: test_proj1.9907@\test_pvob
title: new
change set versions:
M:\test_proj1\test_comp\dir1\mytext.txt@@\main\test_proj1.9907\1
M:\test_proj1\test_comp\dir1\hello.txt@@\main\test_proj1.9907\1

M:\test_proj1>cleartool chact -fcset new -tcset MOVED M:\test_proj1\test_comp\dir1\mytext.txt@@\main\test_proj1.9907\1
Moved version "M:\test_proj1\test_comp\dir1\mytext.txt@@\main\test_proj1.9907\1"
from activity "new" to activity "MOVED".

30. How do I - determine the view association of a UCM Activity from the command line

How can I determine which view (if any) is linked to an IBM® Rational® ClearCase® UCM Activity from the command line on Windows®, UNIX®, and Linux®?

Views that are linked to a UCM Activity can be determined using the cleartool describe or the cleartool lsactivity -long command.

1. Set into any view

2. Mount and cd into the PVOB

3. Run the command cleartool describe activity:<activity-name>

Example: Windows example but same output for UNIX and Linux.

M:\View\PVOB> cleartool describe activity:MyActivity
activity "MyActivity"
created 13-Nov-05.19:57:35 by user.group@host
owner: user
group: group
stream: My_Stream@\PVOB
current view: My_Dev_View
title: MyActivity
change set versions:
M:\My_Dev_View\Source_Comp\headers@@\main\My_Stream\1\hello_world.h\main\My_Stream\3

4. Run the cleartool lsactivity -long <activity-name> for the same output.

Example:

M:\View\PVOB> cleartool lsactivity -long MyActivity
activity "MyActivity"
13-Nov-05.19:57:35 by user.group@host
owner: user
group: group
stream: My_Stream@\PVOB
current view: My_Dev_View
title: MyActivity
change set versions:
M:\My_Dev_View\Source_Comp\headers@@\main\My_Stream\1\hello_world.h\main\My_Stream\3

5. Use the -fmt switch to format your describe or lsactivity output. Review the ClearCase Reference Guide on the topic of fmt_ccase (cleartool man fmt_ccase) for more information on formatting strings for command output.

Example:

M:\View\PVOB> cleartool describe -fmt "%[view]p" activity:MyActivity
My_Dev_View

Note: If there is no line that specifies the current view returned in the output above, this means the activity is not linked to a view.

Example:

M:\View\PVOB> cleartool lsactivity -long MyActivity2
activity "MyActivity2"
13-Nov-05.19:57:35 by user.group@host
owner: user
group: group
stream: My_Stream@\PVOB
title: MyActivity2

31. How do I - list which activity your view is currently set to when using ClearCase and ClearQuest

To list which activity your view is currently set to, run the following command while inside your view:

cleartool lsview  -cact

For example:

M:\UCM_View\UCM_comp> cleartool lsact -cact
2007-07-27T11:16:49-04  agusr00000125  grillak   "test for view value"

32. How do I – understand the Version from the activity is missing from the required version list issue

When performing a deliver operation, UCM complains that a version is missing from the required version list.

Example:

M:\Dev1_Proj1>cleartool deliver -act Act2@\PVOB,Act4@\PVOB
cleartool: Error: Activity "Act3" must be added to activity list.
cleartool: Error: Version "M:\Dev1_Proj1\CVOB\foo.txt@@\main\Dev1_Proj1\3" from the activity "Act3" is missing from the required version list.

Note: When the deliver complains that a version being missing from the required version list, ClearCase is not reporting that the version is actually missing, rather the version is not listed in the merge.

When you deliver two or more activities that have version overlap AND there is an intermediate version in an activity that is not in your deliver -act, then deliver parses for that intermediate version and reports that "version is missing from the required version list".

In the above example Act2 created version 2, and Act4 created version 4.

Resolving the problem

This is expected behavior.

It may not always be clear when deliver will report these versions, however, rest assured that deliver is only expressing why a dependent activity must be delivered.

Activity is already set in view

Attempts to checkin a file in a UCM view results in the following error:

Activity "<AAA>" is already set in view "<VVV>"

Where view <VVV> is not the view of the user currently attempting the checkin.

Cause

A possible cause is that the activity is already set to another view.

Note: An activity can only be set to one view at a time.

Here is an example scenario that could explain how this problem occurs:

• User "A" sets the view (View1) to activity "AAA" and checks out a file.
• User "A" then sets the view (View 1) to a different activity "BBB".
• User "B" from a different view (View 2) then selects the available activity "AAA" and checks out a file.
• User "A" then attempts to checkin the file checked out using activity "AAA".

This activity is currently set to User "B"s view; hence the error.

Resolving the problem

You must find the user with the view set to the activity (for example, User "A" needs to find User "B") and unset the activity.

Note: You can unset from an activity using the ClearCase Explorer. From the view the activity is currently set to > My Activities > Deselect the checkbox for the desired activity.

To unset from an activity on the command line: cleartool setact -view <view_tag> -none

The activity will now be available for the other view to complete the checkin.to another view.

Streams

33. How do I – understand the cannot set default deliver target of a non-integration stream issue

When using a child stream for development the parent stream cannot be changed, and the following informational error results:

cleartool chstream -target stream:your_Int@\mypvob stream:my_dev@\mypvob
cleartool: Error: Cannot set default deliver target of a non-integration stream
cleartool: Error: Unable to change all streams.

This is expected behavior as this feature is only intended for use with a project's integration stream.

Example:

cleartool chstream -target stream:your_int@\mypvob stream:my_int@\mypvob
Changed stream "stream:my_int".

Note: Use cleartool describe -long stream:<dev_stream>@\<pvob> to determine its current default deliver stream. This value is NULL for integration streams, by default.

For more information on how To deliver work between integration streams, refer to IBM Rational ClearCase Managing Software Projects.

Solution

If a parent (non-integration) stream is abandoned or no longer required for use, but you are still working on your child stream, then you must rely on Deliver to alternate target to deliver code to a stream other than the former parent stream.

This feature is available from command line using cleartool deliver or from graphical user interface, ClearCase Explorer.

To better understand Stream hierarchy and default targets, refer to IBM Rational ClearCase Managing Software Projects.

34. How do I - prevent users from creating a new UCM stream

There is no built-in functionality to prevent the creation of a new UCM Streams.

Change request (RFE) RATLC00738872, has been submitted to add more extensive access control features for UCM objects and metadata.

WORKAROUND:

Note: Locking the project does not prevent the creation of new streams. Locking the project is equivalent to setting the project as "read only"; new streams can still be created.

You can create a UCM trigger to fire on cleartool mkstream.

Example:

cleartool mktrtype -ucmobject -all -preop mkstream -exec "ccperl c:\perl_script.pl" -project project:<project_name>@<\pvob-tag> TRIGGER_NAME

Where the perl script that is executed can be a simple script that exits with a status of 1.

Note: The -project switch allows you to specify a set of UCM projects for the restriction list. When the trigger fires, the items on the restriction list form a logical condition: if the condition is met, the trigger fires.

35. How do I – understand the do not allow deliver to proceed with checkouts in the stream issue

When the policy, Do not allow deliver to proceed with checkouts in the development stream, is enabled all checkouts must be resolved before the deliver can proceed:

As indicated by the policy, the deliver is blocked for the stream, not per activity; hence, the following message will appear if there are checkouts associated with any activities on the stream during a deliver operation:

Project policy prohibits delivering activities while checkouts are still in effect.

Solution

Change request, (RFE) RATLC00990988, has been opened to enforce this policy on a per activity basis.

This will allow the deliver to proceed as long as there are no checkouts in any of the activities that are included in the operation. That means:

• Only the activities included in the deliver operation will be checked for checkouts,
• Any checkouts found in those activities are the only ones that will keep the deliver from proceeding, and

Checkouts in activities on the stream (that are not included in the deliver) will not prevent the operation from continuing.

36. How do I – understand that after renaming an UCM stream, the old name still appears in the ClearQuest record

How do I resolve the issue where after renaming an IBM® Rational® ClearCase® UCM stream, the old name still appears on the UnifiedChangeManagement tab of the IBM Rational ClearQuest® record

Cause

This behavior is the result of a discrepancy between ClearCase and ClearQuest, as the ClearQuest record is still holding onto the old stream name.

Solution

To resolve this issue, run the following command from within a view\vob context

>cleartool checkvob -ucm -fix -crm_dbname <CQ_Database_Name> -project  <UCM_Project_Name>
Click Yes to each change you are prompted to make.

For example:
M:\DRepro_Proj2_int\int_cvob>cleartool checkvob -ucm -fix -crm_dbname  v2usr -project Repro_proj

Note: This command might take a long time to complete, depending on how many records are affected.

37. How do I - Rebase a UCM stream from ClearCase Explorer may not use the currently-selected view

Attempts to rebase a UCM stream from ClearCase Explorer where the stream has multiple views associated may result in the "rebase stream" GUI not selecting the current view for the rebase operation.

Defect APAR PK47920 has been opened to investigate this issue.

WORKAROUND:

Create a new context menu item to spawn the rebase set into the desired view context.

1. Open ClearCase context menu editor (Start > Run type clearmenuadmin).

2. Select ClearCase Explorer under "Application"

3. Click New in the Available Menu Choices field

4. Enter the following values into the specified fields:

 Menu Text: Rebase Here.
Command: Executable
Command: C:\program files\rational\clearcase\bin\cleartool.exe
Initial Directory: $dir
Arguments: rebase -graphical -stream $stream

5. Click OK.

6. Under Object Type, select Dynamic view

7. Under Object State, select UCM Project View Started

8. Locate your new menu item in the Available Menu Choices field and click Add

9. Use the "Move Up" and "Move Down" buttons to move the choice to the desired location

10. Repeat steps 7 - 9 for the UCM Project View Started And Drive Assigned state.

11. Select Configuration/Apply to apply the changes to the local user profile.

12. Open a new instance of ClearCase explorer and test the change.

13. Select Configuration/Save to file to save the configuration to a registry file.

Repeat steps for Windows explorer context menu if desired.

38. How do I – resolve streams not appearing in the component for the baseline browser

The ClearCase Component Tree Browser has Filtering Options that allow you to control what objects are displayed:

1. Open the Component Tree Browser in the ClearCase Project Explorer

2. Right-click the component and select Browse Baselines

Select Tools > Filtering Options and select the appropriate options.

39. How do I – understand deliver operation already in progress on stream

A UCM deliver operation reports that a delivery is already in progress, but when the status of the delivery on the development stream is checked, UCM reports no deliver operation in progress.

cleartool deliver -stream stream:dev@\VOB -to int -baseline  baseline:dev.334@\VOB                                                    
cleartool: Error: Deliver operation already in progress on stream        
"dev".                                                
cleartool: Error: Use cancel, resume or complete options to reconcile    
the deliver operation.


cleartool deliver -status -stream stream:int@\VOB
No deliver operation in progress on stream "int".

Cause

The local development stream is mastered by a remote site which may be the result of a previously invoked posted delivery operation which is still in progress or the delivery may have completed, but a sync packet returning the stream mastered has not yet been imported at the local site.

Resolving the problem

Check the source stream at the remote site to see if there is a posted delivery in progress.
If so, then complete or cancel the delivery as appropriate for your situation, send a sync packet back to the local site and retry the delivery.

If there is no existing posted delivery in progress, then push the mastership of the stream from the remote site back to the local site and retry the delivery.

Refer to technote 1126522 for more information on how to find UCM posted deliveries.

Derived Objects

40. How do I – understand about site wide settings for shareable derived objects and UCM Integration views

This technote identifies a defect that explains why attempts to change the site-wide default settings for shareable derived objects does not affect the default behavior for IBM® Rational® ClearCase® UCM Integration views on Microsoft® Windows®.

Cause

After running the cleartool setsite command to change the site-wide default settings for shareable derived objects (cleartool setsite view_shareable_dos=FALSE) attempts to create a UCM dynamic view associated with an integration stream on Windows fails to use the new default settings.

Notes:

• Dynamic views associated with development streams as well as base ClearCase dynamic views accept the new defaults as expected.
• Does not affect UNIX® or Linux® machines

Example:

BEFORE

C:\>cleartool lssite view_shareable_dos
 view_shareable_dos=TRUE

Attempts to create a dynamic view will show the Create shareable derived objects radio button selected.

Changing the Site-Wide Defaults

C:\>cleartool setsite view_shareable_dos=FALSE
Registry password:
Set site-wide default view_shareable_dos=FALSE (was "TRUE").

AFTER

Attempts to create a dynamic view should now have the Create shareable derived objects radio button de-selected.

UCM Integration view Behavior

Defect APAR PK34436 has been submitted to adress this behavior.

Solution

The decision was made by Product Management to exclude the resolution of this defect from future upgrades and releases due to the significant architectural changes required to implement the solution.

WORKAROUND:

When creating UCM integration views, be sure to de-select the Create shareable derived objects radio button.

You can access this option by clicking the Advanced Options... button from the View Creation Wizard.

Techniques

41. How do I – remove objects in UCM environments

t is expected that the need will arise to remove UCM objects, whether that be a component, baseline or even the entire project. However, to ensure the stability of the UCM environment and to minimize any unexpected fallout, there are guidelines and restrictions depending on the action you are looking to execute.

Note: The restrictions are enforced within UCM (when attempting to execute a remove operation) through informational error messages explaining why an object cannot be removed. In some cases you will be able to resolve the issue, then proceed with the remove operation, but in others, its a permanent restriction, and you may need to lock/obsolete the object to discontinue its use.

There is a methodology in place for tracking the relationship of UCM objects that enables them to remain in synch throughout the life cycle. Hence, removal of some objects is prohibited to keep this process working correctly.

Review the Overview of the UCM process for more information.

Used versus Unused Objects

In general, objects that have been used in a UCM environment can potentially not be removed to prevent a break in its continuity due to the underlying interdependencies that exist between UCM objects. Where as objects that have never been used can be removed with minimal or no discretion since they are isolated and have not been introduced to other entities in the configuration.

An empty (never used) object is different than an unused object, which may have been in use at one time, but is no longer required. Removal of an unused object will depend on what it is and how it has been used in the environment. Some objects cannot be removed due to subsequent activity that was initiated from its resources.

Removing UCM Objects

Cleaning up the project when it ends is actually recommended to help manage the UCM environment, and improve the transition to the next version of the project.

Directions for Removing unused objects is detailed in IBM Rational ClearCase Managing Software Projects .

The Delete option in ClearCase Project Explorer (Exploring ClearCase Projects) can be used in removing some UCM objects, and command line functionality for the appropriate cleartool sub-commands are documented in IBM Rational ClearCase Command Reference. See the above Note that details how restrictions are enforced when attempting to remove a UCM object.

Requirements:

The component being removed must be empty and have no work performed on it.

To confirm the component has no history of work take the following action:

1. Confirm no baselines have been created on the component:

cleartool lsbl -component component:<component_name>@\<pvob_tag>

Note: This should return only the initial baseline.

Examples:

Good:
C:>cleartool lsbl -component component:UCM_3@\PVOB

18-Oct-06.10:50:37  UCM_3_INITIAL  jdoe   "UCM_3_INITIAL"
 component: UCM_3@\PVOB

Bad:
C:\>cleartool lsbl -component component:UCM_Comp1@\PVOB

11-Jul-06.17:25:01  UCM_Comp1_INITIAL  jdoe   "UCM_Comp1_INITIAL"
 component: UCM_Comp1@\PVOB
11-Jul-06.17:34:04  deliverbl.user1_Cars.20060711.173400  jdoe   "deliverbl.user1_Cars.
0060711.173400"
 stream: user1_Cars@\PVOB
 component: UCM_Comp1@\PVOB
11-Jul-06.17:35:01  Cars_11-Jul-06.8719  jdoe   "Cars_11-Jul-06"
 stream: Cars_Integration@\PVOB
 component: UCM_Comp1@\PVOB

2. Confirm that no stream is using any component baseline INCLUDING the initial.

Note: You should not see any baseline hyperlinks at the bottom of the following commands output.

cleartool describe -long baseline:<initial_bl_name>@<\pvob_tag>

Examples:
Good:
C:\>cleartool describe -long baseline:UCM_3_INITIAL@\PVOB

baseline "UCM_3_INITIAL"
 created 18-Oct-06.10:50:37 by jdoe.clearuser@HOST
 "Initial baseline for component "UCM_3""
 owner: DOM1\jdoe
 group: DOM1\clearuser
 component: UCM_3@\PVOB
 label status: Initially Labeled
 change sets:
 promotion level: INITIAL
 depends on:
 Attributes:
   PromotionLevel = "INITIAL"

Bad:
C:\>cleartool describe -long baseline:UCM_3_INITIAL@\PVOB

baseline "UCM_3_INITIAL"
 created 18-Oct-06.10:50:37 by jdoe.clearuser@HOST
 "Initial baseline for component "UCM_3""
 owner: DOM1\jdoe
 group: DOM1\clearuser
 component: UCM_3@\PVOB
 label status: Initially Labeled
 change sets:
 promotion level: INITIAL
 depends on:
 Attributes:
   PromotionLevel = "INITIAL"
 Hyperlinks:
   UseBaseline@187@\PVOB <- stream:Cars_Integration@\PVOB
   UseBaseline@193@\PVOB <- stream:user1_Cars@\PVOB

3. If any of the above steps return unexpected results, DO NOT REMOVE the component.

Removal Process:

1. Create a new non-UCM (base ClearCase) view (dynamic or snapshot).

2. Navigate into the view and into the Project VOBs directory.

3. Obtain a list of all of your components using the lscomp command.

Example:
M:\baseview\ucmpvob>cleartool lscomp

2006-12-06T15:40:04-05  ucmcomp  jdoe
 root directory: "\ucmcvob\ucmcomp"
2006-12-06T16:34:41-05  ucmcomp_b  jdoe
 root directory: "<none>"
2007-01-08T14:10:55-05  reprocomp  jdoe
 root directory: "\ucmcvob\reprocomp"
2007-02-07T12:42:19-05  singlecomp_d  jdoe
 root directory: "\singlecomp_d"

4. Remove the component using the rmcomp command.

cleartool rmcomp <component-name>

Example:
M:\baseview\ucmpvob>cleartool rmcomp singlecomp_d

Remove component "singlecomp_d"?  [no] yes
cleartool: Warning: Searching PVOBs for baselines that depend upon baseline "singlecomp_d_INITIAL". This may take a few minutes...

Removed component "SingleComp_D".

Notes:

· This will only remove the component object in the PVOB; the VOB object will not be removed with this command. If you wish to remove the VOB object (tag and storage), run the cleartool rmvob command. Review the ClearCase Command Reference Guide on the topic of rmvob (cleartool man rmvob) for more information.

· If the component is a sub-VOB component, you will need to remove the directory in the VOB with cleartool rmname if you no longer wish to see the directory in the VOB, else the directory will still be visible, but non-componentized.

Verify success by obtaining a new list of all of your components using the lscomp command.

Example:
M:\baseview\ucmpvob>cleartool lscomp

2006-12-06T15:40:04-05  ucmcomp  jdoe
 root directory: "\ucmcvob\ucmcomp"
2006-12-06T16:34:41-05  ucmcomp_b  jdoe
 root directory: "<none>"
2007-01-08T14:10:55-05  reprocomp  jdoe
 root directory: "\ucmcvob\reprocomp"

42. How do I - remove an entire UCM environment

A ClearCase Administrator can use the following directions to remove the project VOB (PVOB), the UCM views and, optionally, the VOB(s) that serves as the component root directory.

Note:

• For ClearCase on Windows, a ClearCase Administrator is any member of the ClearCase group.
• For ClearCase LT on Windows, a ClearCase Administrator is any user logged into the ClearCase LT server with local administrative rights.
• On UNIX, for ClearCase and ClearCase LT, a ClearCase Administrator must be logged in as root on the server.

1. Run cleartool rmvob <path to PVOB.vbs> to remove the PVOB, which will remove all projects and other UCM related objects, such as components, streams, activities and baselines.

Note: There is no warning associated with this procedure. Removing the PVOB cannot be reversed except if necessary by a restore from backup. The rmvob command is restricted to VOB owner, root (UNIX), Member of the ClearCase group and the Local Administrator of the ClearCase LT server host (Windows).

2. The VOBs (or the root directory for the UCM components which were removed) will remain intact and the data will not be affected or changed by the removal of the PVOB. The VOBs can still be accessed via Base ClearCase views. Otherwise, if they are no longer needed, then the cleartool rmvob command from step #1 can be used to remove the VOBs as well.

3. Run cleartool rmview -tag <UCM_view_tag> to remove all integration and development views. The remove view GUI option can be used also; for example, from Rational ClearCase Explorer > select the Tool Box tab at the bottom left of the window > select the Base ClearCase page and click Remove View.

For more information, run cleartool man rmvob | rmview from the command line (CLI) or see rmvob and\or rmview in the IBM Rational ClearCase Command Reference.

43. How do I - remove elements in UCM

In a UCM environment, it is strongly recommended to use rmname instead of rmelem when it comes to removing elements. The two main reasons against rmelem are:

1. There are currently no supported methods to recover an element in a UCM environment after the element has been removed using cleartool rmelem due to the restrictions on UCM and commands such as clearexport_ccase and relocate.

Note: Restoring an individual element from backup after the object has be removed using rmelem in UCM is possible; however, you would need to restore the entire VOB to recover the removed element along with restoring the PVOB, all related components to that PVOB up to and including any Rational ClearQuest databases used with Projects.

The only way to reintroduce a backup of the element into UCM is to add the file to source control and re-create the version tree.

2. After using rmelem to remove a file, hyperlinks which exist between versions of that element and activities may still exist especially in a replicated PVOB. This could cause future deliver/rebase operation to fail. Review technote 1134563 for more details.

Note: For Microsoft® Windows® users, the ClearCase Explorer GUI performs an rmname operation when you use the DELETE key to delete a file. There is currently no way to perform and rmelem in the GUI.

An element that has been rmnamed can be restored, refer to technote 1149206 for directions to Restore an element that has been rmnamed.

44. How do I – renaming UCM Objects

This technote provides references to information that details how to rename ClearCase UCM Objects.

Renaming a Project VOB (PVOB)

How to rename a ClearCase UCM Project VOB is the same as renaming a base ClearCase VOB, which is documented in technote 1124390.

Renaming a UCM Project

How to use the command line syntax, cleartool rename, and the graphical user interface, Project Explorer, to rename a ClearCase UCM Project, see technote 1122744.

Note: The name of UCM projects, streams and folders (in Project Explorer) cannot contain spaces, see technote 1130055 for more details.

Renaming a UCM Stream

How to use the command line syntax, cleartool rename, and the graphical user interface, Project Explorer, to rename a ClearCase UCM Stream, see technote 1119147.

If the branch is also getting renamed, then see technote 1134819 for Branch and label rename post checklist.

Renaming a UCM Component

How to use the command line syntax, cleartool rename, and the graphical user interface, Project Explorer, to rename a ClearCase UCM Component, see technote 1135064.

Technote 1144219 provides directions for Renaming the VOB tag of a UCM Component.

Note: The Component root directory in a Multiple Component VOB cannot be renamed, see technote 1135606.

Renaming a UCM Baseline

How to use cleartool rename to rename a ClearCase UCM Baseline, see technote 1146277.

The label type of the baseline must be renamed separately, see technote 1251401.

Renaming a UCM Activity

How to change the name of a ClearCase UCM activity from the graphical user interface or command line interface, see technote 1123180.

45. How do I - trac ing the UCM integration with ClearQuest on UNIX or Linux

To trace the ClearCase UCM integration with ClearQuest, the following environment variables need to be set:

CQ_DIAG_TRACE

CQ_DIAG_REPORT

CQ_DIAG_OUTPUT

SQUID_TRACE

SQUID_TRACE_FILE

Example (c shell on UNIX or Linux):

setenv CQ_DIAG_TRACE "DB_CONNECT=3;THROW;SQL=3;CQINTSVR"

setenv CQ_DIAG_REPORT "MESSAGE_INFO=0X1309"

setenv CQ_DIAG_OUTPUT "/tmp/CQ_SQUID.log"

setenv SQUID_TRACE "*"

setenv SQUID_TRACE_FILE "/tmp/CQ_SQUID.log"

Example (k shell on UNIX or Linux):

export CQ_DIAG_TRACE="DB_CONNECT=3;THROW;SQL=3;CQINTSVR"

export CQ_DIAG_REPORT="MESSAGE_INFO=0X1309"

export CQ_DIAG_OUTPUT="/tmp/CQ_SQUID.log"

export SQUID_TRACE="*"

export SQUID_TRACE_FILE="/tmp/CQ_SQUID.log"

Note: These variables will enable the ClearQuest and SQUID tracing. Make sure that the values for CQ_DIAG_OUTPUT and SQUID_TRACE_FILE are the same location. You can use any valid CQ Diagnostic flags for the CQ_DIAG_* parameters.

Once the variables are set, run the command again that had failed. If you need to use the GUI such as xclearcase or clearquest, launch the GUI from the same shell that you used to set the Env variables.

46. How do I - complete a posted UCM deliver

Attempts to resume a posted delivery results in the following error:

Merge Manager: Error: Invalid name:                              
"deliver.replicaname:developerstream_A.20070613.175858".  
Merge Manager: Error: Unable to create an integration activity.  
Merge Manager: Error: Unable to create integration activity.    
Merge Manager: Error: Unable to do integration.

The source stream was renamed during a MultiSite import and now has a 'Replicaname:' as part of the stream name. The colon is the problem; colon's are not allowed in named objects on Microsoft® Windows®.

The rename that took place is a function of ClearCase MultiSite which is used to avoid naming conflicts. Review the ClearCase MultiSite Administrator's Guide on the topic of Resolving conflicts among type objects for more information.

Solution

1. Cancel the deliver.

2. Rename the stream at the remote site which posted the deliver.

3. Start a new deliver operation.

47. How do I - initiate a UCM Delivery from the ClearCase Explorer

INSTRUCTIONS: Initiating and completing a UCM Delivery from ClearCase Explorer:

1. To initiate a UCM Deliver from the ClearCase Explorer right click the view and select Deliver from Stream to Default...

2. The Deliver from Stream Preview will appear displaying any undelivered activities. After checking the Activities you want to deliver click OK

Note: Other activities might appear due to activity dependencies. Review technote 1134482 for additional information on Activity dependencies

3. After clicking OK, a Delivering to View 'xxxxx' dialog box will appear showing what elements are being merged in this deliver operation.

4. After all the elements have been merged, click OK in the Deliver from stream - Merges Complete dialog box

5. Complete the delivery by clicking Complete

6. After selecting Complete, all the remaining checkouts created during the delivery will be checked in

Click Close to exit the Deliver

48. How do I - find UCM posted deliveries

ABOUT UCM POSTED DELIVERIES

A Posted Delivery occurs when a UCM project is in a MultiSite® replicated environment.
The Target Stream of the deliver is mastered at an alternate site from that of the Source Stream.
Note: The delivery must begin from a source DEVELOPMENT stream. A posted deliver is not allowed when the source of the deliver is an Integration Stream.

Considerations to understand about posted deliveries.

• Mastership of the Source Stream will be pushed to the site it is Posted the deliver to
• The Source Stream must be a development stream
• The Target Stream must be mastered at an alternate site
• The Target Site must be in sync with the source site to know about all changes being posted
• Once the Deliver occurs it must be completed from the Target site where both Streams (development and integration stream) are mastered
  
  Note: The completion of the Deliver clears the necessary process variables (PVARs on the target integration activity, and on the source stream). The clearing of these PVARs is a main reason why the target site must retain mastership while resuming and completing the delivery.
• Once the deliver is completed, Mastership of the source stream is then transferred back to the originating site of the deliver
• Synchronizing after this process should be done so both sites know about changes and cleared process variables.

FIND UCM POSTED DELIVERIES

FIND POSTED DELIVERIES FROM THE COMMAND LINE

From the command line you can find out which deliveries have been posted for a particular stream by executing the cleartool deliver -status -stream <stream-selector> command on the source stream.

%>cleartool deliver -status -stream dev1@/pvob
Deliver operation in progress on stream "stream:dev1@/pvob"
Started by "user1" on "27-May-03.14:34:15"
The integration activity has not been created.
The target view has not been specified.
Activities will be delivered to stream "stream:Integration@\pvob"
in the current project "project:proj1@\pvob".
Operation posted from replica "replica_1" is ready to integrate at replica "original".

Baselines to be delivered:
baseline:deliverbl.dev1_2.20030527.143415@\pvob        
component:comp1@\pvob
Activities included in this operation:
activity:post_me@\pvob

COMPLETE POSTED DELIVERIES

From the command line you can complete deliveries that have been posted for a particular stream by executing the cleartool deliver -complete -stream <stream-selector> command on the source stream.

%>cleartool deliver -complete -stream dev1@/pvob -to proj1_integration
Integrate POSTED deliver
FROM: stream "dev1"
TO: stream "Integration"
Using target view: "dev1_integration".
Do you wish to continue with this deliver operation?  [no] yes
.

.

Are you sure you want to complete this deliver operation?  [no] yes
Deliver has completed
FROM: stream "dev1"
TO: stream "Integration"
Using target view: "dev1_integration".

IMPORTANT: Once a posted delivery integration is initiated, the target view used for the merge can not be changed until the deliver is cancelled or completed. The Integration activity used for the deliver is set to a specific view.

FIND POSTED DELIVERIES FROM PROJECT EXPLORER

In ClearCase Project Explorer, select an integration stream which contains the source stream, then either:

1. Go to Tools > Find Posted Deliveries

OR

2. Right-click the stream > select Find Posted Deliveries

KNOWN ISSUES

• If a Posted delivery hangs in a way that it can not be completed or resumed, the ucmutil tool supplied with ClearCase can be used to clear the necessary PVARs. Review technote 1237620 for more details about the ucmutil tool.

• The ucmutil tool must be used at the mastering site of the integration activity as well as the source stream.
• If the Delivery was posted successfully, you should be able to use the ucmutil at the target site to clear both the activity and the source streams pvars.
• Unable to complete a posted delivery on Unix that was posted from a Windows hosted replica.
  Refer to defect APAR PK04586 for additional information about the issue and a workaround.
• When a posted deliver is performed from a stream to a child stream at another replica, the deliver cannot be found on the target stream.
  The posted deliver can be found on the parent stream of the target stream.

49. How do I - determine which projects are associated with a specific UCM component

There is no direct command that can be used to determine which UCM component is associated with a UCM project. The component is associated with a Project VOB and the project is stored in Project VOB.

To determine what project is associated with a component, you can run a cleartool lsbl -tree -component command.

Example:

• Listing of all the projects:
  M:\proj_int>cleartool lsproject -invob \pvob
  12-Jun-07.18:27:25  proj  user1
  19-Jun-07.14:56:24  TestProject  user1
  20-Jun-07.15:29:03  rootless1  user1
  02-Jul-07.13:12:47  comp_proj  user1
  05-Jul-07.16:25:14  mod1  user1
  05-Jul-07.16:25:47  mod2  user1
  09-Jul-07.16:28:13  baseline  user1
  10-Jul-07.18:25:37  sym_proj  user1

The output below lists all the baselines for the component "comp@\pvob". From that output you can see the "proj" project referenced in the names of the baselines.

cleartool lsbl -tree -component component:comp@\pvob
comp_INITIAL                   baseline  (initial)
  proj_dev                     stream            
    deliverbl.proj_dev.20070613.125208  baseline  
    deliverbl.proj_dev.20070613.130812  baseline  
    deliverbl.proj_dev.20070613.130937  baseline  
    deliverbl.proj_dev.20070613.154343  baseline  
    deliverbl.proj_dev.20070614.130747  baseline  
    deliverbl.proj_dev.20070615.144149  baseline  
    deliverbl.proj_dev.20070615.145038  baseline  
    deliverbl.proj_dev.20070615.150216  baseline  
    proj_6_22_2007             baseline          
  proj_Inte                    stream            
    proj_6_13_2007             baseline          
      user1_proj           stream            
        proj_6_13_2007.2025    baseline          
        deliverbl.user1_proj.20070615.145555  
    proj_6_13_2007.8456        baseline          
    proj_6_14_2007             baseline          
      user1_proj1          stream            
        deliverbl.user1_proj1.20070614.131105
        deliverbl.user1_proj1.20070614.195452
        deliverbl.user1_proj1.20070614.195627
        deliverbl.user1_proj1.20070614.195718
    proj_6_14_2007.2946        baseline          
    proj_6_14_2007.9189        baseline          
    proj_6_15_2007             baseline          
    proj_6_15_2007.9462        baseline          
    proj_6_15_2007.6276        baseline          
    proj_6_15_2007.9950        baseline          
    proj_6_15_2007.6566        baseline          
    sam                        baseline          
    proj_6_15_2007.602         baseline          
    proj_6_15_2007.7289        baseline          
    proj_6_15_2007.5852        baseline          
    proj_6_15_2007.4193        baseline          
    sam1                       baseline          
  TestProject_Int              stream            
    test                       baseline          
    test1                      baseline

50. How do I - display the record ID from the command line when using the UCM or Base ClearCase and ClearQuest integration

How do you display the Record ID of an element instead of the entire version which is attached, when using the UCM or Base IBM® Rational® ClearCase® and IBM Rational ClearQuest® integration.

Problem

Base V2 Integration desc output example:

M:\view\vob23>cleartool desc "new text document.txt@@\main\2"
version "new text document.txt@@\main\2"
 created 2007-06-19T12:20:11-04 by user.clearcase@VITAL
 Element Protection:
   User : VITAL\user : r--
   Group: VITAL\clearcase : r--
   Other:          : r--
 element type: text_file
 predecessor version: \main\1
 Hyperlinks:
   CrmRequest "defect" ->  "v2_200000002"

UCM Integration desc output example:

M:\ucmCq_project_int\ucmCq_component>cleartool desc  test.txt
version "test.txt@@\main\ucmCq_project_Int\1"
 created 2007-06-11T15:24:37-04 by plabbe.clearcase@VITAL
 Element Protection:
   User : VITAL\user : r--
   Group: VITAL\clearcase : r--
   Other:          : r--
 element type: text_file
 predecessor version: \main\ucmCq_project_Int\0
 Attached activities:
   activity:ucmCQ00000050@\ucmCQ_projectvob  "This is an integration test"

This is the result of additional switches must be added to the cleartool desc command to view the actual record ID.

Solution

To display the Record ID of an element when using the Base V2 Integration of ClearCase and ClearQuest, use the following cleartool desc command:

>cleartool desc  -s -ahlink CrmRequest "<filename>"

or

>cleartool desc -l -ahlink "<filename>"

For example:

M:\view\vob23>cleartool desc -s -ahlink CrmRequest "new text document.txt"

->  "v2_200000002"

or

M:\view\vob23>cleartool desc -l -ahlink CrmRequest "new text document.txt"
new text document.txt@@\main\2

Hyperlinks:
    CrmRequest@469@\paul23 "defect" ->  "v2_200000002"

To display the Record ID of an element when using the UCM Integration of ClearCase and ClearQuest, use the following cleartool desc command:

cleartool desc -fmt "%[activity:]%p" <fileName>


For example:
M:\ucmCq_project_int\ucmCq_component>cleartool desc -fmt "%[activity:]%p" test.txt

ucmCQ00000050

51. How do I - avoid ClearQuest Change Request/Activity prompts during file import in UCM using clearfsimport

How can the IBM® Rational® ClearCase® clearfsimport utility can be run in a UCM environment while integrated with IBM Rational ClearQuest® and not be prompted for a Change Request/Activity association for every element being imported into ClearCase.

An Activity must be set in a UCM view prior to running the clearfsimport command to avoid a prompt for each file that is imported.

WORKAROUND:

The workaround would be to have an Activity association set to the view used in the import. To set to an Activity in preparation for running clearfsimport:

1. Open a Command Prompt (Click Start > Run..., type cmd and click OK).

2. Change Directory into the UCM View that will be used for the import.

3. Change Directory into the UCM Component VOB that will be used to store the imported data.

4. Type the command cleartool lsproject -long <projectName>@<PVOBtag> (substituting your Project and PVOB names) to show the ClearQuest Record ID: and the ClearQuest User Database name: that is currently associated with the ClearCase UCM Project.

5. Run the clearfsimport command while set inside the root of the Component VOB.
Note: Include the target-VOB-directory at the end of the command
OR
If you are already set to the target-VOB-directory, then a "." needs to be at the end of the command to signify this is were you are am importing to

For example:

%>clearfsimport -recurse <local_dir_path>


Note: Where local_dir_path is the location of the files and directories you to be added into ClearCase source control.

Unable to get current foundation's closure for stream error reported during a UCM rebase operation

Attempts to rebase a UCM stream results in the following error:

Unable to get current foundation's closure for stream.  

This error indicates a possible problem with one of the stream's current foundation's baselines.

An unknown action previously occurred, possibly associated with a VOB database issue, in which a baseline was associated with two label types.

SYMPTOM:

A cleartool describe -long baseline:<baseline selector>@\<pvob> will show no label status and two hyperlinks to label types at the end of the output:

baseline "TEST.1234" created 05-Jul-07.15:37:31 by
owner: DOMAIN\jdoe
group: DOMAIN\Domain Users
component: COMP@\projects
label status:            <-----NOTE: This baseline has no label
change sets:
promotion level: INITIAL
depends on:
Attributes:
PromotionLevel =
"INITIAL"
Hyperlinks:
BaselineLbtype@463850@\projects -> lbtype:TEST.1234@\ProvOne
BaselineLbtype@464078@\projects -> lbtype:TEST.3245@\ProvOne
UseBaseline@463965@\projects <- stream:mystream@\projects

Solution

1. Check to make sure that both of these lbtypes above exist.

From a command prompt, cd into a UCM view and into the component that this baseline is associated with. Run cleartool lstype -kind lbtype -invob <vobtag>

From Type Explorer GUI verify that both lbtypes exist:

· Click Start > Programs > Rational Software > Rational ClearCase > Type Explorer.

· Click the VOB where the label type resides from the Select VOB applet.

· Click OK.

· Double click the label type folder.

· Ensure that both label types are present

If only one of the lbtypes are present, proceed to step 4.

If both lbtypes are present, then the lbtype whose name matches the baseline will be the correct one.

Remove the base BaselineLbtype hyperlink via the command prompt.

Using our example above, the command is:

cleartool rmhlink BaselineLbtype@464078


The resulting describe of the baseline will show something like the following:

baseline "TEST.1234" created 05-Jul-07.15:37:31 by
owner: DOMAIN\jdoe
group: DOMAIN\Domain Users
component: COMP@\projects
label status:            <-----NOTE: This baseline still has no label
change sets:
promotion level: INITIAL
depends on:
Attributes:
PromotionLevel =
"INITIAL"
Hyperlinks:
BaselineLbtype@463850@\projects -> lbtype:TEST.1234@\ProvOne
UseBaseline@463965@\projects <- stream:mystream@\projects

Promote the baseline to either a full or incremental label from a command prompt. In the example here, we will promote the baseline to full:

cleartool chbl -full baseline:TEST.1234@\projects

A final describe of the baseline shows that it is now labelled properly and can be used in the environment:

baseline "TEST.1234" created 05-Jul-07.15:37:31 by
owner: DOMAIN\jdoe
group: DOMAIN\Domain Users
component: COMP@\projects
label status: full
change sets:
promotion level: INITIAL
depends on:
Attributes:
PromotionLevel =
"INITIAL"
Hyperlinks:
BaselineLbtype@463850@\projects -> lbtype:TEST.1234@\ProvOne
UseBaseline@463965@\projects <- stream:mystream@\projects

52. How do I – understand about UCM Config Specs

The UCM config spec can only be viewed from the command line using the cleartool catcs or cleartool edcs command.

Each UCM config spec consists of 7 sections.

Example config spec:

ucm
identity UCM.Stream oid:5c8838ad.3afb490c.9756.18:86:8e:0e:2b:fd@vobuuid:3c52409f.717248c3.8497.1a:6c:2a:25:8f:d5 1

# ONLY EDIT THIS CONFIG SPEC IN THE INDICATED "CUSTOM" AREAS
#
# This config spec was automatically generated by the UCM stream
# "user1_Project1" at 11-Jul-06 5:29:08 PM.
#


# Select checked out versions
element * CHECKEDOUT

# Component selection rules...

element "[5deb9e438c1b4051a942a264ba0da932=\UCM_Comp1]/..." .../user1_Project1/LATEST
element "[5deb9e438c1b4051a942a264ba0da932=\UCM_Comp1]/..." /main/0 -mkbranch user1_Project1
element "[5deb9e438c1b4051a942a264ba0da932=\UCM_Comp1]/..." /main/0 -mkbranch user1_Project1

element "[9bcdcb215a214a46b34830b8bf423cce=\UCM_Comp2]/Sub1/..." /main/0 -nocheckout

element "[9bcdcb215a214a46b34830b8bf423cce=\UCM_Comp2]/Sub2/..." /main/0 -nocheckout


end ucm

#UCMCustomElemBegin - DO NOT REMOVE - ADD CUSTOM ELEMENT RULES AFTER THIS LINE
#UCMCustomElemEnd - DO NOT REMOVE - END CUSTOM ELEMENT RULES

# Non-included component backstop rule: no checkouts
element * /main/0 -ucm -nocheckout

#UCMCustomLoadBegin - DO NOT REMOVE - ADD CUSTOM LOAD RULES AFTER THIS LINE

Section1:
This section contains 2 lines:

• Line1: ucm - This is a keyword which helps to identify the view config spec as UCM related. All config specs for UCM start out with this line.
• 
  Line2: identity UCM.Stream - This line contains the OID (object identifier) of the stream and UUID (unique identifier) of the PVOB.

Section2:
This section contains the auto generated comments about the creation of the config spec.

Note: The creation time represents the time of the initial creation of the stream or the last rebase.

Section3:
This section contain the first rule that is required in all config specs in order to perform checkout operations: element * CHECKEDOUT

Section4:
This section contains the rules based on which baselines from which components are used in the stream. Instead of seeing the VOB-tag as you would in a base ClearCase view, the VOB family replica UUID is used instead.

Note: This section ends with the keywords end ucm.

Section5:
In this section you can add custom element rules.

Section6:
For all components that are not selected by the rules in Section 4 and 5, there is a backstop rule included: element * /main/0 -ucm -nocheckout

Section7:
This section provides for the load rules if a snapshot views is used.

Troubleshooting

53. How do I – use the ClearCase UCM troubleshooting template

Before any troubleshooting can begin, we need to understand the problem.
Here are some basic questions we need answered before we can proceed:

1. What is the problem?
2. What are you trying to do or avoid?
3. What is the error message (if any)?

Once the problem is determined, we can investigate the issue.
The following information can greatly assist Support in coming to a quicker resolution:

Topography: Gather information about the machines involved.

• Clients
• Views
• VOBs
• Is MultiSite involved?
• Is ClearQuest integration enabled?

Data to Collect: (for each machine above)

UNIX	WINDOWS
COMPLETE ERROR MESSAGE	COMPLETE ERROR MESSAGE
Describe & Dump of problem object	Describe & Dump of problem object
SCT tool, see technote 1208895	ClearBug, see technote 1131335
uname -a, included in SCT	WINMSD, included in Clearbug
ClearCase logs, included in SCT	ClearCase Doctor
System logs, included in SCT	Grabber, included in Clearbug
cleartool hostinfo -long -prop -full, included in SCT	cleartool hostinfo -long -prop -full, included in Clearbug

Understanding the scope of the problem:

• Is the error consistent and or reproducible?
• Does it fail for all users?
• Does it fail on all systems?
• Are there any Dangling Hyperlinks? (Run checkvob)
• Does the problem fail in the Command Line, GUI or both?
• Did this ever work?

If so: what changed?

Problem Type:

Deliver problems: Deliver related troubleshooting, see also technote 1135292.	Can the deliver be canceled? Does the deliver work from a new view? Describe and dump of the deliver activity
Activity dependency problems:	Is there version overlap in the change sets? Has there been an alternate target deliver?
Missing change sets:	Describe –long –ahlink –all <activity>
Component problems:	Does the component exist? Is it a sub-VOB component? Is it modifiable in the project?
Composite baselines problems:	What is the dependency structure? Are the components modifiable?
Elements not visible/modifiable:	What is the Baseline for the component in the stream’s configuration? Was a Baseline version removed?
Integration issues:	Run checkvob –ucm Does the problem fail in ClearCase or ClearQuest?

Reproducible test case: Request a reproducible test case if defect suspect

• Simple
• Portable

Additional Questions:
Is this an interoperability environment? See technote 1146514.

• NFS, CCFS or SMB? (Samba, TAS, Diskaccess, Hummingbird Maestro)
• If so what exact version?
• Does the same operation fail on Windows as in UNIX?
• Are the views stored on UNIX or Windows?

Is there a Network Appliance (NAS) used?

• If so, what is stored there? Pools, database, VOBs, Views?
• What vendor and OS version?

Related information

Troubleshooting UCM deliver problems
Troubleshoot ClearCase Performance with Network Monitor
Troubleshoot ClearCase Performance with Ethereal
Capture a Network Trace on Solaris
Troubleshooting ClearCase on UNIX and Windows (Interop)

54. How do I – understand about ucmutil

The ucmutil tool was created to help resolve problems or errors in Rational ClearCase UCM environments.

The use of this utility is only supported when directed by IBM Rational Client Support, and is not intended for general use without explicit guidance.

LOCATION:

This tool is found in the following directory:

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

UNIX & Linux: /opt/rational/clearcase/etc/utils

USAGE:

Usage: quit

Exit from "interactive" use of ucmutil (entered by "ucmutil" without arguments)

Usage: help [command-name]

Print this usage statement.
Specifying command-name restricts output to the usage of that subcommand

Usage: lspvar {-pvar pvar_name | -all} ucm_object_selector ...

List the value of a Process Variable.
Process Variables are UCM internal implementation objects.

Usage: setpvar -pvar pvar_name [-add] {-value pvar_value | -file file-name | -none} ucm_object_selector ...

Change the value of a Process Variable.
Process Variables are UCM internal implementation objects.
Never use this unless specifically instructed by IBM Rational Client Support.
Invalid values will cause failures in UCM.

Usage: cleanup_crm {vob_selector | project_selector}

Remove all integration links from a UCM project to a removed user database of IBM Rational ClearQuest

Usage: link_pvob [-fix] [-verbose] -from vob_selector -to vob_selector

Associate an existing UCM project VOB to an external AdminVOB.
Restrictions apply!.
Contact IBM Rational Client Support. to get full instructions.

CAUTION: IF THE PVOB IS REPLICATED, YOU SHOULD CONTACT IBM RATIONAL CLIENT SUPPORT BEFORE RUNNING THE LINK_PVOB. Multisite will warn of branches that can not be modified locally, but will still run and cause future issues. The link_pvob utility establishes an adminvob relationship between vobs, this means it should never be undone. It is best to fully understand the operation before running this utility.

Usage: sync_changeset [-fix] [-verbose] ucm_object_selector...

Verify that the changeset map of an activity correctly matches to its Change hyperlinks.
This provides a check that is not currently part of "checkvob -ucm",
for a condition where the changeset map was not updated during a checkin.

Usage: rm_stream_cspec [-update [-force]] [-recurse] ucm_stream_selector...

Remove the cached config spec information from a UCM stream object.
The config spec information can be regenerated with "chstream -generate".

Usage: reset_deliver [-fix] ucm_stream_selector

ClearCase 7.0.0 and later
Clear some problem conditions where a deliver operation can be neither completed nor canceled.

Usage: reset_rebase [-fix] ucm_stream_selector

ClearCase 7.0.0 and later
Clear some problem conditions where a rebase operation can be neither completed nor canceled.

Usage: dump_timeline [-act] -stream stream_selector -comp component_selector

ClearCase 7.0.0 and later
Display the rebase / mkbl / deliver history for a component in the context of one stream

APPROVED USE OF UCMUTIL:

The following technotes contain approved uses of this tool without the need of support assistance:

• Technote 1150472 - Disable the ClearCase UCM and ClearQuest integration
• Technote 1195482 - Re-Establishing UCM ClearCase and ClearQuest integration when the ClearQuest database had been deleted
• Technote 1117451 - Error after running the ucmutil cleanup_crm command
• Technote 1179696 - Rebase fails with integration activity change set is not empty
• Technote 1286573 - How to generate a running list of delivers and rebases on a stream

Technote 1146614 - cleartool: Error: Rebase in progress on stream

55. How do I – understand why a Deliver or Rebase fails while merging file elements

Deliver or rebase fails with messages like:

An error occurred during the Deliver operation.

An error occurred while merging file elements in the target view.

Unable to perform merge.
Unable to do integration.


Invoking the operation from the command line gives more detail:

Needs Merge <path-name> [to \main\...\<integration-stream-name>\1 from \main\...\<integration-stream-name>\<development-stream-name>\1 (base also \main\...\<integration-stream-name>\1)]
Checked out <path-name> from version "\main\...\<integration-stream-name>\1".
Attached activities:
...
cleartool: Error: Unable to get the absolute pathname of "<path-name>@@\main\...\<integration-stream-name>\<development-stream-name>\1". No such file or directory. (or "Filename too long")
Needs Merge <path-name> [to \main\...\<integration-stream-name>\CHECKEDOUT from \main\...\<integration-stream-name>\<development-stream-name>\1 base \main\...\<integration-stream-name>\1]
cleartool: Warning: Can't record a merge arrow from "<path-name>@@\main\...\<integration-stream-name>\<development-stream-name>\1" (not version from same element)


In certain IBM Rational ClearCase for Windows operations, path names are restricted to 260 characters and in the above example the version extended path name of the from version exceeds this limitation.

Solution

How to Avoid this issue:

The only way to successfully avoid any path name issues is to keep control over the length of your paths.

You can avoid any UCM related path problems, by using shorter object names (branches, labels, streams, baselines).

WORKAROUNDS:

1. Map a network drive to your dynamic views to decrease the number of characters in the path.

2. Use the subst command to map long paths to a drive letter:

Example:

C:\>subst K: M:\Joe_Smith_dynamic_view\development_VOB\directory1\directory2

Refer to technote 1120400 for information about the pathname limitations on Windows and other impacts to ClearCase.

56. How do I – understand the Unable to resolve VOB symlink issue

When rebasing a development stream, this error appears:

Unable to resolve VOB symlink "virt.46e5e94ff9024144ab0fe9ed432ce6e6" -> "..\virt" component "virt": No such file or directory.

Cause

ClearCase is seeing a broken link, virt.46e5e94ff9024144ab0fe9ed432ce6e6 , as a VOB object that it cannot completely resolve.

A cleartool ls from the command prompt will show:

virt.46e5e94ff9024144ab0fe9ed432ce6e6 --> ../virt
virt.5043bcc7c8f44439938d634bd5ba9ac2 --> ..virt [not loaded]

The above symbolic link is to a resource outside of ClearCase, which renders the hyperlink invalid for use in UCM.

Resolving the problem

Remove the broken (dangling) link from the VOB to clear the error, using the cleartool rmname command . Then the rebase operation will process without reporting the above error.

Example:

cleartool rmname virt.46e5e94ff9024144ab0fe9ed432ce6e6

Using cleartool rmname allows you to preserve the symbolic link, but remove references
to it from future directory versions. Symbolic links can be permanently removed using cleartool rmelem, refer to technote 1148781 for more details

57. How do I – understand why a rebase fails when trying to remove a component from the integration stream configuration

Rebase fails while attempting to remove a component from the integration stream configuration with the following error:

Unable to determine if there are checked out elements in the attached view 'view1_integration'.

Unable to get VOB object registry information for replica uuid "321b4951.718440dc.9d16.be:91:3f:25:39:07"
(LMIS-POD1:C:\ClearCaseStorage\VOBs\Repros.vbs): Clear Case object not found.
Operation "vob_ob_register_replica" failed: Clear Case object not found.

Cause

The VOB root was removed before removing the component from the integration stream.

Resolving the problem

Run the following command to resolve the issue:

cleartool recoverview -vob <uuid from error> -tag <viewtag from error>

Example:

cleartool recoverview -vob 321b4951.718440dc.9d16.be:91:3f:25:39:07 -tag view1_integration

Note: If the recoverview does not resolve the issue, collect the error information and attempt the workaround below.

WORKAROUND:

1. Create a new integration view and try removing the component from the integration stream configuration.

Note: When the pop-up to rebase the stream appears, ensure the new integration view is selected under 'Merge work into the following view'.

2. If the same error occurs from the new integration view with the rebase, run rgy_check -views and collect the output.

Note: The command is run from the command line interface and the output can be piped to a file. For example: C:\>rgy_check -views >c:\views.txt.

3. Attempt to remove the old integration view from the command line (cleartool rmview).

Send all the information to support.

58. How do I – understand the explanation of .contrib files left for every version just delivered in UCM

After completing a deliver or rebase operation, for any merged file versions, there will be a .contrib file left in the view context. Some of these files can be substantially large, and multiple deliveries (or rebases) will result in accumulating files like, .contrib.n.

Cause

This is currently the expected behavior. Deliver (and rebase) operations use findmerge/merge functionality for merging element versions. These methods preserve the target view's current contents to a .contrib file.

Resolving the problem

The .contrib files are generally used to compare the file's previous contents with its new after-merge version; moreover, these files are view-private and can be removed.

There has been discussion around the ability to allow the end-user to disable/enable the .contrib creation; however, with UCM, since all checkouts involved in deliver or rebase activities are reserved, there is no chance of loss changes as a result of the merge. The .contrib file, in regards to UCM, does not serve the same purpose, or hold the same significance as with base ClearCase.

Change request (RFE) RATLC00608266, was opened to improve the logic used for leaving .contrib files after a deliver or rebase operation. There is no danger for loss of data as a result of the .contrib not getting created.

This behavior has changed in ClearCase 7.0. When using the native client, contrib files are no longer generated when merges occur during deliver and rebase (the Rational ClearCase Remote Client continues to create and use these files). This information is documented in the ClearCase 7.0 Release Notes under the topic of Improvements in Unified Change Management (UCM).

Remove multiple .contrib files

The .contrib files are view-private files and can be removed using regular DOS® commands, such as del on Microsoft® Windows® or rm on UNIX® and Linux®.

Note: The following examples were performed on Windows, but similar functionality should be available for UNIX and Linux.

Set into the view, mount and cd into a VOB from the command line and run the following command to remove all contrib files from that view/VOB context.

del /s *.contrib*

Example to walk through all of the VOBs mounted in your view, and remove any file with a .contrib extension.

1. Set into the view and execute the following command:

for /R %i IN (*.contrib) do del %i

2. You may want to review the files before removing them, if so, run the following command:

for /R %i IN (*.contrib) do echo %i

More information on the for command can be found from the DOS prompt by issuing the following command:

for /?

This website is published "as is". There is no warranty of any kind (express or implied) as to the operation of our site, the accuracy of the information or the services or products referred to on it. All warranties are excluded as far as permitted at law. Neither we nor any third party will be liable for any losses or damage that may result from use of the website or as a consequence of any inaccuracies in, or any omissions from, the information which it contains.