| Version: | 2003.06.00 |
| Edition: | UNIX/Windows Edition |
Table of Contents
Rational ClearQuest is a customizable defect and change tracking system that organizes and automates the processes involved in submitting, assigning, tracking, testing and releasing change requests. ClearQuest helps you track the correction of defects, the enhancement of existing functions, the addition of new features, and the modification of documentation and packaging.
Before you install ClearQuest on Windows, read the Release Notes for Rational Suite (distributed with your software).
See the following books for ClearQuest on Windows installation and upgrade information, including version compatability and language support:
For ClearQuest on UNIX installation and upgrade information, see the Installation Guide for the Rational ClearQuest Product Family.
For specific platform and database support for this release of ClearQuest, see the respective installation and upgrade guides.
This chapter describes new features and other changes in Version 2003.06.00 of Rational ClearQuest:
This release incorporates all the defects fixed and released in version 2002.05.01 Patch 03, additional hotfixes, and customer defects that have been resolved.
Following is a summary of new features introduced in this release:
This release introduces the ClearQuest data code page setting to verify that the set of characters used by any ClearQuest client is compatible with its associated databases and any other ClearQuest clients.
This new setting controls the set of characters, based on code page values, that a client can enter into a ClearQuest database. This value must be explicitly set by a ClearQuest administrator. If it is not set, ClearQuest, by default, uses the most restrictive setting, ASCII characters only.
For existing customers, this feature may alter the behavior of your ClearQuest deployment. Review the documentation about the ClearQuest data code page in the Administrator’s Guide for more information, including instructions about how to set it and what it means for your ClearQuest environment.
The ClearQuest install tool has changed for this release, for both Windows and UNIX.
The Site Preparation Tool for ClearQuest enables you to create a release area and to define the following:
On UNIX, you must create a release area for a client to be installed. For Windows, creating a release area is optional.
This release provides a Getting Started Wizard for the integrations with ClearCase on Windows and ClearQuest UCM.
The ClearCase Getting Started Wizard for Windows supports ClearQuest to configure a complete UCM environment. You must install the current release of ClearQuest before you can install ClearCase LT to have the Wizard start automatically. If you are using ClearCase with ClearQuest, you can use the Getting Started Wizard ClearQuest if you first install ClearCase and then manually run the Wizard by clicking Start > Programs > Rational Software > Rational ClearCase > Administration > Getting Started Wizard
After ClearCase or ClearCase LT is installed, the Getting Started Wizard can be used to configure ClearQuest for any of the following:
Note: The Getting Started Wizard can only be used to create an initial schema and set of user accounts. Subsequently, the ClearQuest administrative applications, such as the Maintenance Tool, Designer and User Administration Tool must be used to modify schemas, databases and user accounts.
The ClearQuest User Administration Tool is now available as a stand-alone application, as well as from within ClearQuest Designer.
You can access the tool when you install the administrative applications for ClearQuest. To start the User Administration Tool, click Start+Programs+Rational Software+Rational ClearQuest+ ClearQuest User Administration.
This version of ClearQuest on Windows ships with a copy of Sybase SQL Anywhere version 8.0.1 on the installation CD. Previous versions of ClearQuest shipped with SQL Anywhere 5.5 or an earlier release.
If you used SQL Anywhere 5.5 or earlier as a ClearQuest database, see the Upgrade Guide for Rational Suite for instructions on how to upgrade to the 8.0.1 release of SQL Anywhere.
If you are creating new databases with SQL Anywhere version 8.0.1, see the Installation Guide for Rational Server Products for configuration instructions.
This release provides CLOB (Character Large Object) support for Oracle 8i. With this release, you can create a column for multiline_text field types by setting the column type as CLOB.
In order to do this, when you create the schema repository or user database using either the Maintenance Tool or Designer, you must specify the LOB_TYPE as CLOB in the Connect Options field.
For more information, see the Restrictions and Guidelines for Using Rational ClearQuest section of the Release Notes and the Administrator’s Guide for Rational ClearQuest.
The Rational E-Mail Reader now uses a Microsoft Windows service called the Rational ClearQuest Mail Service. Because it is a Windows service, you can start, stop, pause, and resume execution on local and remote computers, configure startup and recovery options, and enable or disable its use for particular hardware profiles. For more information, see the Adminstrator's Guide for Rational ClearQuest.
In previous releases, you could not add reference list fields to report formats; 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.
The following new versions of packages with out-of-the-box schemas are included with this release.
The UCMPolicyScripts package has new policies to support the Single Stream Project model.
The UnifiedChangeManagement package contains new queries, exposes more information in delivery-related hooks, and includes Perl-based hooks on Windows and UNIX. It also has improved warning messages. The UCMPolicyScripts package must be installed in order to use the UnifiedChangeManagement package.
The new queries that are available from within ClearQuest if you upgrade UnifiedChangeManagement package to version 5 are All Activities in Stream and My Completed Work.
The Notes and DefectTrackingSetup packages have been enhanced and revised to correct defects. Dates are now in European standard format to provide a consistent format for date handling.
Text fields in the ClearQuest client will display hypertext as a hyperlink. For example, a string starting with http:, ftp:,or file:, will appear highlighted and underscored to indicate it is a recognized reference. When a user selects the hyperlink, the default browser opens with the selected reference.
This feature is also intended to support a list of references used as links to external attachments and is available for clients on Windows only.
A method has been added to the User object of the ClearQuest API for both COM and Perl that improves the performance for updating passwords. The UpgradeInfo method updates user information, including passwords, to each user database to which the user is subscribed and returns the database names that have failed in upgrading.
For more information, see the API Reference for Rational ClearQuest.
This section describes integrations that are new or enhanced in this release.
ClearQuest provides support for working in the Eclipse, IBM WebSphere Studio, and Microsoft VS .NET development environments.
ClearQuest provides a new integration with Eclipse and WebSphere Studio, which allows developers to submit new defects, select and run queries, and view record details without having to leave their IDE. Support is for ClearQuest 2003.06.00 and Eclipse 2.0 or the IBM WebSphere Studio v5.0 product family.
This new integration is currently only available for download from the IBM Rational Software Download Center. To download the integration, visit the following URL and click the Rational ClearQuest Plugins link after accepting the license agreement: http://www.rational.com/support/downloadcenter/addins/index.jsp
ClearQuest is integrated with ClearCase into Microsoft VS .NET. You can use ClearCase and ClearQuest separately, or you can link them through the UCM process model. This configuration enables you to work on activities and manage change requests simultaneously within the VS .NET IDE.2.
This section contains announcements and describes other changes in this release, as follows:
For information about determining feature level, see the Upgrade Guide for Rational Suite. For this release, there are no feature level changes (between version 2002.05.00 and version 2003.06.00).
For this release, the ClearQuest documentation set has been reorganized and updated to significantly improve overall usability and information retrieval. In particular:
The Help included with this release of ClearQuest has also been improved:
A new entry point to Perl is included in this release, ratlperl.exe, in addition to CQperl.exe. This ActiveState 5.6.1 version of Perl provides a common Perl component to ClearCase and ClearQuest.
The version 5.6.1 of Perl is distributed with ClearQuest on all platforms.
Perl is now shared between ClearQuest and ClearCase. The new name is ratlperl.exe. CQperl.exe still can be used, but Rational recommends that you start to convert to using ratlperl. The ratlperl.exe and the Perl libraries are now installed into the Rational common directory instead of the ClearQuest directory. Perl on UNIX now supports the ability to add modules to your ratlperl installation.
In conformance with the Perl Forum's Artistic License Agreement, Table 1 describes the modifications that were made to Perl 5.6.1.
Table 1. Modifications to 5.6.1 Perl Distribution
| Reason for modification | |
|---|---|
| Modification | Source file modified |
| Accommodation of underlying C library changes or other OS changes | |
| Add libmalloc, libndir to link list | hints/hpux.sh |
| Changes to accommodate Rational installation structure | |
| Customize install path | win32/config.vc, win32/cinfig.bc, win32/config.gc |
| Customize @INC | win32/win32.c |
| Use Rational naming conventions | |
| Configure. Add prompt for executable name | Configure |
| Allow arbitrary link library path | Makefile.SH |
| Allow arbitrary executable and library name | Makefile.SH, installperl |
| Specify ratperl in .def | makedef.pl |
| Use “ratl” name and Rational install path | win32/Makefile, win32/config.bc |
| Defect fixes independent of public domain | |
| Do not free environment in perl_destruct when –DPERL_USE_SAFE_PUTENV | perl.c |
| Do not free environment in Perl_my_setenv when –DPERL_USE_SAFE_PUTENV | util.c |
| Compiler related changes | |
| Allow C++ compiler on Sun5 | Configure |
The unmodified sources for Perl version 5.6.1, as well as the binaries built from them, are archived at ftp.rational.com. A link to the archive can be found at www.rational.com/support/downloadcenter/index.jsp.
Rational ClearQuest Version 2003.06.00 can support report formats authored with Crystal Reports 8.5 and the ability to run and view those reports. ClearQuest Version 2003.06.00 does not support Crystal Reports V8.0. Any statements in the documentation that it does are incorrect.
ClearQuest Version 2003.06.00 does not include copies of the Crystal Reports files necessary to enable these capabilities. Crystal Reports Professional is required to author reports in ClearQuest on Windows. Crystal Reports run-time libraries are required to run and view reports on Version 2003.06.00 of the ClearQuest for Windows and ClearQuest Web servers.
For instructions about how to license and install the appropriate Crystal Reports 8.5 software and the components necessary to author and run reports in these ClearQuest environments, contact Crystal Decisions directly. Any reference to Crystal Reports in the ClearQuest product documentation applies only to copies of Crystal software that you have rightfully licensed.
You can purchase licenses for Crystal Reports Professional, and obtain more information about licensing the run-time components required to run and view reports on your ClearQuest products from the Crystal Decisions, Inc. Web site (www.crystaldecisions.com) or by contacting them by telephone:
This chapter summarizes new and changed features in this release of Rational ClearQuest MultiSite.
For more information see the Administrator's Guide for Rational ClearQuest MultiSite and the Help for MultiSite.
The following new feature is introduced in this version of ClearQuest MultiSite:
In certain circumstances, successful import of user database update packets may depend on information contained in other user database packets. If your schema repository is associated with multiple user database families, the import may fail if the packets are not replayed in the order they were generated.
The msimportauto.bat script included in this release scans the import directory for update packets and then attempts to import the packets to each family. If any packets are successfully imported, the imported packets are deleted from the directory and the script attempts to import the next packet. The script stops executing when all packets are replayed and the directory is empty. For instructions about how to run the msimportauto.bat script, see Synchronizing Multiple User Database Families with msimportauto.bat.
Table 1 lists new options and arguments in this release. For more information, see the reference page for the command.
Table 1. New Options and Arguments in MultiSite Version 2003.06.00
| Command | New option or argument | Use |
|---|---|---|
| chmaster | –forceall | Transfers mastership of an object to a specified replica, even if the current replica does not master the object. |
The mkreplica –import command now validates that the replica creation packet was exported from a system running the same operating system code page. If the code pages of the exporter and importer do not match, the new replica is not created.
This chapter provides restrictions and guidelines for using Rational ClearQuest version 2003.06.00 software that are considered noteworthy. These are not considered defects because the behavior reported is not expected to change in a future release of the product.
This chapter includes the following sections:
In some cases, you won't be able to view the Rational copyright information online. If you want to see this information, you can find it in the following places:
During installation, if you select the ClearQuest Evaluation Databases option under custom install, the install does not create the evaluation databases. See the Installation Guide for Rational Server Products for the procedure to install ClearQuest for evaluation.
After you complete the installation of ClearQuest, Rational installer allows you to specify a default connection profile through the installer's Site Preparation Tool to restore your existing ClearQuest database connections or to create new connections.
However, the site preparation process does not automatically restore your existing connections. You must import the connection profile called cqprofile.ini with the ClearQuest Maintenance Tool.
Note: To restore the connection after installation, you must export your connection settings to a profile file before beginning the installation process.
To restore your database connections and import the connection profile, do the following:
Note: The field is prepopulated only if the logon ID that is running the ClearQuest Maintenance Tool is the same logon ID as the person who installed ClearQuest. If they are not the same logon ID, you must enter or manually navigate the UNC path to the file name for the cqprofile.ini file.
Administrators can add a postinstallation command to the sitedef.dat file (created using the Site Preparation Tool), to run the ClearQuest installutil program with the appropriate parameters.
The following command must be entered into the Properties section of the sitedef.dat file:
POST_INSTALL_CMD = [installdir]\ClearQuest\installutil.exe clientregisterschemarepo -dbset [dbsetname] [VendorString] [Server] [DatabaseName] [ReadOnlyLogin] [ReadOnlyPassword] ""
where
Note: Most of the preceding data is available in the cqprofile.ini. The read-only login and password parameters are used by this command to set the user's privileges to those in the ClearQuest database.
The password must be entered unencrypted. It is displayed encrypted in the cqprofile.ini file. The final parameter ("") at the end of the command must be entered but is reserved for future use.
File system corruption can result from installing ClearQuest on Windows 2000 to an NTFS partition that has the Windows Change Journal log enabled on it. Accordingly, the installer checks for and does not install to such partitions. We are working with Microsoft to repair the problem or provide a workaround for it.
Before installing ClearQuest onto a computer running Windows 2000, read Rational Solution 182435434 at http://solutions.rational.com/solutions/display.jsp?solutionId=182435434. Alternatively, you can search for the text change journal in the Rational Solutions Knowledge Base at http://solutions.rational.com/solutions.
Rational recommends that you upgrade all ClearQuest clients to ClearQuest version 2003.06.00. (For requirements specific to MultiSite, see the ClearQuest data code page information in Restrictions and Guidelines for MultiSite.) Previous versions of ClearQuest do not have features to enforce a single code page in your ClearQuest environment. Also, if you decide to run versions of ClearQuest earlier than version 2002.05.01 Patch 02, you are limited to ASCII data entry only.
ClearQuest version 2003.06.00 includes a CharacterSetValidation package that can help prevent data corruption in ClearQuest records if you use earlier clients. However, other ClearQuest objects, such as schemas, query names, record names, report formats, and user profile information are vulnerable to data corruption. You must train your users to create these objects by using only characters valid for the ClearQuest data code page. A ClearQuest administrator must apply the CharacterSetValidation package to all schemas and copy the ClearQuest data code page value to all associated user databases. For more information about the ClearQuest data code page and the CharacterSetValidation package, see Administrator's Guide for Rational ClearQuest.
No entity to which a package has been previously applied should be renamed. Otherwise, attempts to upgrade the schema to a higher version of the package or to upgrade a user database will fail.
For example, the upgrade fails with a returned error message if you do the following:
The workaround is to check out the schema, revert to the original entity name, check in the schema, and upgrade the user database.
This section lists restrictions and guidelines relating to integrations with ClearQuest.
The RequisitePro-ClearQuest Integration Wizard fails with the following error message if a valid product license is not currently available for the ClearQuest product:
Cannot log on to ClearQuest Database. Cannot connect to ClearQuest COM API.
To resolve this issue:
Start the Rational License Key Administrator and configure a valid license for ClearQuest or the suite product you are using.
Start Rational Administrator and right click the project in which you want to enable RequisitePro-ClearQuest integrations.
Click RequisitePro-ClearQuest Integrations to start the Integration Wizard.
Data conflicts can occur when a Rational ClearQuest database and a Rational RequisitePro database are both linked to the same Microsoft Project plan. This is because Requisite Pro may hard code certain text fields in project plan tasks. To avoid this problem, make sure ClearQuest does not use the following fields in Microsoft project tasks:
When you apply the Visual SourceSafe package to a schema to implement the ClearQuest integration with Visual SourceSafe, you can only select one record type at a time. If you select two record types, an error message appears. It is not possible to deselect one of the two record types. Instead, you must start over by applying the Visual SourceSafe package to the schema and selecting only one record type.
If your schema has multiple record types, you can apply the Visual SourceSafe schema to the package more than once, selecting a different record type each time.
Deleting a field from a schema affects all queries, reports, and charts that had included that field. In most cases the ClearQuest Client will fail when one of these queries, reports, or charts is executed.
Therefore, the field to be deleted should be removed from all queries, reports and charts before changing the schema, or else these must be deleted and re-created without the field. A field cannot be removed from an existing query, report, or chart after it has been deleted from the schema.
When you upgrade to a new release of ClearQuest, if you update the BaseCMActivity package, you may find some unexpected error messages when you check in a schema.
To avoid this problem, you must open the schema and map the following state types to states in the existing schema:
For more information about mapping state types, consult the Administrator’s Guide for Rational ClearQuest.
The Rational E-Mail Reader uses a Windows service called the Rational ClearQuest Mail Service.
To start the Rational ClearQuest Mail Service on a local host, you need a user account with administrative privileges on that host.
To start the Rational ClearQuest Mail Service on a system elsewhere on the network, you must specify a user account for that service that has privileges to these network resources.
The Rational ClearQuest Mail Service runs automatically by default after it is installed. If you do not want it to run on every client machine, run it manually.
When formatting an e-mail message for submittal with the Rational E-Mail Reader, if the default field is a multiline text field, then the name of the field must be included within the curley braces (}) surrounding the field. For example, if the default field is description, the field should begin with the word “description”:
{description: content of the field...}
If the name of the default field does not appear within the curley braces, the information in the field will not be included in the ClearQuest record being created or modified.
For more information about formatting e-mails for the Rational E-Mail Reader, consult the Administrator’s Guide for Rational ClearQuest.
If you run multiple reports consecutively with Crystal Reports on a system with Microsoft Office XP applications or the Microsoft XP operating system, ClearQuest may fail and need to be restarted.
To avoid this problem, after you run a report with Crystal Reports, perform some other action with ClearQuest (for example, running a query or working on a record) before running the next report.
Rational ClearQuest supports Crystal Reports Version 8.5. Running reports using ClearQuest Web requires that you also install Crystal Reports Version 8.5 Service Pack 1 (SP1). You cannot run reports using ClearQuest Web without having SP1 installed on your Web server machine.
When you author report formats with Crystal Reports Version 8.5 SP1 on a ClearQuest Windows client, ClearQuest can hang or terminate altogether. You should remove Service Pack 1 for Crystal Reports Version 8.5 if you need to author report formats using the ClearQuest Windows client.
Users cannot add notes to a record if both of the following conditions are true:
The following message appears: The field Notes Log contains characters that are not supported by the data code page....
The date and time stamp for the Notes log is obtained directly from the system, and it may contain characters incompatible with the database's ClearQuest data code page setting.
To avoid potential failure in committing notes to the database because of non-ASCII characters in the date or time stamp, you can modify the schema, and then upgrade the user database, which will propagate the change to all users. The change required involves modifying the schema to use the Perl script instead of the VBScript in the Notes package. (The former will log the time or date independent of the regional settings of the machine).
packageutil setproperty -dbset dbset_name clearquest_login clearquest_password schema_name Package_Notes_Windows_Script_Language PERL
The schema is automatically checked in after the property is set.
This workaround standardizes both the time and date stamps.
For ClearQuest Web users, changing the regional options on the Web server to set the time format to a 24-hour format may also resolve this issue.
See the Administrator's Guide for Rational ClearQuest for additional information about setting the ClearQuest data code page.
It is possible for existing Perl hooks to have name-lookup problems. A ClearQuest action, Submit for example, uses a single Perl interpreter to execute all the action hooks, like Action Initialization, and all the field hooks, like Field Value Changed, that are written in Perl. If the hook code does not declare local variables with the “my” keyword before it uses them, the variable can be shared between hooks unintentionally.
In previous releases, when one Perl hook called another, ClearQuest compiled the second hook in the wrong Perl namespace. In this release, all hooks are compiled in the same Perl namespace. For example:
sub defect_Initialization
{
$variable = "1";
$entity->SetFieldValue("A", $variable);
}
sub a_ValueChanged
{
$entity->SetFieldValue("B", $variable);
$entity->SetFieldValue("C", $variable);
}
sub b_ValueChanged
{
$variable = "3";
} In this release, the fields A, B, and C have the values "1", "1", and "3" because the name $variable refers to the same variable. In previous releases, the fields A, B, and C would have the values "1", "", and "3" because the hooks were compiled as if the code was written as follows:
package main;
sub defect_Initialization
{
$main::variable = "1";
$entity->SetFieldValue("A", $main::variable);
}
package CQEntity;
sub a_ValueChanged
{
# $CQEntity::variable is not set, so defaults to an empty string.
$entity->SetFieldValue("B", $CQEntity::variable);
$entity->SetFieldValue("C", $CQEntity::variable);
}
sub b_ValueChanged
{
$CQEntity::variable = "3";
} To avoid overwriting the variable values, you must declare those variables intended to be local to a hook function in this form:
sub d_ValueChanged
{
my $temp = $entity->GetFieldValue("d")->GetValue();
$session->OutputDebugString("d now set to $temp\n");
} where $temp is declared to be local to the d_ValueChanged function, and this assignment to $temp does not change the value of another variable of the same name.
This section includes guidelines and restrictions about supported databases for ClearQuest.
You cannot make a connection between a DB2 8.1 client and DB2 7.2 server.
The following are the supported combinations:
Using any other combination of client and server versions is neither supported nor recommended.
If you are using an older version of SQL Server, there may be performance issues when retrieving history entries for an entity (record). You can optimize performance by upgrading your database server to SQL Server 2000 and the machine it is running on.
This release of ClearQuest for Windows contains a new version of the Sybase SQL Anywhere database server (version 8.0). If you are upgrading from a previous release, consult the Upgrade Guide for Rational Suite.
If you are currently using SQL Anywhere, you may continue to use your existing SQL Anywhere version 5, databases, but you may not create any new databases with version 5, using this ClearQuest release. Attempting to create new databases with SQL Anywhere version 5 results in an error message.
Under some conditions, attempts to create a new SQL Anywhere version 5 database will fail and a different message is displayed.
You may use previous versions of ClearQuest to create new databases with SQL Anywhere version 5, but with the current version of ClearQuest you should only create new databases with SQL Anywhere version 8.
This section provides information that applies to ClearQuest with an Oracle database.
To ensure that ClearQuest Web clients can connect to Oracle databases, it is necessary to change some of the registry keys on the Web server running Microsoft IIS.
ClearQuest Web clients use an anonymous user account to communicate with Oracle databases through the Oracle client software and the OpenLink driver.
It is necessary to grant full control permissions to the ClearQuest Web anonymous user to one of the listed registry keys that applies to the version of Oracle being used.
To update permissions for these registry keys:
When moving a user database from other vendors to Oracle using ClearQuest Designer, the connect options box is blank. The connect options box should display the HOST, SID, SERVER_VER, CLIENT_VER and LOB_TYPE string.
To obtain a copy of the connect options string using ClearQuest Designer:
With this release, ClearQuest supports the creation of Oracle databases with LOB type as either LONG or CLOB (LOB_TYPE=LONG or LOB_TYPE=CLOB). However, the OpenLink driver version 4, which ClearQuest uses to access Oracle databases, imposes some limitations in the use of the CLOB data type.
This Oracle feature supports the searching and querying of multiline text fields. In previous releases of ClearQuest, the supported Lob_type option was LONG. To enable searching and querying in multiline text fields with LONG Lob_type, you must enable Oracle interMedia. Multiline text fields are used, for example, in the Description field and the Notes field.
This release allows use of the CLOB type for multiline text fields with two limitations:
Therefore, specify the LOB_TYPE as LONG if you will be running reports and charts against the database, or if you will be using systems with non-English Windows operating systems.
A report that is created by using a column of type CLOB results in the error, Problem executing report - Caught unknown exception in running report. This problem occurs on all operating systems, and it prevents charts from working with CLOB databases. Reports also fail to run against user databases when Oracle LOB type is CLOB.
A ClearQuest user database cannot be created on an Oracle database server that is running on a Japanese operating system if Lob_type=CLOB.
One workaround is to run your Oracle database server on an English operating system, on which you can create a user database with Lob_type=CLOB. From your ClearQuest client running on a Japanese operating system, you can then use the installutil setdbcodepagetoplatformcodepage utility to set the ClearQuest data code page to 932 (the Japanese code page).
Multiline text search in ClearQuest does not function correctly on Oracle releases before Oracle 8.1.7.3. To allow for multiline text search, upgrade Oracle databases to Oracle 8.1.7.3.
For an Oracle 8.1.7 client installation to work with ClearQuest on Windows XP, certain components are needed from the 8.1.7 Oracle client installation.
Only the Oracle8i Client has been certified with Windows XP Professional. To install it, a patched version of the installer is required. See Oracle MetaLink NOTE:202139.1 for a full list of 8.1.7.3+ components that have been certified. Also see Oracle MetaLink Note:161546.1 - Oracle Database Server product support Matrix for Windows XP/.NET. Additional information about supported platforms can be found in the Oracle Database on Windows FAQ available at otn.oracle.com.
This section lists restrictions and guidelines for ClearQuest Web.
Reinstalling ClearQuest Web may not force a reboot of the server. When this happens, a subsequent attempt to log on to ClearQuest Web can result in the following error: Logon Error 006~ASP 0177~Server.CreateObject Failed~8007007e
If this happens, reboot the server.
In the current version of ClearQuest Web, you cannot call a ClearQuest hook written in Perl from a Visual Basic package. Visual Basic hooks are required.
ClearQuest Web may display the error message Application Restarting during logon because of the configuration of Microsoft IIS and the McAfee NetShield Virus Scanner. This problem has been seen on a Windows 2000 server running Microsoft Internet Explorer 6.0, Microsoft IIS 5.0, and McAfee NetShield Virus Scanner.
By default, when NetShield Virus Scanner is configured to scan all files, it checks global.asa on access. This causes IIS to unload all its sessions and recompile global.asa. This is not expected behavior.
The workaround is to configure the NetShield Virus Scanner to exclude global.asa.
In the current release, the Advanced Query Editor supports nested queries through five filter-node levels in the Workspace.
The Rational ClearQuest Web Advanced Query Editor (AQE) uses the Java plug-in version 1.3.x or 1.4.x (also referred to as the Java 2 Runtime Environment (JRE), Standard Edition). If both versions of the JRE are installed on your client, the AQE uses JRE 1.4.x. If neither version of the JRE is installed on your client, the JRE 1.4.x is downloaded from the ClearQuest Web server the first time you use the AQE.
In the current release, the Rational ClearQuest Web Advanced Query Editor (AQE) supports Java Plug-in versions 1.3.x and 1.4.x.
Note: The Java Plug-in 1.4.1 is required to run the AQE on HP 11 with Netscape 7.
To use the Advanced Query Editor with Netscape 7.0, you must first verify which version of the Java Plug-in is installed on your system. Do this by clicking Help > About Plug-ins. Depending on the Java Plug-in version installed, you may need to take further action before using the AQE:
To disable the Plug-in Finder Service:
To reenable the Plug-in Finder Service:
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, the URL
http://somehost/somepage?field1=this is a test
must be pasted in as
"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 this character string:
"
Although " appears in the list, it is translated as a double quote and takes you to the correct Web site.
Using the ClearQuest Web interface, when you perform the Unduplicate action, the record opens in edit mode, allowing you to enter any required data. Previously, depending on your schema, the record did not always open in edit mode, so you were not always prompted to enter required data before submitting the record for validation.
The date format for the action_timestamp value on the ClearQuest Web client has changed. The action_timestamp history field value is now returned in 24-hour format.
ClearQuest Web does not display record tabs that contain only noneditable fields, or no fields, when you use the Submit and Modify actions. When you display the same records in read-only (view) mode, these tabs appear.
To work around this limitation, ensure that each tab has at least one editable field.
This section lists issues that are specific to ClearQuest on UNIX.
If you are installing ClearQuest to /opt/rational, when you use rs_install or any of its aliases to set up or check the license, you must enter or select /opt/rational/clearquest as the Rational directory. Otherwise, rs_install places some files in locations that may cause incomplete deinstallation of ClearQuest during deinstall.
Note: The rs_install utility is supported for licensing functionality only.
For this release, the install technology for ClearQuest on UNIX has changed from rs_install to install_release. Unlike rs_install, the install_release program does not support a remote installation (that is, to install software to a single remote system, such as installing from machine_A, to /net/machine_B).
Note: The install_release utility is for product installation, not licensing functionality.
In this release, if you are running a ClearQuest database on Oracle on Solaris, when supporting ClearQuest on UNIX client access, you will need to install an updated OpenLink Broker driver (version 4.2), which is provided on the product CD. With earlier versions of the OpenLink Broker driver, problems can occur with retaining connections with ClearQuest Clients.
For information about how to update the OpenLink Broker driver, see the Installation Guide for the Rational ClearQuest Product Family
Problems can occur with ClearQuest clients on UNIX when a SQL Server instance name is not the same as the machine name. The host name and the machine name must match to avoid these problems; aliases are not supported.
This section presents late changes to documentation and describes errors or information missing from the documentation delivered with ClearQuest software.
The first lesson in Section 1 of the Designer Tutorial requires a schema repository and a sample user database to run the tutorial.
You can create both items by using the Maintenance Tool or by clicking Start > Programs > Rational Software > Rational ClearQuest > Create Rational ClearQuest Evaluation Database.
The Mailreader does not display context-sensitive Help because mappings in the header file are incorrect.
The Installation Guide for Rational Server Products, the Installation Guide for Rational Desktop Products, and the Site Preparation Wizard Help incorrectly state that you can use the Site Preparation Wizard to enable and configure e-mail notification when you install from a release area. You cannot use the Site Preparation Wizard for this purpose. You can, however, use the site_prep script to enable and configure e-mail notification for UNIX release areas as described in the Installation Guide for the Rational ClearQuest Product Family.
The Administrator's Guide for Rational ClearQuest states that if you are using the ClearQuest Web client, you must use VBScript. However, ClearQuest Web works with hooks written in both Perl and VBScript.
The Administrator's Guide claims that the Rational E-Mail Reader will not send e-mail messages to hidden users. This information is incorrect.
It is the ClearQuest e-mail notification feature that does not send e-mail messages to hidden users whose ClearQuest user name is used in an e-mail rule. A hidden user is a person who is not in the same group as the user performing the action, and who does not have the All Users/Groups Visible privilege associated with the user ID.
The documentation that follows is correct. When this situation arises, use an explicit e-mail address, such as <names@company.com>, instead of the ClearQuest user name.
The ClearQuest Web Settings Help topic provides an incorrect definition for Login Timeout. The Login Timeout setting specifies the time that the ClearQuest Web client will wait to log on to the server.
The Administrator's Guide includes a troubleshooting appendix that provides information about determining whether a ClearQuest connection issue is database related.
Use the Oracle TNSPING utility to help determine whether the Oracle SID, specified for the ClearQuest connection, is incorrect. The pdsql command may not be able to provide enough information if the SID is incorrect. For example:
C:\>pdsql -v ora8 -s BADSID -u system -p manager -co "SERVER_VER=8.1"
returns
EXCEPTION: State: S1000 Native: 0 Connect String used: DRIVER={OpenLink Lite for Oracle 8i (32 bit)};UID=system;PWD=manager;SQLNET=BADSID;FBS=99;NRSSL=Yes;SQLNETIF=oc i.dll
C:\>tnsping BADSID
returns
TNS Ping Utility for 32-bit Windows: Version 8.1.7.0.0 - Production on 02-APR-2003 10:46:48
(c) Copyright 1997 Oracle Corporation. All rights reserved.
TNS-03505: Failed to resolve name
The pdsql command connect strings in Administrator's Guide section on troubleshooting database connections are incorrect.
The correct string for connecting to an Oracle 8i database is
pdsql -v ora8 -s oracle_sid -u username -p password -co "SERVER_VER=8.1"
To run the lessons in the Designer Tutorial, you need to create a schema repository and SAMPL database beforehand. These steps are outlined in the Help for the ClearQuest Maintenance Tool.
The context-sensitive Help for the Rational E-Mail Reader dialog boxes does not work properly in this release. Instructions for configuring the Rational E-Mail Reader are available either from Help > Contents and Index within ClearQuest Designer or the Administrator's Guide.
This chapter contains release notes for Rational ClearQuest MultiSite version 2003.06.00.
This version of ClearQuest MultiSite does not include support for multiutil on UNIX. You can install the MultiSite Administration tools on UNIX, but functionality is disabled. This is a temporary restriction that will be eliminated in a future release.
With the introduction of the ClearQuest data code page setting in this release (see Data Verification and ClearQuest Data Code Page Settings), there are new restrictions and guidelines you must follow when using ClearQuest MultiSite:
Before you deploy ClearQuest MultiSite, you must read the chapter about ClearQuest and code pages in the Administrator's Guide for Rational ClearQuest.
The Administrator's Guide for Rational ClearQuest MultiSite does not include information about the new msimportauto.bat script that you can use to synchronize replicas with multiple user database families. The following sections explain when to use the tool and provide syntax examples and instructions.
In certain circumstances, successful import of user database update packets may depend on information contained in other user database packets. If your schema repository is associated with multiple user database families, import may fail if the packets are not replayed in the order they were generated.
A particular clan, with sites in Boston and Denver has two user databases, User1 and User2. The Boston administrator generates a synchronization packet for User1 (Packet1) and then generates one for User2 (Packet2). While the packets are being created, an administrator modifies user account information. This causes schema repository oplog content to be included in both of the user database packets.
Some time later, the Boston administrator generates another pair of user database synchronization packets for User1 (Packet3) and User2 (Packet4). Again, while the packets are being created, an administrator modifies user account information. This causes schema repository oplog content to be included in both of the user database packets.
All four packets are sent to the Denver site. At the Denver site, the administrator runs syncreplica –import and specifies the User1 database family. Packet1 and Packet3 are both intended for the User1 family. Import of Packet1 is successful and replays oplogs in User1 and the schema repository. However, import of Packet3 fails, because it depends on schema repository database oplogs, contained in Packet2, which have not yet been replayed at the Denver replica.
To avoid this situation, packets created at the exporting site must be replayed in the same sequence at the importing sites. We recommend that you use the msimportauto.bat script, which is included with this version of ClearQuest. This script scans the import directory for update packets and then attempts to import the packets to each family. If any packets are successfully imported, the imported packets are deleted from the directory and the script attempts to import the next packet. The script stops executing when all packets are replayed and the directory is empty. If a series of import attempts results in no packets being deleted from the directory, the script stops executing and import fails.
Use the msimportauto.bat script to import update packets in the correct order when a clan contains multiple user databases. The script can also be used to perform syncreplica –export.
This program operates in one of the following modes:
–debug level
Set the debug level:
| 0 | Apply packets to database; don't produce any debugging output |
| 1..9 | Show diagnostic information and apply packets to database (higher numbers show more granular output) |
| 10+ | Show diagnostic information, don't apply packets to database |
Specifies the number of times the script will perform a receive, send, and sleep cycle (one iteration) in loop-and-wait mode.
–TimeToWait seconds
Specifies the amount of time, in seconds, between iterations. If –MaxLoops is specified, but –TimeToWait is not, the default is 30 seconds between iterations.
–AndDoExport
Issue syncreplica –export commands for the input databases (includes export as part of the receive, send, and sleep cycle).
–clan clan-name
Specifies the clans to synchronize. Multiple clans may be specified in one command, but the –clan switch must be repeated.
clan-info
Specify clan-info in the following format (no spaces):
admin_username,admin_password;storage_class | directory; family_1,my_site,other_site_1[,other_site_2,]...[,other_site_n][;family_2,my_site,other_site_1...]... [;family_n,my_site,other_site_1[,other_site_2,]...[,other_site_n]]
my_site is the local site that will be imported into and exported from. other_site_# specifies the other sites in the clan to be exported to and imported from.
Note: The following commands must be entered on one line.
msimportauto -debug 1 -clan TEST admin,"";C:\testdir\test;te,siteb,sitea;te2,siteb,sitea -clan TEST1 admin,"";c:\testdir\test;d2,sitea,siteb
msimportauto -debug 0 -MaxLoops 2 -TimeToWait 30 -clan TESTCLAN admin,""; cq_default;te,SITEA,SITEB,SITEC;te2,SITEA,SITEB -clan TESTCLAN2 admin,"";c:\TESTCLAN2;d2,SITEA,SITEB -clan TESTCLAN3 admin,"";cq_default;dt3,SITEA,SITEB -AndDoExport
The following sections present late changes to documentation and describe errors or information missing from the documentation delivered with ClearQuest MultiSite.
The rmreplica reference page includes documentation about using the –dbset option to remove the last replica in a clan. Because of a known defect (RAMBU00055249), this option does not work as documented. For more information, see the defect description in ms_issues.htm.
The scruboplog reference page incorrectly describes the behavior of the date-time argument when the year is omitted.
If you specify a date with the –before date-time option and omit the year, scruboplog assumes that the date is from the current calendar year. For example, if you run scruboplog to remove all oplogs created before November 19, 2002, and you do not specify a year, scruboplog deletes all oplogs created before November 19, 2003, which includes all of the oplogs between the current date and November 19, 2002 that you wanted to keep.
To ensure that you do not accidentally delete oplogs, you must always specify a year when you use the scruboplog –before date-time command.
The mkorder reference page does not document that mkorder can be used as a multiutil subcommand. The reference page should include the following multiutil mkorder command synopsis:
Noteworthy problems found in or resolved in version 2003.06.00 of Rational ClearQuest are listed in the file, cq_issues.htm.
You can find this file in the following places:
Noteworthy problems found in or resolved in version 2003.06.00 of Rational ClearQuest MultiSite are listed in the file ms_issues.htm.
You can find this file in the following places after you install ClearQuest:
By default, the ClearQuest home directory is opt/rational/clearquest.
Copyright© 2003 Rational Software. All Rights Reserved.