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.
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.
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.
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.
MetaFrame 1.8 Service Pack 2 application server software by Citrix Systems, Inc. on Windows 2000 Service Pack 1 or 2.
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.
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.
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.
You need to have J2RE1_3_0 installed to use the Advanced Query Editor on ClearQuest Web.
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.
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.
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.
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
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.
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:
The following printed documentation is available:
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 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.
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 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.
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.
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).
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.
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:
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.
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.
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:
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/.
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
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.
When using an Oracle database for the backend data storage, searches using the 'Contains' operator are always case-sensitive.
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.
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:
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.
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.
REGEDIT4 [HKEY_CURRENT_USER\Software\Rational Software\ClearQuest\Diagnostic] "Trace"="Email" "Output"="ODS" "EMailSendVB"="ODS"
REGEDIT4 [HKEY_USERS\.default\Software\Rational Software\ClearQuest\Diagnostic] "Trace"="Email" "Output"="ODS" "EMailSendVB"="ODS"
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.
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:
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.
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 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.elseSearch 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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 is now available on the ClearQuest UNIX Installation CD.
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.
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.
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.
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.
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.
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.
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.
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.
The following information should be added to the Administrator's Guide, Rational ClearQuest.
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.
set BB_TEST_DBSET_NAME=my_test
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.
cqload importintegration <login> <password> <schema name> <record type> <"integration name"> <integration version> <schema pathname> <"comment or description"> <new form >)
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.
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.
cqload exportintegration <login> <password> <schema_name> <begin_rev> <end_rev> <record_type> <schema pathname>
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.
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.
cqload importschema <login> <password> <schema pathname>
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.
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.
cqload exportschema <login> <password> <schema name> <schema pathname>
cqload exportschema admin "" DefectTracking c:\schema.txt
The example above exports the contents of the DefectTracking schema to the file C:\schema.txt.
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.
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:
import_status_<year><month><day>_<hour><minute>_<second>.txt
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.
To make a test copy of your production system:
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.
This section provides information that is not included in the documentation and/or includes late-breaking changes made to Rational ClearQuest MultiSite.
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.
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).
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.
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"
You can use the ClearQuest Designer to change the mastership of a user or group.
To change the mastership of a user:
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.
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.
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.
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.
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'.
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).
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.
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.
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.
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.
multiutil describe -clan telecomm -site toyko -family PRODA -user toykoadmin -password secret "workspace:Public Folder\Project Report<boston>" Multiutil: Mastership of `workspace:Public Queries\Project report<boston>' is `boston'.
To fix a naming conflict for a stateless record, you must change the name of one of the records to be unique.
To rename a stateless record that has a naming conflict:
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.
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:
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.
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.
multiutil describe -clan telecomm -site toyko -family PRODA -user toykoadmin -password secret customer:General_Electric<boston> Multiutil: Mastership of `customer:General_Electric<boston>' is `boston'.
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.
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.
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.
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).
multiutil describe -clan telecomm -site toyko -family PRODA -user toykoadmin -password secret user:jsmith<boston> Multiutil: Mastership of `user:jsmith<boston>' is `boston'.
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.
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 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.
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.
If it is not, the URL will be extracted as
Embedded references with embedded double quotes cannot be parsed. If you have a URL with embedded double quotes, replace them with the character string:
Although " will appear in the list, it will be translated as a double quote and will take you to the correct Web site.
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).
Note: The new value is not in effect until the next logon.
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.
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.
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:
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:
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.
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.
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.
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:
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:
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:
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.
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.
To enable e-mail notification on Rational Shipping Server machines where ClearCase is not installed, see Technical Note #22590.
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.
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>
Before running mkreplica -export command verify that all users are logged out.
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.
installutil unlockschemarepo db_vendor server database dbo_login dbo_password connect_options (for Oracle: HOST=host;SID=sid)
installutil unlockschemarepo SQL_SERVER QE_TEST1 test_master_sitea multisite multisite ""
installutil unlockuserdb db_vendor server database dbo_login dbo_password connect_options (for Oracle: HOST=host;SID=sid)
installutil unlockuserdb SQL_SERVER QE_TEST1 test_user_sitea multisite multisite ""
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.
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.
The following table describes some of the common debugging items and provides procedures for recovery.
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
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:
$cqhome = $ENV{"CQ_HOME"};
$cqarch = $ENV{"CQ_ARCH"};
push (@INC,"$cqhome/$cqarch/shlib");
push (@INC,"$cqhome/$cqarch/perllib");
require CQPerlExt;
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:
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);
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.
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.
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.
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.
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 |