Rational ClearQuest Release Notes


Version Number: 2002.05.20 (Windows); 2002.05.01 (UNIX)

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

This version represents a re-packaging of 2002.05.01. There are few differences between 2002.05.20 and 2002.05.01. The section titled New and Changed Features details new functionality available as of version 2002.05.00.

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

Legal Notices Information

Contents

Scope

Hardware/Software Information

Supported Platforms
Hardware Requirements
Software Requirements
Database Vendor Selection
Language Support

Getting Started

Licensing
Installation Issues
Product Documentation

Compatibility Issues

With Rational Products
With Third-party Products

New and Changed Features

Rational ClearQuest Client Enhancements
Rational ClearQuest Designer Enhancements
Rational ClearQuest UNIX Enhancements
Miscellaneous Enhancements

Late Changes to Documentation

Administrator's Guide Changes
ClearQuest Installation Guide Changes
ClearQuest MultiSite Documentation Additions and Changes
Rational MailReader Help System Changes
ClearQuest Client Help System Changes

Guidelines and Restrictions

Network Guidelines, Restrictions, and Tips
Advanced Web Server Troubleshooting Tips
Web Performance and Recommended Configurations
Terminal Server Security Settings
MultiSite Tips and Workarounds
UNIX Tips and Workarounds
Subscribing to the ClearQuest User Group
Accessing the Sample Hooks Database

Defects and Changes

Known Defects
Fixed Defects

Contacting Rational Technical Support

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 needed 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
  • RedHat Linux versions 7.0, 7.1
  • AIX version 4.3.3
Note: HP-UX 10.20 is supported in v.2002.05.01 and v.2002.05.20. HP-UX 11 support is available only in v.2002.05.00. For UNIX client installed with Rational Suite, HP-UX 10.20 is also supported in v.2002.05.00, v.2002.05.01 and v.2002.05.20.

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 RedHatLinux 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: We recommend that the database server and the Web server be located on two different machines. Using one machine for both servers causes frequent hangs and script timeouts and generally causes ClearQuest Web to be unreliable.

Supported Database Servers for ClearQuest on UNIX

Database Server Versions Windows Solaris HP-UX RedHatLinux 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

Supported Databases on Windows Clients

Database Server Versions Windows Solaris HP-UX RedHatLinux 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

Supported Databases for UNIX Client

Database Server Versions Windows Solaris HP-UX RedHatLinux 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 on a dual processor machine. For optimal performance, we recommend at least 1 GB of RAM and a Pentium III processor (500 MHz and greater) on the Web server. We also recommend that the database server and the Web server be located on two different machines. Using one machine for both servers 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

If an MDAC version prior to 2.6 is present, the ClearQuest installation program overwrites the earlier version and installs MDAC 2.6. If no version is present, the installation program installs MDAC 2.6.

JRE

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

Database Vendor Selection

ClearQuest supports the following databases:

To decide which database vendor is best for your needs and determine how many simultaneous users you expect to have, use the following general guidelines:

Note: You can use more than one database vendor for ClearQuest databases. For example, you might want to use high-end databases for your schema repository and user databases, then use an entry- or mid-level database for your test database.

Language Support

The following table summarizes the language support available for ClearQuest:

Note: ClearQuest MultiSite cannot be used to replicate a database that contains data in double-byte character sets.

Getting Started

For full installation instructions, refer to the Installation Guide, 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, 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 requests a ClearQuest license key from FLEXlm, because ClearQuest is a member of several different Rational Suite products. The default selection 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".

Set the first line of the file using the following format (note that the case is sensitive, as well as the formatting):

ClearQuest:1.1 {<Suite Name>:<Version>}... 

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

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, install the new Version 2002.05.20 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 must install OpenLink Broker 4.0. See the section in Installation Guide, Rational ClearQuest for installing OpenLink Broker for your database system.

Product Documentation

Online Documentation

The following online .pdf files are provided in the books folder of your ClearQuest installation directory:

The following online html files are available from the Start menu:

Printed Documentation

The following printed documentation is available:

Compatibility Issues

With Rational Products

This release is compatible with Rational ClearQuest Version 2002.05.00, Version 2002.05.01, and with all other Rational Suite Version 2002 products. It is not compatible with previous releases of ClearQuest or Rational Suite.

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 more information about using ClearQuest MultiSite with the ClearCase integration, 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. 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 its 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 appear on ClearCase operations that indicate 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 MultiSite deployment. You cannot 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; you are restricted from making changes to the integration information captured in a ClearQuest record (for example, adding new requirements to the requirements tab).

Rational Administrator, RequisitePro, and TeamTest

For the integration between the Rational Administrator, RequisitePro, and TeamTest with Rational ClearQuest, a ClearQuest database connection name must be associated with a Rational Administrator project. The Rational Administrator can handle only database connections that have the default name. Refer to the Rational Administrator documentation about establishing associations between the Administrator and ClearQuest. Refer to the following section to create a connection 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 have 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 another connection name, rename it to the default connection name, as follows:

  1. Start the ClearQuest Maintenance Tool. Click Start > Programs Rational ClearQuest > Rational ClearQuest Maintenance Tool.
  2. In the left pane of the ClearQuest Maintenance Tool, select the database set connection name you need to rename.
  3. Right-click and click Rename.
  4. Enter 2002.05.00 and press Enter.

ClearQuest MultiSite

There are compatibility problems when you use ClearQuest MultiSite at replica sites with different versions of ClearQuest. These problems are most apparent when you import packets with user information with ClearQuest Designer version 2002.05 into a replica site with ClearQuest version 2001A.04.00.

To resolve this problem, 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 authentication 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 host name of the machine on which you are installing. The instance name can be accomplished by leaving the instance name blank and accepting the default. If an instance name is required, several issues arise:

For more information, consult the Microsoft support Web site at http://support.microsoft.com.

SQL Server 7.0 and 2000 with Rare Database Schemas

There is a known problem with locking with Microsoft SQL Server 7.0 Service Pack 2 and SQL Server 2000. Certain rows and tables in the database can become locked when users execute the same query three times in a sequence.

This condition creates what is known as a blocking SPID (SQL Server Process ID) on the database server. The major symptom of the problem is ClearQuest becomes unavailable to all users (there may be an hourglass, or just no response from ClearQuest). This particularly affects the ClearQuest Web interface.

To determine whether this is the problem:

  1. Run SQL Server Enterprise Manager.
  2. Select the Management section under the appropriate server.
  3. Click 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 until 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 the workload for site-wide maintenance, but has the side effect of limiting certain heterogeneous Oracle client version configurations. Several configuration options are described in the following paragraphs.

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, consider carefully which Oracle client versions to use 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 deviates from the site standard, you must enter the following at the command:

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 creates 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 setting forces that client to use that CLIENT_VER connect option instead 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 selecting the Details check box 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 is 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 of these commands:

installutil registeroracleoptions "CLIENT_VER=8.0" 
installutil registeroracleoptions "CLIENT_VER=8.1". 

Note: If you reinstall ClearQuest, this setting may be deleted as part of the reinstall. 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 double-click 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 are always 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 set up and enable the interMedia Text search engine.

For more information about obtaining and configuring the interMedia engine, see http://www.oracle.com/. After it is configured, ClearQuest requires that at least one interMedia server process is running.

For detailed instructions on enabling multiline text searches, consult the Installation Guide, Rational ClearQuest manual.

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 you perform any operation that constitutes a database move. For example:

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, see 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

ClearQuest v2001A.04 introduced a new method for debugging e-mail notification issues. ClearQuest, when enabled by means of a registry setting, writes 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:
    For a native client:
    REGEDIT4 
    [HKEY_CURRENT_USER\Software\Rational Software\ClearQuest\Diagnostic] 
    "Trace"="Email" 
    "Output"="ODS" 
    "EMailSendVB"="ODS" 
    
    For a Web server:
    REGEDIT4 
    [HKEY_USERS\.default\Software\Rational Software\ClearQuest\Diagnostic] 
    "Trace"="Email" 
    "Output"="ODS" 
    "EMailSendVB"="ODS" 
    
  2. Stop ClearQuest service.
  3. Import the .reg file into your registry.
  4. Start the ClearQuest service.
    Note: If you are running Windows 2000, you are required to have local administrator permissions to view debug output. For more information about e-mail notification consult Technical Note #7975.

Microsoft Project Update from ProjectTracker Limitation

If you have a linked task with start and finish dates set and then you delete the value of the finish date in ClearQuest and run Update, the change will not propagate to Microsoft Project. The log, however, displays 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

New as of Version 2002.05.20

As of May 1, 2002, licenses for Rational Products no longer include a copy and/or license of Crystal Reports. Licenses of Rational Products acquired before May 1, 2002 that included a copy and/or license of Crystal Reports are not affected.

Any reference to Crystal Reports in the Rational documentation applies only to copies and/or licenses of Crystal Reports you have licensed.

For information about purchasing Crystal Reports Professional Version 8.0 for use with Rational Products, contact Crystal Decisions, Inc. You can purchase Crystal Reports Professional Version 8.0 from the Crystal Decisions, Inc. Web site at http://www.crystaldecisions.com or by contacting them directly:

Crystal Decisions, Inc.
Vancouver, BC
Canada

You can also reach Crystal Decisions by telephone:

Testing Results with Crystal Reports 8.0

We do not test all of the functionality associated with Crystal Reports 8.0. The following section describes what we tested and includes caveats for use with ClearQuest MultiSite. All 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 as follows:

For ClearQuest MultiSite, we do the following:

Note: The nonmastered 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 need to configure your Navigator to support Java Applets. This is a known Netscape Navigator problem, and is documented in the Netscape UNIX Readme. The following is reproduced 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) 
Look at $CLASSPATH, where $CLASSPATH is a colon-delimited list of <path>/<jar-file> entries. 
else
Search in order: 
<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 about resolving this problem, see the Sybase Central 's Web site or call Rational 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 install ClearQuest Web in this environment, a dialog box opens that allows you to download JVM to your desktop. If you do not install it, ClearQuest Web will not work.

New and Changed Features

This section outlines enhancements and new features that have been introduced to Rational ClearQuest since Version 2001A.04.00. These consist of new and changed features added to Rational ClearQuest in Version 2002.05.00 and Version 2002.05.01.

Rational ClearQuest Client Enhancements

Support for Reference Lists in Reports

In previous releases, you could not add reference list fields to report formats and therefore, users could not generate reports that included any reference lists. With this release, reference lists can be included in report formats, and reports with reference lists can be generated.

Display Only Valid Actions

Previously, when a user clicked the Actions button, 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 restarted Rational ClearQuest. With this release, the size of the client window, results set and workspace, column size in the results set and other settings are saved on a per-desktop per database basis.

Correct Record Count When Viewing a Results Set

Previously, when a user executed a query that returned more than approximately 50 records, the record count 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 displayed correctly as soon as the query is executed.

Results Set Updated Dynamically

Previously, 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 in italic to indicate 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 easier 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, and so on.

Rational ClearQuest Designer Enhancements

User Administration

The User Administration functionality in Rational ClearQuest Designer is completely revamped to make it easy to manage an enterprise. Now administrators can subscribe multiple users to databases, subscribe groups to databases, and search for specific users by login name or full name, all at the same time. 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 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 the Actions button, Rational ClearQuest UNIX displays only the actions available at that particular time, based on the user's permissions and the state of the record. Note that because of potential performance issues, ClearQuest will not execute access control hooks when calculating valid actions.

Previously, when a user clicked the Actions buttons, all available actions were displayed, including those that the user did not have permission to execute. So, for example, while only two or three actions were available to run, ten would appear in the list.

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 updated in the results set, the query had to be run again to display the updated data.

OpenLink Request Broker 4.0

OpenLink Request Broker 4.0 is now available on 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 administrator functionality provided by the multiutil utility was only available on Windows. With this 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 had to open a record in order to see which site had mastership. In this release, a small padlock icon indicates the records in the result set that are mastered at other sites.

Allocating Variable Size ID Blocks

To ensure that defects entered at different sites do not have duplicated ID numbers, ClearQuest MultiSite allocates ID blocks to each replicated site. With this release, you can manually increase those blocks whenever necessary.

Previously, customers could not increase the ID blocks, which was a limitation for enterprise users or users importing large numbers of defect records from legacy systems.

GUI Support for Changing Mastership of Queries

You can now change mastership of queries by right-clicking to make necessary edits. Note that only users with the appropriate privileges can edit metrics in public folders.

Previously, to change mastership of a query, you had to use the multiutil utility. In this release of ClearQuest MultiSite, you can right-click the appropriate workspace object. Note that mastership is required only 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 redesigned to make it easier to use. The tool has a new user interface, 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 restarting the tool.

Maintenance Tool

The ClearQuest Maintenance Tool has been redesigned 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 easier because administrators are not required to enter database properties every time. The database properties are 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 is 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 ClearQuest 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, 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.

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 (for example, TeamTest). This schema increases by one revision number after running CQLOAD.
record type The record type in the target schema (for example, 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 was produced by exportintegration. There are a number of integrations delivered out-of-the-box in the <installation-dir>/addin 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. The exportintegration command differs from the exportintegration 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 cannot 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 written to this file. So when you import this schema, that schema name is used to create the schema with cqload importschema. If that name is already in use in your schema repository, the import does not succeed.

exportschema

The exportschema subcommand, part of the cqload command line utility, is used to export entire schemas to a text file. This command 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 (for example, TeamTest).
schema pathname The text file version of a schema to be saved.

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

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

Using Hooks in ClearQuest Web

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

Tips for Implementing Hooks

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

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 reinstall the product you need.

Creating a ClearQuest Test Database

To make a test copy of your production system:

  1. Make a physical copy of the database in a new location.
  2. Use ClearQuest Maintenance Tool to relocate the databases.
  3. On the command line, enter the command: -delete_cqtracking_files installutil relocationschemrepo

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

ClearQuest MultiSite Documentation Additions and Changes

This section provides information that is not included in the documentation and/or includes late-breaking changes made to Rational 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 client on Windows or UNIX:

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 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>" 
"Workspace:Public Queries\<Folder>\<Query>" 

The Workspace item must include the full path name and be enclosed in double quotes. 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 parisadmin and you want to transfer mastership of a report format called "Project report" that resides in the Personal Queries folder of user jsmith, use this command:

multiutil chmaster -clan telecomm -site paris -family PRODA -user parisadmin -password secret bangalore "Workspace:Personal Queries(jsmith)\Triage\project report" 

To change mastership for a public folder:

multiutil chmaster -clan telecomm -site paris -family PRODA -user parisadmin -password secret bangalore "Workspace:Public Queries\Triage\project report" 

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. Click 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 list.
  4. Click OK.
  5. Click OK.

As with any change of a user or user group, the new mastering site must upgrade the database after receiving the synchronization packet that contains the changes. For details, see the Administrator's Guide , Rational ClearQuest MultiSite.

Changing the Mastership of User Groups

  1. Click Tools > User Administration.
  2. In the User Administration dialog box, select the user group you want to modify.
  3. Click Group Action > Edit Group.
  4. In the Group Property dialog box, choose the new mastering site from the Mastership list.
  5. Click OK.
  6. Click OK.

As with any change of a user or user group, the new mastering site must upgrade the database after receiving the synchronization packet that contains the changes. For details, see the Administrator's Guide, Rational ClearQuest MultiSite.

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 Chapter 6 in the Administrator's Guide, Rational ClearQuest MultiSite.

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 by using the standard functionality. For more information, see the ClearQuest client Help.

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 be changed only 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:

multiutil chmaster -clan telecomm -site boston -family PRODA -user bostonadmin -password secret toyko customer:General_Electric  
Multiutil: Mastership of `customer:General_Electric' has been changed to `toyko'.  

Moving a Replicated Schema Repository

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

There may be times when 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.

To move the schema repository using the ClearQuest Maintenance Tool, follow the instructions in the Administrator's Guide, 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, and so on.), users and groups, and other stateless records, it is possible to have objects with the same name.

For example, duplicate names can occur when administrators at two sites, each add a user who has the same name within a synchronization cycle. In this case, after the replicas are synchronized, both users have the same name.

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

Identifying Workspace Naming Conflicts

If two Workspace items (queries, reports, and so on) are inadvertently assigned the same name, both items will work as expected on 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, 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 the Administrator's Guide, Rational ClearCase MultiSite.

To rename a Workspace item,

  1. Right-click the Workspace item you want to rename and click Rename.
  2. Type a new name in the highlighted area and press 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, 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 example uses the describe command. In most cases, you may find it easier to use ClearQuest on Windows or UNIX clients to change the mastership of Workspace items, see the Administrator's Guide, Rational ClearQuest MultiSite.

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.
    To find/view stateless records with naming conflicts, you have two options:
  2. Rename the record. You must have mastership of the record to modify it.
    To rename a stateless record, you must modify the field used as the unique key for that record. To do so, use the action in your schema that allows you to modify records without changing their state.
  3. 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 NetworkInc, is created at two replicas during the same time period between synchronizations. When each site synchronizes, there appear to 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. 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. Adding the ratl_keysite field to the form of any stateless record type for which you expect naming conflicts. For more information about modifying your schema see Chapter 4, Customizing a schema in the Administrator's Guide, 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 example uses the describe command. In most cases, you may find it easier to use ClearQuest on Windows or UNIX to change the mastership of stateless records, see the Administrator's Guide, Rational ClearQuest MultiSite.

Identifying User and User Group Naming Conflicts

To log in 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 login, you get an invalid Login error. Clicking on the detail, gives 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 conflicting user name, the following error message appears:

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

You must rename the user. Until you do, 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. Click 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 clicking DB Action > Upgrade.
  6. In the Upgrade dialog box, select the user database you want to upgrade.
  7. Click OK.
  8. Click OK.

As with any change of a user or user group, the new mastering site must upgrade the database after receiving the synchronization packet that contains the changes. For more information, see the Administrator's Guide, Rational ClearQuest MultiSite.

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 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 the Administrator's Guide, Rational ClearQuest).

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 use the storage class name as the default.

Conversely, several storage classes can share one or more storage bays. You can use multiple storage classes to segregate the packets for replicas that belong 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 changed 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:

Owner: admin, user 

ClearQuest Client Help System Changes

Creating Reports in ClearQuest Web

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

If you need report formats other 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. Click Operations > Create a Report.
    The Create a Report dialog box opens.
  2. Select a record type from the Record Type list.
  3. Enter a name in the Report Name text box.
    Note: You cannot use slashes or backslashes in the report name.
  4. Select a format from the Report Format 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.
  5. Select the type of information to include by choosing a query from the Report Query list.
  6. Click Next.
    ClearQuest indicates that your report was saved successfully.
  7. 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 detects these URLs and adds a list below the description box. The first item in this list is "--Embedded References--". You can select any URL in the list to go directly to the Web site.

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

For example

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

must be pasted in:

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

If it is not, the URL will be extracted as

http://somehost/somepage?field1=this

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

&quot;

Although &quot; will appear in the list, it will be translated as a double quote and 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 15 seconds).

To change the Timeout value:

  1. Log in to ClearQuest Web with administrator privileges.
  2. Click Operations > Edit Web Settings > Login Timeout.
  3. Set the value based on the following considerations:

Note: The new value is not 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 about setting SQL Editor privileges, see Administrator's Guide, Rational ClearQuest.

Guidelines and Restrictions

Network Guidelines, Restrictions, and Tips

Network Installations

When running Rational ClearQuest from a network installation, users cannot create report formats using Crystal Reports. To create new report formats in a network installation, users must run ClearQuest from the shortcut menu, not from the administrative install.

Configuring IIS to Work with the Anonymous User ID

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

  1. Select the properties of virtual directory in IIS by right-clicking the virtual directory.
  2. Set the virtual directory to run in the same memory space:
  3. In the Internet Service Manager workspace, click Microsoft Transaction Server > Computers > My Computer > Packages Installed. 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 the Identity tab, and find the User field.
  5. Set this user field to the anonymous user account defined specifically for serving ClearQuest Web. For more information on the configuration of IIS 4.0 and IIS 5.0, see the Installation Guide, Rational ClearQuest.
  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, stop and restart the Internet Service Manager before you restart 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 must 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 should set the following options:

Advanced Web Server Troubleshooting Tips

In addition to the tips documented here, detailed documentation on the configuration of IIS 4.0 and IIS 5.0 is available in the Installation Guide, Rational ClearQuest.

Incorrect Permissions on the ClearQuest Registry Keys

The ClearQuest Installation on a Windows 2000 Server or a Windows NT 4.0 Server with SP6 installed occasionally resets the Registry Key permissions which makes them inaccessible to the Anonymous Web User. In particular these keys have their permissions reset:

As a result, the ClearQuest Web server fails to grant logons, with one of the following messages:

For information on setting the proper permissions, see the Installation Guide, Rational ClearQuest.

Incorrect Permissions on the Cache Directory

If you have not set proper permissions in the cache directory, you cannot log on and you will see the following error:

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

For information on setting the proper permissions, see the Installation Guide, Rational ClearQuest.

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 your script may time out. If this happens, you see a message like this one:

error 'ASP 0113' 
Script timed out 

The maximum amount of time for a script to execute was exceeded. To change this limit, specify a new value using the Internet Service Manager, as follows:

  1. Start Internet Service Manager.
  2. Right-click your ClearQuest Web directory and click Properties.
  3. Click the Virtual Directory tab and click Configuration.
  4. Click the App Options tab in the Application Configuration dialog box.
  5. Enter the new value in 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, 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. 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, we recommend the following configurations for best performance and stability under high loads:

To ensure top performance in a multiuser environment, complete the following IIS tuning:

Terminal Server Security Settings

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

  1. Click Start > Run and enter regedt32.
  2. In the HKEY_LOCAL_MACHINE window, click SOFTWARE > ODBC.
  3. On the menu bar, click Security->Permissions. The Permissions for ODBC dialog box opens.
  4. If the user group is not present, add the group that the user belongs to. Click Add and select the appropriate group.
  5. In the Permissions for ODBC dialog box, select the user group and select Allow 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 perform any operation that writes the file to the ClearQuest program directory, you must set the security privileges for the Rational installation directory.

  1. From Windows Explorer, select the directory that contains your Rational software. The default location is C:\Program Files\Rational.
  2. Right-click 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. Click Add and select the appropriate group.
  5. In the Rational Properties dialog box, select the user group and select the Allow check box for Full Control in the Permissions area.
  6. Click OK to apply the new permissions and close the Properties dialog box.

MultiSite Tips and Workarounds

Enabling E-mail Notification

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

Adding a User Database That Will Be Replicated

When adding a new user database at the working schema repository site, we recommend that you replicate the new user database before subscribing users to it.

The only exception to this rule is when a user is subscribed to all databases. Users who 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.

Users who are subscribed to the new database before it is replicated, cannot log in to the new database replica until their database subscription is updated at the working schema repository site.

  1. Using the ClearQuest Designer, log in to 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, click Tools > User Administration. In the User Administration dialog box, select the user who has the subscription problem.
  3. Select the user who cannot log into the replica.
  4. Click DB Subscriptions to open the Database Subscriptions dialog box.
  5. In the Database Subscriptions dialog box, click OK.
  6. Click Yes in the change confirmation box.
  7. Repeat this process for each user who 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 that 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 is subscribed only to databases that are replicated, viewing the database subscriptions for the user now works at all sites that have a replica of the new user database. Sites that do not have this replica cannot 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, the database set information on that machine is removed. When you reinstall ClearQuest the database set information must be re-created.

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:

CQMS.<clan_name>.<site_name> 

Running mkreplica -export

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

Recovering from a mkreplica -export Failure

If mkreplica-export fails, your database may be left in a locked state. Use the procedures in this section 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.
    This subcommand has the following usage:
    installutil unlockschemarepo
    db_vendor
    server
    database
    dbo_login
    dbo_password
    connect_options (for Oracle: HOST=host;SID=sid) 
    
    Example: To unlock the SQL_SERVER schema repository database `test_master_sitea' on server QE_TEST1:
    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.
  2. Unlock the user database with the installutil unlockuserdb command. This subcommand has the following usage:
    installutil unlockuserdb
    db_vendor
    server
    database
    dbo_login
    dbo_password
    connect_options (for Oracle: HOST=host;SID=sid) 
    
    Example: To unlock the SQL_SERVER user database 'test_user_sitea' on server QE_TEST1:
    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, see 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 than the ClearQuest client on Windows. This guide is a starting point for debugging these connection problems. Search the table until you find the error message that you received and cross-check it with the command you 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 may be received with examples and debugging tips. The debugging tips may reference common debugging techniques. These can be found in the second table, as follows.

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  
    
  2. 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 
    
  2. 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.
  3. 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 happens 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 running:

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 run, 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. Running 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 run other commands, but in batch mode, replace login with the command to be executed. In 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:

cqtool new_query -type defect -field id -field headline -field submitter -eq state submitted -database SAMPL -user admin -password "" -output_file /tmp/cqoutput 
 
mail cqadmin@yourco.com < /tmp/cqoutput 
 
rm /tmp/cqoutput 
Advanced Reporting and Automation with cqperl

In addition to the command line and batch support provided by 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 API Reference for Rational Clear Quest (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:

# nightlysubmits.pl - A Perl script to list all of the 
# defects currently in the submit state. 
 
$cqhome = $ENV{"CQ_HOME"}; 
$cqarch = $ENV{"CQ_ARCH"}; 
push (@INC,"$cqhome/$cqarch/shlib"); 
push (@INC,"$cqhome/$cqarch/perllib"); 
require CQPerlExt; 
 
# All ClearQuest work is done via a session object. Cqperl 
# obtains a session object with the CQSession_Build global 
# function accessible from the CQPerlExt Perl module. 
#   API Reference: Session Object 
 
$session = CQPerlExt::CQSession_Build(); 
 
# Once we've obtained the session, we need to logon. This is 
# done with the UserLogon method. You need to specify the 
# username, the password, and the database name. The fourth 
# parameter, dbset, is usually left blank. There is a typo 
# in several versions of the API reference. The session_type 
# parameter is no longer required. It should not be included. 
#   API Reference: Session object->UserLogon method 
 
$session->UserLogon("admin","","SAMPL",""); 
 
# Generating a query involves creation of a QueryDef object. 
# This is done via a method of the session object called  
# BuildQuery. It's only parameter is the entitydef  
# (also known as Record Type) that you wish to query on.  
# In this case, we'll use "Defect" 
#   API Reference: Session Object->Build Query method 
#                  QueryDef Object 
#                  EntityDef Object->Name property 
 
$querydef = $session->BuildQuery("Defect"); 
 
# The next step (like creating a query through the ClearQuest 
# UNIX GUI) is to decide which fields will be in the Query 
# Result Set. This is done with the BuildField method of 
# the QueryDef object. We'd like to see ID, headline, and 
# submitter. 
#   API Reference: QueryDef Object->BuildField method 
 
$querydef->BuildField("id"); 
$querydef->BuildField("headline"); 
$querydef->BuildField("submitter"); 
 
# Next, we need to build the filters for this query. 
# This is done by constructing a tree of FilterOperator 
# objects. Creating the top level FilterOperator object for 
# any subtree is done with the BuildFilterOperator method 
# of the QueryDef object. The BuildFilterOperator method 
# takes one parameter, the boolean operator that will 
# determine how each of the subtrees behaves. If there is 
# only one filter, either AND or OR will work. To specify 
# the correct boolean operator, select the proper BoolOp  
# constant and Perl prefix. In this case, we'll use and, so 
# therefore, our constant will be $CQPerlExt::CQ_BOOL_OP_AND.  
#   API Reference: QueryDef Object->BuildFilterOperator Method 
#                  BoolOp constants 
#                  Notation conventions for Perl 
 
$rootfilternode =  
   $querydef->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_AND); 
 
# Once we have the root FilterOperatorNode, we'll assign a 
# filter to it. In this case, state equals submitted. We'll 
# use the BuildFilter method of the QueryFilterNode object 
# for this. Note that the third parameter to BuildFilter must 
# be a Perl reference to an array. 
#   API Reference: QueryFilterNode object->BuildFilter method 
#                  BoolOp constants 
#                  Notation conventions for Perl 
 
@statetest = "Submitted"; 
$rootfilternode->BuildFilter("State", 
                             $CQPerlExt::CQ_COMP_OP_EQ, 
                             \@statetest); 
 
# Okay, the Query definition has been created, now it's time  
# to execute it. We go back to the session object for this 
# and use the BuildResultSet method. It's only parameter  
# is the QueryDef object we'd previously created. After  
# the result set object is ready, we then execute the query. 
#   API Reference: Session object->BuildResultSet method 
#                  ResultSet object->Execute method 
 
$resultset = $session->BuildResultSet($querydef); 
$resultset->Execute(); 
 
# Let's prepare by printing a header for our output. 
 
printf("%13.13s %50.50s %9.9s\n","id","headline","submitter"); 
printf("%13.13s %50.50s %9.9s\n", 
       "-------------", 
       "--------------------------------------------------", 
       "---------"); 
 
# Now, traverse the resultset and print out the output. 
# This is done via the MoveNext method of the result set 
# object. It will return $CQPerlExt::CQ_SUCCESS as long as 
# there are rows to view. GetColumnValue is used to get the 
# data from that row of the resultset. 
#   API Reference: ResultSet object->MoveNext method 
#                  ResultSet object->GetColumnValue method 
 
while ($resultset->MoveNext() == $CQPerlExt::CQ_SUCCESS) { 
    printf("%-13.13s %-50.50s %-9.9s\n", 
           $resultset->GetColumnValue(1), 
           $resultset->GetColumnValue(2), 
           $resultset->GetColumnValue(3)); 
    } 
 
# And we're done, so let's release the session 
 
CQPerlExt::CQSession_Unbuild($session); 
 

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:

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, take a minute and add it to the database.

Defects and Changes

Known Defects

For a list of known defects in Rational ClearQuest v2002.05, please consult Rational Technical Support Technote 121029219 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 121029209 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 Software
http://www.rational.com
Voice: (408) 863-4000
Voice: (800) 433-5444
support@rational.com