Rational ClearQuest Release Notes

Version Number: 2002.05.00

These release notes provide information critical to installing and using Rational ClearQuest, including supported platforms and known issues with this release.

Copyright © 1997-2001 Rational Software Corporation. All Rights Reserved.

Microsoft, Windows, Windows NT, Visual Basic, Microsoft SQL Server, and Visual SourceSafe are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Oracle, Oracle7, Oracle8 and SQL*Net are trademarks or registered trademarks of Oracle Corporation. Rational, the Rational logo, RequisitePro, Rational Rose, SoDA, ClearCase, and ClearQuest are trademarks or registered trademarks of Rational Software Corporation in the United States and in other countries. All other names are used for identification purposes only and are trademarks or registered trademarks of their respective companies.

Contents

Scope

ClearQuest is a customizable defect and change tracking system designed for the dynamic environment of software development. With ClearQuest, you can manage every type of change activity associated with software development, including enhancement requests, defect reports, and documentation modifications.

Before installing Rational ClearQuest, be sure to read the Hardware/software information and Getting started sections of this document. These sections contain important information for a smooth and successful installation.

Hardware/software information

Refer to the following information for system and software requirements. This section provides basic information on the platforms supported and the hardware and software requirements for running ClearQuest. Refer to Compatibility issues for more information.

Supported platforms

Platform

Operating System

Windows Client

  • Windows NT 4.0 Service Pack 6a
  • Windows 2000 Service Pack 1 and 2
  • Windows 98 2nd Edition*
  • Windows ME
  • Windows XP Professional

Windows Administrator

  • Windows NT 4.0 Service Pack 6a
  • Windows 2000 Service Pack 1 and 2
  • Windows 98 2nd Edition
  • Windows ME

MultiSite Administrator

  • Windows NT 4.0 Service Pack 6a
  • Windows 2000 Service Pack 1 and 2

Terminal Server

  • Windows 2000 Advanced Server Service Pack 1 or 2
  • Citrix MetaFrame 1.8

Web Servers

  • IIS 5.0 on Windows 2000
  • IIS 4.0 on Windows NT
Note: We recommend that you use Windows 2000 Server, Windows 2000 Advanced Server, or Windows NT 4.0 Server as the Web Server platform.

Web Clients

  • Internet Explorer 5.01 Server Pack 2
  • Internet Explorer 5.5 and Service Pack 1
  • Netscape 4.72 or higher
Note: Netscape 6.01 is not supported.

UNIX Client

  • Solaris versions 2.6, 7, 8
  • HP-UX versions 10.20, 11.00, 11.11
  • RadHat Linux versions 7.0, 7.1
  • AIX version 4.3.3

Hardware requirements

Platform
Component
Requirements

Windows Client

Processor

  • 32 bit
  • 128 MB RAM
  • 233 MHz or higher Pentium compatible computer

Disk Space

188 MB

Windows Administrator

Processor

  • 32 bit
  • 256 MB RAM
  • 500 MHz or higher Pentium compatible computer

Disk Space

250 MB

MultiSite Administrator

Processor

  • 32 bit
  • 256 MB RAM
  • 500 MHz or higher Pentium compatible computer

Disk Space

250 MB

Terminal Server

Processor

  • 32 bit
  • 256 MB RAM
  • 500 MHz or higher Pentium compatible computer

Disk Space

250 MB

Web Server

Processor

  • 32 bit
  • 1 GB RAM
  • 500 MHz or higher Pentium compatible computer

Disk Space

250 MB

Web Clients

Processor

  • 32 bit
  • 128 MB RAM
  • 500 MHz or higher Pentium compatible computer

Disk Space

188 MB

UNIX Client

Processor

  • 32 bit
  • 128 MB RAM
  • 233 MHz

Disk Space

188 MB

All Platforms

Monitors

  • 800X600X256-dolor video resolution
  • High Color or True Color recommended.

Software requirements

Supported database servers for ClearQuest on Windows

Database Server
Versions
Windows
Solaris
HP-UX
RedHat
Linux
AIX
NT
2000
ME
98
XP
2.6
7
8
10.20
11.00
11.11
7.0
7.1
4.3.3

Microsoft SQL Server

7.0 Service Pack 3

X

X

X

X

 

 

 

 

 

 

 

 

 

 

2000 Service Pack 1

X

X

X

X

 

 

 

 

 

 

 

 

 

 

Oracle

(32 bit)

8.0.5

X

X

 

 

 

X

X

X

X

X

X

X

X

X

8.1.6

X

X

 

 

 

X

X

X

X

X

X

X

X

X

8.1.7

X

X

 

 

 

X

X

X

X

X

X

X

X

X

DB2

Universal Database 7.1 Service Pack 2 & 3

X

X

 

 

 

 

 

 

 

 

 

 

 

X

SQL Anywhere

5.5.05

X

X

X

X

 

 

 

 

 

 

 

 

 

 

Access

2000

X

X

X

X

X

 

 

 

 

 

 

 

 

 

2002

X

X

X

X

X

 

 

 

 

 

 

 

 

 

Note: 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.

Supported client database for ClearQuest UNIX

Database Server
Versions
Windows
Solaris
HP-UX
RedHat
Linux
AIX
NT
2000
ME
98
XP
2.6
7
8
10.20
11.00
11.11
7.0
7.1
4.3.3

Microsoft SQL Server

7.0 Service Pack 3

X

X

 

 

 

 

 

 

 

 

 

 

 

 

2000 Service Pack 1

X

X

 

 

 

 

 

 

 

 

 

 

 

 

Oracle

(32 bit)

8.0.5

 

 

 

 

 

X

X

X

X

X

X

X

X

X

8.1.6

 

 

 

 

 

X

X

X

X

X

X

X

X

X

8.1.7

 

 

 

 

 

X

X

X

X

X

X

X

X

X

DB2

Universal Database 7.1 Service Pack 2

X

X

 

 

 

 

 

 

 

 

 

 

 

X

Supported database servers for ClearQuest MultiSite

Databases supported on Windows Clients

Database Server
Versions
Windows
Solaris
HP-UX
RedHat
Linux
AIX
NT
2000
ME
98
XP
2.6
7
8
10.20
11.00
11.11
7.0
7.1
4.3.3

Microsoft SQL Server

7.0 Service Pack 3

X

X

 

 

 

 

 

 

 

 

 

 

 

 

2000 Service Pack 1

X

X

 

 

 

 

 

 

 

 

 

 

 

 

Oracle

(32 bit)

8.1.5

 

X

 

 

 

X

X

X

X

X

X

X

X

X

8.1.6

 

X

 

 

 

X

X

X

X

X

X

X

X

X

8.1.7

 

X

 

 

 

X

X

X

X

X

X

X

X

X

DB2

Universal Database 7.1 Service Pack 2

X

X

 

 

 

 

 

 

 

 

 

 

 

X

Universal Database 7.2

X

X

 

 

 

 

 

 

 

 

 

 

 

X

Databases supported for UNIX client

Database Server
Versions
Windows
Solaris
HP-UX
RedHat
Linux
AIX
NT
2000
ME
98
XP
2.6
7
8
10.20
11.00
11.11
7.0
7.1
4.3.3

Oracle

(32 bit)

8.1.5

 

X

 

 

 

X

X

X

X

X

X

X

X

X

8.1.6

 

X

 

 

 

X

X

X

X

X

X

X

X

X

8.1.7

 

X

 

 

 

X

X

X

X

X

X

X

X

X

Application server support

MetaFrame 1.8 Service Pack 2 application server software by Citrix Systems, Inc. on Windows 2000 Service Pack 1 or 2.

Web servers

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.

Web browsers

Note: Netscape 6 is not supported at this time. Various issues have been discovered involving a number of buttons and controls that do not operate properly with the new version of Netscape. ClearQuest may support Netscape 6 in a future release.

Database drivers

Note: MDAC 2.5 or greater is required to run Rational ClearQuest. If no version or an earlier version of MDAC is present, then the ClearQuest installation program will install MDAC 2.6.

JRE

You will need to have J2RE1_3_0 installed to use the Advanced Query Editor on ClearQuest Web.

Language support

For the following table, the following definitions are provided.

Language
Level
Double Byte

Dutch

Level 1

No

French

Level 2

No

German

Level 2

No

Hebrew

Level 1

No

Italian

Level 2

No

Japanese

Level 2

Yes

Korean

Level 1

Yes

Simplified Chinese

Level 2

Yes

Swedish

Level 2

No

Traditional Chinese

Level 1

Yes

Note: ClearQuest MultiSite can not be used to replicate a database that contains data in Double Byte Character Sets, see above table.

Getting started

For full installation instructions, refer to the manual Installation Guide for Rational ClearQuest (also available in an electronic version on the Rational Solutions for Windows Online Documentation CD).

For information on upgrading Rational Suite or integrations with other Rational products, refer to the manual Installation Guide for Rational Suite (also available in an electronic version on the Rational Solutions for Windows Online Documentation CD) and the Rational Suite Release Notes.

Licensing

Configuring the Rational Suite License Map

If ClearQuest Unix is installed as a standalone product, it will default to requesting a ClearQuest license key from FlexLM. Since ClearQuest is a member of several different Rational Suite products, this can be configured using a file known as the license map such that ClearQuest Unix requests one or more Suite licenses in addition to, or in place of, the ClearQuest license key.

The license map file resides in $HOME/.Rational (Note the `.' in front of Rational). The file name is "License_Map".

Simply set the first line of the file using the following format (please note that case is sensitive, as is formatting):

Available values for <Suite Name>:<Version> are:

standalone (means the same as the first item listed)

To traverse several licenses, starting with ClearQuest, create a "License_Map" file that has the following line: 

ClearQuest:1.1 standalone, AnalystStudio:1.0, TestStudio, RationalSuiteEnterprise:1.0

To search several licenses, looking for Enterprise Suite first, then ClearQuest, create a "License_Map" file that has the following line: 

ClearQuest:1.1 RationalSuiteEnterprise:1.0, standalone

Installation issues

Upgrading from previous ClearQuest releases

To upgrade to this release, simply install the new Version 2002.05.00 binaries over an existing installation, or on a clean machine. A database upgrade is not required to use the new features in this release.

If you are upgrading a ClearQuest UNIX installation and have previously installed OpenLink Broker on your database server, you will need to install OpenLink Broker 4.0. Please see the section in Installation Guide for Rational ClearQuest for installing OpenLink Broker for your database system.

Product documentation

On-line documentation

The following on-line pdf files are provided in the books folder of your ClearQuest installation directory:

The following on-line html files are provided through the Start menu

Printed documentation

The following printed documentation is available:

Compatibility issues

With Rational products

ClearQuest MultiSite integrations with ClearCase

ClearQuest and ClearCase both support multisite deployments. The ClearQuest/ClearCase UCM and Base integrations have been enhanced to work in a multisite deployment. Both integrations require the use of ClearCase 4.2 or higher. For additional information on using ClearQuest MultiSite with the Base ClearCase integration, please see Technical Note #22587.

Requires UCM Package version 3.0

The ClearQuest UCM package has been enhanced to work in a multisite deployment. If you plan to use ClearQuest MultiSite with the UCM integration you must upgrade your UCM package to the latest version.

Multiutil with ClearCase/ClearQuest UCM integration

Multiutil requires special database set names that are not supported by the UCM integration. Please run multiutil from a machine that does not require the ClearCase/ClearQuest UCM integration.

Must kill cqintsrv process prior to running mkreplica -export

The ClearQuest Integration Server (cqintsrv) caches information about it's current session. It is important to terminate these processes if they were running during the execution of the first mkreplica -export command on the working schema repository. If this is not done, various error messages will appear on ClearCase operations indicating that the session is no longer valid. This applies to both the Windows and Unix platforms.

ClearQuest MultiSite integrations with other products

Other Integrations including Rational RequisitePro, Rational Test Manager, Rational Administrator, Rational PQC, Microsoft Project, and Microsoft Visual Source Safe have significant restrictions in a multisited deployment. You will not be able to modify ClearQuest records that are not mastered through these integrations. Additionally, there are further restrictions on using the RequisitePro, Test Manager, and Rational Administrator integrations in a multisite deployment. Specifically, if you have mastership of a ClearQuest record, but the associated Rational Project record is not mastered in the same ClearQuest database, these integrations are read-only and you are restricted from making changes to the integration information captured in a ClearQuest record (e.g. adding new requirements to the requirements tab).

Rational Administrator, RequisitePro, and TeamTest

For integration between the Rational Administrator, RequisitePro and TeamTest with Rational ClearQuest, a ClearQuest database connection name must be association with a Rational Administrator project. The Rational Administrator can only handle database connections that have the default name. Refer to the Rational Administrator documentation for establishing associations between the Administrator and ClearQuest. Refer to the following for creating a connect to a ClearQuest database with the default connection name.

Creating a default database connection

To enable Rational Suite integrations, the connection to the ClearQuest schema repository must be with named with the default database connection name. For this release the default name is 2002.05.00 .

If the database you want to associate with the Rational project has a connection name other than the default connection name 2002.05.00, perform the following steps to rename the existing connection name to the default connection name:

  1. Start the ClearQuest Maintenance Tool by selecting Start > Programs Rational ClearQuest > Rational ClearQuest Maintenance Tool . The Rational ClearQuest Maintenance Tool is displayed.
  2. In the left pane of the ClearQuest Maintenance Tool, select the database set connection name you need to rename.
  3. Right click and select Rename .
  4. Enter 2002.05.00 to rename the connection to the default connection name, and press Enter to exit edit mode. The connection is renamed.

ClearQuest MultiSite

There are compatibility issues when using ClearQuest MultiSite when replica sites have different versions of ClearQuest. It will be most notable when importing packets with user information update modified with ClearQuest Designer version 2002.05 into a replica site with ClearQuest version 2001A.04.00.

To resolve this issue, install ClearQuest version 2002.05 at all replica sites.

With third-party products

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.

Later in 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:

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

SQL Server 7.0 and 2000 with 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:

  1. Run SQL Server Enterprise Manager.
  2. Select the Management section under the appropriate server.
  3. Select Current Activity > Locks/ProcessID .
  4. 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://www.rational.com/sitewide/support/technotes/.

ClearQuest with Oracle

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,

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\2002.05.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".
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.
Searches with the `Contains' operator are always case sensitive

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

Searching multiline text fields

To allow the searching of MULTILINE_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 Installation Guide for Rational ClearQuest manual for detailed instructions on enabling multi-line text searches.

interMedia may require revoking ctxadmin 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:

ClearQuest releases 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

Debugging E-mail notification issues

Beginning with ClearQuest v2001A.04, 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.

  1. Create *.reg files for native client and/or web server machines with the following information:
Native Client
Webserver
  1. Stop ClearQuest service.
  2. Import the *.reg file into your registry.
  3. Start the ClearQuest service.
Note: 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 Technical Note 7975.

Microsoft Project update from ProjectTracker limitation

If you have a linked task with actual start and finish dates set to some real numbers and then you delete the value of the actual finish date in ClearQuest and run Update , the change will not propagate to Microsoft Project. The log will however, display the new am_actual_finish_date as blank.

Microsoft Project does not allow you to have a blank entry in the start or finish fields.

Crystal Reports 8.0

We do not test all of the functionality associated with Crystal Reports 8.0. The following is a description of what we do test and caveats for usage with ClearQuest MultiSite. All of the testing is performed using Crystal Reports 8.0 and ClearQuest Web.

For manual testing, we test the integration performance and functionality by completing the following procedures:

For automated testing, we test the integration by:

For ClearQuest MultiSite, we:

Note: The non-mastered site cannot edit, rename, or delete a Crystal report.

Netscape Navigator

If the ListView control applet does not appear correctly on Netscape Navigator you may have to configure your Navigator to support Java Applets. This is a know Netscape Navigator issue, and is documented in the Netscape UNIX Readme. The following is reproduce for your convenience.

Java Applet Support

Java Applet support is available for all Unix platforms.

To run Java applets with the Java-enabled version, Navigator must load Java class files from a file called java40.jar . This file is included in this release, and is searched for using the following algorithm: 

if($CLASSPATH environment variable is set) 

else 

    <program directory>
    $MOZILLA_HOME/java/classes
    $HOME/.netscape
    /usr/local/netscape/java/classes
    /usr/local/lib/netscape

If you were running Java with an earlier version of the Netscape Navigator, you need to replace your old moz2_0.car , moz*.zip , or java_3* files with the new java40.jar file supplied in this release.

SQL Anywhere issues when crossing subnets

There is a known issue with Sybase Central SQL Anywhere the client and server machines are in different subnets. For information on resolving this issue refer to Sybase Central 's web site or call ClearQuest technical support.

Internet Explorer 6.0 on Windows XP operating systems

Internet Explorer 6.0 on Windows XP operating systems does not come with a JVM installed. When you ClearQuest Web in this environment, you will be presented with a dialog box to download JVM to your desktop. If you elect not to install it the ClearQuest Web will be inoperable.

New and changed features

Rational ClearQuest client enhancements

Support for reference lists in reports

Previously reference list fields could not be added to report formats and therefore, users could not generate reports, which included any reference lists. With this release, reference lists can be included in report formats and therefore, reports with reference lists can be generated.

Display only valid actions

Previously when a user clicked on the Actions buttons, all available actions were displayed including the ones that the user did not have permission to execute. With this release, access control hooks are executed first and only the valid actions are displayed to the user.

ClearQuest Window and controls sizes are saved

Previously when a user updated the client window size or the size of the results set or its columns, the settings were not saved when the user re-launched Rational ClearQuest. With this release, size of the client window, results set, and workspace, column size in results set, etc. are saved on a per desktop per database basis so that the settings are restored when the user re-launches ClearQuest.

Correct record count when viewing a results set

Previously when a user executed a query, which returned more than approximately 50 records, the record count displayed at the bottom of the client interface was empty until the user scrolled to the bottom of the results set. With this release, the record count is correctly displayed as soon as the query is executed so that users know the size of the results set instantaneously.

Results set updated dynamically

When users updated a record in Rational ClearQuest, the changes were not automatically updated to the results set. With this release, the display fields are updated dynamically with the latest information and the particular entry in the results set is italicized to signify that it has been updated.

Ability to display multiline fields in results set

Previously users could not select multiline fields as display fields in a query. With this release, users can view the first 256 characters of a multiline field in the results set.

GUI support for ClearQuest MultiSite and mastership

This release provides many enhancements to make it easy for users to get more information on mastership of various items when using ClearQuest MultiSite. Users can now figure out which records are not mastered at their site by viewing the results set, or by bringing up the record form. In addition, users can view and change mastership of workspace items such as queries, reports, etc.

Rational ClearQuest Designer enhancements

User administration

The User Administration functionality in Rational ClearQuest Designer is completed revamped to make it easy to manage an enterprise. Besides the new intuitive user interface, administrators now can simultaneously subscribe multiple users to databases, subscribe groups to databases, search for specific users by login name or full name, etc. With the new functionality, ClearQuest administrators will find it easier to manage users and groups.

Upgrade packages

The latest version of ClearQuest enables administrators to upgrade multiple packages simultaneously by automatically applying the latest packages based on the level of the existing packages.

Rational ClearQuest UNIX enhancements

Display only valid actions for any state

When a user clicks on the Actions button, Rational ClearQuest UNIX will only display the actions available at that particular time, based on the user's permissions, and the state of the record. Note that due to potential performance issues, ClearQuest will not execute access control hooks when calculating valid actions.

Previously when a user clicked on the Actions buttons, all available actions were displayed, including the ones that the user did not have permission to execute. So, for example, while only 2 or 3 actions were actually available to run, you might have 10 that would show up in the drop-down list. This enhancement improves the user experience and increases productivity by eliminating time spent clicking on invalid actions.

Results set updated automatically

When a record is modified, the display fields in a query results set are dynamically updated with the modifications made to the record in that client session.

Previously, when users updated a record in ClearQuest UNIX, the changes were not automatically updated in the results set, meaning that the query would have to be re-run to display the updated data. This enhancement saves time and improves the user experience.

OpenLink Request Broker 4.0

OpenLink Request Broker 4.0 is now installable through the ClearQuest UNIX Installation CD.

ClearQuest MultiSite enhancements

Administration on UNIX (Oracle only)

The multiutil administrative utility is now available for the ClearQuest UNIX client when using an Oracle database.

Previously the admin functionality provided by the multiutil utility was only available on Windows. With the new release, it is supported on the UNIX client as well.

Visual Mastership cue in query result set, record form

Icon shows mastership in query results and on record form.

Previously, you would have to open a record in order to be able to see what site had mastership. In the latest release, a small padlock icon highlights all records in the result set mastered at other sites, so users can immediately see which records are eligible for modification, and which are read-only.

Allocating variable size ID blocks

ClearQuest MultiSite automatically allocates ID blocks to each replicated site in order to ensure that defects entered at different sites do not have duplicated ID numbers. With the latest release, customers are able to manually increase those blocks whenever necessary.

Previously, customers were not able to extend the ID blocks, which could present a limit for enterprise customers or customers importing large numbers of defect records from legacy systems.

GUI support for changing mastership of queries

Users can now change mastership of queries through a simple right-click in order to make any necessary edits. Note that only users with the appropriate privileges can edit metrics in public folders.

Previously, in order to change mastership of a query, users would have to use the multiutil utility. In the latest release of ClearQuest MultiSite, this can be done with a simple right click on the appropriate workspace object. Note that mastership is only required when editing a set of metrics - anyone at any site can run metrics from the public folders regardless of site mastership.

Miscellaneous enhancements

Import tool

The ClearQuest Import tool has been revamped to make it user friendlier to use. In addition to the new user interface, it allows users to import defect, history and attachment data files at the same time. In addition, administrators can import multiple sets of data files without re-launching the tool. The import tool has been improved to be more reliable and to perform faster than in previous releases.

Maintenance tool

The ClearQuest Maintenance tool has been revamped to better support multiple schema repositories. Users can now create and edit schema repository connections for each schema repository. In addition, moving and upgrading databases is made easy by not prompting administrators to enter database properties every time. The database properties are automatically displayed when a database is selected in the left pane.

Late changes to documentation

A new optional parameter has been added to all of the subcommands the command line utility installutil . The new optional parameter is [dbset] . For usage and definitions type installutil at the command line with any of its subcommands.

Example: 

installutil relocateschemarepo

The following information will be displayed: 

Usage: installutil relocateschemarepo 
         [-dbset dbset_name] 
         [-delete_cqtracking_files] (see the note below) 
         db_vendor 
         server 
         database 
         dbo_login 
         dbo_password 
         rw_login 
         rw_password 
         ro_login 
         ro_password 
         connect_options(Oracle: HOST=host;SID=sid;SERVER_VER=[7,8.0,8.1];CLIENT_VER=[7,8.0,8.1];LOB_TYPE=[long,clob]) 
         [tcpip,ipx,netbios,namedpipes] (optional) 
         [host1,host2,...] (optional) 
  NOTE: The option -delete_cqtracking_files will delete 
  the information stored in CQ about the CQtracking files 
  used by a Rational Administrator Project. If you are making 
  just a test copy, this option is recommended.

Administrator's Guide changes

The following information should be added to the Administrator's Guide for Rational ClearQuest.

Copying a schema

You can copy an entire schema into a schema repository or copy a partial schema into another schema by using the CQLOAD command line utility.

Note: Make sure that the schema to which you want to apply CQLOAD is not checked out in ClearQuest Designer.
Note: If you run CQLOAD while ClearQuest Designer is running, you must exit the Designer and then login again to see your changes.
Note: Since CQLOAD doesn't support schema repository connection parameter, if you want to use a connection other than the default (2002.05.00), you will need to use the environment variable, BB_TEST_DBSET_NAME to specify the connection, i.e. from command prompt:

importintegration

The importintegration subcommand allows you to import a partial schema as a modification to an existing schema. Before using this command, you must export the partial schema using exportintegration subcommand. To import an entire schema into the schema repository, use the importschema subcommand.

Syntax 
cqload importintegration <login> <password> <schema name> <record type> <"integration name"> <integration version> <schema pathname> <"comment or description"> <new form >)

Where
Represents

ClearQuest login

The ClearQuest login name of the user. This user must have Super User privileges.

ClearQuest password

The ClearQuest password for the respective user.

schema name

The name of the schema associated with the integration. This name is the simple name of a schema that is defined in your schema repository (e.g. TeamTest). This schema will increase by one revision number after running CQLOAD.

record type

The record type in the target schema (e.g. Defect) to which you want to add an integration.

integration name

The name you give the integration. It can be any alphanumeric indicator of the integration you are loading.

integration version

The version you are loading. It should be numeric.

schema pathname

The pathname of a schema integration file that has been produced by exportintegration. There are a number of integrations delivered out-of-the-box in the <installation-dir>/addin's directory.

form name

The forms to which the new tabs (created by the integration) will be added. If no form updates, type "" to indicate no form update.

Example 
cqload importintegration admin "" Testit Defect Email_Integ 1 "c:\program files\rational\clearquest 1.1\schema.txt" ""

The above example imports the partial schema into the Defect record type of the Testit schema.

exportintegration

The exportintegration subcommand, part of the CQLOAD command line utility, exports revisions of a schema that would constitute pieces that could be added to another schema. This is useful for advanced users who want to create an integration for use at different (non-network connected) sites. Exportintegration differs from the exportschema subcommand in that it exports partial schemas, not the entire schema. To import the data into another schema, use the importschema subcommand.

Syntax 
cqload exportintegration <login> <password> <schema_name> <begin_rev> <end_rev> <record_type> <schema pathname>

Where
Represents

login

ClearQuest login name of the user. This user must have Super User privileges.

password

ClearQuest password for the respective user.

schema name

name of the schema associated with the integration.

Begin_rev

First schema revision whose changes you want to save.

End_rev

Last schema revision whose changes you want to save.

record_type

Record type in the schema whose revisions you are saving.

schema pathname

Pathname of the file that will contain the results of exporting the schema revisions.

Example 
cqload exportintegration admin "" Enterprise 5 5 defect c:\]temp\scriptchanges.txt

The above example exports only changes made in version five of the Enterprise schema. 

cqload exportintegration admin `"enterprise 5 8 defect c:\temp\newscripts.txt

The above example exports changes made in versions five through eight.

importschema

The importschema subcommand, part of the CQLOAD command line utility, imports an entire schema from a textual representation and adds it to your schema repository. It can be useful if you want to share schemas with sites that can not access your schema repository or have a different schema repository. Before using importschema, you must export the schema using the exportschema command. To import a partial schema, use the importintegration subcommand.

Syntax 
cqload importschema <login> <password> <schema pathname>

Where
Represents

login

The ClearQuest login name of the user. This user must have Super User privileges.

password

The ClearQuest password for the respective user.

schema pathname

The pathname to the file that contains the textual representation of a schema that has been saved by the exportschema subcommand.

Example 
cqload importschema admin "" c:\schema.txt

The above example imports the schema whose textural representation was contained in c:\schema.txt into the current schema repository.

Note: C:\schema.txt was created using the cqload exportschema command. During that process, the name of the exported schema was saved into this file. So when you import this schema, that schema name will be used to create the schema with cqload importschema. If that name is already in use in your schema repository, the import will not work.

exportschema

The exportschema subcommand, part of the CQLOAD command line utility, is used to export entire schemas to a text file. This can be used to create files that can be used by importschema.

Syntax 
cqload exportschema <login> <password> <schema name> <schema pathname>

Where
Represents

ClearQuest login

The ClearQuest login name of the user. The user must have Super User privileges.

ClearQuest password

The ClearQuest password for the respective user.

schema name

The name of the schema in your schema repository that is to be exported to a text file. (e.g. TeamTest).

schema pathname

The text file version of a schema to be saved.

Example 
cqload exportschema admin "" DefectTracking c:\schema.txt

The above example exports the contents of the DefectTracking schema to the file c:\schema.txt.

Using hooks in ClearQuest Web

Using hooks in ClearQuest Web

Note: Please replace the description for this section. The previous limitation for creating hooks in Visual Basic for the ClearQuest Web is not longer a restriction.

Hooks that you create in your schema will run on the web server with ClearQuest Web. Keep in mind the following when using hooks on ClearQuest Web:

Recovering from import errors

The following text should replace text found on page 251 of Administrator's Guide for Rational ClearQuest .

If errors occur during the import, ClearQuest creates the following files:

For example, import_status_20011012_1355_01.txt would indicate a status file created on October 12, 2001 at 1:55:01 p.m.

To re-import these problem records:

  1. Check the errlog.txt file and review the types of errors encountered.
  2. Open the error file containing the unimported records.
  3. Correct the errors in the records. Be sure the error file uses the import file format. See "Formatting the record import files" on page 251 of the Administrator's Guide for Rational ClearQuest MultiSite .

Perform the import process again, this time specifying the error file as the import file.

ClearQuest Installation Guide changes

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.

Creating a ClearQuest test database

If you want to make a test copy of your production system, either to test the upgrade process to a new release, or to test some new development that you do not want to do in a production database, or for any other purpose:

  1. Make a physical copy of the database in a new location.
  2. Use ClearQuest Maintenance Tool to relocate the databases.
  3. At the command line run the -delete_cqtracking_files option with the installutil relocationschemrepo command.

If you do not perform step 3, the database connection for your users will be reconnected to the new test database rather than the existing production database.

ClearQuest MultiSite documentation additions and changes

The following documentation covers information that is not included in the documentation and/or includes late-breaking changes made to ClearQuest MultiSite.

Changing mastership of objects

With ClearQuest MultiSite 2002.05.00, you can now change the mastership of Workspace items, users and groups from the ClearQuest client and ClearQuest Designer, respectively.

Changing the mastership of Workspace items

You can use the either the ClearQuest Windows and UNIX clients, or the ClearQuest MultiSite commands to change the mastership of a Workspace item (query, report, chart, or report format).

Changing mastership using ClearQuest

To change mastership of a Workspace item using the ClearQuest Windows or UNIX clients:

Note: You must have Public Folder Administrator privileges to modify Workspace items in the Public Queries folder.
  1. In the Workspace , right-click the item you want to modify and choose Mastership .
  2. In the Change Mastership dialog box, choose the new mastering site from the New Mastering Site drop-down list.
  3. Click OK .
Changing mastership using multiutil commands

To change mastership of a Workspace item using the ClearQuest MultiSite commands:

Use the chmaster multiutil command to change the mastership of a Workspace item. Pay special attention to the following syntax for the entity-selector option:
"Workspace:Personal Queries(username)\<Folder>\<Query>"

and

"Workspace:Public Queries\<Folder>\<Query>"

The Workspace item must include the full path name and be encapsulated in quote marks. If you are changing a Workspace item in a personal folder for another user, you must also include the user login name.

For example, at replica paris, if you are user name "parisadmin" and you want to transfer mastership of a report format called "Project report" that resides in the Personal Queries folder of the user, jsmith, enter the following:

To accomplish the change of mastership for a public folder the command would be:

Changing the mastership of users

You can use the ClearQuest Designer to change the mastership of a user or group.

To change the mastership of a user:

  1. Select Tools > User Administration .
  2. In the User Administration dialog box, double-click the user you want to modify.
  3. In the User Properties dialog box, choose the new mastering site from the Mastership drop-down list.
  4. Click OK .
  5. Click OK .
  6. As with any change of a user or user group, the new mastering site MUST perform a database upgrade after receiving the synchronization packet containing the changes. See the ClearQuest MultiSite Administrator's Guide for details.

Changing the mastership of user groups

  1. Select Tools > User Administration .
  2. In the User Administration dialog box, select the user group you want to modify.
  3. Select Group Action > Edit Group .
  4. In the Group Property dialog box, choose the new mastering site from the Mastership drop-down list.
  5. Click OK .
  6. Click OK .
  7. As with any change of a user or user group, the new mastering site MUST perform a database upgrade after receiving the synchronization packet containing the changes. See the ClearQuest MultiSite Administrator's Guide for details.

Changing mastership of records

Because of the dynamic nature of database records, ClearQuest MultiSite provides two ways to change the mastership of a record. You can change the mastership of database records by using the chmaster command or by using the ratl_mastership field.

Changing the mastership of records using ClearQuest

To change the mastership for a state or stateless record type you will need to modify your forms in the ClearQuest Designer. Refer to Administrator's Guide, Rational ClearQuest , Chapter 6: Managing Mastership , section Using Mastership with records .

After you have added the ratl_mastership field to your forms you can modify this field or the record name field in the ClearQuest client using the standard functionality. For more information consult your ClearQuest client help system.

Changing the mastership of records using multiutil

When you use the chmaster command, only ClearQuest users with the Super User privileges and access to MultiSite administration tools can change the mastership of a record. In addition, mastership can only be changed at site of the mastering replica.

Note: When you create a new record, it is mastered by the site or site replica location where you create it.

To transfer mastership of a stateless record to another replica using the chmaster command, at the mastering replica (boston), enter a chmaster command:

Moving a replicated schema repository

Note: This section completely replaces the topic "Moving a replicated schema repository" found in the Administrator's Guide for Rational ClearQuest MultiSite in Chapter 5: Managing replicas .

There may be times where you want to move your replicated schema repository to a different location on the network or switch it to use a different vendor database software. A replicated schema repository can be moved just as a non-replicated schema repository.

Move the schema repository using the ClearQuest Maintenance Tool, using the instructions in the Administrating Rational ClearQuest manual (located in the \\ClearQuest\books directory).

Resolving naming conflicts

If you don't impose a site-specific naming convention for ClearQuest objects such as Workspace items (queries, reports, charts, etc.), users and groups, and other stateless records, it is possible to have same-named objects.

For example, duplicate names can occur when user administrators at two sites add a user of the exact same name within a synchronization cycle. In this case, after the replicas are synchronized, two users will exist that have the same name.

Internally, however, ClearQuest automatically ensures that records and Workspace names are unique.

Identifying Workspace naming conflicts

If two Workspace items (queries, reports, etc.) are inadvertently given the same name, both items will work as expected in both the Windows and UNIX clients, according to mastership restrictions and database privileges. However, in ClearQuest Web, only one of the same-named items will work.

To avoid confusion, you should rename at least one of the items.

Renaming Workspace items using ClearQuest

You must have mastership of a Workspace item to modify it. To determine where a Workspace item is mastered, see Changing mastership of objects .

To rename a Workspace item,

  1. Right-click the Workspace item you wish to rename and select Rename .
  2. Type a new name in the highlighted area and click Enter
Working with ambiguous Workspace objects using multiutil

If you need to use multiutil commands to work with a Workspace item with a naming conflict, you'll need to refer to its keysite name (originating site name). For example:

"Workspace:\Public Queries\Project Report<keysite_name>" .

The keysite name is the name of the site where the Workspace item originated.

Note: The following command line example uses the describe command. In most cases, you may find it easier to use ClearQuest Windows or UNIX clients to change the mastership of Workspace items, see Changing mastership of objects .

Identifying stateless record type naming conflicts

To fix a naming conflict for a stateless record, you must change the name of one of the records to be unique.

Using ClearQuest to rename records

To rename a stateless record that has a naming conflict:

  1. Find the record in question.
To find/view stateless records with naming conflicts, you can do two things:
  • You can create a query designed to viewing naming conflicts.
  • You can also modify your schema by adding the ratl_keysite field to the form of each stateless record type so you can better view naming conflicts. Schema modifications must be made at the working schema repository.
  1. Change the name of the record to be unique. You must have mastership of the record to modify it.
To rename a stateless record, you must modify a field(s) that is used as the unique key for that record. To do this, use the action in your schema that allows you to modify records without changing their state.
  1. Synchronize the replica family.
Using the ratl_keysite field

Stateless record types use the ratl_keysite field to ensure that a record is unique. The ratl_keysite field is an internal system field that ClearQuest uses to store the name of the site where an object was originally created.

For example, a new customer named NetworkInc is created at two replicas during the same time period between synchronizations. When each site synchronizes, there will seemingly be two customer records with identical names. However, internally, ClearQuest references the ratl_keysite field to ensure uniqueness.

Creating a query to view record naming conflicts

You can use the ratl_keysite field in queries designed to find stateless records of the same name.

Follow these guidelines when querying for stateless records with naming conflicts.

  1. Use the ratl_keysite field as both a Display field and Filter when creating a query on the respective stateless record type.
  2. If the query finds any duplicated named records, rename them using a site-specific naming convention that has been agreed upon. Remember that you must have mastership of a record to modify it.
Modifying your schema to view record naming conflicts

You can use the ratl_keysite field in your schema to assist you in viewing/modifying records by adding the ratl_keysite field to the form of any stateless record type where you expect naming conflicts to arise. For more information about modifying your schema see Chapter 4, Customizing a schema in the Administrator's Guide for Rational ClearQuest .

Working with ambiguous records

If you need to use multiutil describe or chmaster commands to work with an ambiguous record, you must refer to its keysite name (originating site name). For example, customer:General_electric<boston> .

The keysite name is the name of the site where the Stateless record item originated.

Note: The following command line example uses the describe command. In most cases, you may find it easier to use ClearQuest Windows or UNIX clients to change the mastership of stateless records, see Changing the mastership of records using multiutil .

Identifying user and user group naming conflicts

To login with an ambiguous user name, use the keysite name as part of the user login name. If an ambiguous user name is used without the site-extension during log in, then you get an invalid Login error. Clicking on the detail, will give you the following error: 

User name 'xxx' is ambiguous; rename or qualify with '<'SITE'>' to proceed.
Using ClearQuest Designer to rename users

In ClearQuest Designer, when you try to modify a user that has a conflicting name, you'll get the following error message:

ERROR! The string value ("DupUser<SITE1>") is invalid: Names cannot contain one of these characters:! "#$%&'()*+,./:;<=>?@[\]^`{|}~

You'll need to rename the user. Until you rename the user to have a unique name, you cannot modify any user information, except for the Name field.

Note: You cannot rename or delete a user group.

To rename a user:

  1. Select Tools > User Administration .
  2. In the User Administration dialog box, double-click the user you want to modify.
  3. In the User Properties dialog box, modify the name of the user.
  4. Click OK .
  5. Upgrade the associated user database by choosing DB Action > Upgrade.
  6. In the Upgrade dialog box, select the user database(s) you wish to upgrade.
  7. Click OK .
  8. Click OK .
  9. As with any change of a user or user group, the new mastering site MUST perform a database upgrade after receiving the synchronization packet containing the changes. See the ClearQuest MultiSite Administrator's Guide for details.
Working with ambiguous users and user groups using multiutil

If you need to use multiutil describe or chmaster commands to work with a user or group that has the same name as another user or group, you'll need to refer to its keysite name (originating site name).

Note: The following command line example uses the describe command. In most cases, you may find it easier to use ClearQuest Designer to change the mastership of users and groups, see Changing the mastership of users .

Differentiating packets with storage classes

You can configure the store-and-forward facility to handle updates for different replica clans in different ways. Each packet can be assigned to a storage class, and each storage class can have its own storage bay, return bay, and expiration period.

Note: The default storage class used by ClearQuest MultiSite varies according to command. All ClearQuest MultiSite commands that use the -sclass argument use the default storage class name of cq_default, except mkorder and shipping_server, which default to the storage class name of default.

Conversely, several storage classes can share one or more storage bays.You can use multiple storage classes to segregate the packets for replicas belonging to different clans. By adjusting the operating system permissions on the storage bay directories, you can protect the packets from unauthorized use. You can also use a separate storage class when you use the store-and-forward facility to transfer non-ClearQuest MultiSite files between sites.

Note: On UNIX, a storage class can be assigned several storage bays; in this case, shipping_server uses the size of the packet to select one of the bays.

Rational MailReader Help system changes

The format for submitting changes to a reference list field from the Rational MailReader has been change to allow you to submit multiple values. The new form is: 

reference_list_field_name: value1, value2, value3

An example of adding the user names admin and user to the Owner reference list field is:

ClearQuest client help system changes

Creating reports in ClearQuest Web

ClearQuest allows you to associate existing queries with existing report formats in order to produce reports. The report formats must already exist in the database. You can choose what kind of information displays in the report by creating a query and associating it with the report.

If you want different report formats than those that display in ClearQuest, you must ask your ClearQuest administrator to define them and add them to the database.

To create a new report:

  1. Select Create a Report from the Operations menu.
The Create a Report dialog box appears.
  1. Select a record type from the Record Type drop-down list.
  2. Enter a name in the Report Name text box.
Note: You cannot use backslashes for forward slashes in the report name.
  1. Select a format from the Report Format drop-down list.
These formats are created and saved in the database by your ClearQuest administrator. If you need additional formats, ask your ClearQuest administrator to create them.
  1. Select the type of information to include by choosing a query from the Report Query drop-down list.
  2. Click Next .
ClearQuest indicates that your report was saved successfully. It displays in the Workspace.
  1. To run the report, click Run Report .
The report appears in a separate window.

Changes to the URL processing in CQWeb

You can paste or enter a URL into the description box of a defect. ClearQuest Web will detect these URLs and add a drop-down list below the description box. The first item in this drop-down list will be "--Embedded References--". You can select any URL in the list to go directly to that web site.

If these URLs contain embedded spaces, they must be enclosed in double quote (") characters to be properly recognized and placed in the list.

For example:

http://somehost/somepage?field1=this is a test

must me pasted in as:

"http://somehost/somepage?field1=this is a test"

Otherwise the URL will be extracted as:

http://somehost/somepage?field1=this

Embedded references with embedded double quote characters cannot be parsed. If you have a URL with embedded double quote characters, replace them with the character string:

&quot;

Although &quot; will display in the drop-down list, it will be translated as a double quote and it will take you to the correct web site.

ClearQuest Web client help system changes

Editing login timeout settings

The Login Timeout value specifies the amount of time in milliseconds it to wait on a global lock before giving up. The default value is 15000 (or fifteen seconds).

To change the Timeout value:

  1. Log in to ClearQuest Web with administrator privileges.
  2. Select Operations > Edit Web Settings > Login Timeout .
  3. Set the value based on the following considerations:
    • If the Login Timeout value equals 0, then the default IIS setting would be in effect.
    • All values should be converted from minutes to milliseconds and then entered as the Login Timeout option.
Note: The value change will not be in effect until the next logon.

ClearQuest/VisualSourceSafe help system changes

User login names for ClearQuest/VisualSourceSafe integration application will need SQL Editor user privileges. For information on setting SQL Editor privileges refer to your Administrator's Guide for Rational ClearQuest .

Guidelines and Restrictions

Network guidelines, restrictions and tips

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.

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:
    • If you are using IIS4, leave the Run in separate memory space unchecked and click Apply .
    • If you are using IIS5, set the Application Protection: setting to Low (IIS Process) and click Apply .
  3. Then, further down the Internet Service Manager workspace, expand Microsoft Transaction Server > Computers > My Computer > Packages Installed and find the entry for the CQWeb virtual directory (the name will be similar to IIS-{Default Web Site//Root/CQWeb} ).
  4. Right click and select Properties , click on the Identity tab, and find the User field.
  5. Ensure that this user field is set to the anonymous user account defined specifically for serving ClearQuest Web. See the Installation Guide for Rational ClearQuest manual for more information on the configuration of IIS 4.0 and IIS 5.0.
  6. Click OK to commit the changes.

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:

Advanced Web Server 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 Installation Guide for Rational ClearQuest.

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:

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

Location: ClearQuest Core:adregistry.cpp:569 occurred in BBOLEI~1

See the Installation Guide for Rational ClearQuest, for information on setting the proper permissions.

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:

See the Installation Guide for Rational ClearQuest, for information on setting the proper permissions.

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 they are not in the same domain, you will get errors. For more information:

Changing Script time out limit

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

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. Right click on your ClearQuest Web directory and select Properties from the pop up menu.
  3. Select the Virtual Directory tab and click Configuration .
  4. Select the App Options tab in the Application Configuration dialog box.
  5. Enter the appropriate number of seconds in the ASP Script timeout box.

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:

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

Terminal Server Security Settings

If you or one of your ClearQuest users get an ODBC error when logging into the ClearQuest database through Citrix or a terminal server, you may need to change the following security privilege settings for your NT or Windows 2000 user group.

  1. Select Start > Run and enter regedt32 .
  2. In the HKEY_LOCAL_MACHINE window select SOFTWARE > ODBC .
  3. From the menu bar, select Security->Permissions . The Permissions for ODBC dialog box is displayed.
  4. If the user group is not present, add the group that the user belongs to by clicking Add and selecting the appropriate group.
  5. In the Permissions for ODBC dialog box, highlight the user group and check the Allow box for Read in the Permissions area.
  6. Click OK to apply the new permissions and exit the Registry Editor.

If you or one of your ClearQuest users cannot do any operation that needs to write the file to ClearQuest program directory, you will need to set the security privileges for the Rational installation directory. For example, the user cannot create a new query.

  1. From Windows Explore, select the directory that contains your Rational Software. The default location is C:\Program Files\Rational .
  2. Right click on the directory and select the Property from the shortcut menu.
  3. In the Rational Properties dialog box, click the Security tab.
  4. If the user group is not present, add the group that the user belongs to by clicking Add and selecting the appropriate group.
  5. In the Rational Properties dialog box, highlight the user group and check the Allow box for Full Control in the Permissions area.
  6. Click OK to apply the new permissions and close the Properties menu.

MultiSite Tips and Workarounds

Enabling Email Notification

To enable email notification on Rational Shipping Server machines where ClearCase is not installed, please see Technical Note #22590.

Adding a User database that will be replicated

When adding a new user database at the working schema repository site, Rational recommends that you replicate the new user database prior to subscribing users to it.

The only exception to this rule is when a user(s) is subscribed to all databases. Users that are subscribed to all databases will work fine regardless of the order in which the steps are done, see the technical note 22578 at http://www.rational.com/sitewide/support/technotes for details to defect 19099.

If users are subscribed to the new database before it is replicated, those users will not be able to login to the new database replica until their database subscription is updated at the working schema repository site.

  1. Using the ClearQuest Designer, log into the working schema repository. This must be done at the working schema repository site and you must have at least User Administrator privileges.
  2. In ClearQuest Designer, choose Tools > User Administration. The User Administration dialog box displays.Open the user administration dialog box and select the user that has the subscription problem.
  3. In the User Administration dialog box, select the user that cannot log into the replica.
  4. In the User Administration dialog box, click DB Subscriptions to view the Database Subscriptions dialog box.
  5. In the Database Subscriptions dialog box, click OK to close the dialog box.
  6. Click yes when the change confirmation box pops up
  7. Repeat this process for each user that is having subscription problems.
  8. Click Yes when the change confirmation box pops up.
  9. In the User Administrator dialog box, click Upgrade the user DB.
  10. In the Select Site dialog box, select the user database you want to upgrade (choose the replica you just created).
  11. Synchronize the change to all sites that have the subscription problem.
  12. If the user(s) is only subscribed to databases that are replicated, then viewing the database subscriptions for the user will now work at all sites that have a replica of the new user database. Sites that do not have this replica will still be unable to view the database subscriptions for the user.

Restoring the multiutil database connections

The ClearQuest MultiSite command line interface, multiutil , uses a unique database set name to access database replicas. When ClearQuest is uninstalled from a machine, the database set information on that machine is removed. When you reinstall ClearQuest the database set information must be recreated.

In the ClearQuest Maintenance Tool, select the Connection > New option and provide the connection information for the schema repository at this site. You must name the connection using the following format:

Running mkreplica -export

Before running mkreplica -export command verify that all users are logged off.

Recovering from a mkreplica -export failure

If a mkreplica-export fails, your database may be left in a locked state. You should use the following procedures to resolve these problems or call Rational Technical Support.

Unlock the Schema Repository and User database
  1. Unlock the schema repository with the 'installutil unlockschemarepo' command.
The 'unlockschemarepo' subcommand has the following usage:
Example: To unlock the SQL_SERVER schema repository database 'test_master_sitea' on server QE_TEST1, use: 
    installutil unlockschemarepo SQL_SERVER QE_TEST1 test_master_sitea multisite multisite ""
where 'multisite' is the dbo_login and password for the 'test_master_sitea' database.
  1. Unlock the user database with the 'installutil unlockuserdb' command. The 'unlockuserdb' subcommand has the following usage:
Example: To unlock the SQL_SERVER user database 'test_user_sitea' on server QE_TEST1, use: 
    installutil unlockuserdb SQL_SERVER QE_TEST1 test_user_sitea multisite multisite ""
where 'multisite' is the dbo_login and password for 'test_user_sitea'.
Subsequent multiutil commands fail

If subsequent attempts with mkreplica -export result in messages that indicate that the replica already exists or that another multiutil operation is in progress refer to Rational Technical Support Tech Note 18770 or contact Rational Technical Support.

UNIX Tips and Workarounds

Debugging Oracle Connection Issues

The ClearQuest Unix client tends to be more sensitive to Oracle connection issues that the ClearQuest Windows client. This guide should serve as a starting point for debugging these connection problems. Search through the table until you find the error message that you've received and cross check it with the command you've entered. The analysis procedure will describe items to check for and possibly correct. It is split into two parts. The first part maps a particular error message that might be received with examples and step by step debugging tips. The debugging tips may reference common debugging techniques. These can be found in the second table, below.

Error messages

Error Message
Description, Example, and Analysis Procedure

RPC: Unknown Host

Description

When ClearQuest Unix attempts to contact the OpenLink Request Broker on the host specified in the connect string and the client unix machine is unable to resolve the host name to an IP address.

Example Command 
pdsql -v ora -s badhost:SID -u system -p manager -co "SERVER_VER=8.1"

"badhost" would not be resolvable to an IP address for this processor in this example. This type of error could also occur during initial registration of the ClearQuest schema repository or during ClearQuest logon processing.

Example Error Message 
OpenLink: RPC: Unknown host 
EXCEPTION: [OpenLink][ODBC]RPC: Unknown host 
State: 08004 Native: 0 
Connect String used: SVT=Oracle 8 ; DRIVER=/files/a/rational/releases/ClearQuestClient. 2002.05.00/linux/shlib/db_ORACLE8;HOST=badhost; PROTOCOL=TCP/IP; UID=admin; DATABASE=SID
Analysis Procedure

Determine the host that ClearQuest is attempting to access for this particular operation. Don't assume that this is the host specified in the input command. To be sure, check the HOST= parameter of the Connect String. In the example, it is "badhost".

The host specified in the HOST= parameter should match the expected host name of the database server. If it does not, perform the "Verify ClearQuest database settings" common debugging procedure to determine the source of the errant hostname and retry the failed operation.

If the host specified matches the expected host name of the database server, then perform the "Ping selected host" common debugging procedure to determine or repair connectivity and retry the failed operation.

RPC: Program unavailable

Description

When ClearQuest Unix attempts to contact the OpenLink Request Broker on the host specified in the connect string, the destination host is available, but the Openlink Request Broker cannot be contacted.

Example Command 
pdsql -v ora -s goodhost:SID -u system -p manager -co "SERVER_VER=8.1"

"goodhost" would be resolvable to an IP address for this processor in the example, but the OpenLink Request Broker could not be contacted. This type of error could also occur during initial registration of the ClearQuest schema repository or during ClearQuest logon processing.

Example Error Message 
OpenLink: RPC: Program unavailable 
EXCEPTION: [OpenLink][ODBC]RPC: Program unavailable 
State: 08004 Native: 0 
Connect String used: SVT=Oracle 8; DRIVER=/files/a/rational/releases/ClearQuestClient. 2002.05.00/linux/shlib/db_ORACLE8;HOST=goodhost; PROTOCOL=TCP/IP; UID=admin; DATABASE=SID
Analysis Procedure

Determine the host that ClearQuest is attempting to access for this particular operation. Don't assume that this is the host specified in the input command. To be sure, check the HOST= parameter of the Connect String. In the example, it is "goodhost".

The host specified in the HOST= parameter should match the expected host name of the database server. If it does not, perform the "Verify ClearQuest database settings" common debugging procedure to determine the source of the errant hostname and retry the failed operation.

If the host specified matches the expected host name of the database server, then perform the "Verify OpenLink Request Broker is running" common debugging procedure to determine or repair connectivity and retry the failed operation.

ORA-01034: ORACLE not available

Description

When ClearQuest Unix attempts to contact the OpenLink Request Broker on the host specified in the connect string, the OpenLink Request Broker is available, but cannot contact the Oracle instance on the database server. There are at least two known reasons for this. First, the Oracle instance id (SID) could be incorrect, it is case sensitive on Unix. Second, the Oracle database or listener might not be running on the database server.

Example Command 
pdsql -v ora -s goodhost:badSID -u system -p manager -co "SERVER_VER=8.1"

"goodhost" would be resolvable to an IP address for this processor in the example, but badSID is not a valid Oracle instance ID. This type of error could also occur during initial registration of the ClearQuest schema repository or during ClearQuest logon processing.

Example Error Message 
OpenLink: [Oracle Server]ORA-01034: ORACLE not available[SQLSTATE:S1000] 
EXCEPTION: [OpenLink][ODBC] ORA-01034: ORACLE not available State: S1000 Native: 0 
Connect String used: SVT=Oracle 8; DRIVER=/files/a/rational/releases/ClearQuestClient. 2002.05.00/linux/shlib/db_ORACLE8;HOST=goodhost; PROTOCOL=TCP/IP; UID=admin; DATABASE=badSID
Analysis Procedure

Determine the host that ClearQuest is attempting to access for this particular operation. Don't assume that this is the host specified in the input command. To be sure, check the HOST= parameter of the Connect String. In the example, it is "goodhost".

The host specified in the HOST= parameter should match the expected host name of the database server. If it does not, perform the "Verify ClearQuest database settings" common debugging procedure to determine the source of the errant hostname and retry the failed operation.

If the host specified matches the expected host name of the database server, verify the exact SID and current state of the Oracle instance by performing the "Verify Oracle Connectivity" common debugging procedure and retry the failed operation.

Debugging descriptions and procedures

The following table describes some of the common debugging items and provides procedures for recovery.

Debugging Items
Description and procedure                                                                                                                                             

Ping selected hosts                   

Description

Much of ClearQuest Unix connectivity is dependent on being able to access a particular host as it has been specified during database configuration.

Debugging Procedure

From the Unix processor that needs connectivity to the remote host, enter: 

    ping <remote host>

If ping is not in the current user's path, it can typically be found in /usr/sbin . Depending on the client operating system, a successful ping will return "<remote host> is alive or that a certain number of bytes was received from that host.

There are several possible responses if the remote host is not accessible:

  • Unknown Host
Unknown Host implies that the nameserver for the current processor does not recognize the specified <remote host>. If the remote processor is a Windows machine, the site nameserver will likely need configuration to support name resolution from the unix client. Contact your site IT organization to assist in resolving this problem.
  • No answer from <remote host> or Destination Host Unreachable
No answer from <remote host> implies that the destination hostname is recognized by the current processor but network configuration or availability of the target host prevents network connectivity. Contact your site IT organization to assist in resolving this problem.

Verify ClearQuest database settings

Description

ClearQuest Unix makes an initial connection to the schema repository using information entered by the administrator in the Register Databases dialog box. The database connection information for the schema repository and all user databases is then downloaded to the client and stored in the ClearQuest databases directory. The connection information that was originally provided when the database was created using the ClearQuest Maintenance Tool or later modified using the modify database properties feature of ClearQuest Designer is the source of the data copied to the Unix client.

Debugging Procedure
  1. From the ClearQuest Unix client, enter the following command: 
    cqreg show
  1. This will display all information that the ClearQuest Unix client has about the schema repository and user database properties.

For Oracle databases, verify the HOST= parameter in the ConnectOptions string matches the host name of the database server. This host name must be pingable by the ClearQuest Unix client using that name (see Ping selected host common debugging procedure for details). The Server parameter refers to the SQLNet alias specified for the Windows client. This is not used on the Unix clients and may be ignored.

If the information is incorrect or out of date, perform the following steps:

  1. Use ClearQuest designer to correct the information
  2. Execute the following refresh command from the ClearQuest Unix command line because the ClearQuest Unix client does not automatically refresh database connection information from the schema repository:
cqreg refresh

Verify OpenLink Request Broker is running

Description

ClearQuest Unix communicates to the Oracle Database via the OpenLink Request Broker. The OpenLink driver which is shipped with the client contacts the OpenLink Request Broker, which in turn spawns off a database vendor specific agent to handle the actual requests. In order for this to function properly, the OpenLink Request Broker must be running and available on the database server processor.

Debugging Procedure
  1. From the Oracle Database server, enter the following command: 
    ps -e | grep oplrqb
  1. This will list all processes on the machine that contain the string "oplrqb". This is the process name for the OpenLink Request Broker. If it is not running, it needs to be started and enabled for restart at system boot time.

To start the OpenLink Request Broker manually, traverse to the openlink_server directory and execute the oplcfg utility:

  1. cd [rational_dir]/releases/ ClearQuestOracleSupport.[version]/ openlink_server/[arch]/bin
  2. Enter oplcfg
  3. Select option `S'

This will start the openlink request broker. To ensure that the request broker is started automatically at boot time, consult the Installing ClearQuest manual.

Verify Oracle Connectivity

Description

ClearQuest Unix communicates to the Oracle Database via the OpenLink Request Broker. The OpenLink Request Broker acts like any other Oracle client and must have connectivity and privileges to access the Oracle database.

Debugging Procedure
  1. Logon as the user that executes the OpenLink Request Broker.
  2. Traverse to the OpenLink install directory. This is typically: 
[Rational_Dir]/releases/ClearQuestClient.[Version]/openlink_server/ [Arch]/bin.
  1. Browse the OpenLink rules file "oplrqb.ini". Search for "generic_ora7" or "generic_ora8", depending on which version of Oracle is running on the database server. Look for the ORACLE_HOME and ORACLE_SID variables. Ensure these are set correctly (case is sensitive).
  2. To determine the actual SID executing on the Oracle database server, execute: 
    ps -ef | grep pmon
The pmon<SID> process contains the actual SID.
  1. Execute sqlplus from the server as the user who executes the OpenLink Request Broker. 
    sqlplus <user id>/<password>@<ORACLE_SID>

This should return an SQL prompt in which SQL commands can be executed, if it does not, consult the Oracle configuration documentation to correct the problem and retry the operation.

When ClearQuest Unix registers databases, it uses the information specified in the Register Database dialog box to initiate the first connection. The information stored in the schema repository is then used for subsequent connections. It is important to verify the connect options string by checking the Database->Database Properties menu item in ClearQuest designer. Verify that HOST, SID, and SERVER_VER are correct. In addition, verify that LOB_TYPE is set to LONG, other values are not currently supported.

Executing Nightly Reports using cqtool

A common question concerns how to automate running various reports overnight. This is almost always coupled with some amount of e-mail notification. This is an example of using cqtool, the ClearQuest Unix command line interface, to dynamically create and execute an ad-hoc query that will display the defects that are in the submitted state. More detailed information on this example can be obtained by executing: 

man cqtool or cqtool new_query -man

There are three essential elements of cqtool use: logging in to the database, assembling a set of commands to execute, and determining the output. All examples will use the out of the box sample database.

Logging in to the sample database is typically done with a database name of SAMPL, a user id of admin and a blank password. Executing cqtool login will start a command line shell that allows you to interactively work with ClearQuest Unix from the command line: 

cqtool login -database SAMPL -user admin -password ""

To execute other commands, but in batch mode, replace login with the command to be executed. In the case of this example, we want cqtool to create a new query and execute it. This is done with the new_query command. The new_query command takes a number of parameters for field display and filter operations. Fields can be displayed with the - field <fieldid> option and filters are executed with -<filterop> variable value. This example displays the id, headline, and submitter fields for all defects that are in the submitted state. 

cqtool new_query -type defect -field id -field headline -field submitter -eq state submitted -database SAMPL -user admin -password ""

This will return the following query result from the sample database: 

id            Headline                                            Submitter 
--            --------                                            --------- 
SAMPL00000011 change due amount is supposed to be red               engineer 
SAMPL00000012 would like logout button to be larger                 engineer 
SAMPL00000016 too many spaces in "change due" field                 lead 
SAMPL00000019 sales tax incorrect for NH                            lead 
SAMPL00000021 inventory report is not running correctly             lead 
SAMPL00000024 overriding price operation allows negative number     QE 
SAMPL00000027 add item button is out of line with the other buttons QE 
SAMPL00000028 context sensitive help fails from reorder window      QE 
SAMPL00000029 formatting does not look right in inventory report    QE 
SAMPL00000030 add items fails for large quantities                  QE 
SAMPL00000032 shortcut to logout does not work                      QE 
SAMPL00000033 unable to add item already in sale list               QE 
SAMPL00000034 cancel sale leaves ite in purchase list               engineer 
SAMPL00000036 inventory report is displaying an empty column        engineer 
SAMPL00000037 need report for items ordered on a given day          engineer 
SAMPL00000038 sales tax amount is offset from label                 engineer 
SAMPL00000039 need automatic logout with QEeout                     engineer 
SAMPL00000040 spelling error in help for override price             engineer 
Count: 22

Finally, the user can specify the output using the -output_file <filename> parameter. This can then be used to mail output to the administrator, for example. The complete example is as follows:

Advanced Reporting and Automation with cqperl

In addition to the command line and batch support provided via the cqtool command, ClearQuest Unix has full support for external Perl scripting via cqperl. There are several considerations when using cqperl on a Unix client:

Consult the Clear Quest API Reference (ClearQuestAPIReference.pdf) document for detailed information on the elements of the ClearQuest Perl API. It is located at:

<Rational Directory>/releases/ClearQuestClient.2002.05.00/books

The following example Perl code can be used to generate a similar report to that which cqtool generated, above:

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.

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 to the database, enter:

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.

Defects/Change Requests

Known Defects

For a list of known defects in Rational ClearQuest v2002.05, please consult Rational Technical Support Technote 22578 at http://www.rational.com/sitewide/support/technotes.

Fixed Defects

For a list of fixed defects in Rational ClearQuest v2002.05, please consult Rational Technical Support Technote 22579 at http://www.rational.com/sitewide/support/technotes.

Contacting Rational Technical Support

Telephone: 1-800-433-5444 or 408-863-5000 (outside the U.S. and Canada)
Fax: 408-863-4300
E-mail: support@rational.com
Web site: http://www.rational.com/support/

Rational Corporation
http://www.rational.com
Voice: (408) 863-4000
Voice: (800) 433-5444
support@rational.com