All other platforms are currently planned for support for future ClearQuest Unix releases. Please plan to migrate ClearQuest Unix clients and databases accordingly.

Platform/Software	Version
Operating Systems	Sun Solaris for SPARC 2.5.1, 2.6, 7, and 8 HP-UX 10.20, 11.00, 11.11 RedHat Linux 6.2 and 7.0 IBM AIX 4.3.3
Hardware Requirements	200 MHz or greater processor (Sun SPARC, HP PA, Intel Pentium, or IBM RS/6000). 128 MB or greater RAM. Hard Drive where ClearQuest is installed: 120 MB
Web Browsers	Netscape Navigator 4.7
Databases	Microsoft SQL Server 7.0 Service Pack 2 and Microsoft SQL Server 2000 on Windows NT SP6a, Windows 2000, and Windows 2000 SP1 Oracle 7.3.4 and 8.0.5 on Solaris 2.5.1, 2.6, 7, and 8, as well as HP-UX 10.20 and 11.00 Oracle 8.1.5, and 8.1.6 on Solaris 2.6, 7, and 8, as well as HP-UX 10.20 and 11.00 Oracle 8.1.7, on Solaris 2.6, 7, and 8, HP-UX 10.20 and 11.00, and RedHat Linux 6.2 and 7.0 IBM DB2 6.1 and IBM DB2 7.1 on Windows NT SP6a, Windows 2000 and Windows 2000 SP1

2. What’s New in Rational ClearQuest Unix v2001A.04.20

1. Rational ClearQuest Security Enhancements

The latest release of Rational ClearQuest Unix significantly improves the security model. First, specific defects and other change requests in ClearQuest can be hidden based on group membership. Second, Super User privileges are no longer required to perform certain administrative tasks. Full details on these new features are available in the Administering ClearQuest manual.

Ability to Hide Change Request Records

This feature allows certain defects and other types of change request records to be hidden from specific users based on which group those users belong to. By allowing any reference field to be a security context field, ClearQuest will hide certain change requests from specified groups of users.

Ability to Administer Dynamic Choice Lists

A new privilege, called Dynamic Choice List Administrator, enables creation and modification of dynamic choice lists. This includes the ability to add, delete, and modify entries in dynamic choice lists without having Super User privileges.

Ability to Administer Public Queries Folder

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

New User Privilege to Edit SQL Code

This privilege allows users to edit the SQL code that is generated for queries. Users without this privilege can view but cannot modify the SQL code. It is important that users not have this privilege when record hiding has been enabled. Modifying the SQL code directly can allow users access to all defects.

Ability to Administer Security at a Site

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

2. Downward Compatibility

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

3. Database Support

Rational ClearQuest Unix now supports IBM DB2 7.1 (on Windows).

4. Platform Support

Rational ClearQuest Unix now supports IBM AIX 4.3.3 as a client platform. Please note that IBM AIX 4.3.2 (and prior versions) is not supported and is known not to function. Support for IBM AIX 4.3.2 is not planned.

5. Rational ClearQuest Multisite

This release of Rational ClearQuest Unix allows full client connectivity to supported ClearQuest databases that have been activated for multisite purposes. If you wish to use the ClearQuest Multisite functionality, please obtain a Rational ClearQuest Multisite media kit and consult the documentation and release notes found therein.

6. ClearCase patch requirements

This release of Rational ClearQuest Unix integrates with Rational ClearCase 2001A.04.00 (version 4.2). If the UCM or base ClearCase integrations are required, please ensure that the proper version and patch level of ClearCase has been installed on the ClearQuest Unix client machine. Consult http://clearcase.rational.com for the latest patches for ClearCase.

3. Upgrading from Previous ClearQuest Unix Releases (including patch releases)

ClearQuest Unix v2001A.04.20 now supports two different database feature levels. ClearQuest Unix v2000.02.10 and ClearQuest Unix v2001.03.00 can use ClearQuest database feature level 3, otherwise known as metaschema level 20. If an upgrade has been performed on the ClearQuest database to feature level 5 (metaschema level 22) or a new database has been created from ClearQuest Windows v2001A.04.00 or higher, then users using these previous versions of ClearQuest Unix will be unable to connect and will receive an incompatibility error message. These Unix clients will need to be upgraded to ClearQuest Unix v2001A.04.00 or higher. Note that the database upgrade (described fully in the Installing ClearQuest manual) is optional, and only need be done if advanced security or multisite features are desired.

ClearQuest Unix v2001A.04.20 is designed to be installed in either a new location or in place of an previously installed version of ClearQuest Unix. If you wish to uninstall an earlier version of ClearQuest Unix navigate to <rational dir>/config and type ./uninstall.

To begin the new install, navigate to the root of the cdrom and type rs_install. The Installing ClearQuest manual contains detailed instructions on performing the ClearQuest Unix install. Also, online help is available during the entire install process.

4. Database Vendor Considerations

1. Use of Oracle with ClearQuest Unix

Supported Versions

ClearQuest Unix v2001A.04.20 supports Oracle 8.1.7 on Solaris SPARC 2.5.1, 2.6, 7, and 8, HP-UX 10.20 and 11.00, and RedHat Linux 6.2 and 7.0. Follow the installation instructions for setting up the Oracle OpenLink request broker to use Oracle with ClearQuest Unix. Note that the OpenLink Request Broker does not need to be re-installed from if it had been previously installed for use with earlier versions of ClearQuest Unix.

Debugging Oracle Connection Issues

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

Error Message

Description, Example, and Analysis Procedure

RPC: Unknown Host

Description:

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

Example Command:

pdsql –v ora –s badhost:SID –u system –p manager –co “SERVER_VER=8.1”

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

Example Error Message:

OpenLink: RPC: Unknown host

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

Analysis Procedure:

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

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

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

RPC: Program unavailable

Description:

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

Example Command:

pdsql –v ora –s goodhost:SID –u system –p manager –co “SERVER_VER=8.1”

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

Example Error Message:

OpenLink: RPC: Program unavailable

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

Analysis Procedure:

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

ORA-01034: ORACLE not available

Description:

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

Example Command:

pdsql –v ora –s goodhost:badSID –u system –p manager –co “SERVER_VER=8.1”

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

Example Error Message:

OpenLink: [Oracle Server]ORA-01034: ORACLE not available[SQLSTATE:S1000]

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

Analysis Procedure:

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

Debugging Item

Description and Procedure

Ping selected host

Description:

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

Debugging Procedure:

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

ping <remote host>

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

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

· Unknown Host

Unknown Host implies that the nameserver for the current processor does not recognize the specified <remote host>. If the remote processor is a Windows machine, the site nameserver will likely need configuration to support name resolution from the unix client. Contact your site IT organization to assist in resolving this problem.

· No answer from <remote host> or Destination Host Unreachable

No answer from <remote host> implies that the destination hostname is recognized by the current processor but network configuration or availability of the target host prevents network connectivity. Contact your site IT organization to assist in resolving this problem.

Verify ClearQuest database settings

Description:

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

Debugging Procedure:

From the ClearQuest Unix client, enter the following command:

cqreg show

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

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

· Use ClearQuest designer to correct the information

· Execute the following refresh command from the ClearQuest Unix command line because the ClearQuest Unix client does not automatically refresh database connection information from the schema repository:

cqreg refresh

Verify OpenLink Request Broker is running

Description:

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

Debugging Procedure:

From the Oracle Database server, enter the following command:

ps –e | grep oplrqb

This will list all processes on the machine that contain the string “oplrqb”. This is the process name for the OpenLink Request Broker. If it is not running, it needs to be started and enabled for restart at system boot time.

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

· cd [rational_dir]/releases/ ClearQuestOracleSupport.[version]/ openlink_server/[arch]/bin

· Type oplcfg

· Select option ‘S’

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

Verify Oracle Connectivity

Description:

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

Debugging Procedure:

Logon as the user that executes the OpenLink Request Broker.

Traverse to the OpenLink install directory. This is typically [Rational_Dir]/releases/ClearQuestClient.[Version]/openlink_server/ [Arch]/bin.

Browse the OpenLink rules file “oplrqb.ini”. Search for “generic_ora7” or “generic_ora8”, depending on which version of Oracle is running on the database server. Look for the ORACLE_HOME and ORACLE_SID variables. Ensure these are set correctly (case is sensitive). To determine the actual SID executing on the Oracle server, execute ps –ef | grep pmon on the database server. The pmon<SID> process contains the actual SID.

Execute sqlplus from the server as the user who executes the OpenLink Request Broker.

sqlplus <user id>/<password>@<ORACLE_SID>

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

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

Oracle Differences for ClearQuest

Searches using the “contains” operator are always case sensitive when using Oracle as a backend database.

Oracle requires additional configuration to allow searching of multilane text fields. Please consult the Installing ClearQuest manual for details.

2. IBM DB2 Installation

ClearQuest Unix v2001A.04.20 supports IBM’s Universal Database (DB2). To use DB2 with ClearQuest, you must:

· Install the IBM DB2 (version 6.1 or 7.1) database server software on a Windows NT or Windows 2000 machine which you will use as your database server (consult the “Installing Rational ClearQuest” manual and the release notes for ClearQuest Windows v2001A.04.00 for further information on configuring DB2 databases for use with both ClearQuest Windows and ClearQuest Unix.). You will need the DB2 database name as well as the local Windows user id and password for further configuration from the ClearQuest Unix client.

· Install the DB2 client software on each client workstation where ClearQuest Unix will be installed. Please note that DB2 requires the client version match the server version for many operations. All ClearQuest Unix client users must install DB2 client software on their client machines before they can install and use ClearQuest. To install DB2 client software, follow the IBM documentation.

Once the DB2 client software is installed on the ClearQuest Unix client machine, perform the following steps:

1. Logon to the ClearQuest Unix client machine as a user with privileges to modify the database instance (perhaps the Unix user that created the DB2 instance).

2. Ensure that the DB2INSTANCE environment variable is set to the correct DB2 instance. This is very important. The IBM DB2 ODBC driver requires that this environment variable be set for all operations. ClearQuest Unix will not operate properly with DB2 if the DB2INSTANCE environment variable is not set. A typical symptom of the DB2INSTANCE environment variable not being set is that the IBM DB2 ODBC driver will cause a Segmentation Fault after attempting to log in to the DB2 database.

3. Run the DB2 command line administration tool:

db2

4. Create a DB2 TCP/IP NODE for use by ClearQuest Unix. The node alias needs to be the same for all DB2 clients. The port number is the TCP/IP port used by the DB2 service. This is typically set to 51164.

db2> CATALOG TCPIP NODE <node alias> REMOTE <server host name> SERVER <port number>

5. Create a DB2 database alias for both the Master Schema Repository and a User database. The database alias needs to be the same for all DB2 clients.

db2> CATALOG DATABASE <database name> AS <database alias> AT NODE <node alias>

6. Test the connection to the DB2 database. The CONNECT command should succeed.

db2> CONNECT TO <database alias> USER <Windows user id> USING <Windows password>

db2> DISCONNECT CURRENT

db2> QUIT

7. Create a symbolic link from the ClearQuest install area into the IBM DB2 installation area for the IBM DB2 ODBC device driver. This is required because ClearQuest Unix does not redistribute the IBM DB2 device driver. A typical symptom of this step being omitted is that ClearQuest Unix will indicate that the specified driver could not be loaded while attempting to logon to the DB2 database. This step needs to be completed for every ClearQuest Unix install area that will access DB2.

cd <rational directory>/releases/ClearQuestClient.2001.03.00

cd <architecture >/shlib

ln –fs <IBM DB2 Install Dir>/V6.1/lib/libdb2.so db_IBMDB2

8. Launch ClearQuest Unix and configure the connection as follows:

· Vendor: DB2

· Server: <server host name>

· Database: <database alias for Master Schema Repository>

· User Name: <Windows user id>

· Password: <Windows password>

3. Use of SQL Server 7.0 Service Pack 2 or SQL Server 2000 with ClearQuest Unix

ClearQuest Unix v2001A.04.00 supports SQL Server running on a Windows machine as a backend database. To enable this, you need to install the OpenLink Request Broker provided on the ClearQuest Unix CD:

1. Insert the ClearQuest Unix CD into the Windows SQL Server database server machine.

2. The request broker resides in a subdirectory of the main CD called extras/openlink. Copy the opl.zip file to any location on the SQL Server database server that has approximately 16 MB of free disk space. A typical location would be C:\Program Files\OpenLink.

3. Unzip the file into that location and execute cqperl oplrqb.pl.

4. It will prompt you for the directory where you unzipped the file. Type that directory in and hit enter. The request broker will be installed and the oplrqb service will be registered. No other server configuration is necessary.

5. Simply connect to it from the Unix client as you would the Windows client. The following information is required to successfully connect. Note that the Windows Server hostname that you enter must be accessible from all Unix clients. When in doubt, use the ping command to verify connectivity.

· Vendor: SQLSERVER

· Server: <Server hostname>

· Database: <Database name for Master Schema Repository>

· User Name: <SQL Server User Name created for Master Schema Repository>

· Password: <SQL Server Password created for Master Schema Repository>

4. Use of SQL Server 7.0 Service Pack 2 or SQL Server 2000 with certain rare database schemas

There is a known issue with these versions of Microsoft SQL Server. For certain database schemas that could be created by ClearQuest, executing the same query three times in a row by the same process can cause certain rows and tables in the database to become locked. This will create what is known as a blocking SPID (SQL Server Process ID) on the database server. Rational has developed a workaround for this problem until it is addressed by Microsoft. The major symptom of the problem is that the ClearQuest Unix client becomes unavailable to all users (hourglass, or just no response from ClearQuest). This would particularly impact the ClearQuest web interface. To diagnose this problem:

· Run SQL Server Enterprise Manager

· Select the Management section under the appropriate server

· Select Current Activity->Locks/ProcessID

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

The relevant Microsoft defect number for this problem is 58388. Rational Software has developed a workaround that addresses this problem. The relevant Rational Software Technical Note is 13899 – please contact Rational Technical support to obtain this technical note and for assistance with this problem.

5. Hints and Tricks

Executing Nightly Reports using cqtool

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

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

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

cqtool login –database SAMPL –user admin –password “”

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

cqtool new_query –type defect –field id –field headline –field submitter –eq state submitted –database SAMPL –user admin –password “”

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

id Headline Submitter

-- -------- ---------

SAMPL00000011 change due amount is supposed to be red engineer

SAMPL00000012 would like logout button to be larger engineer

SAMPL00000016 too many spaces in "change due" field lead

SAMPL00000019 sales tax incorrect for NH lead

SAMPL00000021 inventory report is not running correctly lead

SAMPL00000024 overriding price operation allows negative number QE

SAMPL00000027 add item button is out of line with the other buttons QE

SAMPL00000028 context sensitive help fails from reorder window QE

SAMPL00000029 formatting does not look right in inventory report QE

SAMPL00000030 add items fails for large quantities QE

SAMPL00000032 shortcut to logout does not work QE

SAMPL00000033 unable to add item already in sale list QE

SAMPL00000034 cancel sale leaves ite in purchase list engineer

SAMPL00000036 inventory report is displaying an empty column engineer

SAMPL00000037 need report for items ordered on a given day engineer

SAMPL00000038 sales tax amount is offset from label engineer

SAMPL00000039 need automatic logout with QEeout engineer

SAMPL00000040 spelling error in help for override price engineer

Count: 22

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

cqtool new_query –type defect –field id –field headline –field submitter –eq state submitted –database SAMPL –user admin –password “” –output_file /tmp/cqoutput

mail cqadmin@yourco.com < /tmp/cqoutput

rm /tmp/cqoutput

Advanced Reporting and Automation with cqperl

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

· cqperl must be used for Perl scripting with ClearQuest Unix. Other versions of Perl will not function properly.

· Each Perl script must include code for loading the CQPerlExt Perl module. This is typically as follows:

$cqhome = $ENV{“CQ_HOME”};

$cqarch = $ENV{“CQ_ARCH”};

push (@INC,”$cqhome/$cqarch/shlib”);

push (@INC,”$cqhome/$cqarch/perllib”);

require CQPerlExt;

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

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

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

# nightlysubmits.pl – A Perl script to list all of the

# defects currently in the submit state.

$cqhome = $ENV{“CQ_HOME”};

$cqarch = $ENV{“CQ_ARCH”};

push (@INC,”$cqhome/$cqarch/shlib”);

push (@INC,”$cqhome/$cqarch/perllib”);

require CQPerlExt;

# All ClearQuest work is done via a session object. Cqperl

# obtains a session object with the CQSession_Build global

# function accessible from the CQPerlExt Perl module.

# API Reference: Session Object

$session = CQPerlExt::CQSession_Build();

# Once we’ve obtained the session, we need to logon. This is

# done with the UserLogon method. You need to specify the

# username, the password, and the database name. The fourth

# parameter, dbset, is usually left blank. There is a typo

# in several versions of the API reference. The session_type

# parameter is no longer required. It should not be included.

# API Reference: Session object->UserLogon method

$session->UserLogon(“admin”,””,”SAMPL”,””);

# Generating a query involves creation of a QueryDef object.

# This is done via a method of the session object called

# BuildQuery. It’s only parameter is the entitydef

# (also known as Record Type) that you wish to query on.

# In this case, we’ll use “Defect”

# API Reference: Session Object->Build Query method

# QueryDef Object

# EntityDef Object->Name property

$querydef = $session->BuildQuery(“Defect”);

# The next step (like creating a query through the ClearQuest

# Unix GUI) is to decide which fields will be in the Query

# Result Set. This is done with the BuildField method of

# the QueryDef object. We’d like to see ID, headline, and

# submitter.

# API Reference: QueryDef Object->BuildField method

$querydef->BuildField(“id”);

$querydef->BuildField(“headline”);

$querydef->BuildField(“submitter”);

# Next, we need to build the filters for this query.

# This is done by constructing a tree of FilterOperator

# objects. Creating the top level FilterOperator object for

# any subtree is done with the BuildFilterOperator method

# of the QueryDef object. The BuildFilterOperator method

# takes one parameter, the boolean operator that will

# determine how each of the subtrees behaves. If there is

# only one filter, either AND or OR will work. To specify

# the correct boolean operator, select the proper BoolOp

# constant and Perl prefix. In this case, we’ll use and, so

# therefore, our constant will be $CQPerlExt::CQ_BOOL_OP_AND.

# API Reference: QueryDef Object->BuildFilterOperator Method

# BoolOp constants

# Notation conventions for Perl

$rootfilternode =

$querydef->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_AND);

# Once we have the root FilterOperatorNode, we’ll assign a

# filter to it. In this case, state equals submitted. We’ll

# use the BuildFilter method of the QueryFilterNode object

# for this. Note that the third parameter to BuildFilter must

# be a Perl reference to an array.

# API Reference: QueryFilterNode object->BuildFilter method

# BoolOp constants

# Notation conventions for Perl

@statetest = “Submitted”;

$rootfilternode->BuildFilter(“State”,

$CQPerlExt::CQ_COMP_OP_EQ,

\@statetest);

# Okay, the Query definition has been created, now it’s time

# to execute it. We go back to the session object for this

# and use the BuildResultSet method. It’s only parameter

# is the QueryDef object we’d previously created. After

# the result set object is ready, we then execute the query.

# API Reference: Session object->BuildResultSet method

# ResultSet object->Execute method

$resultset = $session->BuildResultSet($querydef);

$resultset->Execute();

# Let’s prepare by printing a header for our output.

printf(“%13.13s %50.50s %9.9s\n”,”id”,”headline”,”submitter”);

printf(“%13.13s %50.50s %9.9s\n”,

”-------------“,

”--------------------------------------------------“,

”---------“);

# Now, traverse the resultset and print out the output.

# This is done via the MoveNext method of the result set

# object. It will return $CQPerlExt::CQ_SUCCESS as long as

# there are rows to view. GetColumnValue is used to get the

# data from that row of the resultset.

# API Reference: ResultSet object->MoveNext method

# ResultSet object->GetColumnValue method

while ($resultset->MoveNext() == $CQPerlExt::CQ_SUCCESS) {

printf(“%-13.13s %-50.50s %-9.9s\n”,

$resultset->GetColumnValue(1),

$resultset->GetColumnValue(2),

$resultset->GetColumnValue(3));

}

# And we’re done, so let’s release the session

CQPerlExt::CQSession_Unbuild($session);

Configuring the Rational Suite License Map

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

The license map file resides in $HOME/.Rational (Note the ‘.’ in front of Rational). The file name is “License_Map”.

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

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

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

· standalone (means the same as the first item listed)

· ClearQuest:1.1

· DevelopmentStudioUnix:1.0

· RationalSuiteEnterprise:1.0

· AnalystStudio:1.0

· DevelopmentStudio:1.0

· TestStudio:1.0

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

6. Known Defects

For a list of known defects in Rational ClearQuest v2001A.04.20 for Windows, please consult Rational Technical Support Technote 17188 at http://solutions.rational.com/solutions/. In addition, the following defects are currently known to exist in Rational ClearQuest v2001A.04.20 for Unix.

RAMBU00011852	Can't find libClearCase_ActivityChageSetCtrl_1.so Description: This message will appear in the Change Set control of the Unified Change Management Tab if ClearCase is not installed on the local workstation. Workaround: The error indicates that the Change Set control is not available. This is not fatal. Install ClearCase locally to receive the full UCM integration.
RAMBU00011899	Unix GUI doesn't display picture control Description: The ClearQuest Unix GUI does not currently support the bitmap control available in ClearQuest Designer. Workaround: Design forms without the bitmap control.
RAMBU00016482	CQ Unix on Linux doesn’t support Sawfish window manager Description: When performing certain button related actions in the CQ Unix GUI, the Sawfish window manager will return an X error and the ClearQuest Unix GUI will crash. Specifically, right clicking on an item in the workspace or left clicking the action button will cause this error to occur. Workaround: Use the Enlightenment window manager.
RAMBU00016483	CQ Unix doesn’t automatically refresh databases Description: ClearQuest Unix is designed so that a central administrator can create the database registry for all clients. This prevents the Unix client from automatically updating the list of accessible databases upon database connection like the Windows client does. Workaround: If the end user does not have permission to write to their database registry directory, the ClearQuest Unix administrator should execute the cqreg refresh command to manually refresh the list. If the user has the proper permissions, they may do this themselves.
RAMBU00016529	The delete key tries to delete the selected query in a m/l field on CQ Unix Description: The key bindings for various window managers prevent the use of the delete key for deleting queries from the workspace. The delete key should work properly while editing fields. Workaround: Use right click and delete from the workspace or edit and delete from the Menu.
RAMBU00016594	CQ Unix doesn’t support dual headed Sun machines Description: ClearQuest Unix doesn’t currenly support Sun machines with multiple video cards. A typical error that might be received is: X Error of failed request: BadWindow (invalid Window parameter) Major opcode of failed request: 19 (X_DeleteProperty) Workaround: Execute ClearQuest Unix with X Servers that have only one video card.
RAMBU00017560	Closing items in CQ Unix is too slow Description: When closing GUI elements with a number of Widgets (such as the Workspace), the ClearQuest Unix GUI can take an excessive amount of time to complete the operation. For databases with large workspaces, it can take 20-30 seconds to complete the “Close Database” operation from the File menu. Workaround: The user should wait the additional time for the operation to complete.
RAMBU00018346	Cannot create fontset errors on AIX Description: If the user’s LANG environment variable is set to various values other than C or nothing, then the AIX client may display “Cannot create fontset” to the console as ClearQuest is executing. Workaround: Change the LANG environment variable setting to “C” or nothing.
RAMBU00018393	I18N: Unable to type international characters in CQ Unix Description: When a user attempts to enter non-US English characters into field items in ClearQuest Unix, they are not properly accepted. Workaround: None, ClearQuest Unix does not currently support character sets other than US English.
RAMBU00021386	CQUnix: Need better error message if logging in to (unsupported) user db's Description: The ClearQuest Unix client does not support logging in to SQL Anywhere or Microsoft Access databases. An attempt to register or log on to these databases might cause an error to appear of the form “Failed Condition: AdIsValidDbVendor(…)”. Workaround: Only attempt logon to supported database vendors.
RAMBU00021395	CQ Unix: segmentation fault after deleting query Description: When using Hummingbird Exceed as an X emulator with the ClearQuest Unix client, there is a property of Exceed called “copy on loss of focus”. If an item in the ClearQuest workspace is selected and the ClearQuest window is minimized, Exceed will attempt to copy the text from the workspace into the clipboard. ClearQuest Unix doesn’t support this and crashes. Workaround: Turn off “copy on loss of focus” for Exceed when running with ClearQuest Unix.
RAMBU00021396	mkreplica -import on UNIX fails for SQL Server 2000 db vendor Description: The mkreplica –import subcommand of multiutil uses SQL commands that are not supported by the current version of the ODBC driver on Unix. Therefore, multiutil commands are not currently supported from ClearQuest Unix when they access Microsoft SQL Server databases. Workaround: Use multiutil from a Windows client to access Microsoft SQL Server databases.
RAMBU00021417	CQ Unix: scroll bar for fields available for display in Display editor breaks if user selects an existing field Description: When a user selects a field to add to the list of displayed fields and the field is in the lower portion of the list of fields, (user needs to select a field not on the first "page" of the scrolling list) then the list scrolls to the top and the user can't use the scrollbar to scroll up and down in the list. The scrollbar will bounce back up to the top. Workaround: The user needs to select a visible item in the list of fields. The scrollbar will then behave normally.
RAMBU00021445	Query is still valid if deleted using cqtool delete Description: The cqtool command line interface does not immediately delete items from the workspace, it does that upon exit. Workaround: Logoff and then logon to the command line interface to refresh the workspace.
RAMBU00021501	CQ Unix: "Save As" after "Add" in attachment control causes error Description: The user will receive a message indicating that “The string “” cannot be interpreted as an integer, please use a valid string”. Workaround: Apply the changes to the record and subsequent “Save As” actions should work normally.
RAMBU00021503	CQUnix: When mark record as duplicate, screen does not refresh to show duplicate record Description: When the duplicate action is taken on a record, the form is not updated with the duplicate information. Workaround: Selecting another record and then reselecting the duplicated record will refresh the form.
RAMBU0006187	Wrong SQL is generated when using a reference_list field in an OR expression. Description: When trying to generate a query with the following filter: project = 'MyTest' OR owner = 'lead' OR reflist = 'SAMPL00000001' ClearQuest can not process the query, and will return the following error: "ClearQuest cannot currently generate the correct SQL when a list_type field appears in a filter under an OR expression." Workaround: None
RAMBU00006240	Can not create a case insensitive query with a case sensitive database. Description: If a backend data store has been setup to be case sensitive, ClearQuest does not provide a way to run a case insensitive query. Workaround: Use the SQL Editor and modify the query by adding the LOWER function around the fieldnames. For example: {fn LOWER(T1.fieldname)}
RAMBU00016402	Query returns no data when multiple filters used on same reference list field. Description: A query will return no data when multiple filters are used on same reference list or attachments field. Workaround: None

7. Fixed Defects

For a list of fixed defects in Rational ClearQuest v2001A.04.20 for Windows, please consult Rational Technical Support Technote 17187 at http://solutions.rational.com/solutions/. The following defects are fixed in Rational ClearQuest v2001A.04.20 for Unix.

RAMBU00009228	CQEventObject not passed to Perl hook
RAMBU00010980	Caching of session passed into external widget is not updated correctly
RAMBU00011103	hook failure during Assign_To_Developer in db
RAMBU00011353	query editor doesn't check value count for CONTAINS operator
RAMBU00011543	Error not returned when Email Options settings cannot be saved in UNIX home directory
RAMBU00011545	Trying to use View->Change User Profile gives missing SID error
RAMBU00011557	Inconsistencies between CQ UNIX and native client GUI
RAMBU00011580	Query->Run doesn't always run query selected in workspace
RAMBU00011614	cqreg prints plain-text password
RAMBU00011866	save-as doesn't change to new query
RAMBU00011870	cqreg refresh does not update server value for MASTR
RAMBU00011874	Unable to find CQ doc start.htm if not running the default <Rational_dir>/base/cots/netscape.4.7
RAMBU00011889	Calls to Record Scripts from push buttons are different between win/unix
RAMBU00011909	View->Change User Profile from Unix client doesn't upgrade user dbs
RAMBU00011919	the -man option to cqtool subcommands needs to be more prominent
RAMBU00011961	Unix combo boxes don't sort when asked to
RAMBU00011982	cqreg should NOT succeed if -d is not in the same case letters as ConnectOptions in CQ Designer under Database Properties
RAMBU00012109	help message for cqreg is wrong and confusing
RAMBU00012112	cqreg register should work like "connect to schema repository"
RAMBU00012115	cqreg command line echo must quote the connect_options value
RAMBU00012265	Help menu doesn't have "E-Mail Technical Support" like Windows client does
RAMBU00012480	cqreg register doesn't use connect_option to override SID
RAMBU00012522	submitting email rule doesn't check permissions
RAMBU00012659	cqperl temp file names contain garbage
RAMBU00013461	CQ Unix client doesn't support context menu hooks
RAMBU00013752	CQ Unix client spins while waiting for large query
RAMBU00014241	CQ Unix client does not recognize dates after 2000 if they are of the form 00
RAMBU00014427	There is no create user function in the CQPerlExt.pm
RAMBU00014936	date time field is not working correctly
RAMBU00015687	CQ Unix client should check attachment comment length before validation
RAMBU00015944	owner field sometimes has trailing garbage
RAMBU00015952	duplicate records don't display properly
RAMBU00016009	unknown user reference causes 2 repo logins
RAMBU00016286	CQ Unix email fails when you do not have fields to check for change.
RAMBU00016309	Need to 'italicize' mandatory fields on UNIX client
RAMBU00016444	cq_setup.csh should detect multiply defined ClearQuest releases
RAMBU00016478	CQ Unix on Linux requires user set TZ environment variable
RAMBU00017001	CQ Unix 2001.03.00 core dumps on modify of record with dereferenced controls
RAMBU00017169	setfield choice code does not work in cqunix.
RAMBU00017181	user privileges do not work the same way in cq unix.
RAMBU00017279	unable to change password from cqunix.
RAMBU00017411	CQ Unix: Man pages not set up correctly
RAMBU00017412	CQ Unix: Please remove old readme from DOC directory
RAMBU00017438	On an HP11 UX machine the hp10_pa consumes all the CPU cycles
RAMBU00017585	validation hook code message does not appear in cq unix.
RAMBU00017598	cc_change_set limited to a field size, doesn't have automatic scroll bars
RAMBU00017759	Clearquest License Problem
RAMBU00017812	reference list fields do not show in the right order in cq unix
RAMBU00017934	cqtool does not allow user to add multiple values for a field Note: This fix required a change to the syntax of several cqtool subcommands. Previously, subcommands such as submit and edit_record which allowed various parameters to not have option specifiers (-option) in front of them now have slightly different syntax. Please check the man pages for these commands for specific differences.
RAMBU00017982	too long names for a constant list and cq unix.
RAMBU00021384	CQ-Unix: cannot open text attachments
RAMBU00021399	Startup query not displayed on Windows client if startup query was assigned in CQUnix client and vise versa
RAMBU00021424	CQUnix: cqreg initialize during rs_install appears to not have stored my registry directory
RAMBU00021439	CQUnix: cqreg prints plain-text password when invoked on the command line
RAMBU00021444	CQUnix: cqtool prints password in plain-text
RAMBU00021447	example in "cqtool> new_query -man" contains incorrect result set

8. The Rational Web Site

Please visit the Rational Web site for latest Release Notes, patches and information:

http://www.rational.com/

9. Subscribing to the ClearQuest Users Group.

The ClearQuest Users 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/index.jsp

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

10. Accessing the Sample Hooks Database

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

http://clearquest.rational.com/cqhooks

To gain access, select “Sample Hooks Database”.

You can browse the existing hook scripts for ideas, or add a script you would like to share with others.

11. Contacting Rational Technical Support

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

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

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

Support Location	Telephone	Electronic Mail
North America	(800) 433-5444 (408) 863-4000	mailto:support@rational.com
Europe	PHONE: +31 20 454-6200 FAX:+31 20 454-6201	mailto:support@europe.rational.com
Asia Pacific	+61-2-9419-0111	mailto:support@apac.rational.com

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

NOTICE OF PROPRIETARY RIGHTS

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