4.1 Checking Out Elements

To modify files and directories under source control, you must check them out. Checking out does not add versions to the activity that is currently set in the view. (Checking in creates new versions, which Rational ClearCase adds to the activity's change set.)

Placing files and directories under source control is a separate procedure described in Adding Files and Directories to Source Control.

NOTE: For information on checking out VOB symbolic links in a snapshot view, see Under the Hood: VOB Links.

If your project uses the UCM-ClearQuest integration, your project manager may enable a Rational ClearQuest policy called Check Before Work On. This policy runs a customized ClearQuest script when you attempt to work on an activity. For example, your project manager may create a script that checks whether your user name matches the name in the ClearQuest record Owner field. Before you can work on the activity, you have to meet all criteria established by the Check Before Work On policy.

To Check Out Elements

To check out files and directories:

1. In a view, enter this command:

cleartool checkout -query list-of-elements

ClearCase prompts you to enter a comment.

2. Describe the changes you plan to make.

3. To finish entering comments, press RETURN, and type a period or press CTRL+D on a blank line.

You can cancel the checkout operation by entering a standard interrupt signal such as CTRL+C before typing a period or pressing CTRL+D.

cleartool checkout includes several options. These are most commonly used:

-query

Detects potential problems in the checkout process caused by inappropriate config specs or out-of-date snapshot views and prompts for action.

-nc

Prevents ClearCase from prompting for a comment.

-cq

Prompts for and applies a comment to all elements in the list.

ClearCase assigns the version you checked out to the activity currently set in your view. For more information, see the checkout reference page in the Command Reference.

Under the Hood: VOB Links

A VOB link makes a file element or directory element accessible from more than one location in the VOB namespace. There are two kinds of VOB links: symbolic links, which are available for file and directory elements, and hard links, which are available for file elements only. We recommend that you use VOB symbolic links instead of VOB hard links whenever possible.

You use the cleartool ln command to create VOB links. For more information, see the ln reference page in the Command Reference.

Symbolic Links and Hard Links in Dynamic Views

In dynamic views (which use the MVFS, or multiversion file system), VOB links behave similarly to symbolic links or hard links in a UNIX file system: symbolic links point to a file or directory element in a different location, and hard links are alternate names for a single file element.

You cannot check out a VOB symbolic link; you must check out the symbolic link target.

When you check out a hard-linked element from a specific pathname, ClearCase considers other pathnames for the element as "checked out but removed." That is, to prevent you from modifying the element from multiple pathnames, ClearCase executes standard checkout behavior at only one pathname (the one from which you entered the checkout command), but does not create view-private files at other pathnames. For information about standard checkout behavior, see the checkout reference page in the Command Reference.

Symbolic Links in Snapshot Views

Snapshot views created from a UNIX host maintain standard symbolic link behavior.

NOTE: When you create a snapshot view from a UNIX host, ClearCase assumes that the file system that contains the view supports symbolic links. If your file system does not support symbolic links, ClearCase reports errors if it encounters VOB links during the update operation.

If a load rule selects a symbolic link, ClearCase copies the link as well as the link target into the snapshot view (regardless of whether a load rule selects the link target). As with dynamic views, you cannot check out a symbolic link; you must check out the symbolic link target.

Hard Links in Snapshot Views

Instead of creating hard links in a snapshot view, each time a load rule selects a hard link, ClearCase loads the element into the view as a standard file.

Caution: Losing Data Because of VOB Hard Links

If you load multiple instances of a hard-linked element into a snapshot view, you must be careful to check out, modify, and check in only one instance of the file.When you check in a hard-linked file, ClearCase updates all other instances in your view, which could result in loss of data if you modified multiple copies of the same file. (Note that, when updating instances of files because of a checkin, ClearCase renames any hijacked file to filename.keep before updating it.)

For example, the following sequence of events will lead to lost data:

1. You check out the hard-linked file src/util.h.

2. ClearCase removes the read-only permission from util.h in the src directory only (which is the location from which you issued the checkout command).

3. You modify src/util.h but do not check it in.

4. Later, you lose track of which file you checked out. You then remove the read-only permission and modify util.h in the temp directory.

5. You check in temp/util.h. Even though you checked out and modified src/util.h, ClearCase does not prevent you from checking in temp/util.h; with a VOB hard link, temp/util.h is just another name for src/util.h.

6. Any changes you made to src/util.h are lost upon checkin because ClearCase updates all copies of duplicated files when you check in an element. Note that ClearCase does not consider any copy of util.h to be hijacked (even if you change permissions), because you checked out the element in the VOB.

Resolving Checkout Problems

You can encounter problems when attempting to check out an element. Table 2 suggests ways to resolve common problems.

Table 2 Resolution of Checkout Problems

Problem	Likely cause	Suggested resolution
Snapshot view is out of date	You are checking out a nonexplicit version, and the snapshot view is not up-to-date with the VOB. If the element being checked out were updated, a different version would be loaded.	Update the element and then check out the updated version.
Target branch is already reserved	Another view holds a reserved checkout of the target branch.	Check out the branch as unreserved.
Non-LATEST version selected	You are checking out a nonexplicit version, the config spec selects a version that is not the LATEST on the branch, and there is no mkbranch rule. This can occur because a label or a time rule selects elements.	Check out the LATEST version.
File is hijacked and does not correspond to the selected version	The file is in the hijacked/nocheckout state or the checkout explicitly specifies a different version.	Check out the hijacked file; or merge the hijacked version and the selected version, and use the merge result as the checkout data.
A mkbranch rule in the view's config spec fails and automatic branch creation fails	The branch exists. The config spec does not select the branch before specifying that the branch should be created (as it should). Or, for a dynamic view, a time rule prevents it from seeing the branch. Or, for a snapshot view, the branch was created after the view was lasted updated.	Check out the LATEST version on the branch; for an out-of-date snapshot view, this means an update of the element followed by a checkout of LATEST.