Chapter 1 ClearCase Concepts

Rational ClearCase provides a flexible set of tools that your organization uses to implement its development policies. To use these tools, you need to understand the following concepts:

ClearCase views Versions, elements, and VOBs Parallel development

1.1 Recommended Reading Paths

Read this chapter first. Then, if you want to start working immediately, use online help to learn as you go. Or, if you prefer a more structured approach, use the remainder of Working in Base ClearCase as a guide through your organization's development cycle. The sections titled Under the Hood provide detailed information and suggest ways to become an advanced ClearCase user.
1.2 ClearCase Views To access files under ClearCase control, you set up and work in a view. Figure 1 shows a view named pat_v1.4_cropcircle as seen from ClearCase Explorer. Figure 1 A View as Seen from ClearCase Explorer

A view shows a directory tree of specific versions of source files. The view pat_v1.4_ cropcircle is a directory tree of source files for developing release 1.4 of the Cropcircle software product. Snapshot Views and Dynamic Views ClearCase includes two kinds of views:

Snapshot views, which copy files from data repositories called VOBs (versioned object bases) to your computer.

Dynamic views, which use the ClearCase multiversion file system (MVFS) to provide immediate, transparent access to the data in VOBs. (Dynamic views may not be available on all platforms. For more information, see ClearCase online help.)

1.3 Versions, Elements, and VOBs Each time you revise and check in a file or directory from a view, ClearCase creates a new version of it. Files and directories under ClearCase control (and all of their constituent versions) are called elements and are stored in VOBs. Figure 2 illustrates a VOB that contains the file elements prog.c, util.h, msg.cat, and lib.c. Figure 2 A VOB Contains All Versions of an Element

Depending on the size and complexity of your software development environment, ClearCase elements may be distributed across more than one VOB. For example, the elements used by the documentation group are stored in one VOB, while the elements contributing to software builds are stored in a different VOB. Selecting Elements and Versions A set of rules called a configuration specification, or config spec, determines which files are in a view. Config Specs for Snapshot Views

Config specs for snapshot views contain two kinds of rules: load rules and version-selection rules. Figure 3 illustrates how the rules in a config spec determine which files are in a view. Figure 3 Config Spec Selecting Versions

Config Specs for Dynamic Views Dynamic views use version-selection rules only (and ignore any load rules). A dynamic view selects all elements in all VOBs activated on your computer, and then uses the versionselection rules to select a single version of each element. Instead of copying the version to your computer as a standard file, the view uses the MVFS (multiversion file system) to arrange the data selected in the VOB into a directory tree. Criteria for Selecting Versions

The rules in the config spec constitute a powerful and flexible language for determining which versions are in your view. For example, version-selection rules can specify the following criteria:

The latest version. A version identified by a label.

A label is a text annotation that you can attach to a specific version of an element. Usually, your project manager attaches a label to a set of versions that contributed to a specific build. A typical config spec rule uses version labels to select versions: element * BASELINE_1 For example, if your project manager attaches version label BASELINE_1 to a version of element prog.c, any view configured with this rule selects the labeled version (unless some rule earlier in the config spec matches another version of prog.c).For more information about labels, see Managing Software Projects.

A version identified by a time rule, that is, a version created before or after a specific time.

The version-selection rules are prioritized. For example, the view can try to select a version identified by a label first, and if no such version exists, the view can select a version based on a time rule. Version Labels in Version-Extended Pathnames In addition to affecting the way the element appears in views, labeling a version of an element also provides a way to access the version with a version-extended pathname. Labeling a version effectively adds a new hard link to the version in the extended namespace. If you attach version label R4.1A to version /main/rls4/12 of element lib.c, these pathnames are equivalent: lib.c@@/main/rls4/12 lib.c@@/main/rls4/R4.1A In addition, a third pathname is usually equivalent: lib.c@@/R4.1A This version-extended pathname is valid if it is unambiguous, that is, if no other version of lib.c is currently labeled R4.1A. (This is usually the case because, by default, label types are restricted to being used once per element. See the description of the -pbranch option in the mklbtype reference page in the Command Reference.) Learning the Config Spec Syntax Usually only one or two members of your software team learn the syntax for these rules and create config specs for everyone on the project to use. For more information, see Managing Software Projects and the config_spec reference page in the Command Reference.

View-Private Objects In addition to versions of source files, a view also contains file-system objects that are not under ClearCase source control, such as temporary files that you create while developing your source files. These non-ClearCase file system objects are called view-private files and view-private directories. Figure 4 shows the pat_v1.4_cropcircle view with the objects labeled. Figure 4 A View Contains Versions of Elements and View-Private Objects

1.4 Parallel Development The combination of config spec rules, views, VOBs, and branches (described in Chapter 5, Working On a Team) provide the basis for parallel development, a strategy in which an organization can work on multiple versions of the same source file concurrently. For example, you're working on release 1.4 of a software product, and you want to experiment with the GUI as a result of feedback from usability testing. You can create a view that isolates your modifications from the rest of the release 1.4 development project. Although you work with the same set of files used in the official builds, the versions of the files that you create from this view evolve separately from the versions used in the official builds. When you're satisfied with your usability modifications, you can use ClearCase tools to merge your work with the files used in the official release 1.4 build. 1.5 About Rational ClearCase Explorer Rational ClearCase Explorer is a developer's tool that supplies a coherent, adaptable, and customizable interface to your software environment, providing:

Organization of ClearCase developer tools Access to the ClearCase environment Flexible navigation mechanisms

Using a Windows Explorer-like interface with dockable panes, ClearCase Explorer supports shortcuts to ClearCase tools, to ClearCase documentation, and to ClearCase objects.

The ClearCase Explorer Window In its initial state, the ClearCase Explorer window has three panes (Figure 5). The leftmost pane, called the Shortcut pane, is dockable and provides the Views tab to access ClearCase objects and the Toolbox tab to start ClearCase tools and configurable user tools. In the Toolbox page, rectangles at the top and bottom provide a paging mechanism to access hidden tool icons. The middle pane, called the Folder pane, is dockable and contains the tree control that displays the directory hierarchy for a given view. The rightmost pane, called the Details pane, is not dockable and contains the list control that displays the contents of a selected folder. An optional pane, called the Information pane, is not dockable. It provides context-dependent ClearCase state and processing information and access to introductory online help topics. Figure 5 A Base ClearCase View From ClearCase Explorer

ClearCase Explorer Tool Organization ClearCase Explorer supports access to tools by clicking a tab in the Shortcut pane or by rightclicking in the Folder pane or Details pane. Toolbox Tab In the Shortcut pane, ClearCase Explorer provides the Toolbox tab for finding and running both ClearCase tools and user-selectable tools and for accessing documentation. Tools are organized by tool groups divided into two pages, UCM for project-related tools and Base

ClearCase for tools not related to UCM projects. The tools provided by default are classified as developer tools. Other ClearCase tools classified as project manager or administrator tools are accessible in the Windows Taskbar by clicking Start > Programs > Rational ClearCase Administration. The Toolbox tab also presents a Getting Started page that provides access to online help information, online versions of printed documentation, and tutorials. Shortcut Menu Support ClearCase Explorer provides two types of shortcut menus:

For the ClearCase integration in the Folder pane and in the Details pane For customizing the Shortcut pane

If you right-click in the Folder pane or the Details pane, a context-sensitive shortcut menu appears offering access to file handling operations and ClearCase functions. The shortcut menu commands are activated based on the state of the item you select. You can also add tool shortcuts to your Send To folder to access your favorite integrated development environment (IDE), your favorite editor, or a command shell. Any tool shortcuts newly added to your Send To folder appear on the shortcut menu Send To command the next time ClearCase Explorer starts. If you right-click in the Shortcut pane, another type of context-sensitive shortcut menu appears enabling you to add your own tool groups and tool shortcut icons. In the Toolbox tab, the shortcut menu commands enable you to add shortcuts to your favorite tools and URLs and add page controls for your own tools. In the Views tab, with the shortcut menu, you can add and remove view shortcuts and add pages to organize view shortcut icons. And you can perform some ClearCase operations on views. The ways to do this are described in the online help. Tool Context A tool started from the Shortcut pane or from a shortcut menu command can have view context, if applicable. For example, starting the History Browser shows the event log for the currently selected element. If you start a project file (for example, a .DSW or a .VPB file) from within ClearCase Explorer, you can perform ClearCase functions from within the IDE. As you are working with ClearCase objects within the IDE, you can refresh the ClearCase Explorer display to see the state change of the elements in the Details pane. ClearCase Explorer Navigation Through the Views tab in the Shortcut pane, ClearCase Explorer provides means for accessing and navigating among ClearCase views. View Access You access a non-UCM view by clicking the General page in the Views shortcut pane. In the General page are icons for views that you own.

Clicking a view icon activates (starts) the view. ClearCase Explorer displays in the Folder pane a folder hierarchy rooted at the view-tag, and, as subfolders under the view, the contents of the view. For a dynamic view, the subfolders are for all mounted VOBs. For a snapshot view, the subfolders are for all VOBs rooted at the view. By default, in a snapshot view, only loaded elements are visible. You can change this default so that unloaded elements are displayed. The title bar shows the currently selected path within the view. As you click a subfolder, the subordinate elements display in the Details pane showing ClearCase details about the items, element and version information. In the Details pane, elements possessing unique characteristics (like a file under version control or an eclipsed version) display with visual characteristics familiar in other ClearCase tools. History of Visited Locations As you move within the Folder pane from one location to another, ClearCase Explorer stores the path for each of your visits. To return to a previously visited location, click File and, from the numbered list of pathnames (ordered most recently visited to first visited), select the pathname. Access to ClearCase Information The tree control provided in the Folder pane provides navigation to ClearCase objects in a view. Display of ClearCase Information Each view is represented as a top-level folder in the Folder pane. Expanding the subfolders provides details about the ClearCase objects accessible in the view. Selecting a folder displays fields of file system and ClearCase information in the Details pane. You can customize which fields are displayed. Because gathering some data for display takes more processing time and affects tool performance, you may not want to display all possible fields. You can also sort the data in the columns using standards Windows techniques. Any customizations you make are persistent across invocations of the tool. Initial Use and Appearance If you start ClearCase Explorer on a computer without any projects or views defined, the Shortcut pane under the Views tab contains only the General page. If you join a project, the tool creates a page under the Views tab with the project name. If you create a view associated with a project from within ClearCase Explorer, the tool creates a shortcut for that view on the page for that project. If you introduce into ClearCase Explorer a view that is associated with a project that does not have a page, the tool creates a shortcut bar for that page. For any view that you own that is not associated with a project, the tool adds to the General page an icon with the view-tag. (There is no way to tell ClearCase Explorer not to create an icon for a view that you own.) When ClearCase Explorer exits, it stores, as the default view, information about the view that you last worked in. When ClearCase Explorer starts again, it restores the default view.

Ongoing Use and Appearance Use the View menu to adjust the window appearance. Click the check boxes to toggle the display of window panes and bars. Click the Refresh commands to have ClearCase Explorer examine the system for the latest state information and re-display the information in the Folder pane and Details pane. If you remove a view that you own, its shortcut in ClearCase Explorer is removed. If you remove all the views for a project, its page in ClearCase Explorer is removed. To remove a shortcut for a view that you do not own, remove its view-tag from the registry. Features for a New User For new users, ClearCase Explorer offers an Information pane whose contents depend on the context of your work. The Information pane presents workflow help topics that outline the stages required while working in different ClearCase environments. As you work with ClearCase objects, the Information pane displays contextual information about a selected element. Included is brief information about a selected element and its current state. For example, if you select a file, the Information pane shows two columns, one listing the details of your selection and the other offering, under the heading About, informative text or, under the heading Uses, tips on some of the operations that you can perform with the selected object. In a view context in ClearCase Explorer, you can work in the Details pane where you can create a new file or directory. If you select the newly created file or directory, the Information pane tells you that you can add it to source control. If you add the file or directory to source control, the Information pane keeps the item selected and tells you that you can check it out. If you are working within a UCM project, you can select an activity; or, if you are checking an element out, you can create a new activity. If the project is enabled for ClearQuest, you can select a change request. After you become used to the environment, you can hide the Information pane to reclaim the screen area. 1.6 Extended Namespace for Elements, Branches, and Versions An element's version tree has the same form as a standard directory tree (Figure 6), which compares components of the version tree to components of a directory tree in extended namespace. As a component of the version tree, the element is the root of the directory tree in the extended namespace. The element itself appears to be a directory, which contains a single subdirectory, corresponding to the main branch. (It can also contain some version labels.) A branch in the version tree appears as a subdirectory in the extended namespace. As a directory, each branch can contain files (individual versions and version labels), directories (subbranches), and links (version labels).

A version in the version tree is a leaf name of the directory tree in the extended namespace. Each version of an element is a leaf of the directory tree. For a file element, the leaf contains text lines or binary data. For a directory element, the leaf contains a directory structure. Figure 6 Version Tree and Extended Namespace

Accordingly, any location within an element's version tree can be identified by a pathname in this extended namespace: sort.c@@ sort.c@@/main sort.c@@/main/branch1 (specifies an element) (specifies a branch) (specifies a branch)

sort.c@@/main/branch1/2 (specifies a version) doctn/.@@/main/3 (special case: extra component is required in VOB's top-level directory)

Dynamic View Access Model All ClearCase data is accessed through the MVFS, which, by default, occupies drive M: on each ClearCase host. Each active view has a name called a view-tag which appears in the root directory of M. Each active VOB has a path called a VOB-tag which appears as a subdirectory under each active view, as shown in Figure 7. Figure 7 ClearCase MVFS Namespace

From drive M, you can access VOBs using pathnames of the following form: \view-tag\vob-tag\pname-in-vob Typically, however, you do not work directly on drive M, but in the view root directory accessed by a shortcut in ClearCase Explorer. In Windows Explorer, you typically assign a drive to a view. Figure 8 shows how the MVFS namespace looks from a drive assigned to a view in the ClearCase Explorer view shortcut, with the net use command, or by clicking Tools > Map Network Drive in Windows Explorer. Figure 8 The MVFS Namespace from a Drive

From any drive, you can specify view-extended pathnames of the following form: M:\view-tag\vob-tag\pname-in-vob If you move to drive M, you are in view-extended namespace, and all VOB access is by viewextended pathnames. To eliminate any confusion that may result from unintentional use of view-extended pathnames when you are working at a command prompt, we recommend that you work from a drive letter assigned to a view. This permits you to use VOB pathnames of the following form: drive-letter:\vob-tag\vob-object-pname

in both cleartool and standard operating system commands. Furthermore, this approach is required if you want to share DOs between views at build time. 1.7 The Base ClearCase-ClearQuest Integration Rational ClearQuest is a change-request management system that can integrate with base ClearCase projects to provide extended features. These features enable you to associate change requests in a ClearQuest user database and versions of ClearCase elements on which you are working. The Base ClearCase-ClearQuest Schema and User Databases ClearQuest stores data in two databases: a schema repository and a user database. A schema defines the types of records in the database and other attributes of the database. ClearQuest stores all schemas in a schema repository. The user database stores your change-request data. The ClearQuest schema package provides additional information in your ClearQuest records to track associations with ClearCase versioned objects. To support associations between base ClearCase and ClearQuest record types, the schema repository needs to have the schema package applied to its record types and the user database used with the integration must be updated to add the new fields provided by the package. Your ClearQuest user database may include different record types for different purposes. The record type used by the SAMPL database supplied with the base ClearCase-ClearQuest integration is called a defect, but with the ClearCase schema package installed, any record type can be used. ClearCase Triggers and ClearQuest Change Requests The base ClearCase-ClearQuest integration consists of ClearCase triggers that fire when you check out a file, cancel a checkout, or check in a file. Your ClearCase administrator installs the integration triggers into each target VOB. The integration associates one or more ClearQuest change requests with one or more ClearCase versions stored in one of the target VOBs.

A single change request may be associated with more than one version. The set of versions that implement the requested change is called the change set for that request. A single version may be associated with more than one change request. These change requests are called the request set for that version.

Uses of the Base ClearCase-ClearQuest Integration The integration provides a text-based user interface for users of the cleartool command-line interface and a clearprompt pop-up window interface for users of the ClearCase GUIs such as ClearCase Explorer and Windows Explorer (on Windows computers) and ClearCase File Browser (on UNIX workstations).

The base ClearCase-ClearQuest integration has triggers on checkin, checkout, and cancel checkout operations. As a ClearCase user, you can do the following:

Associate a version with one or more change requests when you check out or check in the element. List the request sets that are associated with a project over a period of time, list the change requests associated with a specific version, and see the related hyperlinks.

As a ClearQuest user, you can do the following:

View the change set for a change request. See the files that fix a specific problem.

ClearCase administrators can do the following:

Install the related triggers in a VOB and set a policy for each VOB that determines the conditions under which you are prompted to associate versions with change requests. Specify that you are prompted on checking out a version, checking in a version, or both. Specify that prompting occurs only for some VOBs, branch types, or element types. Associations of checked-in versions with change requests can be either optional or required.

A ClearQuest administrator adds the ClearCase schema package to a ClearQuest schema. The administrator sets a policy for one or more VOBs that specifies the conditions under which you are prompted to associate versions with change requests. Chapter 2 Setting Up a View Usually you set up a separate view for each development project to which you contribute. Setting up a view involves the following tasks:

Choosing snapshot view or dynamic view Choosing a location and name Adding or modifying version-selection rules Selecting elements to load into snapshot views

NOTE: If you plan to access source files stored in UNIX VOBs, you may need to create your view in MS-DOS text mode, depending on how your shared source files handle line termination sequences. For more information, see Accessing Views and VOBs Across Platform Types. 2.1 Starting the View Creation Wizard

The View Creation Wizard assists you in each step of setting up a view. Start the View Creation Wizard and use this chapter to complete the steps. To Start the View Creation Wizard 1. Start ClearCase Explorer by clicking the shortcut on your desktop. If you did not install the shortcut, click Start > Programs > Rational ClearCase > ClearCase Explorer. 2. In the ClearCase Explorer Shortcut pane, click Toolbox. Then, click Base ClearCase > Create View. 3. The first step of the wizard asks whether you want to work on a UCM project. Click No, and then click Next. If you do want to work on a UCM project, see Working in UCM. 2.2 Choosing a Snapshot View or a Dynamic View Depending on how your computer is configured, the View Creation Wizard may ask you to choose to create a snapshot view or dynamic view. As described in ClearCase Views, snapshot views load elements onto your computer; dynamic views use the MVFS to arrange VOB data into a directory tree. (Dynamic views may not be available on all platforms. For more information, see ClearCase online help.) Work in a snapshot view when any of these conditions is true:

Your computer does not support dynamic views. You want to optimize build performance to achieve native build speed. You want to work with source files under ClearCase control when you are disconnected from the network that hosts the VOBs. You want to access a view from a computer that is not a ClearCase host. Your development project doesn't use the ClearCase build auditing and build avoidance features.

Work in a dynamic view when any of these conditions is true:

Your development project uses build auditing and build avoidance. You want to access elements in VOBs without copying them to your computer. You want the view to reflect changes made by other team members at all times (without requiring an update operation).

For more information, see the Administrator's Guide for Rational ClearCase. 2.3 Choosing a Location and Name

For a snapshot view, the View Creation Wizard prompts you to choose a location for the view. For a dynamic view, the wizard prompts you to choose a name, drive letter, and, the first time you create a dynamic view, a location for the view storage directory. Snapshot View: Choosing a Directory When creating a snapshot view, you must specify a directory into which ClearCase loads (copies) files and directories. When choosing a directory for the view, consider these constraints:

The view's root directory must be located on a disk with enough space for the files loaded into the view and any view-private files you add. Your organization may restrict where you can create a view. For example, you may be required to use a disk that is part of a data-backup scheme. If you want to access the view from other computers, it must be located in a shared directory.

If your makefiles or other files require absolute pathnames with a specific drive letter, assign the view to a drive letter. See Assigning Snapshot Views to Drive Letters. Under the Hood: A Snapshot View Storage Directory Every snapshot view has a view storage directory in addition to the directory tree of source files that it loads from VOBs. ClearCase uses the snapshot view storage directory to keep track of such information as which files are loaded into your view and which versions are checked out to it. The view storage directory is for ClearCase administrative purposes only. Do not modify anything in it. For every 1,000 elements loaded into the view, ClearCase uses about 400 KB of disk space for the view storage directory. Locations for Snapshot View Storage Directories Usually, your ClearCase administrator sets up a storage location, which is a directory on a ClearCase server host on UNIX or Windows. By default, ClearCase locates snapshot view storage directories there. If your ClearCase administrator sets up more than one storage location, ClearCase selects any one of these locations as the default when you create a view. If your ClearCase administrator does not set up storage locations, by default, ClearCase software locates the view storage directory under the root directory of the snapshot view. You can override these defaults. If your administrator sets up multiple storage locations, you can select one explicitly. If your ClearCase host is set up to store view storage directories (which happens when you install ClearCase), you can place the view storage directory under the root directory of the snapshot view. Or you can choose another location.

If you place the view storage directory under the root directory of the view, be aware of the following recommendations:

Do not choose this configuration if you use the view when disconnected from the network. You can corrupt the data in the view storage directory if you disconnect it from the network while the view's view_server process is running. Make sure that the view storage directory is accessible to any data backup schemes your organization institutes.

If you override the default and place the view storage location under a directory other than the root directory of the view, the directory must be below a shared network directory on a ClearCase host running Windows NT or Windows 2000 and must remain connected to the network. (A view process runs on the machine that physically stores the view storage directory, and only a ClearCase host running on Windows NT or Windows 2000 can run a view process.) The pathname for the directory must not use a Windows special share name, for example, the share that is designated by drive-letter$ and allows an administrator access to a drive over the network. The directory cannot be on a removable storage device or on a laptop. NOTE: If you plan to work while disconnected from the network, or if your ClearCase host is not set up to store view storage directories, your administrator must set up storage locations. To Override the Default Value for a Snapshot View Storage Location 1. When creating a view, on the step of the wizard that asks you to choose a location for a snapshot view, click Advanced Options. 2. In the Advanced View Options dialog box, do one of the following:
o

If Use Server Storage Location is selected and your administrator created multiple locations, ClearCase selects one for you. To choose a different one, click the name of the location. If your computer is set up to store view storage directories and you want to locate the view storage directory in the root directory of the snapshot view or choose another location, select Use explicit path.

Do not select this option if you plan to use the view while disconnected from the network. 3. If you select Use explicit path, do one of the following:
o o o

Accept the default path displayed in the View storage location box. Edit the path in the View storage location box to specify a valid location. Click Browse and choose a valid location.

4. Click OK to return to the view location step of the wizard.

Choosing a View Name Each view must have a descriptive name (called a view-tag) that is unique within a network region. For dynamic views, the View Creation Wizard suggests a view-tag based on the following convention: username_view. This name is designed to help you determine the owner and purpose of the view. Names like myview or work do not describe the view's owner or contents; if you work with more than one view, such generic names can lead to confusion. Here are some suggested names: pat_v1.4_cropcircle Personal view for a user named Pat to develop source files for release 1.4 of the Cropcircle product 1.3_fix Shared view for use in a particular bug-fixing task

A view's name must be a simple name; that is, it must follow the format of a single file or directory name with no special characters or spaces. Dynamic View: Choosing a Drive Letter If your makefiles or other files require absolute pathnames, assign your view to a drive letter. When you use a wizard to create a view, ClearCase prompts you to assign the dynamic view to a drive letter. After creating a view, if you want to change a drive-letter assignment or assign a drive letter to a team member's view, you can create or modify the assignment while adding a view shortcut to ClearCase Explorer. In addition, you can create or modify drive-letter assignments from Windows Explorer. Any changes you make to a view's drive-letter assignments outside ClearCase Explorer will invalidate the view's shortcut in ClearCase Explorer. Pathname Differences In Windows Explorer, you can access any dynamic view that is started on your computer from the dynamic-views-drive (by default, drive M). However, when you access a view from the dynamic-views drive, its pathname includes one more component than when you access a view from an assigned drive letter (Figure 9). For example, both of the following pathnames are available to an element in the pat_v1.4_cropcircle dynamic view that is assigned to drive P: M:\pat_v1.4_cropcircle\guivob\lib.c P:\guivob\lib.c Figure 9 Dynamic Views Started on a Host

Dynamic View Storage Directories If this is the first time you're setting up a dynamic view, ClearCase prompts you to choose a shared directory on your host as a location for the view storage directory. For dynamic views you create subsequently, ClearCase uses this location by default. Every view has a view storage directory. For dynamic views, ClearCase uses this directory to keep track of which versions are checked out to your view and to store view-private objects. The view storage directory is for ClearCase administrative purposes only. Do not modify anything in it. The size of the view storage directory depends on the following factors:

Whether you use the clearmake or omake build auditing and build avoidance features The size and number of view-private files

For more information, refer to the Administrator's Guide for Rational ClearCase and to the clearmake and omake reference pages in the Command Reference. Choosing Locations for Dynamic View Storage Directories If your computer is set up to store view storage directories, ClearCase reduces communication over the network by locating the view storage directory on your computer. Consider the following restrictions when choosing a dynamic view storage directory location:

The directory must be a subdirectory of a shared network resource on a ClearCase host on Windows NT or Windows 2000. View processes (specifically, view_server processes) run on the computer that physically stores the view storage directory, and only ClearCase hosts on Windows NT can run view processes. The pathname for the directory must not use a Windows special share name. Special share names usually include the dollar sign ($), such as the driveletter$ share name that allows an administrator to gain access to a drive over the network. For example, \\bread\c$\view\pat_1.4_cropcircle.vws is not a valid pathname.

To maintain data integrity, the view storage directory must remain connected to the network. For example, do not locate the view storage directory on a removable storage device. If you locate the view storage directory on a laptop and then disconnect the laptop from the network, all of the following restrictions apply:
o o

You cannot use the dynamic view. Team members who try to start your view from their hosts will receive error messages from ClearCase. Any clearmake or omake process that attempts to wink in a derived object from your view will spend some amount of time trying to contact your view. If it cannot contact your view, it will not consider derived objects in your view as winkin candidates for 60 minutes. (You can change the amount of time by setting the CCASE_DNVW_RETRY environmental variable.) For more information, see the clearmake reference page.

If your ClearCase administrator sets up storage locations (which are directories on ClearCase server hosts), you can locate your dynamic view storage directory in a storage location. However, for best performance, we recommend that you locate dynamic view storage directories on your local host.

We recommend that you make the view storage directory accessible to any data backup schemes your organization institutes. To Choose a Location for a Dynamic View Storage Directory 1. On the step of the wizard that asks you to choose a name and drive for a dynamic view, click Advanced Options. 2. In the Advanced View Options dialog box, do one of the following:
o

Select Use Explicit Path and provide a UNC pathname to a shared directory on a ClearCase host on Windows NT. For best performance, we recommend this option.

The first time you create a view with the wizard, ClearCase presents a template: \\currenthostname\<Share>\view-tag.vws To locate the view storage directory on your computer (recommended), replace <Share> with the name of a shared directory on your computer. For example, \\bread\view_storage\pat_v1.4_cropcircle.vws
o

Select Use Server Storage Location. If your administrator created more than one location, ClearCase selects one for you. You can choose a different one if you prefer.

Chapter 3 Working in a View

Accessing files Checking out files Working with checkouts Canceling checkouts Checking in files

3.1 Accessing Files The Views tab in ClearCase Explorer provides access to views (see About Rational ClearCase Explorer). By default, ClearCase Explorer creates shortcuts to all base ClearCase views that you own and places the shortcuts on the General page of the Views tab. Starting Dynamic Views To access files from a dynamic view, you must start the view and activate the VOBs that contain your source files. Starting the view also starts a view_server process, which maps the data in the VOBs that are activated on your computer into a directory tree. VOBs that you activate appear as subdirectories of a view. Then you browse the VOB as you would any other directory. If you assign a view to a drive letter, ClearCase starts the view when you log on to your computer. If you do not assign a view to a drive letter but have a ClearCase Explorer shortcut to the view, ClearCase starts the view when you click the shortcut. To start a dynamic view that was created from a UNIX host, you must first use the Region Synchronizer to import the view's view-tag into your Windows network region. Then, refresh the view shortcuts in ClearCase Explorer. To Start Dynamic Views 1. In the ClearCase Explorer Shortcut pane, click Views. Then, click General or the page in which the shortcut to the dynamic view resides. 2. Click the shortcut for the view. The view-tag appears as the top-level folder in the Folder pane with folders below for the active VOBs (see About Rational ClearCase Explorer). If you do not have a shortcut, refresh the view shortcuts (if you own the view or created the view-tag). To access other dynamic views from

ClearCase Explorer (for example, to access a team member's view), add a view shortcut to the Views tab. For information on creating or modifying shortcuts in ClearCase Explorer, refer to ClearCase Explorer online help. The ClearCase Explorer title bar shows the location of the view in your computer's namespace. Any command you issue from ClearCase Explorer that requires a pathname uses the pathname displayed in the title bar. If you are unable to start a dynamic view that is on another host, check with your administrator to make sure that you can access the view's view storage directory. For more information, see the Administrator's Guide for Rational ClearCase. To Activate VOBs To access files from a dynamic view, you must activate the VOBs that contain your source files. 1. On the Windows desktop, click Start > Programs > Rational ClearCase Administration > Mount VOB. 2. In the Mount dialog box, select the VOBs containing your source files. 3. Select Reconnect at Logon to activate the VOBs when you log on. 4. Click Mount. 5. In ClearCase Explorer, click View > Refresh to see the activated VOBs as folders in the Folder pane. Accessing Snapshot Views To access files from a snapshot view, use the view shortcut in ClearCase Explorer. 1. In the ClearCase Explorer Shortcut pane, click Views. Then, click General or the page in which the shortcut to the snapshot view resides. 2. Click the shortcut for the view. If you do not have a shortcut, either refresh the view shortcuts (if you own the view) or add a view shortcut (if someone else owns the view; see To Access Another's Snapshot View from ClearCase Explorer). The view-tag appears as the top-level folder in the Folder pane with folders below for the elements loaded in the view (see About Rational ClearCase Explorer). The ClearCase Explorer title bar shows the location of the view in your computer's namespace. Any command you issue from ClearCase Explorer that requires a pathname uses the pathname displayed in the title bar. If you are unable to access a snapshot view that is on another host or its storage location is on another host, check with your administrator to make sure that you can access the view's view

directory or view storage location. For more information, see the Administrator's Guide for Rational ClearCase. If you plan on working disconnected from the network, follow the guidelines in Appendix A, Working in a Snapshot View While Disconnected from the Network. Accessing Views from Windows Explorer This section describes how to access snapshot views and dynamic views from Windows Explorer. Accessing Snapshot Views from Windows Explorer A snapshot view is a directory tree in a standard file system (plus some hidden, administrative files). You can access it through Windows Explorer as you would access any other directory tree in a file system. For information on assigning a snapshot view to a drive letter, see Using the subst Command for Snapshot View Access. Accessing Someone Else's Snapshot View from Windows Explorer You can access someone else's snapshot view as you would access any other directory on another computer. If the directory's owner has shared the directory and set up the proper permissions, you can use Network Neighborhood to access the view. If you want to perform ClearCase operations in the view, see To Register Another's Snapshot View for Windows Explorer Use. Accessing Dynamic Views from Windows Explorer You can access any view that you have started on your computer from the dynamic-views-drive (by default, drive M) in Windows Explorer. If you assign the view to a drive letter, you can also access it from the drive letter in Windows Explorer. For information on assigning dynamic views to drive letters, see ClearCase online help. 3.2 Checking Out Files To modify files and directories under ClearCase control, you must check them out. (Placing files and directories under source control is a separate procedure; see Adding Files and Directories to Source Control.) If you work in an environment with the base ClearCase-ClearQuest integration, you may have to perform additional steps (see Checking Out Files in a VOB Enabled for ClearQuest). To Check Out Files 1. In ClearCase Explorer, navigate to the directory that contains the files you want to check out. Then select the files. 2. Right-click one of the selected files. On the shortcut menu, click Check Out to open the Check Out dialog box.

3. In the Check Out dialog box, provide comments describing the changes you plan to make. 4. Determine whether you want a reserved or unreserved checkout (refer to Reserved and Unreserved Checkouts). 5. Click OK. Using the Open Dialog Box The Open dialog box that many applications use is actually part of ClearCase Explorer. As illustrated in Figure 13, right-clicking a loaded version of a ClearCase element in the Open dialog box displays the ClearCase shortcut menu. To check out a file from an Open dialog box: 1. In an application such as Microsoft Notepad, click File > Open. 2. In the Open dialog box, access the file or directory that is under source control. 3. Right-click the file; then click ClearCase > Check Out. Figure 13 The ClearCase Shortcut Menu from the Open Dialog Box

Checking Out Directories Directories, as well as files, are under ClearCase source control, yet you rarely need to check out a directory explicitly. ClearCase checks out and checks in a file's parent directory when you add the file to source control.

What does it mean for a directory to be under source control? In a version-controlled directory, ClearCase creates a new version of the directory when you add or rename a file element under source control. Having versions of directories can be helpful if, for example, you rename a source file used in a particular release and then modify your makefile to reflect this change. If you need to rebuild a previous release, you can set up your view to select the version of the directory that contains the file under its previous name. NOTE: When you issue commands from a command-line interface (CLI), such as an MS-DOS command prompt, ClearCase does not check out directories automatically. When using a CLI to change a directory element, you need to check out the directory explicitly. For more information about checking out files and directories from a CLI, see the checkout reference page in the Command Reference. Reserved and Unreserved Checkouts In some version-control systems, only one user at a time can reserve the right to create a new version. In other systems, many users can compete to create the same new version. ClearCase supports both models by allowing two kinds of checkouts: reserved and unreserved. The view with a reserved checkout has the exclusive right to check in a new version for a given development project. Many views can have unreserved checkouts. An unreserved checkout does not guarantee the right to create the successor version. If several views have unreserved checkouts, the first view to check in the element creates the successor; developers working in other views must merge the checked-in changes into their own work before they can check in. Your organization's development policy may determine whether to check out reserved or unreserved. Figure 14 illustrates checked-out versions created by reserved and unreserved checkouts, and the effects of subsequent checkins. Figure 14 Resolution of Reserved and Unreserved Checkouts

Another kind of checkout is an unreserved, nonmastered checkout, which can be used only in a replicated VOB (created with Rational ClearCase MultiSite). For more information about this kind of checkout, see Sharing Control of a Branch with Developers at Other Sites. To Change the Status of a Checked-Out Version 1. In the ClearCase Explorer Details pane select a checked-out version. 2. Select the Tools menu and choose either Reserve or Unreserve. Setting the Default for Reserved or Unreserved Checkouts NOTE: Your ClearCase administrator can make this option unavailable to you. 1. In ClearCase Explorer, select Tools > Options. 2. In the Options dialog box, click ClearCase Options. 3. In the ClearCase User Options dialog box, do one of the following in the Check Out box:
o

To make reserved checkouts the default setting, select Reserved. With this selection, you can also select Unreserved if already reserved to check out unreserved by default if someone else has a reserved checkout for the same element. If you do not select this check box, attempts to reserve a reserved checkout fail.

To make unreserved checkouts the default setting, clear the Reserved check box.

For more information unreserved, nonmastered checkouts, see Setting the Default for Nonmastered Checkouts. Under the Hood: What Happens When You Check Out a File or Directory Because a snapshot view contains copies of files and directories, and a dynamic view provides access to data in VOBs, ClearCase follows different procedures for checking out from the different view types. From a Snapshot View When you use the GUI to check out a file or directory from a snapshot view, the ClearCase software handles the request as follows: 1. It gathers the following information:
o o o

The version currently loaded in the view The version selected by the config spec The latest version in the VOB

2. If the version of a file in your view is not the latest in the VOB, ClearCase asks you to specify which version to check out. For directory elements, ClearCase requires you to check out the version of the directory currently loaded in your view. The version in your view will not be the latest in the VOB if either of these conditions exist:
o o

Someone else has checked in a new version since you last updated your view. Your view's config spec selects versions based on a label or a time rule, and the latest version in the VOB falls outside those parameters (Figure 15).

3. If you check out a version other than the one currently loaded in your view, ClearCase loads the checked-out version into your view. 4. ClearCase notifies the VOB which version of the element you checked out. 5. For files, it removes the Read-Only attribute. For directories, it allows you to add new elements to source control. For information on checking out VOB links in a snapshot view, see Under the Hood: VOB Links. Figure 15 Selecting the Non-Latest Version of an Element

From a Dynamic View When you use the GUI to check out a file from a dynamic view, ClearCase handles the request as follows: 1. If your view's version-selection rules do not select the latest version in the VOB, ClearCase prompts you to choose a version to check out. Your view may not select the latest version in the VOB if, for example, your config spec selects versions based on labels or time rules (Figure 15). See Merging with the Latest Version for information about checking in a nonlatest version. 2. ClearCase notifies the VOB which version of the element you checked out. 3. For files, ClearCase creates in the view an editable view-private file, which is a copy of the checked-out version. For directories, it allows you to use add new elements to source control. Checking Out Files in a VOB Enabled for ClearQuest If the VOB in which you access versions is set up for the base ClearCase-ClearQuest integration, you may have to associate the version on which you are working with a ClearQuest change request record. For more information, see The Base ClearCase-ClearQuest Integration. Logging on to a ClearQuest User Database The first time that you attempt to check out a file from or check in a file to a VOB enabled for the base ClearCase-ClearQuest integration, you are prompted to log in to ClearQuest. Specify a ClearQuest user ID, password, and database name. ClearQuest keeps its own database of user IDs and passwords. Make sure that your ClearQuest administrator has added a user ID and password to the ClearQuest user database for you. After you log in to ClearQuest, you can use the integration to complete your checkout and checkin operations (see Using the Base ClearCase-ClearQuest Integration Interface). The

integration stores the user ID and an encoded version of the password in a file named .cqparams, which it creates in platform-specific areas. On Windows computers: <windows>\Profiles\<login>\Application Data\Rational\Cqcc\ On UNIX workstations, it is stored in the home directory. Thereafter, the integration uses the user ID and password in .cqparams instead of prompting you for them. If you change your password or connect to a different database, the next time you check out or check in a version from that VOB, the integration displays an error message and prompts you to reenter the user ID and password. The integration updates the .cqparams file with the new information. Using the Base ClearCase-ClearQuest Integration Interface If you are logged in to a ClearQuest user database (see Logging on to a ClearQuest User Database) and check out or check in a file, you see a different interface. You have the options shown in Table 1. Table 1 Base ClearCase-ClearQuest Integration Options

Option

Description

OK - commit associations

Make the requested associations and exit.

CANCEL

Exit without making any changes and cancel the related ClearCase operation.

HELP

Print this text.

REVIEW Associations

Shows currently selected associations and allows you to delete one or more items from the list.

QUERY - Select from

Displays the contents of a query that your local administrator defines to show defects that are appropriate. Depending on your local policy, you

ClearQuest Query

select one or multiple items.

TYPEIN - Enter Associations from Keyboard

Allows you to enter one or more change-request IDs directly.

DATABASE

Shows the current database name; allows you to change to a different database.

RECORD TYPE

Shows the current record type with which you are working; for example, a defect. Allows you to change to a different record type if multiple entities are supported by the current database.

PATHNAME

Shows the full path for the version that you are checking in or checking out. Select this item to see more information.

If you use a cleartool command line interface (CLI), you see a numbered menu of the options shown in Table 1. To select an option, type the number of the entry and press Enter. Some menus allow multiple choices, to which you can enter one or more number separated by a space or a comma. To dismiss the menu without making a choice, simply press Enter. If you use ClearCase Explorer or Windows Explorer, you see the ClearQuest Associations Menu provided by ClearPrompt. The dialog box opens when you check out or check in a version of an element in a VOB enabled for ClearQuest. In the dialog box, select an option from those shown in Table 1 and click Yes to continue. If multiple choices are allowed, click multiple items. Clicking the same choice a second time clears it as a choice. To close the dialog box without making a change, click Yes or Abort. Both the CLI and GUI interfaces use the same text for the choices to associate a ClearCase version with one or more ClearQuest change requests and to remove a version's existing associations with change requests. Some systems use an integration based on a Visual Basic trigger to provide a GUI. You use the Associate Change Requests dialog box to associate a ClearCase version with one or more ClearQuest change requests and to remove existing associations. To change your stored user name, password, or database name, use the Registry Editor to delete the following key: HKEY_CURRENT_USER\Software\Rational Software\ClearQuest\1.0\Common\CQIntSvr

The integration prompts you for the information the next time you checkin or checkout a version. Associating a Checkout with a ClearQuest Entity If you are required to associate versions with change requests, use the options from Table 1 to enter change-request IDs as follows:

Use the QUERY option to see a list of all open change-request IDs currently assigned to you and select one or more items from the list to make associations. Use the TYPEIN option to enter one or more change-request IDs with which to associate the version that you are checking out. Use the REVIEW option to list and possibly delete current associations. If the association is optional and you do not want to specify a change request, enter the OK option and click Yes (clearprompt) or press Enter (text menu). To cancel the checkout operation, use the CANCEL option or click Abort. To display help text, use the HELP option.

After you specify your options, use the OK option to create or update the associations your specified and complete the checkout operation. 3.3 Working with Checkouts After you check out a version, you do not need to interact with ClearCase until you're ready to check in. However, some ClearCase tools can help you with the following tasks:

Viewing an element's history Comparing versions of elements Tracking checked-out versions

Viewing an Element's History The History Browser displays the history of an element's modifications, including versioncreation comments (entered when someone checks out or checks in an element). To View an Element's History In ClearCase Explorer, right-click an element; on the ClearCase shortcut menu, click History. Comparing Versions of Elements As you modify source files, you may want to compare versions to answer such questions as these:

What changes have I made in my checked-out version?

How does my checked-out version differ from a particular historical version or from the version being used by one of my team members?

To Compare with a Predecessor In ClearCase Explorer, right-click a file. On the ClearCase shortcut menu, click Compare with Previous Version. To Compare with a Version Other Than the Predecessor 1. In ClearCase Explorer, right-click a file and click Version Tree. 2. In the Version Tree Browser, right-click a version and click Compare > with Another Version. The cursor changes to a target icon. 3. Click the version you want to compare. To Compare Any Two Files If you want to compare any two files, you can use the Diff Merge utility from a Send To menu. First, create a shortcut in your SendTo folder. Use Windows Explorer to navigate to the SendTo folder, right-click in the details pane and click New > Shortcut. In the Create Shortcut dialog box, enter cleardiffmrg.exe in the Type the location of the item box. No path is necessary. Then stop and restart ClearCase Explorer. After you create the entry in your Send To menu, right-click any file in ClearCase Explorer (also Windows Explorer or any application with a Send To menu) and click Send To > cleardiffmrg. Then, in the Open a Second File to Compare with dialog box, navigate to the second file and click Open. Diff Merge runs. This method can be used anywhere in the file system, not just within a view. Tracking Checked-Out Versions Depending on how you work, you may forget exactly how many and which files are checked out. To list all the files and directories you currently have checked out to your view: 1. In the ClearCase Explorer Folder window (middle), right-click a folder for a versioned directory and click Find Checkouts. 2. In the Find Criteria dialog box, edit the path from the root directory of the snapshot view in the Search folder box. 3. Under Include additional folders?, select Include subfolders. 4. Click OK. Prototype Builds

Typically, when you're developing source files for a project, you want to perform prototype builds to test your modifications. If your organization uses clearmake or omake, you can use these ClearCase build tools for your prototype builds; however, the build auditing and build avoidance features are available only from dynamic views. For more information, see Building Software and the clearmake or omake reference pages in the Command Reference 3.4 Canceling Checkouts If you check out a file but don't want to check in your changes or want to start with a fresh copy, you can cancel the checkout as follows: 1. In the ClearCase Explorer Details pane, select one or more checkouts. Then right-click. 2. On the shortcut menu, click Undo checkout. 3. Click Yes in the Confirm Undo Checkout dialog box. You can choose to save any of your changes in the file filename.keep. Under the Hood: Canceling Checkouts When you cancel the checkout of a file element, ClearCase handles the request as follows: 1. It prompts you to rename the file in your view to filename.keep. 2. It notifies the VOB that you no longer have the version checked out in your view. 3. In a snapshot view, it copies from the VOB the version that was in your view when you performed the checkout operation. In a dynamic view, it uses the config spec's version-selection rules to select a version. If you work in an environment with the base ClearCase-ClearQuest integration, any associations with ClearQuest change requests you may have made at checkout (see Checking Out Files in a VOB Enabled for ClearQuest) are canceled if you cancel the checkout. Canceling Directory Checkouts Although you rarely need to check out a directory explicitly, if you do and then cancel the checkout, ClearCase notifies the VOB that you no longer have the version of the directory checked out to your view. ClearCase does not prompt you to rename a canceled directory checkout to directory-name.keep. If you cancel a directory checkout after changing its contents, any changes you made with cleartool rmname, mv, and ln are lost. Any new elements you created with mkelem or mkdir become orphaned. (When you create elements from the GUI with the Add to source control command, ClearCase checks out the directory, adds the element, and checks in the directory, avoiding the creation of orphaned elements.) ClearCase moves orphaned elements (and any

data that exists in the view at the pathname of the new element) to the VOB's lost+found directory under names of this form: element-name.UUID In such cases, uncheckout displays this message: cleartool: Warning: Object "prog.c" no longer referenced. cleartool: Warning: Moving object to vob lost+found directory as "prog.c.5f6815a0a2ce11cca54708006906af65". In a snapshot view, ClearCase does not remove view-private objects or start the update operation for the directory in the view. To return the directory in your view to its state before you checked it out, you must start the Update Tool. For information on starting the Update Tool, see ClearCase online help. In a dynamic view, ClearCase does not remove view-private objects, but it does revert the view to its previous state. To Move and Delete Orphaned Elements To move an element from the lost+found directory to another directory within the VOB, use the cleartool mv command. To move an element from the lost+found directory to another VOB, use the relocate command. For more information about moving elements to another VOB, see the relocate reference page in the Command Reference. To permanently delete an element in the lost+found directory, take note of the orphaned element's name and use this command: cleartool rmelem VOB-pathname\lost+found\orphaned-element-name For example, from a dynamic view: cleartool rmelem \guivob\lost+found\prog.c.5f6815a0a2ce11cca54708006906af65 From a snapshot view: cd c:\pat_v1.4_cropcircle_sv cleartool rmelem guivob\lost+found\prog.c.5f6815a0a2ce11cca54708006906af65 NOTE: In a snapshot view, ClearCase treats the lost+found directory, which is located immediately below the root directory of a VOB, as any other directory. To load the directory in your view, you must use a load rule that specifies either the element's parent directory or the directory itself. However, as with any other directory in a snapshot view, you do not need to load the lost+found directory to issue ClearCase commands for elements in the directory. To Cancel the Checkout of a Deleted File

If you check out a file element and then delete that file from your view (by using, for example, the Delete command in ClearCase Explorer), use this procedure to cancel the checkout: 1. In ClearCase Explorer, right-click the directory containing the deleted file. 2. On the shortcut menu, click Find Checkouts. 3. Complete the Find Criteria dialog box. 4. In the Find Checkouts window, select the file whose checkout you want to cancel and click Undo Checkout. 3.5 Checking In Files Until you check in a file, ClearCase has no record of the work in your view. Checking in a file or directory element creates a new version in the VOB, which becomes a permanent part of the element's history. We recommend that you check in a file or directory any time you want a record of its current state. Ideally, your organization's development strategy isolates your checked-in work from official builds and requires you to merge your work to official project versions at specified intervals. To Check In Files 1. In ClearCase Explorer, select one or more files. 2. Right-click a selected file. On the shortcut menu, click Check In. 3. In the Check In dialog box, ClearCase displays the comments you entered when you checked out the file. You can reuse these comments or modify them. Merging with the Latest Version If the version you checked out is not the latest version in the VOB and you try to check in your modifications, ClearCase requires you to merge the changes in the latest version into the version checked out in your view (Figure 16). Figure 16 Merging with the Latest Version

In Figure 16, version 2 of prog.c is the one that you checked out. Before you check in your modifications, someone else checks in version 3 of prog.c. When you check in your modifications, ClearCase tells you that the version you checked out is not LATEST on the branch. (The section Under the Hood: What Happens When You Check Out a File or Directory describes the situations in which you may have to merge before checking in.) Note that the reserve status of the checkout is not relevant to whether your modifications can be checked in. You need to merge the latest version in the VOB (prog.c@@/main/LATEST) to the version in your view before you can check in your modifications. This merge creates a version that reconciles modifications made in the latest version with your modifications. Then, when you check in the merge results, the system sees the merge arrow from version 3 to your checkedout version containing the merge results. The checkin creates a version 3 successor, version 4 of prog.c. To Merge with the Latest Version When you issue the Check In command for a nonlatest version, you are prompted to merge. If you choose to merge, ClearCase attempts to merge automatically, starting the Diff Merge tool if it needs your input to complete the merge. For information about using Diff Merge, see ClearCase online help. After the merge, ClearCase prompts you to check in the file. Under the Hood: Checking In Files The steps ClearCase follows when you issue the checkin command vary depending on the kind of view you use. From a Snapshot View When you issue a checkin command from a snapshot view, ClearCase handles the request as follows:

1. It copies your modifications to the VOB as a new version. The version you check in remains in the view, regardless of the view's config spec. 2. It removes write permission for the file. For any other instance of the file loaded into a snapshot view, ClearCase copies the new version from the VOB into your view. (If your load rules specify an element that appears in more than one VOB location, the element is copied into each of the appropriate locations in your view's directory tree.) When you check in a symbolic-linked directory from a snapshot view, ClearCase does not update any other instances of the directory loaded in your view. As you add file elements to source control, ClearCase adds a copy of the element to all instances of a parent directory loaded in your view. From a Dynamic View When you issue the checkin command from a dynamic view, ClearCase handles the request as follows: 1. It copies your modifications to the VOB as a new version. 2. It uses the config spec's version-selection rules to select a version from the VOB. If the config spec selects a version other than the one you checked in, ClearCase displays a message. ClearCase may select another version if, for example, your view selects versions based on labels or time rules. 3. It removes the view-private file and provides transparent access to the version checked in to the VOB. Checking In Files in a VOB Enabled for ClearQuest If you use the base ClearCase-ClearQuest integration (see Checking Out Files in a VOB Enabled for ClearQuest), the version you are checking in must be associated with at least one change request; otherwise, the checkin cannot proceed. When you check in the version, the base ClearCase-ClearQuest integration displays those change-request IDs whose associations you made during checkout. Using the options in Table 1, you can do the following:

Keep the same change-request IDs.

Use the QUERY option to see a list of all open change-request IDs currently assigned to you.

Delete some or all of the change-request IDs.

Use the REVIEW option to list and possibly delete current associations.

Add new change-request IDs.

Use the TYPEIN option to enter one or more change-request IDs with which to associate the version that you are checking in. If the associations are correct, use the OK option to continue the checkin. The base ClearCase-ClearQuest integration creates associations for new change-request IDs that you add, removes associations for change-request IDs that you delete, and updates information on existing ones. View the Versions for a Change Request from ClearQuest To view the ClearCase versions associated with a ClearQuest change request: 1. In ClearQuest, run a query to find the desired set of change requests. 2. In the query result set, select a change request to display its Record form. 3. On the Record form, click the ClearCase tab. The ClearCase tab shows the last known names of the versions of ClearCase elements associated with the change request.

Chapter 5 Working On a Team

You may want to experiment with some changes to the GUI as a result of feedback from usability testing, but are not yet sure whether to include your changes in official builds. Another team may try to optimize the database schema without upsetting the current one. Another group may need to get a head start on a feature for the next release of the product.

This chapter describes the functions that Rational ClearCase provides to support parallel development, a style of working in which teams use the same set of source files for different, concurrent development projects:

Version trees Working on branches Merging Sharing control of a branch in an environment using Rational ClearCase MultiSite

(You do not need to read the section about sharing control of a branch with developers at other sites unless your project manager or MultiSite administrator directs you.) 5.1 The Version Tree Each time you revise and check in an element, ClearCase creates a new version of the element in the VOB. Throughout this part of the book, this linear progression has been illustrated with a graphic similar to Figure 19. Figure 19 Linear Progression of Versions

ClearCase can organize the different versions of an element in a VOB into a version tree. Like any tree, a version tree has branches. Each branch represents an independent line of development. Changes on one branch do not affect other branches until you merge. In Figure 20, main, pat_usability, and db_optimize are branches being used to develop different releases of the file element prog.c concurrently. Figure 20 Version Tree of a File Element

Under the Hood: The Initial Version on a Subbranch When you create a subbranch for an element, which is any branch below the main branch, the initial version contains the same data as the version from which you start the branch (Figure 21). (The initial version on the main branch contains no data. For more information, see Excluding Elements.) Figure 21 The Initial Version on a Subbranch

5.2 Working on Branches

Your organization's policies may dictate that each development project use its own branch to isolate its changes from other development projects. To adhere to this policy, each member of a project team uses a view whose config spec specifies this information:

The versions to select in the development project's specific branch. As Figure 22 illustrates, some or all source files for the project have at least one version on the specified branch. If an element does not have a version on the specified branch, other rules in the config spec select a version of the element. In Figure 22, because lib.c does not have a version on the pat_usability branch, the view selects the version on the main branch. A special make branch rule. When this view checks out a version, the make-branch rule creates the development project's branch (if it doesn't already exist).

For example, each member of the project team that is optimizing the database schema uses a view that selects versions on the db_optimize branch and creates new versions on that branch. Figure 22 Elements Have Common Branches

For more information about branches, see Managing Software Projects and the mkbranch reference page in the Command Reference. The Version-Extended Pathname ClearCase commands and documentation use a notation to specify a version of an element on a branch. For example, util.h@@\main\2 specifies version 2 of util.h on the main branch; util.h@@\main\r1_bugs\bug404\1 specifies version 1 of util.h on the bug404 subbranch below the r1_bugs subbranch, which is below the main branch (Figure 23).

Figure 23 Version-Extended Pathnames

From a command-line interface, you can use version-extended pathnames to access versions other than the ones currently selected by your view. To view the contents of a version that is not currently in a snapshot view, you must use the cleartool get command in addition to versionextended pathnames. For a full description of the syntax for version-extended pathnames, see the pathnames_ccase reference page in the Command Reference. 5.3 Merging In a parallel development environment, the opposite of branching is merging. In the simplest scenario, merging incorporates changes on a subbranch into the main branch. However, you can merge work from any branch to any other branch. ClearCase includes automated merge facilities for handling almost any scenario. One of the most powerful of ClearCase features is versioning of directories. Each version of a directory element catalogs a set of file elements and directory elements. In a parallel development environment, directory-level changes may occur as frequently as file-level changes. All the merge scenarios discussed in this chapter apply to both directory and file elements. This section describes the following merge scenarios:

Merging all changes made on a single subbranch (see Scenario: Merging All Changes Made on a Subbranch) Merging selectively from a single subbranch (see Scenario: Selective Merge from a Subbranch) Removing the contributions of some versions on a single subbranch (see Scenario: Removing the Contributions of Some Versions) Recording merges that occur outside ClearCase (see Recording Merges That Occur Outside ClearCase)

ClearCase also supports merging work from many branches to a single branch; this is typically a project manager's or integrator's task (see Managing Software Projects). Under the Hood: How ClearCase Merges Files and Directories A merge combines the contents of two or more files or directories into a new file or directory. The ClearCase merge algorithm uses the following files during a merge (Figure 24): Figure 24 Versions Involved in a Typical Merge

Contributors, which are typically one version from each branch you are merging. (You can merge up to 15 contributors.) You specify which versions are contributors. The base contributor, which is typically the closest common ancestor of the contributors. (For selective merges, subtractive merges, and merges in an environment with complex branch structures, the base contributor may not be the closest common ancestor.) If all the contributors are versions of the same element, ClearCase determines which contributor is the base contributor (but you can specify a different one). For more information about determining a base contributor, see Determination of the Base Contributor. The target contributor, which is typically the latest version on the branch that will contain the results of the merge. You determine which contributor is the target contributor. The merge output file, which contains the results of the merge and is usually checked in as a successor to the target contributor. By default, the merge output file is the checkedout version of the target contributor, but you can choose a different file to contain the merge output.

To merge files and directories, ClearCase takes the following steps: 1. It identifies the base contributor. 2. It compares each contributor against the base contributor (Figure 25). 3. It copies any line that is unchanged between the base contributor and any other contributor to the merge output file. 4. For any line that has changed between the base contributor and one other contributor, ClearCase accepts the change in the contributor; depending on how you started the merge operation, ClearCase may copy the change to the merge output file. However, you can disable the automated merge capability for any given merge operation. If you disable this capability, you must approve each change to the merge output file. 5. For any line that has changed between the base contributor and more than one other contributor, ClearCase requires that you resolve the conflicting difference. Figure 25 ClearCase Merge Algorithm

File Merge Algorithm A merge is a straightforward extension of a file comparison. Instead of displaying the differences, Diff Merge analyzes them (sometimes with your help) and copies sections of text to the output file:

Sections in which there are no differences among the contributors are copied to the output file. When one contributor differs from the base contributor, Diff Merge accepts the change and copies the contributor's modified section to the output file: ------------[changed 3-4]----|--------[changed to 3-4 file 2]--now is the thyme | now is the time for all good men | for all good people -|*** Automatic: Applying CHANGE from file 2 [lines 3-4] ============

(You can turn off automatic acceptance of this kind of change.)

When two or more contributors differ from the base contributor, Diff Merge detects the conflict, and prompts you to resolve it. It displays all contributor differences and allows you to accept or reject each one. [changed 10] | [changed to 10 file 2]--cent | sent -|[changed 10] | [changed to 10 file 3]--cent | scent |Do you want the CHANGE made in file 2? [yes] no Do you want the CHANGE made in file 3? [yes] yes Applying CHANGE from file 3 [line 10] ============

Be sure to verify that the changes you accept produce consistent merged output. For example, after performing a merge involving file util.h, you can compare files util.h.contrib (which contains its previous contents) and the new util.h (which contains the merge output). Determination of the Base Contributor If all the contributors are versions of the same element, Diff Merge determines the base contributor automatically. It examines the element's version tree, which includes all the merge arrows created by previous merge operations. This examination reveals the relationships among versions from the standpoint of their contents (which versions contributed their data to

this version?), rather than their creation order (which versions were created before this version?). Diff Merge selects as the base contributor the closest common ancestor in this enhanced version tree. Figure 26 illustrates common cases of merging. If no merges have been performed in the element, the actual common ancestor (A) of the contributors (C) in the version tree is selected to be the base contributor. Figure 26 Determination of the Base Contributor for a Merge

If the contributors are not all versions of the same element, there is no common ancestor (or other base contributor). In this case, ClearCase turns off automated merging, and you must resolve all discrepancies among the contributors. Recording of Merge Arrows Under the following conditions, the merge is recorded by creating one or more merge arrows (hyperlinks of type Merge):

All contributor files must be versions of the same file element. One of the contributors must be a checked-out version, and you must specify this version as the target to be overwritten with the merge output (the -to option in the merge command). (Alternatively, you can optionally create merge arrows without performing a merge; in this case, you do not need to check out any of the contributors.)

You must not perform the merge but suppress creation of merge arrows. You must not use any of these options: selective merge, subtractive merge, or base contributor specification (the -insert, -delete, and -base options in the merge command).

Diff Merge draws an arrow from each contributor version (except the base contributor) to the target version. You can see merge arrows with the Version Tree Browser. Locating Versions with Merge Hyperlinks The find and lsvtree -merge commands can locate versions with Merge hyperlinks. The describe command lists all of a version's hyperlinks, including merge arrows: cleartool describe util.h@@/main/3 version "util.h@@/main/3" . . . Hyperlinks: Merge@278@/vob_3 /vob_3/src/util.h@@/main/rel2_bugfix/1 -> /vob_3/src/util.h@@/main/3 Directory Merge Algorithm Each version of a ClearCase directory element contains the names of certain file elements, directory elements, and VOB symbolic links.Diff Merge can process two or more versions of the same directory element, producing a directory version that reflects the contents of all contributors. The algorithm is similar to that for a file merge. Diff Merge prompts for user interaction only when two or more of the contributors are in conflict. One of the directory versions-the merge target-must be checked out. (Typically, it is the version in your view.) Diff Merge updates the checked-out directory by adding, removing, and changing names of elements and links. NOTE: A directory merge does not leave behind a .contrib file, with the pre-merge contents of the target version. Merging Directories We recommend that you use this procedure when merging directories: 1. Ensure that all contributor versions of the directory are checked in. 2. Check out the target version of the directory. 3. Perform the directory merge immediately, without making any other changes to the checked-out version.

If you follow this procedure, it easier to determine exactly what the merge accomplished. Enter a diff -predecessor command on the checked-out version, which has just been updated by merge. Using ln and rmname in Diff Merge ClearCase implements directory merges using VOB hard links. You can use the ln and rmname commands to perform full or partial merges manually. See the ln and rmname reference pages in the Command Reference. Scenario: Merging All Changes Made on a Subbranch Merging all changes made on a subbranch is the simplest and most common scenario (Figure 27). Bug fixes for an element named opt.c are being made on branch r1_fix, which was created at the baseline version RLS1.0 (\main\4). Now, all the changes made on the subbranch are to be incorporated into main, where a few new versions have been created in the meantime. Task Overview Merging the changes from the r1_fix branch involves the following tasks: 1. Start a dynamic view or change directories to a snapshot view. The view must select the target version, which in Figure 27 is opt.c@@\main\8. 2. If the target version is checked out to your view for other revisions, create a pre-merge checkpoint by checking it in. To make it easier to find this checkpoint, consider labeling the version. 3. Use the Merge Manager to find elements with versions on a specific subbranch and automatically merge any nonconflicting differences. For example, in Figure 27, you find elements with versions on the r1_fix subbranch. In your project, several elements might have versions on the r1_fix branch. With the Merge Manager, you can choose for which elements you merge changes from one branch to another. Figure 27 Merging All Changes from a Subbranch

4. Use Diff Merge to resolve any conflicting differences between merge contributors. 5. Test the merge results in the view you start in Step #1. Then check in the target version (which contains the results of the merge). Getting More Information For detailed information about completing this task, see ClearCase online help. Scenario: Selective Merge from a Subbranch In the selective merge scenario, the project manager wants to incorporate into new development several lines of code that were added in version \main\r1_fix\4 (Figure 28). Figure 28 Selective Merge from a Subbranch

It's critical that you merge only the lines of code as written in this version: it was used and verified to fix a specific bug that prevents further development on the new project. Selective merges can be tricky: versions you exclude as contributors to the merge may contain needed revisions. For example, if the function you added in \main\r1_fix\4 relies on a variable definition that was added in \main\r1_fix\2, you must include version 2 in the merge. Merging a Range of Versions You can also specify a single range of consecutive versions to contribute to the merge. For example, if you need the variable definitions added in \main\r1_fix\2 as well as the code added in \main\r1_fix\4, you can include versions 2 through 4 in the merge. Task Overview Merging selective versions from the r1_fix branch involves the following tasks: 1. Start a dynamic view or change directories to a snapshot view. The view must select the target version, which in Figure 28 is opt.c@@\main\8. 2. If the target version is checked out to your view for other revisions, create a pre-merge checkpoint by checking it in.

3. To determine which versions contain changes that you want to merge to the target version, use the Version Tree Browser and the History Browser. In a snapshot view, use either the cleartool get command or Send To command in the Version Tree Browser or History Browser to see the contents of versions not loaded into your view. (For information about opening a version not currently in your view, see ClearCase online help.) 4. To start the merge, check out the target version, and then issue the cleartool merge command with the -insert -graphical arguments. (You cannot start a selective merge from Diff Merge.) For example, the following commands merge only the changes in version 4 on the r1_fix branch: cleartool checkout opt.c cleartool merge -graphical -to opt.c -insert -version \main\4 These commands merge only the changes in versions 2 through 4 on the r1_fix branch: cleartool checkout opt.c cleartool merge -graphical -to opt.c -insert -version \main\r1_fix\2 \main\4 5. In Diff Merge, complete the merge. Then save the results and exit. For information on using Diff Merge, refer to the online help. 6. Test the merge results in the view you start in Step #1. Then check in the target version. NOTE: In a selective merge, ClearCase does not create a merge arrow. A merge arrow indicates that all of a version's data has been merged, not parts of it. Getting More Information For detailed information about completing this task, see the merge and version_selector reference pages in the Command Reference or ClearCase online help. Scenario: Removing the Contributions of Some Versions The project manager has decided that a new feature, implemented in versions 14 through 16 on the main branch, will not be included in the product. You must perform a subtractive merge to remove the changes made in those versions (Figure 29). Figure 29 Removing the Contributions of Some Versions

Task Overview A subtractive merge is the opposite of a selective merge: it removes from the checked-out version the changes made in one or more of its predecessors. Performing a subtractive merge involves the following tasks: 1. Start a dynamic view or change directories to a snapshot view. The view must select the branch from which you want to remove revisions. 2. If the target version is checked out to your view for other revisions, create a pre-merge checkpoint by checking it in. In Figure 29, the target version is opt.c@@\main\18. 3. To determine which versions contain changes you want to remove, use the Version Tree Browser and the History Browser. From a snapshot view, use either the cleartool get command or the Send To command in the Version Tree Browser or History Browser to see the contents of versions not loaded into your view. (For information about opening a version not currently in your view, see ClearCase online help.) 4. To perform the merge, check out the target version, and then use the cleartool merge command with the -delete -graphical arguments. (You cannot start a subtractive merge from Diff Merge.) For example, the following commands remove revisions to versions 14 through 16 on the main branch: cleartool checkout opt.c cleartool merge -graphical -to opt.c -delete -version \main\14 \main\16

5. In Diff Merge, complete the merge. Then save the results and exit. For information on using Diff Merge, refer to online help. 6. Test the merge results in your view. Then check in the target version (which contains the results of the merge). NOTE: In a subtractive merge, ClearCase does not create a merge arrow. A merge arrow indicates that data has been merged, not removed. Getting More Information For detailed information about completing this task, see the merge and version_selector reference pages in the Command Reference or ClearCase online help. Recording Merges That Occur Outside ClearCase You can merge versions of an element manually or with any available analysis and editing tools. To update an element's version tree with a merge that occurs outside ClearCase, check out the target version, perform the merge with your own tools, and check it back in. Then record the merge by drawing a merge arrow from the contributors to the new version that contains the result of the merge. After you've drawn the merge arrow, your merge is indistinguishable from one performed with ClearCase tools. For example, use the following commands to merge a version of nextwhat.c on the enhance branch to the branch currently selected by your view: cleartool checkout nextwhat.c Checkout comments for "nextwhat.c": merge enhance branch . Checked out "nextwhat.c" from version "\main\1". <use your own tools to merge data into checked-out version> cleartool merge -to nextwhat.c -ndata -version ...\enhance\LATEST Recorded merge of "nextwhat.c". The -ndata option suppresses the merge but creates merge arrows as if ClearCase had merged the versions. Getting More Information For detailed information about completing this task, see the merge and version_selector reference pages in the Command Reference or ClearCase online help. 5.4 Sharing Control of a Branch with Developers at Other Sites

NOTE: This section describes how to request control of a branch from another development site. You do not need to read this section unless your project manager or MultiSite administrator directs you to. If your company uses MultiSite to distribute development among multiple geographical sites, you may share source files with developers at other sites. Each site has its own replica of the VOB, and developers work in their site-specific replica (known as the current replica). Each replica controls (masters) a particular branch of an element, and only developers at that replica's site can work on that branch. In this scenario, MultiSite branch mastership does not affect you, and you can do your work as usual. However, sometimes elements cannot have multiple branches. For example, some file types cannot be merged, so development must occur on a single branch. In this scenario, all developers must work on a single branch (usually, the main branch). MultiSite allows only one replica to master a branch at any given time. Therefore, if a developer at another site needs to work on the element, she must request mastership of the branch. NOTE: The developer can also request mastership of branch types. For more information, see the Administrator's Guide for Rational ClearCase MultiSite. For example, the file doc_info.doc cannot be merged because it is a file type for which you do not have a type manager, but developers at different sites need to make changes to it. If the branch is mastered by your current replica, you can check out the file. If the branch is mastered by another replica, you cannot check out the file. If you try to check out the file, ClearCase presents an error message:

In the graphical interface:

Branch '\main' is not mastered by the current replica. Master replica of branch is 'raleigh'. Only unreserved, nonmastered checkout is allowed at the current replica.

On the command line:

cleartool: Error: Cannot checkout branch 'main'. The branch is mastered by replica 'raleigh'. Current replica is 'lexington'. cleartool: Error: Unable to check out 'doc_info.doc'. For you to check out the file reserved or to check in the file after a nonmastered checkout, your current replica must master the branch. You can request mastership through the graphical interface or with a cleartool command. If you have permission to request mastership from the master replica of the branch, if mastership requests are enabled, and if there are no blocking conditions, then the mastership change is made at the master replica, and a MultiSite update packet that contains the change is sent to your current replica. When your current replica imports the packet, it receives mastership of the branch and you can check out the file.

NOTE: Authorizing developers to request mastership and enabling mastership requests at a replica are tasks performed by the MultiSite administrator. For more information, see the Administrator's Guide for Rational ClearCase MultiSite. When you use mastership requests to transfer control of a branch, you can use either of two methods to do your work:

Request mastership of the branch and wait for mastership to be transferred to your current replica; then perform a reserved checkout. You must use this method if you cannot or do not want to merge versions of the element. Request mastership of the branch and check out the branch immediately, using a nonmastered checkout. You may have to perform a merge before you can check in your work.

The following sections describe both methods. To Request Mastership of a Branch and Wait for the Transfer From the command line: 1. At a command prompt, enter a cleartool reqmaster command for the branch you need to check out. cleartool reqmaster -c "add info re new operating systems" ^ read_me_first.doc@@\main 2. Wait for mastership to be transferred to your current replica. To list the master replica of a branch, use describe: cleartool describe read_me_first.doc@@\main branch "read_me_first.doc@@\main" created 15-May-99.13:32:05 by sg.user branch type: main master replica: doc_lex@\doc ... In this example, your current replica is lexington in the VOB family \doc. The output of the describe command shows that lexington is the master replica of the branch, which means that you can check out the branch as reserved. 3. Perform a reserved checkout, edit the file, and check in your work. For detailed information about requesting mastership from the graphical interface, see ClearCase online help: 1. From ClearCase Explorer, click Help > Help Topics. 2. In the ClearCase Help window, click Help Topics.

3. On the Contents tab of the Help Contents window, select Developing Software with Base ClearCase > Requesting mastership of a branch > To request mastership of a branch. You can request mastership from the Find Checkouts window, the Merge Manager, or the Version Tree Browser. To Check Out the Branch Before Mastership Is Transferred If you can merge versions of the element you need to check out, you can work on the file while you wait for mastership to be transferred to your replica. To use this method from the graphical interface: 1. In ClearCase Explorer, right-click the element you want to check out and click Check Out on the shortcut menu. 2. In the Check Out dialog box, select the Unreserved if already reserved check box. 3. If the Confirm Version to Check Out dialog box is open, select the Request mastership of the branch check box and click Yes. 4. In the Request Mastership dialog box, click Request Mastership. 5. Make changes to the element. 6. Wait for mastership to be transferred to your current replica. To list the master replica of a branch, use the Property Browser: a. Right-click the element and click Version Tree on the shortcut menu. b. In the Version Tree, right-click the branch icon and click Properties on the shortcut menu. c. Click the Mastership tab. 7. Check in the element. If the checkin succeeds, you're finished. If the checkin fails because you have to perform a merge, proceed to Step #8. 8. Use the Merge Manager to merge from the latest version on the branch to your checkedout version. 9. Check in the file. To use this method from the command line: 1. Enter a reqmaster command for the branch you need to check out. cleartool reqmaster -c "fix bug #28386" prog.c@@\main\integ

2. Use cleartool checkout -unreserved -nmaster to perform a nonmastered checkout. cleartool checkout -c "fix bug #28386" -unreserved -nmaster prog.c@@\main\integ 3. Make changes to the element. 4. Wait for mastership to be transferred to your current replica. To list the master replica of a branch, use describe: cleartool describe \lib\prog.c@@\main branch "\lib\prog.c@@\main" created 15-May-99.13:32:05 by nlg.user branch type: main master replica: lib_london@\lib ... 5. Check in the element. If the checkin succeeds, you are finished. cleartool checkin -nc prog.c Checked in "prog.c" version "\main\65". If the checkin fails because you have to perform a merge, proceed to Step #6: cleartool checkin -nc prog.c cleartool: Error: The most recent version on branch "\main" is not the predecessor of this version. cleartool: Error: Unable to check in "prog.c". 6. Merge from the latest version on the branch to your checked-out version. cleartool merge -to prog.c -version \main\LATEST (if necessary, you are prompted to resolve conflicts) Moved contributor "prog.c" to "prog.c.contrib". Output of merge is in "prog.c". Recorded merge of "prog.c". 7. Check in the element. Requesting Mastership After the Checkout You can perform a nonmastered checkout, but not request mastership at the time of the checkout. You can request mastership at any time by using the reqmaster command, or by clicking Request Mastership on the shortcut menu for nonmastered checkouts available in Find Checkouts or the Merge Manager. Setting the Default for Nonmastered Checkouts You can set the default behavior of the Check Out dialog box so that you always perform a nonmastered checkout if a reserved or unreserved checkout would fail.

1. Click Start > Programs > Rational ClearCase > User Preferences. 2. Click the Operations tab. 3. Select the Unreserved, nonmastered if branch is mastered by another replica check box. When you check out an element in a replicated VOB, the Check Out dialog box opens with the Unreserved, nonmastered check box selected. When you check out an element in an unreplicated VOB, this setting is ignored. Troubleshooting If the request for mastership fails because there are checkouts on the branch at the master replica, try your request again later or ask the other developer to check in the file or directory and then try again. If you receive other errors, contact your project manager or MultiSite administrator.