Rational^® ClearCase^® and ClearCase MultiSite^®

ClearCase and MultiSite Version 2002.05.00 run on the platforms listed in Table 1.1.

This release of ClearCase does not include support for the following architectures:

This release of ClearCase is the final release that will include support for the following platforms:

Patches for ClearCase 2002.05.00 will continue to be available for Solaris Intel/x86 and Caldera UnixWare and OpenUnix, but no future product releases of ClearCase will be made available for these platforms.

For more information about differences in features and functionality by platform, see the Platform-Specific Guide in online help. To access the platform guide, go to ClearCase help and click Help Topics.

The following platforms support a ClearCase Web server:

All supported ClearCase platforms support the ClearCase Web interface. For details about the Web servers and Web browsers supported on different platforms, see Basic Software Requirements .

Table 1.2 lists the file systems that ClearCase supports for view and VOB storage. If a file system does not appear in the table, it is not supported. Inform Rational Technical Support or your sales representative of any concerns you have about this list.

The following file systems cannot be used to store any ClearCase data on any platform:

This section describes hardware requirements for installing and running ClearCase and MultiSite.

This section describes software requirements for running ClearCase and MultiSite.

Typically, correct ClearCase operation depends on your having installed a number of required or recommended operating system patches. These are available from your OS vendor. The operating system patches are cumulative. Therefore, if you install a more recent patch, it will include the fix required for ClearCase. See Table 1.6 for a list of patches recommended or required for all hosts on which ClearCase software will run. There may also be required layered packages, as listed in Layered Software Packages.

In addition to the patches listed below, which fix problems known to affect ClearCase functionality, you may require other OS vendor patches to keep your systems functioning properly. See Operating System Vendor Web Sites for information on where to obtain these patches.

ClearCase is guaranteed to be Y2K-compliant only on operating systems that are themselves Y2K-compliant.

MultiSite has no known dependencies on operating system patches.

You can find up-to-date information on operating system patches at the vendor Web sites listed in Table 1.7.

In some cases, correct ClearCase processing requires installation of a layered software package. Before installing ClearCase on a host, see Table 1.8 to determine whether you need to install any such packages.

Table 1.9 lists the Linux software version numbers supported by this release of Rational ClearCase.

This section presents information relevant to installing Rational ClearCase Version 2002.05.00 on Red Hat Linux 7.1, Red Hat Linux 7.2, kernel 2.4.x, or SuSE Linux 7.2.

Follow the instructions in the Installation Guide to install the Version 2002.05.00 software. This section describes installation steps presented after the standard installation selections.

This section presents information relevant to installing Rational ClearCase 2002.05.00 on Red Hat 7.0 Linux.

You must patch and rebuild the kernel before you can run the ClearCase MVFS (multiversion file system). Rebuilding a Linux kernel is not always straightforward because variety of hardware and the variety of configurable options are available under Linux. If you are not familiar with the process of building and rebooting the Linux kernel, we recommend that you try this before you install ClearCase. For more information on configuring and compiling the Linux kernel, see the Web site www.linuxdoc.org/HOWTO/Kernel-HOWTO.html.

Useful information is also available in the Linux release notes, which you can find in the README file in the top-level kernel source directory.

The tasks presented in the following sections must be performed before you can run the MVFS on Red Hat Linux 7.0 systems:

The Installation Guide for the ClearCase Product Family provides information necessary to install the ClearCase family of products. Here is some general information to keep in mind about upgrading:

See also Known Issues Related to Installation.

This version of ClearCase introduces a new feature level, FL3, to support some of its new functionality.

To enable Version 2002.05.00 in UCM environments, you first install Version 2002.05.00 on all systems in a specific order (for UCM, this order is different from the order required at previous releases of ClearCase and MultiSite), then raise the feature level of VOBs and PVOBs, and finally set the recommended baselines. Following is the procedure:

For more information, see the ClearCase white paper on migrating to Version 2002.05.00 on the Rational Web site, www.rational.com/support/products/clearcase.jsp.

If servers are upgraded to Version 2002.05.00 before all client systems have beem upgraded, new VOBs must be created on servers that run ClearCase Release 4.x, because Release 4.x clients cannot communicate with VOBs created on systems that run the new release.

After you upgrade the feature level on your PVOBs, you must also set the recommended baselines on integration streams that are in use. If you do not, existing development stream configurations may be unexpectedly changed when you perform a rebase -recommend command.

For more information, see the ClearCase white paper on migrating to Version 2002.05.00 on the Rational Web site, www.rational.com/support/products/clearcase.jsp.

The way in which you evaluate Version 2002.05.00 depends on which release of ClearCase you are currently running.

If you are running a 4.x release and you want to evaluate Version 2002.05.00, you can install this version on one or more test systems in your existing environment of servers, clients, views, and VOBs, and configure the test systems to use your 4.x license server.

Even the simplest ClearCase operation invokes a communications chain that can involve several components. For example, the act of checking out a file element involves a client program (running on the developer's workstation), which acts through a particular view (located on that workstation or elsewhere) and uses a particular VOB (typically located on a dedicated VOB server host). If all the components in this operation are running the same ClearCase release, compatibility is guaranteed.

Table 1.11, Table 1.12, and Table 1.13 show the compatibility paths if all hosts are not running the same ClearCase release. In these tables, client means ClearCase client software. In each table, a component in a row can use a component in a column if there is a yes at the intersection of the row and column. For example, Table 1.11 shows that a 4.x view can use a 2002.05.00 VOB or a 4.x VOB, but a 2002.05.00 view cannot use a 4.x VOB.

Specifically, these tables make two points:

In general, 4.x clients can access 4.x and 2002.05.00 servers, but 2002.05.00 clients can access only 2002.05.00 servers. A notable exception is that 2002.05.00 clients and servers will talk to 4.x albd_server s to support access to registry, license and other administrative functions.

A Version 2002.05.00 client on UNIX can access a VOB on Windows NT using a snapshot view. However, the snapshot view storage directory and the VOB storage directory must be on servers running Version 2002.05.00 or later.

ClearCase MultiSite Version 2002.05.00 is fully compatible with ClearCase Version 2002.05.00 client and server hosts:

The following sections describe compatibility restrictions and issues when different sites are running different MultiSite releases.

For detailed information about installing and licensing ClearCase and MultiSite, see the Installation Guide for the ClearCase Product Family.

This section discusses restrictions or defects that involve the installation of the ClearCase product. Take into account the information in this section before or during installation to be sure that ClearCase software or particular features are installed properly.

In the basic UCM process, the integration stream is the project's only shared work area. You may want to create additional shared work areas for developers who work together on specific parts of the project. Now you can accomplish this by creating a hierarchy of development streams. For example, you can create a development stream and designate it as the shared work area for the developers working on a particular feature. Developers then create their own development streams and views under the feature-specific development stream. In other words, the developers join the project at the feature-specific development stream level rather than at the integration stream level. The developers deliver work to the feature-specific development stream and rebase their streams to recommended baselines in that development stream.

You can now deliver work from an integration stream or a development stream in one project to an integration stream or development stream in another project. In addition, you can deliver work from one development stream to another within a project. These features make it easier to manage related areas of development within a project and parallel releases of multiple projects.

The default target for a deliver operation is the source stream's parent stream. You can also deliver work to nondefault target streams. Because any stream can now be the target of a deliver operation, this release adds several policies that you can set on streams to control what kind of deliver operations the target stream will accept. For example, you can set a policy to reject deliver operations that contain changes to components that are not in the target stream's configuration. You can set these policies at the project level so that the policy settings apply to all streams within the project, or you can set the policies on a per-stream basis.

A baseline selects one version of every element visible in a component. This release lets you create composite baselines. A composite baseline is a baseline that selects baselines from other components. By creating a composite baseline that selects baselines from every component in your project, you can use one baseline to represent the entire project.

After you create a composite baseline to represent the project, the next time you invoke the make baseline operation on the composite baseline, UCM performs the operation recursively. If a component that contributes to the composite baseline has changed since its latest baseline, UCM creates a new baseline in that component.

A composite baseline can select other composite baselines. This feature allows you to use a composite baseline to represent a system that consists of multiple projects. The system-level composite baseline can select project-level composite baselines.

You now have greater flexibility in storing components in VOBs. For example, you can now store multiple components in a VOB. Within a VOB you can make an existing directory tree into a component. The component's root directory must be the VOB's root directory or one level beneath it. To store multiple components within a VOB, each component's root directory must be one level beneath the VOB's root directory.

This version of ClearCase provides enhanced support for UCM-related GUIs, as follows:

This release adds support for triggers to the following UCM commands.

Other new features in this product release include:

This version of the ClearCase Web interface supports the UCM developer role. A developer can use the Web interface to join a project, create new activities, perform work in those activities, deliver work to an integration stream, and rebase a development stream to recommended baselines.

Performing the UCM rebase or deliver operation requires the ability to merge changes in files. The ClearCase DiffMerge tool has been implemented for this purpose within the Web interface context. The DiffMerge tool is called automatically when you do a rebase or deliver operation from within the Web interface; you can also run the Merge Manager directly from the Web interface toolbar.

ClearCase now provides workspace management capabilities for Web views which are similar to those for standard ClearCase snapshot view functionality on a local copy of element versions.

A new configuration variable has been added to the ccweb.conf file to control the length of time that elapses before an unattended ClearCase Web session times out. The new variable is -session_timeout age_in_seconds where the minimum value for age_in_seconds is 600 (10 minutes) and the default value is 14400 (4 hours).

It is now possible to specify interop text mode as a characteristic of a ClearCase Web view during the view creation process.

Installing the ClearCase Web server components is now optional; previously these components had been installed on all systems.

To install the Web Server components, select ClearCase Web Interface Server from the list of components to select for installation. The Web Interface Server components require about 3 MB of disk space.

The online help for the ClearCase Web interface has been updated to reflect the enhanced functionality of this feature. In addition, the chapter Configuring a Web Server for the ClearCase Interface in the Administrator's Guide for Rational ClearCase contains updated information on configuring the ClearCase Web server.

Forte Developer V6.0 now supports a ClearCase integration. This integration provides a set of commands and tools that allow a software development team to share, control, and track files created with Forte Developer.

Using this integration, you can check out, modify, and check in your files without leaving the Forte Developer IDE or starting another application. You can also use this integration to access files under version control.

You can access commands and tools supported by the integration from the Forte Developer's Tools menu.

The following ClearCase commands and tools are available:

The first nine commands and tools give you all the capabilities you generally need. However, when you need advanced capabilities, the last command on this list, xclearcase, gives you access to the complete set of functions of the ClearCase system.

With this version of ClearCase, the clearprompt command is included in the minimal developer installation as well as the full-function installation.

In this version of ClearCase LT, you have the option during installation of the ClearCase LT server to install support for either VOB schema 53 or 54.

clearmake now offers support to record the versions of makefiles, and optionally to have changes to them affect reuse of derived objects. Two new makefile special targets have been added: .MAKEFILES_IN_CONFIG_REC and .MAKEFILES_AFFECT_REUSE. The .MAKEFILES_IN_CONFIG_REC special target causes makefiles read by a build session to be recorded in the configuration record of all derived objects built during that build session. You can use the .MAKEFILES_AFFECT_REUSE special target to specify changes to makefiles as criteria affecting the reuse of derived objects during builds. For more information, see the Building Software manual for Rational ClearCase.

When clearmake rebuilds a target because a build script mismatch is detected, you can now use the -d and -v options to generate a print of the actual script differences to standard output.

The command clearmake -C gnu now allows special characters such as ";" to be used in macro names.

The clearmake utility now supports the use of special characters such as "$$" (as an equivalent to a literal "$") or "\%" (as the string literal "%") in target names. This has been implemented by default for -C gnu, and through the .JAVA_TGTS special target for all other compatibility modes.

Certain Clearcase applications on UNIX systems--db_server, vobrpc_server, db_loader, and the db_dumper--now access the databases as the owner of the VOB. The permissions on the database files automatically have their ownership changed to those of the vob_owner account.

chevent type triggers now fire correctly when a trigger is set on MODIFY_TYPE. The chevent operation for element triggers is now a suboperation of the MODIFY_ELEM operation rather than the MODIFY_MD and MODIFY_DATA operations that it fell under previously.

This release supports an improved Lock Manager on HP-UX 11 platforms. The Lock Manager takes advantage of a shared memory implementation to provide greater scalability and better performance under stress. For more information, see the Administrator's Guide for Rational ClearCase.

Operations that enumerate the contents of VOB or view-private directories (such as /bin/ls on UNIX, dir on Windows in a command shell or in Windows Explorer) can be accelerated by MVFS caching of the directory contents. Directory contents at the MVFS level are handled in blocks of entries. This value determines the upper limit of how many blocks can be cached per directory. The default setting of 4 blocks is enough space for approximately 600 directory entries.

For more information, see the Administrator's Guide for Rational ClearCase.

The clearimport command now checks for VOB locks before processing an element or version. If it detects a VOB lock, it shows a message indicating that the VOB is locked and that it will wait 60 seconds to retry. It remains in this state until either the VOB is unlocked or the user interrupts the import.

Beginning with this version of ClearCase, use of rmelem is restricted to the VOB owner or privileged user unless no versions have metadata (labels, attributes, or hyperlinks) and all branches were created by the user.

Removing a VOB symbolic link with the rmelem command now causes all-element rmelem triggers to fire. This works only for all-element trigger types and does not work with per-instance triggers.

The view_server now dumps and/or loads very large views. Previously it would fail to dump or load a view if the dump file exceeded 2 GB in size. The view_server now creates multiple dump files for very large views, each of which is limited to about 1 GB.

Previously, diffbl displayed confusing error messages when it failed while comparing imported baselines, initial baselines, or baselines/streams based off imported or initial baselines, to other, similar baselines or streams. These messages described the failure as resulting from the fact that the baselines or streams involved did "not share a common ancestor (initial or imported) baseline".

Now the error message describes the cause of the failure more accurately as resulting from the fact that the baselines/streams "are derived from different import baselines or the initial baseline".

xcleardiff can now compare files whose pathnames contain the "-dir" substring. Before, xcleardiff could not compare such files because the "-dir" string can be used as a keyword for a ClearCase directory comparison.

It is now possible to use the cleartool mktrtype and cleartool cptype commands for creating and copying trigger types that have locked obsolete types in the restriction list. It is also possible to use the cleartool mkeltype and cleartool cptype commands to create and copy element types whose super types are locked as obsolete.

Previously, the command cleartool describe oid:oid-number returned an extra version ID string when the version was not selected by the view. In the current version of ClearCase, it returns exactly one version ID string.

Table 2.1 lists new commands in this version of ClearCase. In addition, the clearprompt command is now available as part of the minimal developer installation.

Table 2.2 lists new options and arguments to commands in this version of Rational ClearCase.

The -title title option/argument pair, previously used by the ClearCase commands chfolder, chproject, chstream, mkfolder, mkproject, and mkstream, is obsolete at this release of the product.

In addition, the -generate old-object-selector option to the rename command is also obsolete.

The clearexport_ffile command is obsolete; use clearfsimport instead.

Redefinition of element types (mkeltype -replace) is no longer allowed in replicated VOBs.

The Command Reference is now published in a single edition for both UNIX and Windows. At the beginning of each reference page are tables that show the platforms and ClearCase Product Family products to which the interface described applies.

The READ_ME_FIRST chapter of the Release Notes for Rational ClearCase and ClearCase MultiSite (this document) has been reorganized. All the material related to basic hardware and software requirements for installing and running the products has been moved to a single section titled Hardware and Software Requirements , to make it easier for customers to prepare for installation of new versions of the products.

Large sections of material in the Command Reference have been moved to other manuals, and some material from Building Software has been moved to the Command Reference.

In previous releases, restrictions for commands were in a section called PERMISSIONS AND LOCKS. In this release, the section is named RESTRICTIONS. The section that was previously named Permissions Checking is now called Identities. There is a new section named Mastership, which describes any restrictions applied when the command is run in a replicated VOB.

The msdostext_mode reference page now describes the options -r and -f. The -r option resets the line counters for elements of type text_file that have been changed to a binary type, and the -f option forces a recalculation of the line count of all VOB objects of type text_file.

The following sections describe the changes to command output in this release.

2002.05.00

This version of ClearCase introduces a new feature level, Feature Level 3 (FL3). To support all of the new UCM functionality provided with the new release, a PVOB must be upgraded to the new feature level. Until a 2002.05.00 PVOB has been upgraded to FL3, it will support ClearCase Release 4.x clients as well as Version 2002.05.00 clients, but without providing support for all the new UCM functionality delivered with the new release.

Specifically, the following new features are not supported, even on 2002.05.00 clients accessing 2002.05.00 servers, until the feature level of the associated PVOB has been raised to FL3:

Installing this software on a PVOB server that is running a previous release of ClearCase does not automatically change the PVOB's feature level; you must raise the feature level manually. Before raising the feature level, all ClearCase clients accessing that PVOB must be upgraded to Version 2002.05.00. ClearCase UCM operations will fail on clients that run previous versions of ClearCase if they try to access a PVOB whose feature level has been upgraded to FL3.

This release of ClearCase supports the ability to change a stream's configuration from one using a modifiable component to one using a nonmodifiable one. However, we generally recommend that components initially be specified to be nonmodifiable when creating a new project. After verifying that the project builds and tests correctly, update the project policies to allow modifications to any or all components.

When you join a project in which the integration stream is not mastered by your current replica, you can create a development stream and view, but not an integration view. The Join Project Wizard displays a message that you will not be able to create an integration view; but when you click Finish, the wizard attempts to create the integration view and fails. If creation of the development view and stream succeeded, you can ignore the error.

The UCM process in ClearCase is enhanced for sites that have installed Rational ClearQuest by a very tight integration between the activity management provided by UCM and the change request management provided by ClearQuest. Use the following guidelines with the UCM-ClearQuest integration.

REM Add complete resolution code 
REM Defect record type requires Resolution field to be non-empty
'Get hook's session context 
Set Session = GetSession() 
'Get the entity 
Set entity = Session.GetEntity(entity_type,entity_id)
REM If record type is "Defect"
... If(entity.GetEntityDefName = "Defect") Then
REM If Resolution field is empty
... If(entity.GetFieldValue("Resolution").GetValue = "") Then 
REM Fill in required field
    session.EditEntity entity, "modify"
    Call entity.SetFieldValue("Resolution", "Fixed")     msg = entity.Validate 
REM Remember to do some action if validate fails 
    entity.Commit 
    End If End If

A stream can be rebased to a baseline that meets the following criteria:

Additional rules apply to integration streams and development streams in selecting a baseline:

Rebase is typically used to advance a stream's configuration, that is, to replace its current foundation baselines with more recent ones. However, under certain conditions, rebase can be used to revert a baseline, and to add or drop a component in a stream's configuration. It can also switch to a baseline that is neither an ancestor nor a descendant of the current foundation. The rules explained above are general rules for all rebase operations. You need to satisfy only the general rules when adding a component to a stream. When you advance, revert, drop, or switch a baseline, you need to satisfy the general rules and some additional ones.

These rules ensure that any changes made in a stream are not lost when the configuration changes.

If a baseline is recommended for a stream, and then that baseline is removed, clear the recommended baseline setting in the stream by typing the command chstream -nrecommended. Then you can set new recommended baselines by using the command chstream -recommended.

The deliver operation cannot allow changes to a read-only component. This situation can occur if someone changes the component modifiability in your project. The actions you take depend on whether you are doing an intraproject or an interproject deliver.

You can recommend a baseline for a stream if the baseline is from the stream or the stream's foundation.

For a baseline not from the stream or the stream's foundation, the following rules apply:

You are not required to recommend a baseline for every component in the stream's configuration.

You can clear the list of recommended baselines. Note that doing this step alone will cause problems when existing development streams rebase to the recommended baselines. The rebase operation will attempt to drop all baselines in the development streams' configuration. This operation will probably fail or produce errors and is, therefore, not desirable.

You can choose to reset the recommended baselines to baselines from the stream or the stream's foundation with or without clearing the recommended list. This allows the stream to return to a known correct state after being changed inadvertently to a bad list.

Delivering selected activities to a nondefault target is subject to the following restrictions:

It is possible for a remote deliver to include changes to a component when the component is nonmodifiable in the project. This only happens when the remote site has not synchronized with the local site and does not know that the component has been made nonmodifiable. When the integrator attempts to resume the remote deliver, a check is made to ensure that no versions in nonmodifiable components will be changed. If there are such versions in the deliver, the operation fails and the user has to cancel the deliver operation.

In this release, the integration includes a new trigger, which runs on Windows and UNIX platforms. The release includes the source code, in the form of Perl scripts, that the trigger uses. The Perl scripts include extensive comments that describe the purpose of their classes. For additional source code documentation, including an architectural overview and formatted class documentation, contact Rational Support. However, Rational Support cannot and will not support changes that you make to this source code.

If you are using the Web interface in a UCM environment, you cannot use the Web interface to work effectively in projects enabled for ClearQuest. You can view such projects, but you cannot perform any integration operations through the Web interface; also, you cannot use the interface as a suitable client in a UCM project enabled for ClearQuest.

The ClearCase Web interface supports noninteractive triggers. Interactive triggers, such as those that attempt to read input or create a window, fail.

If a trigger attempts to read input using clearprompt, the ClearCase Web interface prints this error:

clearprompt is not supported in the Web interface

If a trigger attempts to read directly from standard input, it receives an error, because standard input does not specify a valid file descriptor.

In addition, any trigger failure in the Web interface context displays this error message:

Interactive triggers are not supported in the Web interface. If the trigger was interactive, it may have failed for that reason.

Trigger script writers can detect whether a trigger is running in the Web interface context by checking for the environment variable ATRIA_WEB_GUI. It is set to 1 if you are running in the Web interface context.

Note that the base ClearCase-ClearQuest integration is dependent on the operation of interactive triggers; for this reason, the ClearCase Web interface is not a viable interface for using that integration.

The Java program used in the Web interface attempts to connect to the Web server to transfer files. Web browsers only allow Java programs to open connections to the server from which the programs were downloaded.

To enforce this rule, the Web browser on the Web interface client must be able to resolve the Web server's host name to an IP address. If you use a host name in a URL that cannot be resolved by the client host, the Java program cannot connect to the server. In this case, Web-interface file-transfer operations such as checkout, checkin, and download fail.

If the Web server is being accessed through a firewall by means of a proxy server, the proxy server being used must support DNS lookup outside the firewall.

When the ClearCase Web server on Windows logs on to a client, it sets the primary group to the designated primary group in the client user's domain account. In Release 4.0, you could not override this group setting. As a result, sites that use domain mapping to allow user accounts in multiple domains to share VOBs could not access those VOBs through the ClearCase Web interface.

Workaround: Specify a configuration variable in the ccweb.conf file, and add a value to the registry that enables domain mapping.

When you use the ClearCase Web interface on a Netscape browser, the MOZILLA_HOME environment variable must be set to the Netscape Communicator installation directory. Otherwise, messages similar to the following may be displayed when you try to check out or download files.

We recommend that you check the Netscape Web site, www.netscape.com, for more information on general Netscape requirements.

Toolbar popup menus don't close properly when running the Web interface using Netscape Navigator. Rather than closing automatically when the pointer is moved out of the menu location, they close only when you reselect the menu button.

The fonts used for ClearCase Web interface pages in UNIX versions of Netscape Navigator can be hard to read. Users can work around this by setting font preferences in Navigator:

Web views can only be accessed from the Web interface; they cannot be used with native ClearCase interfaces (for example ClearCase Explorer or cleartool). Various native GUIs may allow selection of a Web view (for example as a deliver target), but any attempt to access a Web view using a native ClearCase interfaces will result in a warning or error message.

Rational ClearCase Version 2002.05.00 introduces a new ClearCase Web interface. This interface is not compatible with Web views created by previous ClearCase Web interface clients. If you want to reuse existing Web views, we recommend that you clean them up before you upgrade the ClearCase Web server host to ClearCase 5.0.

Use the following procedure:

Using the Version Tree Browser to open a file from within a snapshot view on a UNIX system creates a temporary file that contains the text for that version of the element. Although the name assigned to the temporary file is not the version-extended pathname of the element, it provides all the information contained within that version-extended pathname, including the version number and branch structure of the selected element version. For example, the temporary file name for an element foo.c@@/main/11 would be unique_id_foo.c_main_11.

The temporary file is removed when the editor exits.

The Version Tree Browser now displays an error message if you try to access a checked-out version that is eclipsed. Previously, accessing the checked-out version would appear to work but the version actually accessed was the version visible in the view (that is, the eclipsing version) instead of the checked-out version. The error message now includes the following text with the pathname of the checked-out version:

The following problems relevant to ClearCase exist in the Command Reference.