Supporting a mixed local character set or a UTF-8 multilingual database

This topic provides guidelines for supporting a mixed local character set deployment or a UTF-8 (8-bit Unicode Transformation Format) multilingual database.
If you are working in an environment in which different computers with different local character sets connect to the same Rational® ClearQuest® database set, or you have selected the ClearQuest UTF-8 data code page (65001) for your database set, then you must consider the following character representation issues:

In versions of Rational ClearQuest earlier than 7.0, write operations were not allowed unless the local character set matched the ClearQuest data code page. If the settings did not match, only read-only operations were allowed. Read-only mode was necessary because the ClearQuest applications used the local character set of the client or Web server to write data to the database instead of the ClearQuest data code page for the database set.

Beginning in version 7.0, Rational ClearQuest software processes data in Unicode, and its applications use the ClearQuest data code page to write to its databases. These applications can connect to the ClearQuest database in read/write mode even when the local character set does not match the ClearQuest data code page.

Beginning in Rational ClearQuest version 7.1.1, you can select a UTF-8 ClearQuest data code page for Oracle and DB2 database sets. A UTF-8 data code page allows multilingual character storage in the user database. When you select UTF-8 as the data code page, you are working in a mixed local character set deployment unless the local code page of the operating system is also UTF-8. The latter is not an option on Windows systems.

This new functionality allows great flexibility in a ClearQuest environment that includes computers with different local character sets. However, scripts and hooks written for these environments must handle ClearQuest character data that might not be included in the local character set. Those scripts and hooks must be coded to support Unicode to take full advantage of this capability in these environments.

The Designer includes a new setting: Unicode Aware. Hooks written for version 7.0 can specify whether characters in strings returned from ClearQuest API calls must be in the local character set only (RETURN_STRING_LOCAL) or can be any Unicode character (RETURN_STRING_UNICODE). Also, new API functions are available to control the return string mode. In RETURN_STRING_LOCAL mode, an API call returns an exception if the return string includes characters that cannot be represented in the local character set. In RETURN_STRING_UNICODE, an API call returns all characters without error.

To ensure that hooks and scripts handle all data in a mixed local character set or UTF-8 deployment, you must set the mode to RETURN_STRING_UNICODE and properly handle the Unicode characters that might be returned. Setting the return string mode to RETURN_STRING_UNICODE is not sufficient; you must verify that your code can handle Unicode characters correctly. The guidelines listed below are helpful, but ultimately, you must use the appropriate Unicode programming techniques for the scripting language.

If you are upgrading to version 7.0, these changes have no impact on an existing schema if all local character sets in the environment match the ClearQuest date code page, as was common in earlier versions. The default mode is RETURN_STRING_LOCAL, which allows hooks and scripts to continue to function.

If you are deploying version 7.0 into an environment in which local character sets do not match the ClearQuest data code page, you must ensure that your scripts can process Unicode character data for ClearQuest software, set the return mode for scripts to RETURN_STRING_UNICODE, and upgrade packages to version 7.0. For a list of the ClearQuest packages that support Unicode, see Table 1 . Scripts that do not handle Unicode can run, but an error is returned if the system attempts to return to the script any character data that is not included in the local character set. These scripts continue to work as long as the data that they process is restricted to the local character set of the client or Web server.

Table 1. Package return string mode
Package Return string mode
AMWorkActivitySchedule RETURN_STRING_UNICODE
ATStateTypes RETURN_STRING_UNICODE
Attachments RETURN_STRING_UNICODE
AuditTrail RETURN_STRING_UNICODE
BTStateTypes RETURN_STRING_UNICODE
BuildTracking RETURN_STRING_UNICODE
CQTM RETURN_STRING_UNICODE
Customer RETURN_STRING_UNICODE
DeploymentTracking RETURN_STRING_UNICODE
DTStateTypes RETURN_STRING_UNICODE
EMail RETURN_STRING_UNICODE
EnhancementRequest RETURN_STRING_UNICODE
eSignature RETURN_STRING_UNICODE
History RETURN_STRING_UNICODE
Notes RETURN_STRING_UNICODE
Project RETURN_STRING_UNICODE
Resolution RETURN_STRING_UNICODE
TPM RETURN_STRING_UNICODE
When developing an application that must handle mixed character set deployments, you must address several considerations.

If the local character sets of all clients connected to a database set or clan match the data code page, you do not need to consider these issues. For more information about character representations and code page settings, see the Administering Rational ClearQuest online help.


Feedback