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.
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
13. Known
Problems in Rational ClearQuest v2002.05.01 Patch 02
14. Resources
for Rational ClearQuest
15. Contacting
Rational Technical Support
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
·
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.
·
Create all new
replicas from the master site.
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.
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:
|
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 |
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.
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.
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 |
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
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.
Previous
versions of ClearQuest clients, including UNIX
clients, may interoperate with this
patch in the following ways:
The following sections include information about ClearQuest MultiSite enhancements included in v2002.05.01 Patch 02.
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
|
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 |
|
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.
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.
In
certain circumstances, successful import of user database update packets may
depend on information contained in other user database packets. If your schema repository is associated with
multiple user database families, import may fail if the packets are not
replayed in the order they were generated.
A particular clan,
with sites in Boston and Denver has two user databases, User1 and User2. The Boston administrator generates a
synchronization packet for User1 (Packet1) and then generates one for User2
(Packet2). While the packets are
being created, an administrator modifies user account information. This causes schema repository oplog content
to be included in both of the user database packets.
Some time later,
the Boston administrator generates another pair of user database
synchronization packets for User1 (Packet3) and User2 (Packet4).
Again, while the packets are being created, an administrator modifies user
account information. This causes schema
repository oplog content to be included in both of the user database packets.
All four packets
are sent to the Denver site. At
the Denver site, the administrator runs syncreplica –import and
specifies the User1 database family.
Packet1 and Packet3 are both intended for the User1 family. Import of Packet1 is successful and replays
oplogs in User1 and the schema repository. However, import of Packet3 fails, because it depends on schema
repository database oplogs, contained in Packet2, which have not yet been
replayed at the Denver replica.
To avoid this situation,
packets created at the exporting site must be replayed in the same sequence at
the importing 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.
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.
msimportauto [–debug level] [–MaxLoops
num-loops [–TimeToWait seconds]]
[–AndDoExport]
{ –clan clan-name clan-info }…
|
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. |
|
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
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:
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.
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.
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.
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>.
The following defects are resolved in ClearQuest v2002.05.01 Patch 02:
|
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. |
|
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. |
|
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. |
|
|
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:
|
|
RAMBU00035823: |
Record
ID does not appear in error message when syncreplica or mkreplica fails with
the message, “Fatal error from XML_parse(): INVALID_TOKEN.” |
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 |
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.
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 |
|
|
Europe, Middle East, Africa |
PHONE: +31 20 454-6200 FAX:+31 20 454-6201 |
|
|
Asia Pacific |
+61-2-9419-0111 |
© 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.