Setting Up a Work Environment

Usually when you set up a work environment, you establish 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

Adjusting your umask

Using the cleartool mkview command

Adding or modifying version-selection rules

Adding or modifying load rules in a snapshot view

If your project uses the base ClearCase-ClearQuest integration, you access one RationalClearQuest user database. Accessing a ClearQuest user database involves the following tasks:

Choosing a master schema

Setting up a profile file (.ini)

Choosing a Snapshot View or a Dynamic View

Decide whether you want to work in a snapshot view or a 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 Help. To access Help, see To Access Online Information.)

Your workstation does not support dynamic views.

You want to work with source files under ClearCase control when you are disconnected from the network that hosts the VOBs.

You want to simplify accessing a view from a workstation that is not a ClearCase host.

Your development project does not use the build auditing and build avoidance features of ClearCase.

Your development project uses build auditing and build avoidance.

You want to access elements in VOBs without copying them to your workstation.

You want the view to reflect changes made by other team members at all times (without requiring an update operation).

Choosing a Location and Name

Before creating the view, you must choose its location. For a dynamic view, you must also choose a name. This section describes the following tasks:

Choosing a location for a snapshot view

Choosing a view name

Choosing a location for a dynamic 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 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 workstations, it must be located in a directory that is accessible to the other workstations; that is, choose a disk partition that is exported.

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. You can place the view storage directory under the root directory of the snapshot view.

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_server process of the view is running.

Make sure that the view storage directory is accessible to any data backup schemes your organization institutes.

Note: If you plan to work while disconnected from the network, your administrator must set up storage locations.

Choosing a View Name

Each view must have a descriptive name (called a view tag) that is unique within a network region. Choose a view name that helps you determine the owner and purpose of the view. Names like myview or work do not describe the owner or contents of the view; if you work with more than one view, such generic names can lead to confusion. Here are some suggested names:

The name of a view 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.

Using the View Tag

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

ClearCase provides a default view tag for snapshot views based on the following convention:

user-ID_leaf-of-view-path

You do not refer to the view tag when performing most ClearCase operations. Instead you usually refer to the path of the view.

The root directory of the snapshot view contains a file, .view.dat, which provides information that ClearCase uses to perform operations on the files in the view. When ClearCase finds the .view.dat file of the view, it can determine the view tag of the view. (If you delete the .view.dat file inadvertently, see Regenerating a Snapshot View .view.dat File.)

For dynamic views, the view tag is the only name you use when performing most ClearCase operations. After setting (activating) a dynamic view, you use the view tag to refer to the root directory of the directory tree of the view. For more information, see Accessing Files and the pathnames_ccase reference page in the Command Reference.

Dynamic View: Choosing a Location for the View Storage Directory

When creating a dynamic view, you must choose a location for its view storage directory. 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.

Whether you use the clearmake build auditing and build avoidance features

The size and number of view-private files

For more information, see the Administrator’s Guide for Rational ClearCase and the clearmake reference page in the Command Reference.

Choosing Locations for Dynamic View Storage Directories

Consider the following restrictions when choosing a dynamic view storage directory location:

The directory must be located on a ClearCase host or on a Network Attached Storage (NAS) device. View processes (specifically, view_server processes) run on the computer that physically stores the view storage directory or on the computer that can access a location on a supported NAS device which contains the view storage directory. And only ClearCase hosts can run view processes.

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:

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 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 you use the view on several hosts, make sure that the location can be accessed by all those hosts; that is, choose a disk partition that is exported.

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 (with mkview –stgloc). 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.

Adjusting Your umask

Your umask(1) setting at the time you create a view affects how accessible your view is to others. For example:

A umask of 002 is appropriate for a view that you share with other users in the same group. Members of your group can create and modify view-private data; those outside your group can read view-private data, but cannot modify it. To completely exclude nongroup members, set your umask to 007.

A umask of 022 produces a view in which only you can write data, but anyone can read data.

A umask of 077 is appropriate for a completely private view. No other user can read or write view-private data.

Change your umask in the standard way. For example, enter this command from a shell:

The CCASE_BLD_UMASK Environment Variable

You can also use the CCASE_BLD_UMASK environment variable to set the umask(1) value for files created from a clearmake build script. It may be advisable to have this EV be more permissive than your standard umask—for example, CCASE_BLD_UMASK = 2, where umask is 22.

For more information about environment variables for ClearCase, see the env_ccase reference page in the Command Reference.

Creating the View with cleartool mkview

After gathering information on names and locations, open a shell and enter the cleartool mkview command as described in the following sections.

To Create a Snapshot View

Remember the path that you enter; ClearCase creates your directory tree of source files at this path.

For a complete list of mkview options, see the mkview reference page in the Command Reference.

For example, to create the pat_v1.4_cropcircle_sv view located under Pat’s home directory, enter the following command:

cleartool mkview –snapshot ~/pat_v1.4_cropcircle_sv
Selected Server Storage Location "cropcircles_view_storage”.
Created view.
Host-local path: 
BREAD:/storage/cropcircles_view_storage/pat_v1.4_cropcircle_sv.vws
Created snapshot view directory "~/pat_v1.4_cropcircle_sv".

Under the Hood: .ccase_svreg

When you create a snapshot view, ClearCase creates or modifies the file .ccase_svreg in your home directory. Do not remove or relocate this file; some ClearCase operations require it.

To Create a Dynamic View

For a complete list of mkview options, see the mkview reference page in the Command Reference.

For example, create pat_v1.4_cropcircle as a dynamic view with the following command:

Under the Hood: The cleartool Command-Line Interface

cleartool is the command-line interface (CLI) to interact with ClearCase. It has a large set of subcommands, which create, modify, and manage the information in VOBs and views.

You can use cleartool in either single-command mode or interactive mode. To use a single cleartool subcommand from a shell, use this syntax:

When entering a series of subcommands, you may find it more convenient to type cleartool without any arguments. This places you at the interactive-mode prompt:

You can then issue any number of commands, ending with quit to return to the original shell. cleartool commands can be continued onto additional lines with backslash (\), as with UNIX shells.

Command options may appear in any order, but all options must precede any nonoption arguments (typically, names of files, versions, branches, and so on).

For more information, see the cleartool reference page in the Command Reference. For information about input and output for cleartool commands, see pathnames_ccase and fmt_ccase in the Command Reference.

Adding or Modifying Version-Selection Rules

ClearCase creates a set of default version-selection rules in the initial config spec of your view. However, development projects often require team members to add specific version-selection rules. This manual assumes that someone in your organization creates these rules, and you must either copy them into your config spec or add an inclusion rule so that your config spec includes them from a config spec available over the network. For information about creating version-selection rules, see Managing Software Projects.

You can use the following procedure whenever you need to add, remove, or otherwise modify the version-selection rules of your view.

To Copy or Include Version-Selection Rules

Do one of the following:

If you work in a dynamic view, type the following command:

cleartool setview view-tag

If you work in a snapshot view, change to the root directory of the view.

Type the following command:

cleartool edcs

ClearCase opens the config spec of the view in your default text editor. For information about changing the default editor, see the env_ccase reference page in the Command Reference.

In your text editor, do any of the following:

Copy or insert the rules for your project into the config spec. The rules may be available in a text file accessible over the network, or even through e-mail. Verify with the author of the shared config spec whether you need to include any rules other than the ones you paste.

Type on its own line include path-to-shared-config-spec. Verify with the author of the shared config spec whether you need to include any rules other than the include rule.

Note: Rather than create your own config spec with an include rule, you can use cleartool setcs to use some other config spec directly. For more information, see the setcs reference page in the Command Reference.

If you work in a snapshot view, create or modify load rules. (For more information, see Snapshot View: Adding or Modifying Load Rules.)

If you work in a dynamic view, do the following:

Save the config spec and exit the text editor.

In your shell, answer Yes at the prompt for setting the config spec.

Snapshot View: Adding or Modifying Load Rules

Load rules determine which elements are copied into the snapshot view. Any projectwide config spec that you include in the config spec for your view may already contain a set of default load rules.

Listing the VOB namespace

Adding or modifying load rules

Excluding elements from loading

Listing the VOB Namespace

To create load rules, you must know the names of the elements in the VOB namespace. Because ClearCase loads directory elements recursively, you need to know only the names of parent directory elements.

VOB Namespace

In its general sense, a namespace is a set of unique names. The namespace of a file system usually consists of a hierarchical arrangement of files and directories. Each file and directory has a unique name.

In a VOB, a simple file name is not sufficient to select a single, unique object. For example, prog.c is ambiguous: does it refer to version 1 of prog.c or version 42 of prog.c?

A VOB namespace is the set of file and directory versions your config spec selects. For example, the view pat_v1.4_cropcircle_sv sees a VOB namespace of the files and directories that contribute to release 1.4 of a software product; the view pat_v1.3_cropcircle_sv sees a VOB namespace of the files and directories that contribute to release 1.3 of the same product. Because ClearCase tracks versions of directories, the VOB namespace varies depending on the versions of directories you select.

To List the VOB Namespace

Enter cleartool lsvob to see the list of VOBs at your site. For example:

cleartool lsvob –short
/guivob
/doc

To see the namespace in a VOB, enter the following command:

cleartool ls snapshot_view_path/VOB-path […]

To see further down a directory tree in the namespace, use cleartool ls recursively. For example:

cleartool ls pat_v1.4_cropcircle_sv/guivob 
pat_v1.4_cropcircle_sv/guivob/batch@@main/1 [not loaded] Rule: /main/LATEST
pat_v1.4_cropcircle_sv/guivob/src@@main/1 [not loaded] Rule: /main/LATEST
cleartool ls pat_v1.4_cropcircle_sv/guivob/batch
pat_v1.4_cropcircle_sv/guivob/batch/prog.c@@main/1 [not loaded] Rule: 
/main/LATEST
pat_v1.4_cropcircle_sv/guivob/batch/lib.c@@main/1 [not loaded] Rule: 
/main/LATEST

The annotation not loaded indicates that there are no load rules specifying the element or that the version-selection rules do not select any version of the element.

Adding or Modifying Load Rules

When editing the config spec. Any time you edit and modify the config spec for a snapshot view, ClearCase updates the entire view. This is appropriate when you first create a view, or when you modify the version-selection rules of a view, but it may be cumbersome if you only want to add a few elements to the view.

By using update –add_loadrules. The –add_loadrules option of cleartool update adds load rules to the config spec for your view but updates only the portion of the view that is affected by the new load rules.

To Add or Modify Load Rules When Editing the Config Spec

Open the config spec of a view for editing by doing the following:

Open a shell and change to a directory in the view.

Enter the following command:

cleartool edcs

ClearCase opens the config spec of the view in your default text editor.

In your text editor, use the following syntax to create load rules:

load vob-tag/element-path […]

For example, the rule load /guivob loads all files and directories in the VOB named /guivob. The rule load /guivob/batch loads only the batch directory recursively.

Save the config spec and exit the text editor.

In your shell, answer Yes at the prompt for setting the config spec.

To Add Load Rules with update –add_loadrules

The variable element-path names an element in the VOB namespace at a path that is relative to a snapshot view. For example, the following command loads all elements in a VOB named /guivob into the view pat_v1.4_cropcircle_sv:

cleartool update –add_loadrules ~/pat_v1.4_cropcircle_sv/guivob/batch/lib.c 
Loading "guivob/batch/lib.c" (100352 bytes).
Done loading "/guivob/batch/lib.c" (1 objects, copied 98 KB).
Log has been written to 
"/net/triazol/export/home/lsweeney/pat_v1.4_cropcircle_sv/update.27-Ja
n-03.13:23:16.updt".

The load rule is added at the end of the config spec and the new config spec is set.

You can also use a relative path for the element-path argument. For example, these commands load all elements in guivob:

Excluding Elements from Loading

ClearCase loads all directory elements recursively. To exclude some elements from loading, you can use an element rule in the config spec that selects the initial version of an element. For all ClearCase elements, the initial version contains no data.

To Exclude Elements

Open the config spec of the view for editing:

Open a shell and change to a directory in the view.

Enter this command:

cleartool edcs

In the text editor, create an element rule that specifies the initial version of the element you want to exclude by using the following syntax:

element vob-tag/element-path /main/0

For example, the element rule element /guivob/interface /main/0 loads the empty version of the interface directory in /guivob, preventing any of its child elements from loading.

Save the config spec and exit the text editor.

In your shell, answer Yes at the prompt for setting the config spec.

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 alternative 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 given path, ClearCase considers other paths for the element as “checked out but removed.” That is, to prevent you from modifying the element from multiple paths, ClearCase executes standard checkout behavior at only one path (the one from which you entered the checkout command), but does not create view-private files at other paths. 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. In the context of loading a snapshot view, links are treated as VOB links (those that point to objects inside the VOB) and non-VOB links (those that point outside the VOB). Hard VOB links are followed; symbolic links are copy-created. If a VOB link cannot be resolved, an error results. Non-VOB links are resolved, if possible, but it is not an error if they cannot be resolved.

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

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

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

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

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.

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.

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.

Setting Up ClearQuest User Database Defaults

If your project uses the base ClearCase-ClearQuest integration (see The Base ClearCase-ClearQuest Integration), the tasks that you perform can be associated with records in a ClearQuest user database. For each ClearQuest user database that you access, you can set up defaults for the following purposes:

Controlling the appearance of the ClearQuest client display

Receiving e-mail notification of ClearQuest user database changes

Determining the print format of result sets

Specifying start-up and operational actions

To Control the Display Appearance

You can control the appearance of the Result set and whether the SQL editor displays. To change the Result set appearance, do the following:

In the ClearQuest client, click Edit > Grid Properties. The Display Settings dialog box appears.

Select or clear an option. The Preview area shows the effect of the option setting.

To save the setting in the ClearQuest user database profile, select Save settings to profile.

Click OK.

To control the display of the SQL editor, click View and select or clear View SQL pane.

To Enable EMail Notification

Your project manager can define hooks in the ClearQuest user database to enable mail messages to be sent to users when certain state transitions occur in ClearQuest records. To provide the information for mail to reach you, do the following:

In the ClearQuest client, click View > E-mail Options. The Choose Email Provider page opens.

Select Enable Email notification to have mail messages sent to you and to have others notified of changes that you make.

In Email Provider, select the transport to use. Then click Next. The Configure Mail Server page opens.

Do one of the following:

If you selected the SMTP transport, in Outgoing SMTP Server, enter the name of the mail server that your ClearQuest administrator tells you to use.

In Your Email Address, enter the user and domain name of your mailbox (this address appears in the From field of messages triggered by your actions on a record and sent to others).

If you selected the MAPI transport, in Choose MAPI Profile, select one from the list.

Click Finish. The Configure Mail Server page closes.

In the ClearQuest client, click View > Change User Profile. The User Profile dialog box opens.

In Email, enter the user and domain name of your mailbox.

This e-mail address is used in the Send field of messages directed to you. It differs from the similar field that you enter if you use the SMTP transport. This field is useful to specify the address of a group of users who share a common interest.

Click OK.

To Set Defaults for Printing a Result Set

To support printing, you can associate a report format with a record type, tailor the appearance of the Result set, and determine the location of date and paging information at the top and bottom of report pages.

Click File > Print Preview to see the effects of the settings that are described in this section.

To Associate a Format and Record Type

To associate a report format for printing with the record type of the ClearQuest user database that you have opened, follow these steps:

In the ClearQuest client, click File > Print Record Setup. The Print Record Setup dialog box appears with the name in Record Type inactive, and, if any format association is current, the path to that format.

Click Associate Format. The Select Report Format dialog box appears.

If you have a current association, click Undo Association and select another format.

Navigate to and click the report format entry and click OK.

To Change Result Set Print Appearance

To tailor the appearance of the result set in the print output, follow these steps:

In the ClearQuest client, click File > Page Setup. The Page Setup dialog box appears.

Select and clear the desired settings

To save the setting in the ClearQuest user database profile, select Save settings to profile.

Click OK.

To Set Headers and Footers

In the ClearQuest client, click File > Headers/Footers. The Header/Footer dialog box appears.

Use the Header tab to define the alignment of text appearing at the top of each page and the Footer tab to specify the contents at the bottom of each page.

To save the setting in the ClearQuest user database profile, select Save settings to profile.

Click OK.

To Set Start-Up and Operational Defaults

When working in a ClearQuest user database, you can run queries when the database starts or can use optionally use the query wizard.

To Run Queries at Startup

In the ClearQuest client Workspace pane, right-click on a query to run and click Run at Startup. Note that you may run multiple queries at startup, but startup time increases with each query that runs.

To Use the Query Wizard

When you click Query > New Query, the Choose Record Type dialog box appears. You select a record type and click OK. If Use Query Wizard on the Query menu is clear, the Display editor tab in the Query builder pane becomes active so that you can create a query. If Use Query Wizard on the Query menu is selected, the ClearQuest Query Wizard starts.

To use the query wizard, click Query and select Use Query Wizard. The next time you create a new query, the Query Wizard starts.