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:

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

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

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

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.