Rational ClearQuest v2002.05.01 Patch 02 (Windows) Release Notes

Copyright © 2002 Rational Software and its subsidiaries. All rights reserved.

Release Notes - September 30, 2002

ClearQuest administrators must read this entire release notes document before installing ClearQuest v2002.05.01 Patch 02.  ClearQuest users should not install this patch without consulting their ClearQuest administrator. 

Rational ClearQuest v2002.05.01 Patch 02 is designed to be installed on ClearQuest v2002.05.01, v2002.05.01 Patch 01, and v2002.05.20. 

ClearQuest MultiSite Customers

This patch is mandatory for all ClearQuest MultiSite deployments.  ClearQuest MultiSite customers must run a Rational ClearQuest Analysis Tool on their repository before they apply this patch.  The ClearQuest Analysis Tool is available by contacting Rational Technical Support.  See Section 5 for the mandatory customer restrictions and requirements you must observe in order to ensure a successful ClearQuest MultiSite deployment. 

ClearQuest Customers

 

This patch contains significant enhancements with regards to data integrity and is recommended for ClearQuest customers.  For information on the effects this patch will have on a non-replicated ClearQuest deployment, see Section 4.  See Section 5 for the mandatory customer restrictions and requirements you must observe in order to ensure a successful ClearQuest deployment. 

 


Table of Contents

 

1.   Supported Hardware and Software Platforms

2.   What’s New in Rational ClearQuest v2002.05.01 Patch 02

3.   ClearQuest MultiSite Deployment Roadmap

4.   ClearQuest (Non-replicated) Deployment Roadmap

5.   Installing Rational ClearQuest v2002.05.01 Patch 02

6.   Rational ClearQuest Analysis Tool

7.   Applying the CharacterSetValidation Package

8.   Setting the Data Code Page Value

9.   Divergence Protection on the Web

10. Interoperation with Previous Versions of ClearQuest

11. ClearQuest MultiSite Enhancements

12. Resolved Defects

13. Known Problems in Rational ClearQuest v2002.05.01 Patch 02

14. Resources for Rational ClearQuest

15. Contacting Rational Technical Support

 


1.              Supported Hardware and Software Platforms

There are no changes to the supported platforms in this patch.  For information on supported platforms, please see the Rational Suite Release Notes, Version 2002.05.01.

Note:  There is a temporary restriction that all MultiSite synchronization servers must run on Windows platforms.

 


2.              What’s New in Rational ClearQuest v2002.05.01 Patch 02

 

This patch includes fixes and enhancements to ClearQuest and ClearQuest MultiSite in the areas of:

 

·         Enforcement of a single code page to prevent data corruption

 

·         Replica removal using rmreplica

 

·         Schema modification in a MultiSite environment

 

·         Additional enhancements

 

The following sections contain detailed information about the fixes and enhancements included in this patch.

 

2.1    Enforcement of a Single Code Page to Prevent Data Corruption

 

A code page, or character set, defines a collection of characters, numbers, punctuation, symbols, and special characters for a particular language.

 

In order to prevent potential data corruption in a ClearQuest deployment, one of the following conditions must be met:

 

·         All databases/servers/clients must use the same code page

 

·         If different code pages are used, all databases must contain only ASCII data

 

When you use ClearQuest, each client that accesses your ClearQuest databases has its own code page.  A code page specifies the set of characters that are valid in a given environment.  In other words, a code page controls which characters will be manipulated correctly on a particular client. 

 

ClearQuest and ClearQuest MultiSite have limited internationalization support (see Solution # 125963522 at www.eservice.rational.com).  Data corruption can occur when clients using different code pages attempt to modify the same data.  Data corruption is typically noted as a “?” character in the client.  These problems are more likely to occur in a MultiSite environment when data from one code page is exported to replicas running different code pages, causing data corruption and divergence (members of a replica family having different values for the same record) in a replica family.

 

Example

 

For example, User1 is working on a client with the 1252 (European) code page and enters data into the SAMPL database, which also uses the 1252 code page.  Down the hall, User2 is working on a client with the 932 (Japanese) code page and opens the record modified by User1.  The data that User1 entered is translated so that it can be represented in User2’s client code page.  Because the two code pages differ, the data that User2 sees is converted into characters that his client’s code page can understand (typically the “?” character). At this point the display is corrupted, but the data in the database remains valid.

 

If User2 enters more data into the record (using characters from the 932 code page) and commits it to the database, the record now permanently contains corrupted data that is no longer meaningful when read by any code page. 

 

Solution

 

Rational ClearQuest v2002.05.01 Patch 02 now includes functionality to enforce the use of a single code page or ASCII-only data for a successful ClearQuest deployment, and to ensure data integrity.  The patch contains a CharacterSetValidation package that prevents users from entering data from multiple code pages into a database record.  The patch also introduces a new “data code page” setting for a MultiSite database that prevents divergence on packet export. 


In addition to installing this patch and applying the package, you must follow the guidelines and restrictions in Section
5 to protect your database and MultiSite environment from data corruption and divergence.  This includes running the Rational ClearQuest Analysis Tool to ensure that the existing data in your database is safe to replicate.  For more information about the Rational ClearQuest Analysis Tool, see Section 6. 

 

2.2           Replica Removal using rmreplica

 

ClearQuest v2002.05.01 Patch 02 includes enhancements to the process of removing replicas with rmreplica.  In addition to the rmreplica improvements in this patch, several changes have been made to the recommended procedure for removing replicas.  See Section 11.4 for the updated procedure and see Section 12 for a list of all resolved rmreplica defects.

 

2.3    Schema Modification in a Replicated Environment

 

ClearQuest v2002.05.01 Patch 02 includes several enhancements to the process of modifying schemas in a replicated environment.  Also included in these release notes is a recommended procedure for upgrading to a new schema version.  See Section 11.1 for the updated procedure and see Section 12 for a list of all resolved schema modification defects.

 

2.4           Additional Enhancements

 

ClearQuest v2002.05.01 Patch 02 includes additional enhancements to the ClearQuest product, including improvements in the areas of performance and replica synchronization.  See Section 12 for a list of all defects resolved in this patch.

 

 


3.              ClearQuest MultiSite Deployment Roadmap

 

ClearQuest MultiSite customers must follow these steps to successfully deploy the patch.  ClearQuest customers should read Section 4 for instructions on how to deploy the patch in a non-MultiSite ClearQuest deployment.

 

1.       In addition to this patch you will also need the Rational ClearQuest Analysis Tool to analyze your database.  Contact Rational Technical Support to obtain this tool.

 

2.       To apply this patch you must not be using any UNIX synchronization servers. If you use them, Rational recommends that you decommission them and switch to Windows servers.

If you cannot decommission your UNIX synchronization servers, then stop here and do not apply this patch.

Note: UNIX clients may continue to be used with Windows synchronization servers.

 

3.       Choose a data code page value for your set of databases.  Refer to the guidelines in Section 8 for instructions on choosing the appropriate data code page value.  For a list of code pages supported by Rational, see Table 1 in Section 8.

 

4.       If you have not yet deployed ClearQuest MultiSite:

 

a.       Notify all users that maintenance is scheduled and they must disconnect from all user databases.

 

b.       Using the Rational ClearQuest Analysis Tool, run a database analysis to ensure that your databases contain only characters from your selected code page.  See the documentation included with the tool for instructions on how to run a database analysis.

 

c.       Review the analysis results and create a repair plan if necessary. Depending on the analysis results, you may need to repair the contents of your database.  See the documentation included with the Rational ClearQuest Analysis Tool for instructions on how to repair your database.

 

d.       Install the patch on your servers and admin machines.  See Section 5 for instructions. 

 

e.       Back up all user databases.

 

f.         Repair your database (if necessary) based on the plan from Step b.  See the documentation included with the Rational ClearQuest Analysis Tool for instructions on how to repair your database.

 

g.       Apply the CharacterSetValidation package and upgrade user databases.  See Section 7 for instructions.

 

h.       Set the data code page for your schema repository and all user databases.  See Section 8 for instructions on setting the data code page value.

 

i.         Upgrade all clients to the patch.

 

j.         Notify users that the databases are available.

 

k.       Follow the normal instructions for creating replicas.  For information on creating replicas, see the Administrator’s Guide for ClearQuest MultiSite.

 

 

5.       If you have already deployed ClearQuest MultiSite, do one of the following:

 

5.1 (Recommended) Remove existing replicas and recreate:

 

Note:  ClearQuest MultiSite customers with a UCM or Base ClearCase integration should skip to Step 5.2.  It is not recommended that you remove your existing replicas.  Doing so may result in the permanent loss of integration.

 

a.       At each site other than the working master:

 

·         Notify all users that maintenance is scheduled and they must disconnect from all user databases in the ClearQuest MultiSite clan.

 

·         Export update packets from all sites in the ClearQuest MultiSite clan to the working master site. 

 

·         Back up all user databases.

 

b.       At the working master site:

 

·            Notify all users that maintenance is scheduled and they must disconnect from all user databases in the ClearQuest MultiSite clan.

 

·            Import update packets from all sites in the ClearQuest MultiSite clan.

 

·            Back up all user databases.

 

c.       Using the Rational ClearQuest Analysis Tool, run a database analysis on the working master schema repository to ensure that it contains only characters from your selected code page.  See the documentation included with the tool for instructions on how to run a database analysis.

Note:  In this case, you only need to do a database analysis (not an oplog analysis). 

 

d.       Review analysis results and create a repair plan if necessary. Depending on the analysis results, you may need to repair the contents of your database.  See the documentation included with the Rational ClearQuest Analysis Tool for instructions on how to repair your database.

 

e.       Install the patch on all servers and admin machines.  See Section 5 for instructions on how to install the patch.

 

f.         Repair the working master schema repository (if necessary) based on the plan from Step b.  See the documentation included with the Rational ClearQuest Analysis Tool for instructions.

 

g.       Remove all other replicas in the clan.  See Section 11.4 for information on how to remove replicas using the rmreplica command.

 

h.       Apply the CharacterSetValidation package and upgrade the databases at the working master site.  See Section 7 for instructions on how to apply the CharacterSetValidation package.

 

i.         Set the data code page for your schema repository and all user databases at the working master site.  See Section 8 for instructions on setting the data code page value.

 

j.         Upgrade all clients to the patch.

 

k.       Notify users that the working master is available.

 

l.         Recreate your replicas and site following the normal instructions.  Note that you cannot give your new site and replicas the same names as the old site and replicas you deleted (see RAMBU00036844 in Section 13).  For information on creating replicas, see the Administrator’s Guide for ClearQuest MultiSite. 

      

5.2 If you cannot remove existing replicas:

 

a.       Synchronize all sites in the ClearQuest MultiSite clan. 

 

b.       Notify all users that maintenance is scheduled and they must disconnect from all user databases in the ClearQuest MultiSite clan.

 

c.       Using the Rational ClearQuest Analysis Tool, run a database and oplog analysis on all databases at all sites to ensure that they contain only characters from your selected code page.  See the documentation included with the Rational ClearQuest Analysis Tool for instructions on how to run an oplog and database analysis.

Note:  In this case, you must do both database AND oplog analysis. 

 

d.       Review the analysis results and create a repair plan if necessary. Depending on the analysis results, you may need to repair the contents of your database.  See the documentation included with the Rational ClearQuest Analysis Tool for instructions on how to repair your database.

 

e.       Stop synchronization between sites.

 

f.         Deploy the patch on all servers and admin machines.  See Section 5 for instructions on how to install the patch.

 

g.       Back up all user databases.

 

h.       Repair ALL sites (if necessary) based on the plan from Step b.  See the documentation included with the Rational ClearQuest Analysis Tool for instructions on how to repair your sites.

 

i.         Apply the CharacterSetValidation package and upgrade all databases at the working master site.  See Section 7 for instructions on how to apply the CharacterSetValidation package.  Follow the instructions on schema modifications in replicated environment in Section 11.1.

 

j.         Start synchronization and allow the entire clan to synchronize.  Note that synchronization may fail if the repair was not complete.

 

k.       Set the data code page at the working master schema repository.  See Section 8 for instructions on setting the data code page value.

 

l.         Upgrade all clients to the patch.

 

m.     Notify users that the databases are available.

 


4.              ClearQuest (Non-replicated) Deployment Roadmap

 

Rational recommends that ClearQuest customers consider enforcing the single code page restriction to prevent potential data corruption in their ClearQuest deployment.  Enforcing this restriction will result in new behavior in your ClearQuest environment relating to the type of data allowed in your database.  The new behavior differs based on whether you choose to install only the patch, or to use all of the mechanisms to enforce a single code page, including the package, and the data code page setting.

 

Note:  In addition to preventing data corruption, installing the patch and using the single code page enforcement mechanisms will ensure a successful migration to a ClearQuest MultiSite deployment in the future.

 

Patch Only

 

If you choose to only install the patch (and not to apply the CharacterSetValidation package and set the data code page value) there are no restrictions on the data allowed in your database.  By installing only the patch, you can take advantage of the non-code page enhancements included in this patch, such as performance improvements.

 

Follow the instructions below to deploy ClearQuest v2002.05.01 Patch 02 for full single code page enforcement.

 

4.1           Deployment Instructions

 

  1. Decide whether your site will benefit from deployment of the patch.  Refer to the beginning of this section for information on the effect this patch, the CharacterSetValidation package, and the data code page value will have on your non-replicated ClearQuest deployment.

 

  1. In addition to this patch you will also need the Rational ClearQuest Analysis Tool to analyze your database. Contact Rational Technical Support to obtain this tool.

 

  1. Choose a data code page value for your set of databases.  Refer to the guidelines in Section 8 for instructions on choosing the appropriate data code page value. For a list of code pages supported by Rational, see Table 1 in Section 8.

 

  1. Using the Rational ClearQuest Analysis Tool, run a database analysis to ensure that your databases contain only characters from your selected code page. See the documentation included with the tool for instructions on how to run a database analysis.

 

  1. Review the analysis results and create a repair plan if necessary. Depending on the analysis results, you may need to repair the contents of your database. See the documentation included with the Rational ClearQuest Analysis Tool for instructions on how to repair your database.

 

  1. Notify all users that maintenance is scheduled and they must disconnect from all user databases.

 

  1. Install the patch on your servers and admin machines. See Section 5 for instructions.

 

  1. Back up all user databases.

 

  1. Repair your database (if necessary) based on the plan from Step b. See the documentation included with the Rational ClearQuest Analysis Tool for instructions on how to repair your database.

 

  1. If you want to enforce a single code page in your ClearQuest deployment, do the following:

 

a.       Apply the CharacterSetValidation package to your schema.  See Section 7 for instructions.

 

b.       Upgrade all user databases.

 

c.       Set the data code page value on your schema repository.  See Section 8 for instructions.

 

d.       Set the data code page value for all user databases.  See Section 8 for instructions.

 

  1. Upgrade all clients to the patch.

 

  1. Notify users that the databases are available.

 


5.              Installing Rational ClearQuest v2002.05.01 Patch 02

Rational ClearQuest v2002.05.01 Patch 02 is designed to be installed directly on top of ClearQuest v2002.05.01, v2002.05.01 Patch 01, and v2002.05.20.  This patch contains this Release Notes document, a self-extracting executable that includes the necessary ClearQuest binary files as well as a ClearQuest CharacterSetValidation package, and a package installation script.  See Section 7 for instructions on running the script and installing the CharacterSetValidation package.  See Section 8 for instructions on setting the new data code page value.

Follow these steps to install the patch:

1.       Review the Deployment Roadmap:

 

·         If you are running ClearQuest MultiSite, see Section 3. 

 

·         If you are running ClearQuest in a non-replicated environment, see Section 4.

 

2.       If ClearQuest Web is installed on the machine, make sure that the ClearQuest\WWW folder allows write access.

 

3.       Double-click CQ_2002.05.01_Patch02.exe.

 

4.       Follow the instructions in the Installation dialog box.

 

Required Upgrades and General Requirements

 

·         All MultiSite synchronization servers must run on Windows operating systems (temporary restriction). 


Note:  If you are using UNIX MultiSite servers and want to install this patch, Rational requires that you switch to Windows servers and follow the required upgrade.  UNIX servers cannot read oplogs or packets generated by ClearQuest versions following v2002.05.00.  They will corrupt v2002.05.01 oplogs and fail when reading v2002.05.01 Patch 01 oplogs.  If you are unable to switch to Windows servers, do not install this patch.

 

·         You must upgrade all Windows servers and clients to ClearQuest v2002.05.01 Patch 02 in the following order:

 

1.       Upgrade all Windows MultiSite servers (MultiSite synchronization, Web) and apply the CharacterSetValidation package to all production schemas.

 

2.       Upgrade all Windows clients.

 

·         All MultiSite synchronization servers must use the same code page.

 

·         All multiutil commands must be run only on v2002.05.01 Patch 02 machines.

 

·         The ClearQuest Designer must be run only on v2002.05.01 Patch 02 machines.

 

Recommendation

 

·         Create all new replicas from the master site.

 


6.              Rational ClearQuest Analysis Tool

 

You must run the Rational ClearQuest Analysis Tool on your databases and oplogs before you install ClearQuest v2002.05.01 Patch 02.  This tool will locate characters in your database and oplogs that are outside of your chosen code page. 

 

Contact Rational Technical Support to obtain this tool.  See the documentation included with the Rational ClearQuest Analysis Tool for instructions on using the tool to repair your databases and oplogs.

 


7.              Applying the CharacterSetValidation Package

 

Rational ClearQuest v2002.05.01 Patch 02 contains a CharacterSetValidation package that prevents data corruption by preventing users of the native client from entering data in a user record from a code page other than the code page value set for that database. 

 

All ClearQuest MultiSite customers must apply the CharacterSetValidation package.  ClearQuest customers not using MultiSite should also consider installing the patch and applying the package.  For information on the effects of installing the patch and applying the CharacterSetValidation package to a non-MultiSite database, see Section 4. If you do not apply the CharacterSetValidation package to your database, it is possible for users to enter non-supported data from the client and for data to be corrupted when modified on certain clients.

 

 

For each schema, follow these steps to apply the CharacterSetValidation package:

 

  1. Check in the schema and make sure that each user databases is using the latest version of the schema.

 

  1. Run the script apply_character_set_validation_package.bat that is included with ClearQuest v2002.05.01 Patch 02:

 

apply_character_set_validation_package admin-username admin-password myDB myDBSet schema

 

where

 

myDB

One of the user databases using the schema being modified

 

myDBSet

The schema’s database set name

 

schema

The schema to which the CharacterSetValidation package is being applied

 

  1. Verify that the script did not output any errors.  If an error occurs contact Rational Technical Support.

 

  1. Log in to the ClearQuest Designer and upgrade your user databases.

 

 


8.              Setting the Data Code Page Value

                       

After installing ClearQuest v2002.05.01 Patch 02, it is strongly recommended that a ClearQuest administrator set the data code page value for each user database. 

 

Notes: 

·         ClearQuest customers who do not want to enforce the use of one code page should not set the data code page value. 

 

·         ClearQuest UNIX customers and customers with heterogeneous deployments must set the data code page to ASCII as there is no internationalization support for UNIX platforms.

 

After the code page value is set in a ClearQuest MultiSite environment, ClearQuest compares the data code page of the database to the code page of the client during export of a packet. The export operation succeeds if the code pages are the same, or if the data code page is set to ASCII.  The data code page value is then written in the header of the packet being exported.  Import succeeds only if the code page value in the header is the same as, or a subset of, the code page of the importer process.

 

If a code page value is not set (in both replicated and non-replicated ClearQuest environments), the default value of ASCII will be used, limiting your database to printable ASCII data (ASCII values 32-126, tab, carriage return, and line feed characters) entry only.  Earlier versions of ClearQuest clients will not be able to submit or edit any records if the data code page value is not explicitly set to ASCII and the CharacterSetValidation package is applied.

 

Note:  If your database already contains data from more than one code page, future exports may fail no matter which code page you select.  Before installing the patch, use the Rational ClearQuest Analysis Tool to determine whether your database contains characters from multiple code pages.  Contact Rational Technical support to obtain this tool. 

 

8.1    Selecting a Data Code Page Value

 

Follow these guidelines to help you determine the appropriate code page value for your ClearQuest database:

 

·         Identify which code page is appropriate for the language used by the majority of your users.  See Table 1 for a list of code page values and their associated languages.

 

·         If you cannot upgrade all servers and clients immediately (for example, you are using UNIX clients), then set the data code page value to ASCII.  Otherwise, clients running earlier versions of ClearQuest will not be able to edit or submit any user records.

 

·         If you use different code pages on your ClearQuest clients, Web servers, MultiSite servers and DBMS servers, then set the data code page value to ASCII.

 

·         If you use the same code page on all ClearQuest clients, Web servers, MultiSite servers and DBMS servers, then set the data code page value to that code page. 

 

Notes: 

 

·         If you set the data code page to ASCII, you can change the data code page value to a non-ASCII code page at any time.

 

·         If you set the data code page to a value other than ASCII:

 

-         All clients must be running the patch.

 

-         Changing the code page value to ASCII, or any another code page, may cause future exports to fail if your database contains data outside of the new code page.

  

8.2           Rational Supported Code Pages

 

The following table contains a list of all code pages supported by Rational at Level 2.  See Solution # 125963522 at www.eservice.rational.com for information on internationalization support levels.

 

Table 1:  Rational supported code pages

Code Page Number

Code Page Language

932      

Japanese (Shift-JIS)

936

Chinese – Simplified (GBK)

1252    

Danish, Dutch, English, Finnish, French, German, Italian, Norwegian, Brazilian Portuguese, Spanish, Swedish (Latin-1)

20127

ASCII

 

8.3           Setting the Data Code Page Value

 

To set the data code page value, run the following commands from a command prompt on your MultiSite synchronization server:

 

Notes:

 

·         You must run the installutil commands to set the data code page value as a super-user from the working master site.

 

·         Setting the data code page value does not convert the data in your database to characters in your selected code page.  If your database already contains characters that do not map to your selected code page, replication failure will occur.

 

1.    Run the installutil lscodepage command to determine the client code page being used by your MultiSite synchronization server.

installutil lscodepage –dbset myDBSet user password

Sample Command Output

 

         Code page of 2002.05.00:  20127 (US-ASCII) (default)
Code page of client:  1252  (ANSI – Latin I)

 

Note:  In this example, the client code page is 1252 (Latin-1).

 

2.       From the working master site, set the data code page value for your schema repository to the data code page being used by your MultiSite synchronization server, or to ASCII: 

·         If the client code page value listed by lscodepage is supported by Rational, run the installutil setdbcodepagetoplatformcodepage command to set your data code page to this value.  For a list of code pages supported by Rational, see Table 1.

installutil setdbcodepagetoplatformcodepage –dbset myDBSet admin_user admin_password

 

·         To set your code page value to ASCII, run the installutil setdbcodepagetoascii command.

installutil setdbcodepagetoascii –dbset myDBSet admin_user admin_password

Note:  If you change the data code page value to ASCII from another code page, all data that cannot be represented by ASCII characters will cause future exports to fail.

 

·         If the client code page value listed by lscodepage is an unsupported code page, and you choose not to prevent data corruption in your database, you can use the –force option to set the data code page to this value.  However, the use of this option is not supported.

installutil setdbcodepagetoplatformcodepage –dbset myDBSet –force admin_user admin_password

 

3.       After you set the data code page for your schema repository, run the installutil setuserdbcodepage command to set the code page for your user databases.  This prevents data from being corrupted when it is modified by a client using a code page other than the code page set for your database. 

 

·         To set the code page for a specific database, specify a database name:

installutil setuserdbcodepage -dbset myDBSet admin_user admin_password user_db_name            

                              

·         To set the code page of all user databases, do not specify a database name:

installutil setuserdbcodepage -dbset myDBSet admin_user admin_password

 

 


9.              Divergence Protection on the Web

 

The Rational ClearQuest Web client and UNIX/Windows clients offer different levels of protection against data corruption and divergence.  Because the Web client cannot determine the code page used by the Web browser, there is limited protection against invalid code page characters when you use the Web interface.  When you use the Web client instead of a native client, there is no guarantee that invalid characters won’t enter your database and cause data corruption. 

 

Therefore, when using the ClearQuest Web interface, you should input only characters that are supported by the data code page of the ClearQuest user database.  If unsupported characters are used, then those characters may be rejected or corrupted.

 


10.        Interoperation with Previous Versions of ClearQuest

 

Previous versions of ClearQuest clients, including UNIX clients, may interoperate with this patch in the following ways:

 

 

 


11.        ClearQuest MultiSite Enhancements

 

The following sections include information about ClearQuest MultiSite enhancements included in v2002.05.01 Patch 02.

 

11.1  Upgrading a Schema Version with ClearQuest MultiSite

 

This procedure describes how to introduce a new schema version to a ClearQuest MultiSite clan by synchronizing the new schema to all sites before upgrading any user databases.  Rational requires that you follow this procedure to help ensure a stable and reliable ClearQuest MultiSite environment. 

 

In addition to following this procedure, you must not do the following when using ClearQuest MultiSite:

 

·         Delete record types and states

 

·         Change the working master if all databases are not using the same schema version

 

·         Change mastership of package-owned queries

 

Upgrade Instructions

 

  1. Make the desired schema changes and test them against a local test database.

 

  1. Notify all users that maintenance is scheduled and they must disconnect from all user databases in the ClearQuest MultiSite clan.

 

  1. Suspend automated synchronization between ALL user databases in the ClearQuest MultiSite clan.

 

  1. (Optional) Stop and restart your vendor database server to ensure that there are no open connections to the schema repository or user database.

 

  1. Synchronize all sites in the ClearQuest MultiSite clan.  After synchronization, check the incoming and outgoing storage bays to make sure that all packets were sent and imported.  Run the lsepoch command at each site to verify that all replicas report the same epoch estimates.

 

  1. Back up all schema repositories and user databases in the ClearQuest MultiSite clan.

 

  1. Check in the new schema version at the master schema repository replica, but DO NOT upgrade the user database. 

 

  1. Export and send an update packet from the MASTR family only (not the user database family) to all other sites in the clan. 
 

multiutil syncreplica -export -clan DEMO -site SITEA

-family MASTR -u admin -p "" -out c:\cqms\syncA.xml SITEB

Multiutil: Packet file 'c:\cqms\syncA.xml' generated

 

  1. Import the update packet at all sites. 

multiutil syncreplica -import -clan DEMO -site SITEB

-family MASTR -u admin -p "" c:\cqms\syncA.xml

Multiutil: 1 transactions from SITEA have been replayed into the MASTR database

Multiutil: Deleting packet c:\cqms\syncA.xml

 

Note:  At this point, the schema version exists at all the sites in the clan, but the user databases have not been upgraded.

 

  1. Upgrade the user databases by performing the following steps.  This ensures that all replicas in the family are running the same version of the schema before synchronization is restarted.

 

a.       Upgrade the user database at the working master site.

 

b.       Synchronize all sites. 

 

c.       Upgrade the user databases at all remaining sites.

 

11.               Restart synchronization among the user databases at your sites.

 

12.               Confirm that all synchronizations are successful and that all user databases in the clan are using the same schema version.

 

13.               Notify users that the replicas are available.

 

 

11.2  Synchronizing User Database Families

 

In certain circumstances, successful import of user database update packets may depend on information contained in other user database packets.  If your schema repository is associated with multiple user database families, import may fail if the packets are not replayed in the order they were generated. 

 

Example

 

A particular clan, with sites in Boston and Denver has two user databases, User1 and User2.  The Boston administrator generates a synchronization packet for User1 (Packet1) and then generates one for User2 (Packet2).  While the packets are being created, an administrator modifies user account information.  This causes schema repository oplog content to be included in both of the user database packets.

 

Some time later, the Boston administrator generates another pair of user database synchronization packets for User1 (Packet3) and User2 (Packet4). Again, while the packets are being created, an administrator modifies user account information.  This causes schema repository oplog content to be included in both of the user database packets.

 

All four packets are sent to the Denver site.  At the Denver site, the administrator runs syncreplica –import and specifies the User1 database family.  Packet1 and Packet3 are both intended for the User1 family.  Import of Packet1 is successful and replays oplogs in User1 and the schema repository.  However, import of Packet3 fails, because it depends on schema repository database oplogs, contained in Packet2, which have not yet been replayed at the Denver replica.

 

Solution

 

To avoid this situation, packets created at the exporting site must be replayed in the same sequence at the importing site(s). We recommend that you use the msimportauto.bat script, included with this patch. 

 

The msimportauto.bat script scans the import directory for update packets and then attempts to import the packets to each family.  If any packets are successfully imported, the imported packets are deleted from the directory and the script attempts to import the next packet.  The script stops executing when all packets are replayed and the directory is empty.  If a series of import attempts results in no packets being deleted from the directory, the script stops executing and import fails.  For instructions on how to run the msimportauto.bat script, see Section 11.3.

 

11.3  Running msimportauto.bat

 

Use the msimportauto.bat script to import update packets in the correct order when a clan contains multiple user databases.  The script can also be used to perform syncreplica –export. 

 

Syntax

 

msimportauto [–debug level] [–MaxLoops num-loops [–TimeToWait seconds]]

            [–AndDoExport] { –clan clan-name clan-info }…

 

Options and Arguments

 

Operating Modes

 

This program operates in one of two modes:

 

1.       Synchronize now:   The program receives pending updates, sends pending updates (optionally, with AndDoExport), and then exits. Use this mode if you want to synchronize immediately or if you want to schedule the program's execution with an external scheduler package, such as the Windows Scheduled Tasks facility or the ClearCase scheduler.

 

2.       Loop and wait:  The program receives pending updates, sends pending updates (optionally, with AndDoExport), sleeps a specified number of seconds, then loops back and receives, sends, and sleeps again. Use this mode if you want the program to essentially act as its own scheduler.

 

–debug level

 

Set the debug level:

 

 

0    

 

1..9

 

10+

 

 

Apply packets to database; don't produce any debugging output

 

Show diagnostic information and apply packets to database (higher numbers show more granular output)

 

Show diagnostic information, don't apply packets to database

–MaxLoops num-loops

 

Specifies the number of times the script will perform a receive, send, and sleep cycle (one iteration) in “Loop and wait” mode.

 

TimeToWait seconds

 

Specifies the amount of time, in seconds, between iterations.  If –MaxLoops is specified, but –TimeToWait is not, the default is 30 seconds between iterations.

 

AndDoExport

 

Issue syncreplica –export commands for the input databases (includes export as part of the receive, send, and sleep cycle).

 

clan

clan-name

 

Specifies the clans to synchronize.  Multiple clans may be specified in one command, but the –clan switch must be repeated.

 

clan-info

 

Specify clan-info in the following format (no spaces):

 

admin_username,admin_password;storage_class | directory;

family_1,my_site,other_site_1[,other_site_2,]...[,other_site_n][;family_2,my_site,other_site_1...]...

[;family_n,my_site,other_site_1[,other_site_2,]...[,other_site_n]]

 

Where my_site is the local site that will be imported into and exported from.  other_site_# specifies the other sites in the clan to be exported to and imported from.

 

Examples

 

Note:  All of the following commands must be entered on one line.

 

·         In this example, two clans, TEST and TEST1 are synchronized.  TEST contains two user database families (te and te2) and TEST1 contains one (d2).  Both clans and use directories to store packets.

msimportauto -debug 1 -clan TEST admin,"";C:\testdir\test;te,siteb,sitea;te2,siteb,sitea -clan TEST1 admin,"";c:\testdir\test;d2,sitea,siteb

 

·         In this example, three clans (TESTCLAN, TESTCLAN2, and TESTCLAN3) are synchronized.  Clan TESTCLAN consists of two user database families, te and te2.  Clans TESTCLAN and TESTCLAN3 use the MultiSite synchronization server, while TESTCLAN2 uses the directory c:\TESTCLAN2 to store packets.

msimportauto -debug 0 -MaxLoops 2 -TimeToWait 30 -clan TESTCLAN admin,""; cq_default;te,SITEA,SITEB,SITEC;te2,SITEA,SITEB –clan TESTCLAN2 admin,"";c:\TESTCLAN2;d2,SITEA,SITEB -clan TESTCLAN3 admin,"";cq_default;dt3,SITEA,SITEB -AndDoExport

 

11.4  Removing Replicas with rmreplica

 

The procedure for removing replicas with rmreplica in the Administrator’s Guide for ClearQuest MultiSite and in the ClearQuest MultiSite online help is incomplete.  To remove a replica from your clan, follow these instructions:

 

 

Removing a Functioning Replica from a Clan

 

To remove a replica that is still accessible and functioning, use the following steps. The example syntax shows how you would remove the BUGDB replica at site GOINGAWAY and decommission the site named GOINGAWAY for a clan that also includes sites REMAINING and WMASTER, the working master.  Note that all commands should be entered on one line.

 

  1. Stop all work on the replica to be removed.

 

  1. Transfer mastership of all objects to another replica.

    At site GOINGAWAY, run this command:

    multiutil chmaster -clan BUGCLAN -site GOINGAWAY -family BUGDB -user admin -password secret WMASTER -all –long

    If the chmaster command reports errors, address them and rerun the command until it succeeds.

 

  1. If you are decommissioning the whole site, you must also transfer mastership of users and groups in the site's schema repository.

    At site GOINGAWAY, run this command:

    multiutil chmaster -clan BUGCLAN -site GOINGAWAY -family MASTR -user admin -password secret WMASTER -all –long

    If the chmaster command reports errors, address them and rerun the command until it succeeds.

 

  1. Synchronize to the site receiving mastership.

    At site GOINGAWAY, run this command:

    multiutil syncreplica -export -clan BUGCLAN -site GOINGAWAY -family BUGDB -user admin
    -password secret -workdir c:\work -fship WMASTER


    At site WMASTER, run this command:

    multiutil syncreplica -import -clan BUGCLAN -site WMASTER -family BUGDB -user admin -password secret -receive

 

  1. Synchronize from the site receiving mastership to all remaining sites.

    At site WMASTER, run this command:

    multiutil syncreplica -export -clan BUGCLAN -site WMASTER -family BUGDB -user admin
    -password secret -workdir c:\work -fship REMAINING


    At site REMAINING, run this command:

    multiutil syncreplica -import -clan BUGCLAN -site REMAINING -family BUGDB -user admin -password secret -receive

 

  1. At the working master site, run the rmreplica command to remove the replica. Be sure to include the final argument, the replica you want removed.

    At site WMASTER, run this command:

    multiutil rmreplica -clan BUGCLAN -site WMASTER -family BUGDB -user admin -password secret GOINGAWAY

 

  1. If you are decommissioning the whole site, you must also run the rmreplica command on its schema repository.

    At site WMASTER, run this command:

    multiutil rmreplica -clan BUGCLAN -site WMASTER -family MASTR -user admin -password secret GOINGAWAY

 

  1. Synchronize from the working master site to all remaining sites.

    At site WMASTER, run this command:

    multiutil syncreplica -export -clan BUGCLAN -site WMASTER -family BUGDB -user admin
    -password secret -workdir c:\work -fship REMAINING


    At site REMAINING, run this command:

    multiutil syncreplica -import -clan BUGCLAN -site REMAINING -family BUGDB -user admin -password secret -receive

 

  1. Remove the vendor databases for the replica and schema repository that were removed.

 

Note:  Rational does not support the use of a database after it has been removed from a clan using rmreplica. Attempting to do so may result in data corruption.

 

 

Removing an Inoperable Replica from a Clan

 

If you have a replica whose databases have been damaged beyond repair or deleted without a sufficient backup, and you want to remove the replica from the clan, use the following steps. The example syntax shows how you would remove a BUGDB replica at site GONE and decommission the site GONE from a clan that also includes sites REMAINING and WMASTER, the working master.  Note that all commands should be entered on one line.

 

  1. Force the transfer of mastership for all objects from the unrecoverable replica to another replica.

    At site WMASTER, run this command:

    multiutil chmaster -clan BUGCLAN -site WMASTER -family BUGDB -user admin -password secret WMASTER -all -force GONE

 

  1. If you are decommissioning the site AND the schema repository is also inoperable, force the transfer of mastership for all users and groups.

    At site WMASTER, run this command:

    multiutil chmaster -clan BUGCLAN -site WMASTER -family MASTR -user admin -password secret WMASTER -all -force GONE

 

  1. At the working master site, run the rmreplica command to remove the unrecoverable replica. Be sure to include the final argument, the replica you want removed.

    At site WMASTER, run this command:

    multiutil rmreplica -clan BUGCLAN -site WMASTER -family BUGDB -user admin -password secret GONE

 

  1. If you are decommissioning the whole site, run the rmreplica command to remove its schema repository.

    At site WMASTER, run this command:

    multiutil rmreplica -clan BUGCLAN -site WMASTER -family MASTR -user admin -password secret GONE

 

  1. Synchronize from the working master to all remaining sites.

    At site WMASTER, run this command:

    multiutil syncreplica -export -clan BUGCLAN -site WMASTER -family BUGDB -user admin
    -password secret -workdir c:\work -fship REMAINING

    At site REMAINING, run this command:

    multiutil syncreplica -import -clan BUGCLAN -site REMAINING -family BUGDB -user admin -password secret -receive

 

  1. If they still exist, remove the vendor databases for the replica and schema repository that were removed.

 

 

Using MultiSite After Removing the Last Replica in a Clan

 

If you use the rmreplica –dbset command on the last replica in your clan (leaving only the database at the working master site), the database is no longer part of a MultiSite environment.  It is now a non-replicated database and cannot be used to create new replicas.  For more information, see the rmreplica reference page or Chapter 5 in the Administrator’s Guide for ClearQuest MultiSite.  To replicate this database again, you do not need to run the multiutil activate command.  You must use the Rational ClearQuest Maintenance Tool to change the database set name back to the form expected by multiutil; for example, CQMS.<clan_name>.<site_name>.

 


12.        Resolved Defects

The following defects are resolved in ClearQuest v2002.05.01 Patch 02:

Schema Modification

 

RAMBU00035064:

CQDesigner crashes when a row in the master_links table has master_dbid=0

 

RAMBU00035120:

Applying a package containing a query and upgrading a user database family creates one copy of the query for each replica (e.g. 3 queries if there are 3 replicas).

 

RAMBU00035225:

In ClearQuest MultiSite, a schema imported into a master schema repository replica is not replicated to other members of the family.

 

RAMBU00036110:

A MultiSite user database gets corrupted with invalid master_dbid.

 

RAMBU00036328:

Users can check out a schema in the working master replica and change the working master to another site.  This behavior causes the ClearQuest Designer to hang during checkin of the schema.

 

 

 

Problems Removing Replicas with rmreplica

 

See Section 11.4 for instructions on how to remove a replica from a clan.

 

RAMBU00022847:

ClearQuest cannot create a site-extended name if the keysite is removed.

 

RAMBU00036009:

The syncreplica –export command will not export oplogs previously generated by a removed replica.

 

RAMBU00035766:

The rmreplica command can fail with the message '”There is a reference to an object that does not exist”.

 

RAMBU00036586:

The rmreplica command does not work at the master schema repository replica.

 

 

Divergence Issues

 

RAMBU00035679: 

The use of clients and servers running different versions of ClearQuest MultiSite, and the use of ASCII control characters and multi-byte character strings may introduce divergence into a replica family.

 

RAMBU00036260:

In rare circumstances, v2002.05.01 Patch 01 misidentifies v2002.05.00 oplogs and packets as v2002.05.01 oplogs and packets.  This may occur in the following situation:

 

       The code page has printable characters in the range 128-255.  This most likely occurs in multi-byte code pages, such as Shift-JIS.  Printable characters in the range 128-255 appear in an oplog or packet before any XML character references.  The XML character references identify the oplog or packet as being from v2002.05.00.

 

If printable characters in the range 128-255 appear in an oplog or packet before any XML character references, one of the following things may occur:

 

·         If the data contains a pair of bytes that look like valid UTF-8, the XML parser corrupts the character.

 

·         If an XML character reference is found later in the data of an oplog, an error is generated and the database is not corrupted.

 

·         If an XML character reference is never encountered in an oplog, the oplog is assumed to be from v2002.05.01, and the database is corrupted.  If an XML character reference is found later in the packet, the oplog with no XML character references is still assumed to be from v2002.05.01.

 

RAMBU00036320:

During import of an oplog, control characters that were converted to Unicode may be mistaken for other characters that were converted to the same value.

 

RAMBU00036376:

The ClearQuest client allows the user to enter characters not supported by the DBMS, which get corrupted when being stored in the database.  This may cause divergence in a replicated database.  If different code pages are being used in a clan, only characters common to all code pages should be allowed in the database.

 

 

 

Performance Issues

 

RAMBU00035213: 

When a database contains a large number of users creating user objects can take up to five minutes.

 

RAMBU00035415:

During a user database upgrade, the ClearQuest Designer may hang and your database may be locked if you are using SQL Server 2000.

 

RAMBU00035644:

When using SQL Server, there is a long delay when you try to display the next defect in a query result set.

 

RAMBU00036109:

Some administrator operations (for example, creating a new user) create a lock in the database that isn’t released until the administrator completes the operation.  This can prevent other users from logging into ClearQuest.

 

RAMBU00036085:

Opening the User Administration tool from the ClearQuest Designer can take more than three minutes.

 

Related Issue:

 

RAMBU00045782:

The version number list in the ClearQuest Designer User Database Upgrade wizard keeps growing when the back and next buttons are clicked. Selecting any of the version numbers from the list upgrades the user database to the correct version. The problem is limited to display only and has no impact on the user database upgrade process.

 

Other Issues

RAMBU00022875: 

In the ClearQuest Web client, trend charts display states twice; that is, they draw two lines for each state specified.

 

RAMBU00035350: 

Use of ASCII control characters that are not legal XML characters can cause syncreplica –export to fail.

 

RAMBU00035415:

In replicas with multiple user databases, import of update packets may fail if user database update packets contain schema repository oplogs.  For more information, see Section 11.2.

 

RAMBU00035802: 

In v2002.05.01 and earlier, ClearQuest populates choice lists for fields incorrectly if all of the following things are true:

  • The database is replicated.
  • The field is a reference to a stateless record type.
  • There are more than 100 records of that stateless record type.

 

RAMBU00035823: 

Record ID does not appear in error message when syncreplica or mkreplica fails with the message, “Fatal error from XML_parse(): INVALID_TOKEN.”

 

 


13.        Known Problems in Rational ClearQuest v2002.05.01 Patch 02

The following are known problems in ClearQuest MultiSite v2002.05.01 Patch 02:

RAMBU00017072:

After importing an update packet that contains user admin changes for the user database or schema repository, no message is displayed to let the user know that a database upgrade is required.  If the user database is not upgraded at the importing site, the database will be out of sync with the schema repository. 

 

Workaround:  You must upgrade your user databases after importing an update packet that contains user admin changes in order to keep the databases in sync with the schema repository.

 

RAMBU00020803:

 

Deleting a child record mastered at your site removes the link from the parent record, even if the parent record isn’t mastered at your site. This is erroneous ClearQuest behavior. This seems to be a problem only if the parent is not mastered at that site where you are trying to delete the child record. If the parent is mastered at the site, then the correct error message is generated which asks the user to remove the link from the parent record before deleting the child record. 

 

RAMBU00036613:

 

The restorereplica command fails if you try to restore a replica that is dependent on restoration packets from a removed replica. 

 

Workaround:  To use restorereplica in this situation you must do one of the following:

 

·         Specify only the active replicas the first time you run the restorereplica command.  Run the lsreplica command to display a list of active replicas.

 

·         Run the initial restorereplica command (specifying all active and deactivated replicas), wait for responses from all of the active replicas (run the lsreplica command to display the active replicas along with the status of their response), and then run the restorereplica –completed command to force completion of the restore operation.

 

RAMBU00036659:

The string data type used by external Perl scripts can handle only single-byte characters.  Perl script and hook developers must remember that Perl hooks are not appropriate for multi-byte characters. 

 

Workaround:  VBScript may be used as an alternative.

 

RAMBU00036611:

 

 

Changing mastership of a package query results in duplication of the query when the package is upgraded.

 

Related defects:  RAMBU00036370, RAMBU00036758

 

RAMBU00036844:

After removing a replica, you cannot recreate the replica using the same name. 

 

Workaround:  You must create a new site with a different name to use in its place.

 

RAMBU00037160:

The mkreplica –import command allows you to create a replica even if the exporter is using a different code page than the server where the export was run.  Future attempts at synchronization will fail because syncreplica –import blocks packets containing data from code pages other than the importer code page.

 

Workaround:  Make sure your replicas are running the same data code page.  For more information on the guidelines and restrictions to follow when running this patch, see Section 5.

 

RAMBU00037164:

The restorereplica command expects only one packet from each site in the clan. If the –limit option is used with restorereplica, and all the requested data can't fit within the specified size limit, the site being restored can be unlocked prematurely.  The –limit option should not be used when generating packets for a site under restoration.

 

RAMBU00045796:

When using syncreplica –export –out, you cannot specify the root directory of a drive as a location for an output packet file.

 

RAMBU00045799:

The filenames of attachments submitted from a Web browser must contain only characters from the database code page.   

 

Note:  For more information about divergence protection on the Web, see Section 9.

 

RAMBU00037271:

ClearQuest does not prevent users from entering characters outside of the data code page in the following:

 

·         user names and data

 

·         group names and data

 

·         queries

 

·         dynamic lists

                                                                                                                                                                                                   

 


14.        Resources for Rational ClearQuest

Rational Web site

Please visit the Rational Web site for the latest Release Notes, patches and information:
http://www.rational.com/

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:
http://www.rational.com/support/usergroups/index.jsp

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

Sample Hooks Database

The ClearQuest Sample Hooks Repository provides a place for users to trade hook scripts. The Repository is located at:
http://clearquest.rational.com/

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


15.        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 at 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://www.rational.com/sitewide/support/technotes/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, Middle East, Africa

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

© 2002 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.