Rational ClearQuest Release Notes

Copyright (c) 2001 Rational Software and its subsidiaries. All rights reserved.
Version 2001A.04.00
Updated 5/8/2001 6:00 PM

Thank you for choosing Rational ClearQuest®!
Please read this document to learn about new features, known product issues, important tips, and other Rational ClearQuest product information.

Table of Contents

1. Supported Hardware and Software Platforms

2. What's New in Rational ClearQuest v2001A.04.00

• Security Enhancements
• Web Enhancements
• Integration with Microsoft Project 2000
• Miscellaneous Enhancements
• Rational ClearQuest UNIX (v2001.03.00 - released 3/2001)

2.1 Rational ClearQuest Security Enhancements

The latest release of ClearQuest significantly improves the security model. This is achieved on two levels. First, specific defects and other change requests in ClearQuest can be hidden based on group membership. Second, Super User privileges are no longer required to perform certain administrative tasks.

Ability to Hide Change Request Records
Enables certain defects and other types of change request records to be hidden from specific users based on what group those users belong to. By enabling any reference field to be a security context field, ClearQuest will hide certain change requests from specified groups of users.

Ability to Administer Dynamic Choice Lists
A new privilege, called Dynamic Choice List Administrator, enables creation and modification of dynamic choice lists. This includes the ability to add, delete, and modify entries in dynamic choice lists.

Ability to Administer Public Queries Folder
A new privilege, called Public Folder Administrator, enables specific users to manage the public folder. This enables certain users to move queries, charts, report formats and reports to the public folder without Super User privileges.

New User Privilege to View and Edit SQL Code
This privilege allows users to view and edit the SQL code that is generated for queries. Users without this privilege can view but cannot modify the SQL code.

Ability to Administer Security at a Site
This privilege is related to the ability to hide change request records based on user group membership. Users with the Security Administrator privilege can view all data in a database since the security checks are not enabled for users with this privilege. This enables the administrator to grant one or more users in a specific group access to all data in the system, even if other members of that group are restricted from viewing certain records in the database. However, this user is not allowed to add new users or update the schema.

2.2 Web Enhancements

Easier Email Notification Setup
Email notification can now be set up from the Web interface instead of having to manually create registry entries. From Edit Web Settings, users can input all relevant data to enable either MAPI or SMTP email notification mechanisms.

Ability to Pick Query at Start-up
Queries can be selected from the Web interface as start-up queries so that the results set is automatically displayed as soon as users log in to ClearQuest. Start-up queries can be selected by editing the user profile.

Support for Multiple Schema Repositories
ClearQuest Web now supports multiple schema repositories so that a single Web server can be used to serve many schema repositories. Users can select a schema repository from the log in screen. Once the schema repository is selected, the end user can select from an appropriate list of user databases.

Ability to View and Edit SQL Code Associated with a Query
ClearQuest Web allows specific, authorized users to view and edit the SQL code that is generated for queries. By right clicking on the query in the workspace from the Advanced Query Editor, users can view and modify the SQL code for that query.

2.3 Integration with Microsoft Project 2000

Rational ClearQuest now provides an integration with Microsoft Project 2000. This is enabled through Rational ClearQuest Project Tracker, a Microsoft Project 2000 add-in. It provides an integration with ClearQuest; by creating a two-way association between project plan tasks in Microsoft Project 2000 and defects (and/or other change requests) in ClearQuest.

With Rational ClearQuest Project Tracker, tasks can be exported from a Microsoft Project 2000 project plan to automatically create new database records in Rational ClearQuest. The tasks are automatically linked with these new database records. Corresponding tasks and records can then be synchronized, so that changes made in one system are automatically reflected in the other.

Records can also be imported from Rational ClearQuest to create new project plan tasks in Microsoft Project 2000. These records and tasks are also linked and can continue to be synchronized at periodic intervals. In this way, progress reported in Rational ClearQuest can be transferred automatically to Microsoft Project 2000, so that a project manager can always update the project plan with the most accurate and up-to-date information.
Documentation is provided in soft copy form.

2.4 Miscellaneous Improvements

Integration with Rational SoDA
In order to offer ClearQuest customers another reporting option, (in addition to Crystal Decisions Crystal Reports) an integration with Rational SoDA has been added to this release. Users can choose to run a SoDA report directly from the ClearQuest menu. SoDA provides two out of the box templates, including "AllDefectsInthisState" and "AllDefectsBythisOwner". In both cases the user is prompted to enter the specific state or owner to be reported on. Using SoDA, administrators can edit the existing templates or add new ones.

Upgrade Improvements
Rational ClearQuest now upgrades schema repositories and user databases more efficiently, reducing the upgrade time.

Downward Compatibility
Rational ClearQuest now supports downward compatibility between different releases of the product. This enables users to upgrade to a newer version of the product in a staged manner by first upgrading all the client machines to the new version and then upgrading the databases.

NOTE: If taking advantage of ClearQuest integrations with ClearCase or Rational Suite, some additional steps are required. See the Installing Rational ClearQuest manual for details.

Terminal Server Support
ClearQuest can now be run on a terminal server machine (Citrix or Windows Terminal Server). Other clients can then connect to the terminal server and use ClearQuest.

Database Support
Rational ClearQuest's database support has been extended to include Oracle 8.1.7 (on Windows and UNIX) and IBM DB2 7.1 (on Windows).

2.5 Rational ClearQuest UNIX (v2001.03.00, released 3/20/01)

With the latest release of ClearQuest UNIX, database support was extended beyond Oracle on UNIX so ClearQuest UNIX can be used with SQL Server and IBM DB2 on Windows. In addition, platform support was extended to include the latest release of Sun Solaris, as well as new support for RedHat Linux. Specific version numbers are listed below:

Database Support:

• Microsoft SQL Server 2000 and SQL Server 7.0 SP2 (Windows)

• IBM DB2 7.1 and 6.1 (Windows)

• Oracle 8.1.7, 8.1.6, 8.1.5, 8.0.5, or 7.3.4 (UNIX)

Platform Support:

• RedHat Linux 7.0 and 6.2

• Solaris 8 (2.8), 7 (2.7), 2.6, and 2.5.1

• HP-UX 11.0 and 10.x

2.6 ClearQuest MultiSite Beta Release

Based on the proven technology in Rational ClearCase MultiSite, ClearQuest MultiSite will be an optional add-on solution for Rational ClearQuest that supports synchronous development efforts across geographically distributed sites. Rational ClearQuest MultiSite helps geographically distributed project teams to work together more efficiently by providing local access to replicated defect and change tracking data and enabling automatic synchronization of those databases.
A beta release of Rational's new ClearQuest MultiSite product is included in this release. If you would like to participate in the beta test of this product, please contact your Rational Account team and ask them to nominate you for the beta program. Once you are signed up for the beta, you will receive a beta software CD and a ClearQuest MultiSite license key.

3. Upgrading from Previous ClearQuest Releases

In order to upgrade to ClearQuest v2001A, there are two things you need to consider. First, do you intend to use the new security model? If you intend to use this feature, you are required to upgrade your schema repository and all the user databases. Secondly, if you have enabled integrations with other Rational tools such as Rational ClearCase or Rational Requisite Pro or Rational Robot, you are not required to upgrade your schema repository but you must install new packages in order to continue using the integrations. Please refer to the Installing Rational ClearQuest manual for detailed information on performing upgrades and installing new packages.

Note: The latest information on upgrading your databases can be found in Rational Technical Support Technote 17185.

Note UNIX client users:
ClearQuest UNIX v2001 cannot be used if you upgrade your databases to ClearQuest v2001A. If you upgrade your schema repository and user databases to v2001A, ClearQuest UNIX clients will not be able to connect to the upgraded databases and will receive an error indicating a version mismatch. ClearQuest UNIX v2001A, which will be compatible with v2001A databases, will be released within 60 to 90 days from the date of the general availability of Rational ClearQuest v2001A for Windows.

A typical upgrade cycle would comprise some of the following steps:

Administrator:

• Confirm whether or not Crystal Reports 6 needs to be uninstalled - consult the Converting from Crystal Reports 6 to Crystal Reports 8 section below.

• Install Crystal Reports 8 if desired.

• Install ClearQuest v2001A.04.00. - Consult the Installing Rational ClearQuest manual.

  Note: If you are not upgrading from v2001 then you should uninstall ClearQuest prior to installing the new release.

• Upgrade your schema repository and user databases using the Rational ClearQuest Maintenance Tool. See the appropriate section below:

• Upgrading from Rational ClearQuest v2001

• Upgrading from Rational ClearQuest v2000 (Including Patch Releases)

• Upgrading from Rational ClearQuest v2.0 (Including Patch Releases)

• Upgrading from Rational ClearQuest v1.0 or v1.1 (Including Patch Releases)

• Installing ClearQuest resets the connection to the ClearQuest database. Run the ClearQuest Maintenance Tool to establish a new connection to your ClearQuest database.

• Decide whether the Email package needs to be applied to your schema - consult the "Analyzing Your Current Package Version" section of the Installing Rational ClearQuest manual.

• Upgrade your database with the Email package, if necessary, and test your database - consult the Installing Rational ClearQuest manual.

• Install ClearQuest v2001A.04.00 on the Web Servers as needed - consult the Installing Rational ClearQuest manual.

Client:

• Confirm whether or not Crystal Reports needs to be upgraded - consult Converting from Crystal Reports 6 to Crystal Reports 8 below. Install Crystal Reports 8 if desired.

• Install ClearQuest client software - consult the Installing Rational ClearQuest manual.

  Note: If you are not upgrading from v2001 then you should uninstall ClearQuest prior to installing the new release.

• Installing ClearQuest resets the connection to the ClearQuest database. Start ClearQuest to establish a new connection to your ClearQuest database.

3.1 Converting from Crystal Reports 6 to Crystal Reports 8

Starting with ClearQuest v2001.03, Crystal Reports 6 was no longer supported for authoring reports. If a user attempts to use Crystal Reports 6 against a ClearQuest v2001A.04.00 database, various run time errors may occur when authoring report formats or executing reports.

Crystal Reports 8 is now included with the media for ClearQuest and there are a few steps you will need to perform to successfully upgrade clients who have Crystal Reports Designer 6 installed:

To successfully upgrade clients who have Crystal Reports Designer 6 installed follow these steps:

1. Uninstall Crystal Reports 6
2. Install Crystal Reports 8
3. Install ClearQuest v2001A.04.00

Warning: If Crystal Reports 6 is not uninstalled before the installation of ClearQuest v2001A.04.00 it will be necessary to uninstall ClearQuest and Crystal Reports and then reinstall Crystal Reports 8 followed by ClearQuest v2001A.04.00.

If you have not received a Crystal Reports v. 8 CD, please contact Rational Technical Support to request one.

3.2 Upgrading from Rational ClearQuest v2001

In order to upgrade to ClearQuest v2001A, there are two things you need to consider. First, do you intend to use the new security model? If you intend to use this feature, you are required to upgrade your schema repository and all the user databases. Secondly, if you have enabled integrations with other Rational tools such as Rational ClearCase or Rational Requisite Pro or Rational Robot, you are not required to upgrade your schema repository but you must install new packages in order to continue using the integrations.

Upon invoking ClearQuest for the first time, you will need to connect to the ClearQuest databases again. Get the database location and connection information from your ClearQuest Administrator, and enter it when prompted.

In order to upgrade your databases, you must follow the instructions listed in the Installing Rational ClearQuest manual.

It is possible to inter-operate between releases ClearQuest v2001.03 and ClearQuest v2001A.04 (i.e. for some clients to have ClearQuest v2001.03 installed while others have ClearQuest v2001A.04 installed), however this is not recommended for the following reasons:

• Clients running ClearQuest v2001A will not be able to utilize any of the integrations with other Rational products such as the Rational Administrator, RequisitePro, or TestStudio. Note that merely modifying ClearQuest records where any of these integrations are enabled may be sufficient grounds to require compatible versions of the Rational Suite Components be installed on the client machine.

When using Oracle databases, any operation involving exporting the schema or schema repository will not work if the export is done from ClearQuest v2001 or v2001A and the import is done on ClearQuest v2.0 or ClearQuest v2000. This is because the specification for Oracle databases has changed from "Oracle7" to "Oracle" in the text files created by these tools. ClearQuest v2001 and ClearQuest v2001A support either format, but ClearQuest v2.0 and ClearQuest v2000 do not.

3.3 Upgrading from Rational ClearQuest v2000 (Including Patch Releases)

In order to upgrade to ClearQuest v2001A, there are two things you need to consider. First, do you intend to use the new security model? If you intend to use this feature, you are required to upgrade your schema repository and all the user databases. Secondly, if you have enabled integrations with other Rational tools such as Rational ClearCase or Rational Requisite Pro or Rational Robot, you are not required to upgrade your schema repository but you must install new packages in order to continue using the integrations.

Upon invoking ClearQuest for the first time, you will need to connect to the ClearQuest databases again. Get the database location and connection information from your ClearQuest Administrator, and enter it when prompted.

In order to upgrade your databases, you must follow the instructions listed in the Installing Rational ClearQuest manual.

It is possible to inter-operate between releases ClearQuest v2000 and ClearQuest v2001A.04.00 (i.e. for some clients to have ClearQuest v2000 installed while others have ClearQuest v2001A.04.00 installed), however this is not recommended for the following reasons:

• Clients running ClearQuest v2000 will not be able to utilize any of the integrations with other Rational products such as the Rational Administrator, RequisitePro, or TestStudio. Note that merely modifying ClearQuest records where any of these integrations are enabled may be sufficient grounds to require compatible versions of the Rational Suite Components be installed on the client machine.

• ClearQuest v2001A.04.00 clients can use reports and report formats created in ClearQuest v2000 with Crystal Reports 6, but Crystal Reports 8 must be used with ClearQuest v2001A.04.00 when authoring report formats.

When using Oracle databases, any operation involving exporting the schema or schema repository will not work if the export is done from ClearQuest v2001 or v2001A and the import is done on ClearQuest v2.0 or ClearQuest v2000. This is because the specification for Oracle databases has changed from "Oracle7" to "Oracle" in the text files created by these tools. ClearQuest v2001 and ClearQuest v2001A support either format, but ClearQuest v2.0 and ClearQuest v2000 do not.

3.4 Upgrading from Rational ClearQuest v2.0 (Including Patch Releases)

In order to upgrade to ClearQuest v2001A, there are two things you need to consider. First, do you intend to use the new security model? If you intend to use this feature, you are required to upgrade your schema repository and all the user databases. Secondly, if you have enabled integrations with other Rational tools such as Rational ClearCase or Rational Requisite Pro or Rational Robot, you are not required to upgrade your schema repository but you must install new packages in order to continue using the integrations.

Upon invoking ClearQuest for the first time, you will need to connect to the ClearQuest databases again. Get the database location and connection information from your ClearQuest Administrator, and enter it when prompted.

In order to upgrade your databases, you must follow the instructions listed in the Installing Rational ClearQuest manual.

It is possible to inter-operate between releases ClearQuest v2.0 and ClearQuest v2001A.04.00 (i.e. for some clients to have ClearQuest v2.0 installed while others have ClearQuest 2000 or ClearQuest v2001A.04.00 installed), however this is not recommended for the following reasons:

• Clients running ClearQuest v2.0 will not be able to run queries that were created or modified under ClearQuest v2000 or later.

• Clients running ClearQuest v2.0 will not be able to utilize any of the integrations with other Rational products such as the Rational Administrator, RequisitePro, or TestStudio. Note that merely modifying ClearQuest records where any of these integrations are enabled may be sufficient grounds to require compatible versions of the Rational Suite Components be installed on the client machine.

• ClearQuest v2001A.04.00 clients can use reports and report formats created in ClearQuest v2.0 later with Crystal Reports 6, but Crystal Reports 8 must be used with ClearQuest v2001A.04.00 when authoring report formats.

When using Oracle databases, any operation involving exporting the schema or schema repository will not work if the export is done from ClearQuest v2001 and ClearQuest v2001A and the import is done on ClearQuest v2.0 or ClearQuest v2000. This is because the specification for Oracle databases has changed from "Oracle7" to "Oracle" in the text files created by these tools. ClearQuest v2001 and ClearQuest v2001A support either format, but ClearQuest v2.0 and ClearQuest v2000 do not.

3.5 Upgrading from Rational ClearQuest v1.0 or v1.1 (Including Patch Releases)

Customers upgrading from ClearQuest v1.0 or v1.1 should contact Rational Technical Support for assistance.

4. Tips and Workarounds

4.1 Unified Change Management (UCM) Documentation

For information on the ClearQuest/ClearCase Unified Change Management (UCM) Integration please refer to the Rational ClearCase Documentation and Release Notes, and Appendix B of the Administering Rational ClearQuest manual.

4.2 ClearQuest with SQL Server

4.2.1 SQL Server 2000 Installation

During the installation process for Microsoft SQL Server 2000, you have the option of selecting Windows only authentication or mixed mode (Windows and SQL Server) authentication. You must select mixed mode (Windows and SQL Server) authentication in order for ClearQuest to function properly.

Also during the installation process for Microsoft SQL Server 2000, you are prompted for a database instance name. The database instance name must be the same as the hostname of the machine on which you are installing. This can be accomplished by leaving the instance name blank and accepting the default. If an instance name is required, there are several issues that will arise:

• Clients running earlier versions of MDAC (such as 2.1.2) will not be able to connect to the database.

• The Client machine will need to install the SQL Server client or manually edit the registry. The following is an excerpt from the Microsoft white paper entitled "Upgrading to SQL Server 2000":

  "When using the SQL Server client connectivity components from SQL Server 7.0 or earlier, you must set up an alias using the Client Network Utility before you connect to a named instance of SQL Server 2000. For example, on a SQL Server 7.0 client, to connect to a named instance of SQL Server 2000, you must add an alias that points to \\computername\pipe\MSSQL$instancename\sql\query. If you use an alias name of computername\instancename, clients can connect by specifying this name in the same way as SQL Server 2000 clients do. For the TCP/IP Sockets and NWLink IPX/SPX Net-Libraries, you must use the Client Network Utility to define an alias on the client that specifies the port address on which the named instance is listening."

Please consult the Microsoft support web site at http://support.microsoft.com for more information.

4.2.2 Use of SQL Server 7.0 Service Pack 2 or SQL Server 2000 with Certain Rare Database Schemas

There is a known issue with Microsoft SQL Server 7.0 Service Pack 2 and SQL Server 2000 such that a user can use the ClearQuest schema designer to create a schema, where executing the same query three times in a row by the same process can cause certain rows and tables in the database to become locked. This will create what is known as a blocking SPID (SQL Server Process ID) on the database server. The major symptom of the problem is that the ClearQuest system becomes unavailable to all users (there maybe an hourglass, or just no response from ClearQuest). This particularly impacts the ClearQuest web interface. To diagnose if this is the problem:

• Run SQL Server Enterprise Manager

• Select the Management section under the appropriate server

• Select Current Activity->Locks/ProcessID

• You will see which SPID is the blocker, and all SPIDs that are blocked by the blocker

The relevant Microsoft defect number for this problem is 58388. Rational Software has developed a workaround for this problem until such time as Microsoft provides a solution. The relevant Rational Software Technical Support Tech Note is 13899, which can be obtained at http://solutions.rational.com/solutions//.

4.3 ClearQuest with Oracle

4.3.1 Oracle Database Connection Options

When connecting to Oracle databases, ClearQuest uses a database property called "connect_options" which determines behavior of the client under certain configurations. Generally, these connect options are stored in the schema repository and are replicated to each client when they connect. This reduces workload for site-wide maintenance, but has the side effect of limiting certain heterogeneous Oracle client version configurations. There are several configuration options that are discussed here.

The "connect_options" database property has several options. They are:

HOST=<host>;SID=<sid>;SERVER_VER=<ver>;CLIENT_VER=<ver>;LOB_TYPE=LONG

where,

<host> is the network hostname of the Oracle database server;
<sid> is the instance ID of the Oracle database server;
<ver> is the Oracle version number, either, 7, 8.0 or 8.1;
SERVER_VER is the Oracle database server version number;
CLIENT_VER is the Oracle client version number;
LOB_TYPE is the Oracle data type used for text fields; currently, this must be of type LONG.

Generally, the "connect_options" property is set when the schema repository is created for the first time. This can be modified later (on a site wide basis) for the user database using the database properties option of ClearQuest Designer or for the schema repository itself using the ClearQuest Maintenance tool.
When setting up a site for use with Oracle, you should carefully consider which Oracle client versions will be used across the site. You should determine which is the most likely Oracle client version and specify that version in the CLIENT_VER parameter of the "connect_options" database property using ClearQuest designer. There will then be an additional step required for clients that use a different Oracle client version. For each client that wishes to deviate from the site standard, you will need to enter the following at the command line:

installutil registeroracleoptions "CLIENT_VER=<ver>"

where <ver> is one of "7", "8.0", or "8.1". The installutil executable is located in the ClearQuest installation directory.

This command has the effect of creating a registry key setting under HKEY_LOCAL_MACHINE\Software\RationalSoftware\ClearQuest\2001.03.00\Core with a value OverrideOracleConnectOptions equal to "CLIENT_VER=<version>". This will then force that client to use that CLIENT_VER connect option in place of the CLIENT_VER option specified in the schema repository.

You will know that this override is required because the user will be unable to successfully connect to Oracle databases. The salient error message will indicate a version of the Openlink ODBC driver for Oracle that references the wrong Oracle client version. This can be viewed by clicking the "Details" checkbox on the login error message dialog box.

There are two major examples of use. The first is a homogenous environment of Oracle 8.1 clients and an Oracle 8 server. The connect options string should be:

HOST=<host>;SID=<sid>;SERVER_VER=8.0;CLIENT_VER=8.1;LOB_TYPE=LONG

In this example, registeroracleoptions is not necessary because all client versions use the Oracle 8.1 client. Another example would be the heterogeneous case, with the majority of clients running Oracle 7.3.4 and a few running 8.0 and 8.1 against a 7.3.4 server. The connect options string in the database properties would be:

HOST=<host>;SID=<sid>;SERVER_VER=7;CLIENT_VER=7;LOB_TYPE=LONG

As clients install Oracle 8.0.5 or 8i (8.1.6), they would need to override the connect options with either:

installutil registeroracleoptions "CLIENT_VER=8.0"

Or

installutil registeroracleoptions "CLIENT_VER=8.1".

One final note: If you reinstall ClearQuest, this setting might be deleted as part of the reinstall. Please make sure it is set for the client after each install. It may be useful to create a ".bat" file with the appropriate installutil command options, which the user can simply double click on to reset the override. This could be placed in a network install area.

4.3.2 'Contains' Searches are always case sensitive

When using an Oracle database for the backend data storage, searches using the 'Contains' operator will always be case sensitive.

4.3.3 Searching Multi-line text fields

To allow the searching of MUTLILINE_TEXT_STRINGS in ClearQuest when using an Oracle database as the backend data storage, you must setup and enable the interMedia Text search engine. See http://www.oracle.com for more information on obtaining and configuring the interMedia engine.

Once configured, ClearQuest requires that there be at least one interMedia server process running.

Please consult the Installing Rational ClearQuest manual for detailed instructions on enabling multi-line text searches.

4.3.4 InterMedia may require revoking cxtadmin role

If you are using the interMedia search engine, you must revoke the ctxadmin role from the ClearQuest user before doing any operation that constitutes a database move, such as:

• Copying or physically moving a user database from an Oracle location to another of any vendor type

• Using any of the ClearQuest tools like the Designer or the installutil command utility. This would also include any tools users write themselves against the ClearQuest APIs.

• Doing a ClearQuest database upgrade (from any release prior to v2.0)

• Doing a ClearQuest database upgrade from any releases v2.0 or later that is not an in-place upgrade

4.4 Network Installations

When running Rational ClearQuest from a network installation, users will not be able to create report formats using Crystal Decisions' Crystal Reports. In order to create new report formats in a network installation, users must execute ClearQuest from the shortcuts menu and not by executing ClearQuest from the administrative install.

4.5 Versions of ClearQuest prior to v2001.03 with MDAC 2.5.1 or Later

Microsoft released MDAC 2.5.1 as part of Windows 2000 SP1. With that release, ClearQuest versions prior to v2001.03 were no longer able to successfully perform queries against Microsoft Access databases. This manifested itself through a number of different error messages either in the ClearQuest Client or in the ClearQuest Maintenance tool while creating sample databases. The specific symptoms included spurious "Out of memory" errors executing various commands. This issue has been addressed in ClearQuest v2001A.04.00. Earlier versions of ClearQuest do not support use of MDAC 2.5.1 or later or Windows 2000 SP1. For more information, please consult the Microsoft knowledge base article Q272951 at http://support.microsoft.com/support/kb/articles/Q272/9/51.ASP?LN=EN-US&SD=gn&FR=0

4.6 Debugging E-mail Notification Issues

Beginning with ClearQuest v2001A.04.00, there is a new method for debugging e-mail notification issues. ClearQuest, when enabled via a registry setting, will output interesting debug information to the Windows debug log. This can be viewed using the dbwin32 tool located under the ClearQuest install directory or any other tool that can browse the Windows debug log. Importing the following ".reg" file after ClearQuest has been installed will enable the e-mail notification debug information. Note that you have to stop and restart ClearQuest for this to take effect on that client (this would include the web server).

Native Client:

REGEDIT4

[HKEY_CURRENT_USER\Software\Rational Software\ClearQuest\Diagnostic]
"Trace"="Email"
"Output"="ODS"
"EMailSendVB"="ODS"

Webserver:

REGEDIT4

[HKEY_USERS\.default\Software\Rational Software\ClearQuest\Diagnostic]
"Trace"="Email"
"Output"="ODS"
"EMailSendVB"="ODS"

Please note that beginning with Windows 2000, you are required to have local administrator permissions to view debug output. For further information on E-mail notification please consult Technote 17189.

4.7 Submit Date Hook (RAMBU14985)

The OOTB schemas define a Default Value hook for the Submit_Date field. The Perl version includes the current time component, but the Basic version does not. This is interpreted as the start of the day, local time, which can affect the results of date-based queries run from other time zones. Customers basing their schema on any of the OOTB schemas may experience this behavior.

4.8 Reinstall Required When ClearCase/MultiSite or the Rational Shipping Server Are Uninstalled

If you are using ClearCase/MultiSite and the Rational Shipping Server on the same computer and uninstall one of those products, the other product is partially uninstalled and stops working. To resolve the problem you must uninstall both products and then reinstall the product that is needed.

4.9 Security Settings for Terminal Servers

In order users to run ClearQuest properly in a Citrix or terminal server environment, the system administrator of the Windows NT or Windows 2000 server must set the appropriate security privilege for the user (the NT or Win2000 user, not the ClearQuest user) as follows:

1. Set the security privilege for \\HKEY_LOCAL_MACHINE\SOFTWARE\ODBC

• Run "regedt32" program.
• Select the folder "\\HKEY_LOCAL_MACHINE\SOFTWARE\ODBC".
• Select the menu Security->Permission.
• Add the group that the user belongs to.
• Set the permission of the group above to be "Read".

If the permissions are incorrect, the user will receive an ODBC error when trying to logon to the CQ database.

2. Set the security privilege for the Rational software installation directory (possibly c:\program files\Rational)

• Open Windows Explore.
• Select the directory that contains Rational Software. (Possibly \Program Files\Rational)
• Right mouse click to select the "Property" from the pop-up menu.
• Click the Security Tab.
• Add the group that the user belongs to.
• Set 'Full Control" for that group.

If the permissions are incorrect, the user cannot do any operations that need to write to the ClearQuest program directory. For example, the user cannot create new queries.

5. Troubleshooting Web Services

5.1 Basic Troubleshooting Tips

5.1.1 Configuring IIS to work with the anonymous user id

In order to successfully run ClearQuest Web, you must ensure that IIS is configured correctly to work with the anonymous user id (typically, IUSR_<machinename>). In order to do this, you must:

1. Select the properties of virtual directory in IIS by right clicking on the virtual directory.
2. Set the virtual directory to run in the same memory space (in IIS4 leave the "Run in separate memory space" check-box unchecked. In IIS5 set the "Application Protection: setting to "Low (IIS Process)" and apply.
3. Then, further down the Internet Service Manager workspace view drill down under "Microsoft Transaction Server" > "Computers" > "My Computer" > "Packages Installed" and find the entry for the CQWeb virtual directory (it'll have a name like "IIS-{Default Web Site//Root/CQWeb}"), right-click > Properties, go to the Identity tab, and look at the "User" field.
4. Ensure that this user field is set to the anonymous user account defined specifically for serving ClearQuest Web. See the Installing Rational ClearQuest manual for more information on the configuration of IIS 4.0 and IIS 5.0.
5. Click on OK to commit the changes.

5.1.2 IIS server (inetinfo.exe) crash

The IIS Server (inetinfo.exe) may crash when you stop the service from the Microsoft Internet Service Manager application. If this happens, you must stop and restart the Internet Service Manager before restarting the WWW service. If this machine provides FTP or Gopher services, you must restart them too.
If you are using Microsoft Internet Explorer version 4.72.2106.8 or 4.71.1712.6, you will need to upgrade to a newer version, such as 4.72.3110.8. Otherwise, you will run into a JavaScript error when selecting Help, About or attempting to view an attachment.

Users of Netscape Communicator 4.0x browsers should have the following options set:

• In the browser, select Edit>Preferences.

• Select "Advanced->Cache" Category.

• Set "Document in cache is compared to Document on network" to "every time" and press OK.

5.2 Advanced Troubleshooting Tips

In addition to the tips documented here, there is detailed documentation on the configuration of IIS 4.0 and IIS 5.0 in the Installing Rational ClearQuest manual.

5.2.1 Incorrect permissions on the ClearQuest registry keys

Sometimes the ClearQuest Installation on a Win2000 Server or an NT4 Server with SP6 installed ends up with Registry Key permission settings that make them inaccessible to the Anonymous Web User. In particular the keys:

• HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\*
• HKEY_CLASSES_ROOT\TypeLib\{F71DCDF3-8DFB-11D1-8CA9-00A0C92337E5} have their permissions reset.

The consequences of this are that the ClearQuest Web server fails to grant logons, with one of the following messages:

• "Object required"
• "Unable to logon to the <dbvendorname> database "<dbname>" ...Datasource name not found and no default driver specified.
• Failed condition: disposition == (0x00000001L)
  Location: ClearQuest Core:adregistry.cpp:569occurred in BBOLEI~1

See the Installing Rational ClearQuest manual, for information on setting the proper permissions.

5.2.2 Incorrect permissions on the cache directory

If you haven't granted proper permissions in the cache directory, you will not be able to logon and you will see the following
error:

Logon Error 80020009
Could not create directory
occurred in ClearQuest.FileCache.1

See the Installing Rational ClearQuest manual, for information on setting the proper permissions.

5.2.3 Single Network domain for SQL Server database and ClearQuest Web Server

Your SQL Server databases must be in the same network domain as your ClearQuest Web server and any ClearQuest clients or tools that need to connect to the database. If it is not in the same domain, you will get errors. For more information:

• Consult the Microsoft KnowledgeBase Article Q152828. To locate the article, go to the Microsoft web site at http://www.microsoft.com/, click the Search button at the top of the page, and enter the article number.

• Consult Rational Technical Support TechNote 8184, "How do I access an SQL Server database in another domain?" which can be obtained at http://solutions.rational.com/solutions/.

5.2.4 Changing Script time out limit

Occasionally you may have your script time out. If this happens, you'll see a message that looks like:

error 'ASP 0113'
Script timed out

The maximum amount of time for a script to execute was exceeded. You can change this limit by specifying a new value using the Internet Service Manager. To do this:

1. Start Internet Service Manager
2. Select your ClearQuest virtual directory
3. Select properties
4. Press the configuration button on the Virtual Directory tab
5. Select the App Options tab of the Application Configuration dialog.
6. Set the ASP script time-out setting to the desired time.

5.3 Web Performance and Recommended Configurations

Rational has performed extensive performance and stability testing on various web server configurations. As a result of these tests, we have developed a set of recommended database and web server configurations.

ClearQuest Web has been load tested extensively with hooks written in both Perl and VBScript. In order to ensure web stability under high loads, Rational's load testing involved 50 simultaneous users performing normal operations such as submitting records, modifying records, and executing queries. Based on this load testing, Rational recommends the following configurations for best performance and stability under high loads:

• Windows 2000 or Windows 2000 SP1, IIS 5.0, SQL Server 2000

• Windows NT 4.0 SP6a, IIS 4.0, SQL Server 7.0 SP2

• Windows NT 4.0 SP6a, IIS 4.0, Oracle 8.0.5 Server, Oracle 7 Client

In order to ensure top performance from ClearQuest Web in a multi-user environment, please be sure the following IIS tuning is completed:

• On the Internet Service Manager->host_name->Properties->Internet Information Server tab, check "Enable Bandwidth Throttling" and use the default of 1024 kb/s for maximum network use.

• On the Internet Service Manager->host_name->Default Web Site->Properties->Web Site tab, uncheck the "Enable Logging" option.

• On the Internet Service Manager->host_name->Default Web Site->Properties->Performance tab, set the performance tuning scale to the maximum (more than 100,000).

• On the Internet Service Manager->host_name->Default Web Site->Properties->Performance tab, make sure the "Enable Bandwidth Throttling" option is unchecked.
  On the Internet Service Manager->host_name->Default Web Site->Properties->Performance tab, uncheck the "http Keep-Alives Enabled" option (this option is in the Web Site tab for IIS5).

Note: Rational ClearQuest was load tested using Rational Performance Studio. Rational recommends at least 1 GB of RAM and a Pentium III processor (500 MHz and greater) on the Web server for optimal performance. All load testing above was performed on a dual processor machine. In addition, Rational recommends that the database server and the Web server be located on two different machines. Using one machine as both the database server and the Web server causes frequent hangs and script timeouts and generally causes ClearQuest Web to be unreliable.

6. Known Defects

For a list of known defects in Rational ClearQuest v2001A.04, please consult Rational Technical Support Technote 17188 at http://solutions.rational.com/solutions/.

7. Fixed Defects

For a list of known defects in Rational ClearQuest v2001A.04, please consult Rational Technical Support Technote 17187 at http://solutions.rational.com/solutions/.

8. Subscribing to the ClearQuest User Group

The ClearQuest User Group is an e-mail forum where you can share your experiences, pose questions, or obtain useful information from other ClearQuest users. To subscribe to the group, visit the Rational web site at: http://www.rational.com/support/usergroups/

Your e-mail address will not be given out to anyone.

9. Accessing the Sample Hooks Database

The ClearQuest Sample Hooks Repository provides a place for users to trade hook scripts with one another. The Repository is located at: http://clearquest.rational.com/

To gain access enter:

username: hooks
password: password

Select the link for the "Sample Hooks Database." From here you can browse the database of existing hooks scripts. If you have a script that others might find useful, please take a minute and add it to the database.

10. Contacting Rational Technical Support

If you have any problems with the software or documentation, please contact Rational Technical Support via telephone or electronic mail as described below. For information regarding support hours, languages spoken, and other Rational Software information, visit the Rational web site, http://www.rational.com/sitewide/support.

Rational's web site contains an extensive library of Technical Notes. To access the Technical Notes, go to http://solutions.rational.com/solutions/

Rational maintains Support Centers in different geographic regions. To contact the center nearest you, consult the chart below. If you are contacting Technical Support by phone, dial the phone number shown below and follow the voice prompts to select ClearQuest Technical Support.

(c) 2001 Rational Software and its subsidiaries. All rights reserved. Rational Software and its subsidiaries ("Rational") claim copyright in this Program and documentation as an unpublished work, versions of which were first licensed on the date indicated in the foregoing notice. Claim of copyright does not imply waiver of Rational's other rights. See Notice of Proprietary Rights.

NOTICE OF PROPRIETARY RIGHTS
This computer program and documentation are confidential trade secrets and the property of Rational Software and its subsidiaries. Use, examination, reproduction, copying, disassembly, decompilation, transfer and/or disclosure to others, in whole or in part, are strictly prohibited except with the express prior written consent of Rational Software and its subsidiaries.