TEAMCONNECTION FREQUENTLY ASKED QUESTIONS:
NATIONAL LANGUAGE SUPPORT (NLS)
AND DOUBLE-BYTE CHARACTER SETS (DBCS)

Document Number TR 29.2266

Angel Rivera, Keith Purcell

CMVC/TeamConnection Development
IBM Software Solutions
Research Triangle Park, North Carolina
Copyright (C) 1997 IBM Corp.
All rights reserved.

ii TeamConnection and NLS/DBCS topics

ABSTRACT

This technical report describes how to use TeamConnection Version
2 in situations that require National Language Support (NLS) and
Double-Byte Character Sets (DBCS). Several important related
issues are described, such as the need for using the same code
page among the clients and the server, and how to setup an AIX
workstation to handle different locales.

ITIRC KEYWORDS

o TeamConnection

o NLS

o DBCS

o SBCS

ABSTRACT iii

iv TeamConnection and NLS/DBCS topics

ABOUT THE AUTHORS

ANGEL RIVERA

Mr. Rivera is an Advisory Software Engineer working with the
TeamConnection and CMVC development teams. He joined IBM in 1989
and since then has worked in the development and support of
library systems.

Mr. Rivera has an M.S. in Electrical Engineering from The Univer-
sity of Texas at Austin, and a B.S. in Electronic Systems Engi-
neering from the Instituto Tecnologico y de Estudios Superiores
de Monterrey, Mexico.

KEITH PURCELL

Mr. Purcell is an Advisory Software Engineer who has worked on
several support and development teams, including TeamConnection.
He joined IBM in 1979 and has worked with over 10 programming
languages in more than 8 operating system environments in pro-
gramming and support roles.

Mr. Purcell has an A.S. in Mathematics Computer Science from
Dutchess Community College in Poughkeepsie, N.Y.

ABOUT THE AUTHORS v

vi TeamConnection and NLS/DBCS topics

CONTENTS

ABSTRACT . . . . . . . . . . . . . . . . . . . . . . . . . III
ITIRC KEYWORDS . . . . . . . . . . . . . . . . . . . . . iii

ABOUT THE AUTHORS . . . . . . . . . . . . . . . . . . . . . . V
Angel Rivera . . . . . . . . . . . . . . . . . . . . . . . v
Keith Purcell . . . . . . . . . . . . . . . . . . . . . . . v

FIGURES . . . . . . . . . . . . . . . . . . . . . . . . . VIII

INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 1
Bibliography . . . . . . . . . . . . . . . . . . . . . . . 1
Bibliography for TeamConnection . . . . . . . . . . . . . 1
Bibliography for NLS and DBCS . . . . . . . . . . . . . . 2

OVERALL VIEW OF NLS AND DBCS SUPPORT PROVIDED BY
TEAMCONNECTION . . . . . . . . . . . . . . . . . . . . . . 3
Supported locales (languages and code pages) . . . . . . . 5
Supported Single-Byte Character Set (SBCS) locales . . . . 5
Supported Double-Byte Character Set (DBCS) locales . . . . 6
Supported platforms by TeamConnection . . . . . . . . . . . 8
Locales supported for the ObjectStore database . . . . . . 9

CHARACTERISTICS AND LIMITATIONS OF THE SUPPORT FOR NLS AND
DBCS . . . . . . . . . . . . . . . . . . . . . . . . . . 11
There is no conversion of code points when exchanging data 11
There is no impact if using English characters . . . . . 11
There is impact if using non-English characters . . . . 12
To maximize compatibility, use same/similar code page . 14
Once a family is created, do not change the code page . 14
Using UNICODE in the future to solve incompatibilities . 14
Exceptions to the handling of characters in TeamConnection 14
The &splitvbar. split vertical bar character could be
changed . . . . . . . . . . . . . . . . . . . . . . . . 15
Keyword expansion . . . . . . . . . . . . . . . . . . . 15
CR (carriage return) and LF (line feed) . . . . . . . . 15
All clients in the same host must use the same language
(Intel only) . . . . . . . . . . . . . . . . . . . . . . 16
Untraslated strings that are visible to the users . . . . 17
DBCS Limitations . . . . . . . . . . . . . . . . . . . . 17

INSTALLATION, ADMINISTRATION AND RUNTIME ISSUES . . . . . . 19
Installation issues related to NLS and DBCS . . . . . . . 19
Using a similar directory structure across all the
platforms . . . . . . . . . . . . . . . . . . . . . . . 19
Installation issues for UNIX . . . . . . . . . . . . . . 21
Installation issues with OS/2 and Windows . . . . . . . 21
Family administration issues . . . . . . . . . . . . . . 22
A family should use the same language all the time . . . 22
Client runtime issues . . . . . . . . . . . . . . . . . . 23

Contents vii

A client should use the same language all the time . . . 23

MISCELLANEOUS TOPICS THAT ARE SPECIFIC TO OPERATING SYSTEMS 27
Problem resolution . . . . . . . . . . . . . . . . . . . 27
Potential problems if the language locale is not set
properly . . . . . . . . . . . . . . . . . . . . . . . . 27
When using LANG=C in AIX, the message catalogs are
ignored! . . . . . . . . . . . . . . . . . . . . . . . . 27
Using misc/tcmsgcat to verify the NLS message catalog
settings . . . . . . . . . . . . . . . . . . . . . . . . 28
Using misc/showmsg to display a given message from the
catalog . . . . . . . . . . . . . . . . . . . . . . . . 29
Problems when the UNIX teamcgui window does not show up 29
Topics related to the message catalog used by
TeamConnection . . . . . . . . . . . . . . . . . . . . . 30
Using the "teamc report" command to test the NLS settings 30
How to know when TeamConnection is not using the message
catalog . . . . . . . . . . . . . . . . . . . . . . . . 31
Setting and verify the current locale setting in UNIX . . 31
How to enter SBCS extended characters using an English
keyboard . . . . . . . . . . . . . . . . . . . . . . . . 32
How to specify NLS settings for AIX GUI on aixterm/dtterm
windows . . . . . . . . . . . . . . . . . . . . . . . . . 33
Using aixterm . . . . . . . . . . . . . . . . . . . . . 33
Using dtterm . . . . . . . . . . . . . . . . . . . . . . 34
Creating a Teamcgui resource file for AIX . . . . . . . . 34
Using iconv to convert files to other code pages . . . . 35
How to install additional locales for AIX . . . . . . . . 35
How to change the keyboard for an AIX host . . . . . . . 36
How to install a non-English PC keyboard to an X-station 37
How to specify a different keyboard mapping . . . . . . 38

COPYRIGHTS, TRADEMARKS AND SERVICE MARKS . . . . . . . . . 39

FIGURES

1. How TeamConnection handles the locale environment
variables . . . . . . . . . . . . . . . . . . . . . . . 3
2. SBCS locales supported by TeamConnection . . . . . . . . 6
3. SBCS locales supported by TeamConnection . . . . . . . . 7
4. Platform support for TeamConnection components . . . . . 8
5. Graphical representation of code point 100 in several
code pages . . . . . . . . . . . . . . . . . . . . . . 11
6. Graphical representation of code point 100 in several
code pages . . . . . . . . . . . . . . . . . . . . . . 13
7. Sample output of "tcmsgcat.aix" . . . . . . . . . . . 28
8. Sample output of "showmsg" . . . . . . . . . . . . . . 29

viii TeamConnection and NLS/DBCS topics

9. Sample output of "teamc report -testServer" . . . . . 30
10. Sample output of "teamc report -testClient" . . . . . 31

Figures ix

x TeamConnection and NLS/DBCS topics

INTRODUCTION

This technical report describes how to use TeamConnection Version
2 in situations that require National Language Support (NLS) and
Double-Byte Character Sets (DBCS).

The topics in this technical report are:

o The overview of the NLS and DBCS support provided by
TeamConnection Version 2, such as usage of locale XPG/4 I18N
programming model, supported locales and platforms.

o The main characteristics and limitations related to NLS/DBCS,
such as the interoperability between clients and server, and
special cases for the manipulation of data by TeamConnection.

o The main issues related to installation, administration and
runtime, such as directory structure of the installed code,
and you should not change the code page of an existing
TeamConnection family.

o Miscellaneous topics, such as how to install locales in AIX.

NOTE: In OS/2 and Windows, the locale support is not pro-
vided by the operating system and it is provided by
TeamConnection during installation.

BIBLIOGRAPHY

Bibliography for TeamConnection
_______________________________

For more information on how to use TeamConnection, you can
consult the following manuals and publications:

SC34-4551 TeamConnection, Administrator's Guide
SC34-4552 Getting Started with the TeamConnection Clients
SC34-4499 TeamConnection, User's Guide
SC34-4501 TeamConnection, Commands Reference
SC34-4500 TeamConnection, Quick Commands Reference

Introduction 1

Bibliography for NLS and DBCS
_____________________________

o GG24-3850, AIX Version 3.2 for RISC System/6000, National
Language Support.

o SC23-2431, Internationalization of AIX Software, A Program-
mer's Guide

o SE09-8001-02, National Language Design Guide Volume 1

This manual contains very good information on how to enable
an application for NLS.

o SE09-8002-02, National Language Design Guide Volume 2.

This manual provides information on the IBM language codes
(consult the "Language codes" chapter).

2 TeamConnection and NLS/DBCS topics

OVERALL VIEW OF NLS AND DBCS SUPPORT PROVIDED BY TEAMCONNECTION

.LANGUAGE AND CULTURE SENSITIVE INFORMATION IN TEAMCONNECTION
_____________________________________________________________

TeamConnection supports the I18N (Internationalization) locale
model proposed by XPG/4 (X/Open Portability Guide, issue 4) in
which the language and culture sensitive information is not hard
coded in the executables; instead, they are provided as system
resources by means of a "locale" that the user can specify at
run-time.

One of the components of a locale is the code page in which the
characters will be handled. For example, in AIX, the default
locale is "en_US" which is for English in the USA and the associ-
ated code page is ISO8859-1, which is different than the default
one used for English in OS/2 (code page IBM-850) but similar to
the one used for English in Windows (code page MS-1252 Latin 1).

The locale model for XPG/4 establishes several environment vari-
ables that can be used for controlling the culture sensitive
information. The table Figure 1 describes these environment var-
iables, their function and how TeamConnection deals with them.

Overall view of NLS and DBCS suTeamConnection b3

4 TeamConnection and NLS/DBCS topics

NOTES:

1. TeamConnection itself does not perform any sorting of data,
instead, the sorting is performed by the database. Because
only the English version of the database is provided, by
default the English character collation rules are used.
However, there is an exception: the Japanese locale is pro-
vided for the database.

2. The date and time in TeamConnection is represented as
follows:

YYYY/mm/dd hh:mm:ss
** -> seconds
** ----> minutes
** -------> hours

** -> day
** ----> month
**** -------> year

Because 4 digits are used for the year, TeamConnection is
compliant with the 2000 Year specifications.

SUPPORTED LOCALES (LANGUAGES AND CODE PAGES)

TeamConnection Version 2 provides support for the following
locales (which include the translated message catalogs):

o Single-Byte Character Set (SBCS) locales:

See Figure 2.

o Double-Byte Character Set (DBCS) locales:

See Figure 3 on page 6.

Supported Single-Byte Character Set (SBCS) locales
__________________________________________________

Each row in the following table represents what code pages and
locales are compatible accross the different platforms. For
example, the locale "En_US" is different than the locale "en_US"
and therefore each locale is explicitly described in a separate
entry.

Overall view of NLS and DBCS suTeamConnection b5

+---------------------------------------------------------------+
| Figure 2. SBCS locales supported by TeamConnection |
+------------+------------+------------+------------+-----------+
| LANGUAGE | LOCALE | CODE PAGE | CODE PAGE | CODE PAGE |
| AND | | OS/2 | WINDOWS | AIX 4 |
| COUNTRY | | | NT/95 | |
+------------+------------+------------+------------+-----------+
| English, | En_US | IBM-437, | DOS: | IBM-850 |
| USA (enu) | | IBM-850 | MS-437, | |
| | | | MS-850 | |
| | | | (note 1) | |
+------------+------------+------------+------------+-----------+
| English, | en_US | n/a | GUI: | ISO8859-1 |
| USA (enu) | | | MS-1252 | |
| | | | (note 1) | |
+------------+------------+------------+------------+-----------+
| Portuguese,| Pt_PT | 850 | MS-850 | IBM-850 |
| Portugal | | | (note 1) | |
| (ptb) | | | | |
+------------+------------+------------+------------+-----------+
| Portuguese,| pt_BR | n/a | GUI: | ISO8859-1 |
| Brazil | | | MS-1252 | |
| (ptb) | | | (note 1) | |
+------------+------------+------------+------------+-----------+

NOTES:

1. When using directly the TeamConnection line commands from a
DOS Command Prompt in Windows, the DOS code pages are used
(such as MS-850).

In contrast, when using the TeamConnection GUI the MS code
pages are used (such as MS-1252).

It is important to emphasize that the locales "Pt_PT" and "pt_BR"
are different. If you use a TeamConnection family in AIX with
the ISO locale pt_BR (code page ISO8859-1), then you will see
"code page incompatibility" problems (some characters will NOT be
shown or will not look OK) if you use a TeamConnection client in
OS/2 with the Pt_PT locale (code page IBM-850).

Supported Double-Byte Character Set (DBCS) locales
__________________________________________________

Each row in the following table represents what code pages and
locales are compatible accross the different platforms. For
example, the locale "Ja_JP" is different than the locale "ja_JP"
and therefore each locale is explicitly described in a separate
entry.

6 TeamConnection and NLS/DBCS topics

+---------------------------------------------------------------+
| Figure 3. SBCS locales supported by TeamConnection |
+------------+------------+------------+------------+-----------+
| LANGUAGE | LOCALE | CODE PAGE | CODE PAGE | CODE PAGE |
| AND | | OS/2 | WINDOWS | AIX 4 |
| COUNTRY | | | NT/95 | |
+------------+------------+------------+------------+-----------+
| Japanese, | Ja_JP | IBM-932 | MS-932 = | IBM-932 |
| Japan | | (note 1) | IBM-943 | |
| (jpn) | | | | |
+------------+------------+------------+------------+-----------+
| Japanese, | ja_JP | n/a | n/a | IBM-eucJP |
| Japan | | | | |
| (jpn) | | | | |
+------------+------------+------------+------------+-----------+
| Korean, | ko_KR | IBM-949 | MS-949 | IBM-eucKR |
| Korea | | | (UHC) = | |
| (kor) | | | IBM-1363 | |
| | | | (note 2) | |
+------------+------------+------------+------------+-----------+
| Simplified | zh_CN | IBM-1381 | MS-936 | IBM-eucCN |
| Chinese, | | | (GBK) = | |
| RPC (chs) | | | IBM-1386 | |
| | | | (note 3) | |
+------------+------------+------------+------------+-----------+
| Tradi- | Zh_TW | IBM-950 | MS-950 | BIG5 |
| tional | | (note 4) | (note 4) | (note 4) |
| Chinese, | | | | |
| Taiwan | | | | |
| (cht) | | | | |
+------------+------------+------------+------------+-----------+
| Tradi- | zh_TW | n/a | n/a | IBM-eucTW |
| tional | | | | = IBM-964 |
| Chinese, | | | | (note 5) |
| Taiwan | | | | |
| (cht) | | | | |
+------------+------------+------------+------------+-----------+

NOTES:

1. The Japanese IBM-932, IBM-942 and IBM-943 have very small
differences between them, but generally speaking, they are
compatible with each other.

2. The Korean code page for Windows NT/95 is called UHC (Unified
Hangeul Code).

The IBM-1363 code page extends IBM-949 by adding missing
Hangeul characters with no change of assignments in code
points for IBM-949.

3. The code page for Simplified Chinese for Windows NT/95 is
called GBK (Guo Biao Kuo).

Overall view of NLS and DBCS suTeamConnection b7

The IBM-1386 code page extends IBM-1381 by adding missing
Unicode characters with no change of assignments in code
points for IBM-1381.

4. The PC code page for Traditional Chinese is called Big-5.

5. The EUC code page for Traditional Chinese (IBM-eucTW) for AIX
4.1 has been enhanced with respect to AIX 3.2, but it keeps
the same locale name (zh_TW). This means that if the user in
AIX 4.1 exploits the new characters in the enhanced locale
version, there could be compatibility problems when the user
uses the old locale version.

It is important to emphasize that the locales "Ja_JP" and
"ja_JP", and "Zh_TW" and "zh_TW" are different. If you use a
TeamConnection family in AIX with the EUC locale ja_JP (code page
IBM-eucJP), then you will see "code page incompatibility" prob-
lems (some characters will NOT be shown or will not look OK) if
you use a TeamConnection client in OS/2 with the Ja_JP locale
(code page IBM-932). The similar problem if you use incompatible
Traditional Chinese code pages.

SUPPORTED PLATFORMS BY TEAMCONNECTION

The supported platforms by TeamConnection are shown in Figure 4.

+---------------------------------------------------------------+
| Figure 4 (Page 1 of 2). Platform support for TeamConnection |
| components |
+--------------------------------+-------+-------+-------+------+
| PLATFORM | SERVER| CLIENT| BUILD | BUILD|
| | | | AGENT | PROCE|SOR
+--------------------------------+-------+-------+-------+------+
| OS/2 Warp (3.x) | YES | YES | YES | YES |
| | | | | |
+--------------------------------+-------+-------+-------+------+
| OS/2 Merlin (4.x) | YES | YES | YES | YES |
| | | | | |
+--------------------------------+-------+-------+-------+------+
| Windows 3.1 (16-bit) | no | GUI | no | no |
| | | | | |
+--------------------------------+-------+-------+-------+------+
| Windows 95 (32-bit) | no | YES | no | YES |
| | | | | |
+--------------------------------+-------+-------+-------+------+
| Windows NT 3.51 (32-bit) | YES | YES | YES | YES |
| | | | | |
+--------------------------------+-------+-------+-------+------+

8 TeamConnection and NLS/DBCS topics

+---------------------------------------------------------------+
| Figure 4 (Page 2 of 2). Platform support for TeamConnection |
| components |
+--------------------------------+-------+-------+-------+------+
| PLATFORM | SERVER| CLIENT| BUILD | BUILD|
| | | | AGENT | PROCE|SOR
+--------------------------------+-------+-------+-------+------+
| Windows NT 4.x (32-bit) | YES | YES | YES | YES |
| | | | | |
+--------------------------------+-------+-------+-------+------+
| MVS | no | no | no | YES |
| | | | | |
+--------------------------------+-------+-------+-------+------+
| AIX 4 | YES | YES | YES | YES |
| | | | | |
+--------------------------------+-------+-------+-------+------+
| HP-UX 10 | YES | YES | YES | YES |
| | | | | |
+--------------------------------+-------+-------+-------+------+

NOTES:

1. YES: for client means: both GUI and line commands

2. GUI: means ONLY the graphical user interface, no line com-
mands

3. no: means that there is no support

LOCALES SUPPORTED FOR THE OBJECTSTORE DATABASE

TeamConnection uses the ObjectStore object-oriented database man-
agement system (DBMS), which is enabled to handle DBCS, regard-
less of the locale.

The installation of TeamConnection also includes the installation
of ObjectStore and only the English locales for ObjectStore are
included in the installation images. This means that if there
are messages issued by ObjectStore, then these messages will be
in English, regardless of the locale of the client or server.

NOTE: In UNIX, the installation images for ObjectStore include
also the Japanese locales. If the ObjectStore server is running
with the Japanese locale, then the messages from ObjectStore will
be in Japanese.

Overall view of NLS and DBCS suTeamConnection b9

10 TeamConnection and NLS/DBCS topics

CHARACTERISTICS AND LIMITATIONS OF THE SUPPORT FOR NLS AND DBCS

THERE IS NO CONVERSION OF CODE POINTS WHEN EXCHANGING DATA

The TeamConnection clients and servers do not alter the code
points of the data. This means that the data is NOT converted
from one code page to another when entered by the user, when
stored in the database used by the family or when exchanged
between a client and the server.

The information about the code page in which the data was entered
is not stored with TeamConnection objects; furthermore, there is
no exchange of information between the client and the server to
indicate which code page is being used by each of them.

There is no impact if using English characters
______________________________________________

Because most code pages have the same code points for the first
128 characters, which includes all the characters used in the
English alphabet, then in practice there is no effect in using
different code pages between clients and servers, if using only
English characters.

As an example, the default multilingual code page for OS/2 is
IBM-850, for Windows is MS-1252 Latin 1, and for AIX Version 4 is
ISO8859-1; in these code pages the first 128 characters are the
same, and thus, there is no impact in code points the English
characters are used when entering remarks for a defect in the
OS/2 client, then stored in the AIX server and retrieved by the
Windows client.

For example, the code point value of 100 is the lower case letter
"d" which has the same graphic representation in most of the code
pages, as exemplified in Figure 5.

+---------------------------------------------------------------+
| Figure 5 (Page 1 of 2). Graphical representation of code |
| point 100 in several code pages |
+------------------+------------+------------+------------------+
| PLATFORM | LOCALE | CODE PAGE | REPRESENTATION |
| | | | |
+------------------+------------+------------+------------------+
| OS/2 | English | IBM-437 | lower case 'd' |
| | | | |
+------------------+------------+------------+------------------+

Characteristics and limitations of the support forDBCS a11

+---------------------------------------------------------------+
| Figure 5 (Page 2 of 2). Graphical representation of code |
| point 100 in several code pages |
+------------------+------------+------------+------------------+
| PLATFORM | LOCALE | CODE PAGE | REPRESENTATION |
| | | | |
+------------------+------------+------------+------------------+
| OS/2 | English | IBM-850 | lower case 'd' |
| | | | |
+------------------+------------+------------+------------------+
| Windows, DOS | English | MS-437 | lower case 'd' |
| mode | | | |
+------------------+------------+------------+------------------+
| Windows, DOS | English | MS-850 | lower case 'd' |
| mode | | | |
+------------------+------------+------------+------------------+
| Windows, Graph- | English | MS-1252 | lower case 'd' |
| ical | | | |
+------------------+------------+------------+------------------+
| AIX | En_US | IBM-850 | lower case 'd' |
| | | | |
+------------------+------------+------------+------------------+
| AIX | en_US | ISO8859-1 | lower case 'd' |
| | | | |
+------------------+------------+------------+------------------+
| OS/2 | Japanese | IBM-932 | lower case 'd' |
| | | | |
+------------------+------------+------------+------------------+
| Windows | Japanese | MS-932 | lower case 'd' |
| | | | |
+------------------+------------+------------+------------------+
| AIX | ja_JP | IBM-eucJP | lower case 'd' |
| | | | |
+------------------+------------+------------+------------------+

There is impact if using non-English characters
_______________________________________________

However, if the customer wants to use non-English characters,
which are characters with code points greater than 128 such as
accented characters, umlauts, double-byte characters, then the
code pages differ greatly in this respect.

For example, the character with code point value of 252 (which
can be entered by pressing ALT and typing 2, 5 and 2 from the
numeric keypad in most systems) has the following different
representations, as shown in Figure 6.

12 TeamConnection and NLS/DBCS topics

+---------------------------------------------------------------+
| Figure 6. Graphical representation of code point 100 in |
| several code pages |
+------------------+------------+------------+------------------+
| PLATFORM | LOCALE | CODE PAGE | REPRESENTATION |
| | | | |
+------------------+------------+------------+------------------+
| OS/2 | English | IBM-437 | superscript 'n' |
| | | | |
+------------------+------------+------------+------------------+
| OS/2 | English | IBM-850 | superscript '3' |
| | | | |
+------------------+------------+------------+------------------+
| Windows, DOS | English | MS-437 | superscript 'n' |
| mode | | | |
+------------------+------------+------------+------------------+
| Windows, DOS | English | MS-850 | superscript '3' |
| mode | | | |
+------------------+------------+------------+------------------+
| Windows, Graph- | English | MS-1252 | lower case 'u' |
| ical | | | with dieresis |
+------------------+------------+------------+------------------+
| AIX | En_US | IBM-850 | superscript '3' |
| | | | |
+------------------+------------+------------+------------------+
| AIX | en_US | ISO8859-1 | lower case 'u' |
| | | | with dieresis |
+------------------+------------+------------+------------------+
| OS/2 | Japanese | IBM-932 | First byte of |
| | | | DBCS character |
+------------------+------------+------------+------------------+
| Windows | Japanese | MS-932 | First byte of |
| | | | DBCS character |
+------------------+------------+------------+------------------+
| AIX | ja_JP | IBM-eucJP | First byte of |
| | | | DBCS character |
+------------------+------------+------------+------------------+

In the above case, a German customer using Windows in Graphical
Mode, with code page MS-1252 may enter a string that contains the
u with umlaut and store it in TeamConnection, but the same cus-
tomer when retrieving the data from OS/2 using IBM-850 code page,
the character in the string will be shown as the number 3 in
superscript.

Characteristics and limitations of the support forDBCS a13

To maximize compatibility, use same/similar code page
_____________________________________________________

As shown in "There is impact if using non-English characters" on
page 12, it is important that the customers who are using mul-
tiple platforms with TeamConnection, must understand the impli-
cations of using different code pages when dealing with
non-English characters.

If possible, the customer should use the same (or similar) code
page in the TeamConnection client and in the server.

Once a family is created, do not change the code page
_____________________________________________________

To avoid compatibility problems, if a family is created and used
with a given code page, then this code page should not be changed
later on.

For example, if a family is created with the Japanese IBM-932
code page in OS/2 and then migrated to the Japanese IBM-eucJP
code page in AIX, then there might be several DBCS characters
that are valid in the IBM-932 code page that will not be dis-
played properly when using the IBM-eucJP code page.

Using UNICODE in the future to solve incompatibilities
______________________________________________________

In the future, once the support for the UNICODE code page is
widespread and available in all the platforms supported by
TeamConnection, then the customer could choose to use the UNICODE
code page for the clients and the server, and in this way, avoid
the current incompatibility between different code pages.

Another alternative that we studied to solve to this incompat-
ibility problem between code pages was to add an extra field for
EVERY SINGLE piece of data that is handled by TeamConnection in
order to identify the code page that was used when the data was
originated; then, this would require that the TeamConnection
server should get the code page used by each client that is
requesting a service, and then do the necessary conversions when
exchanging the data. Because this alternative is very expensive
to implement and has a lot of ramifications, and because UNICODE
is the right way for the long term, we are not implementing this
alternative to tag each piece of data.

EXCEPTIONS TO THE HANDLING OF CHARACTERS IN TEAMCONNECTION

14 TeamConnection and NLS/DBCS topics

The &splitvbar. split vertical bar character could be changed
_____________________________________________________________

The &splitvbar. split vertical bar character is used to separate
the fields in the "teamc report -raw" command. Thus, if this
character is found in a field that is shown by this command, such
as in the abstract of a defect, then the character is changed to
"!" (exclamation point) by the TeamConnection client. Thus, the
server does not see these split vertical bar characters.

The reason for this change is to avoid confusion during the
parsing of the -raw output because the split vertical bar is used
to separate the fields. If in the output to be parsed there is a
split vertical bar character that is NOT intended to be a sepa-
rator of a field, then the parsing routine will not be able to
guess that this particular split vertical bar should not be con-
sidered as a field separator. In other words, ALL split vertical
separator bars are considered to be field separators, and thus,
any such characters in the abstract will not be parsed appropri-
ately.

For example, when opening a defect, if the abstract field is left
blank then the first 63 characters of the remarks field will be
placed in the abstract. The abstract is a field that is shown
with the "teamc report -raw" command, but the remarks field is
not shown with this command. Thus, if the first 63 characters of
the remarks have split vertical bar characters they will be left
untouched in the actual remarks, but they will be converted to
"!" in the abstract.

Keyword expansion
_________________

TeamConnection supports the expansion of certain keywords
embedded in the text during the extraction of text files. The
routines that handle the expansion are NLS and DBCS enabled.

The important characteristic to remember is that the expansion is
done by the TeamConnection family server and not by the client.

CR (carriage return) and LF (line feed)
_______________________________________

Although this is not an NLS issue, this is another topic that is
worth to include in this technical report, because some users may
think, incorrectly, that this could be caused by code conversion
processing done by TeamConnection.

The end of a line of text in OS/2 or in Windows is represented by
the character pair CR-LF (carriage return and line feed), whereas
in UNIX is represented simply by the character LF (line feed).

Characteristics and limitations of the support forDBCS a15

In TeamConnection, the model of what-you-see-is-what-you-get is
used. This means that if a user creates a file in
TeamConnection, regardless of the platform of the server, then
TeamConnection will NOT do any conversion of LF or CRLF on that
file. There are choices in the -extract action to allow for more
fine tuning of these on-the-fly-conversions. For example, an AIX
user may wish to extract with only LF a file that was stored ori-
ginally from OS/2 that has CRLF.

The following file will be the source file to be used in the rest
of the examples in this section:

This is line 1
This is line 2
This is line 3

If the source file is created from an OS/2 client and later on is
extracted into a UNIX client without CRLF conversion, then the
resulting file will have the CR character at the end of each line
and the file would look like:

This is line 1&caret.M
This is line 2&caret.M
This is line 3&caret.M

If the source file is created from a UNIX client and later on is
extracted into an OS/2 client without CRLF conversion, then the
resulting file will not have the CR character at the end of each
line and the file would look like:

This is line 1
This is line 2
This is line 3

ALL CLIENTS IN THE SAME HOST MUST USE THE SAME LANGUAGE (INTEL
ONLY)

For OS/2 and Windows NT clients, all the TeamConnection clients
that execute from one single host must use the same language if
they run at the same time.

This limitation is due to the inherent limitation of these plat-
forms in which ONLY ONE version of given DLL can be loaded at the
same time, and because these platforms are not fully compliant
with the XPG/4 model that allows usage of multiple locales. If
there are different versions of some DLLs for each language, and
if the English version of the DLL is loaded, the Japanese one
cannot be loaded at the same time. This precludes having clients
that have different languages to run at the same time.

16 TeamConnection and NLS/DBCS topics

UNTRASLATED STRINGS THAT ARE VISIBLE TO THE USERS

There are certain kinds of strings that are visible to the user
that are not translatable:

o command, action and flag names
o state names
o database table and view names
o database table column headings
o action name used in the audit log, the mail notifications,
and the authority and interest tables
o the type field in the config database table

DBCS LIMITATIONS

1. The administration tools for the TeamConnection Server expect
SBCS characters as the reply for Yes (y) and No (n).

2. The administration tools for the TeamConnection Server have
the following limitations for DBCS:

a. The *.ld files (authority, interest, cfgcomproc and
cfgrelproc) in the family account can accept DBCS charac-
ters in the first field for each entry. The maximum size
for this field is 15 bytes.

b. The config.ld file in the family account can accept DBCS
characters in the following fields (the positions are
defined from left to right):

o Field position 1 ("Field Type"): limit is 15 bytes

o Field position 2 ("Value"): limit is 15 bytes

o Field position 6 ("Description"): limit is 63 bytes

c. The chfield program can accept only SBCS characters in
the following fields:

o CMD attribute

o DB Column Name

d. The chfield program can accept DBCS characters in the
following fields:

o Field label: limit is 15 bytes

o Title label: limit is 15 bytes

o Type: must be a valid type defined in config.ld
(limit is 15 bytes).

Characteristics and limitations of the support forDBCS a17

3. The TeamConnection Commands Reference manual, in Appendix A,
"Querying the TeamConnection database", shows the datatype
and the size limit for the attributes of the TeamConnection
objects; however, the actual size limit for many of the char-
acter attributes is smaller than the specified limit. For
example, the field "login" in the "Users" table shows that
the limit is 31 bytes, but in reality only 15 characters
(SBCS or DBCS) can be stored in that field. The fields
affected are usually related to names, such as the User
login, the Component name, etc.

If you specify a string that has DBCS characters and that the
size of the string goes beyond the limit, then the following
error message will be displayed by the TeamConnection server:

0010-149 Your request cannot be completed.
The attribute flag argument xxx is not valid.

4. Warning on the use of 0x7C as a second byte in a DBCS char-
acter

The Ox7C character corresponds to the vertical bar ('|')
which in TeamConnection is interpreted as a field separator
when dealing with reports and with handling windows and
fields in the GUI.

You can use this value as the 2nd byte of a DBCS character,
however, when the data that contains this 2nd byte is handled
in a TeamConnection client that has an SBCS code page (and
not a DBCS code page), then, the output shown by the client
may be displaced, that is, the 0x7C value will be interpreted
as the field separator. Moreover, this situation will apply
for any string in the *.ld files and in the configurable
fields.

18 TeamConnection and NLS/DBCS topics

INSTALLATION, ADMINISTRATION AND RUNTIME ISSUES

INSTALLATION ISSUES RELATED TO NLS AND DBCS

The installation process for TeamConnection is similar in UNIX,
in OS/2 and Windows with respect to NLS. The similarities and
the differences are explained in the following sections.

After the installation process, the executable code and the lan-
guage related files will be installed in separate directories
that are system wide, that is, they are not exclusive to one
account.

When a TeamConnection family is created, several files are copied
into the directory for the TeamConnection family; several of
these files contain language sensitive information (such as the
config.ld file and the files in the chfField directory). The
family administrator can modify these files for the specific
family; these files are not shared with other families.

Using a similar directory structure across all the platforms
____________________________________________________________

Even though there are differences in the NLS facilities that are
available from the UNIX and the Intel (OS/2 and Windows) plat-
forms the installation of TeamConnection in these platforms
create a similar directory structure which top directory is shown
below (using the default directory):

AIX 4 /usr/teamc

HP-UX 10 /opt/teamc

OS/2 c:\teamc

WINDOWS 3.1 c:\ProgramF\TeamC

WINDOWS NT AND 95 c:\Program Files\TeamConnection

Installation, administration and runtime issues 19

Storing the language-independent files

The language-independent files for the TeamConnection code are
stored in similar directories, as shown in the following example.
The teamc server daemon (teamcd) is located in the subdirectory
"bin", from the TeamConnection top directory as shown below:

AIX 4 /usr/teamc/bin

HP-UX 10 /opt/teamc/bin

OS/2 c:\teamc\bin

WINDOWS 3.1 c:\ProgramF\TeamC\bin

WINDOWS NT AND 95 c:\Program Files\TeamConnection\bin

Storing the language-dependent files

In a similar way, the language-dependent files for the
TeamConnection code are stored in a similar subdirectory struc-
ture, which is the subdirectory "nls" as parent and then the
"msg" for messages and "cfg" for configuration items.

For example, the ISO US English message catalog will be stored as
shown below, using the default location:

AIX 4 /usr/teamc/nls/msg/en_US (which really is a
symbolic link to /usr/lib/nls/msg/en_US)

HP-UX 10 /opt/teamc/nls/msg/C (which really is a sym-
bolic link to /usr/lib/nls/msg/C)

OS/2 c:\teamc\nls\msg\en_US

WINDOWS 3.1 c:\ProgramF\TeamC\nls\msg\en_US

WINDOWS NT AND 95 c:\Program Files\TeamConnection\nls\msg\en_US

List of language-dependent files

The "nls" directory (see previous section for the complete path)
contains the following subdirectories and files:

nls/msg/<locale>/
* All message catalog files, such as teamcv2.cat
* All help files.
* All resource DLLs for the GUI that are specific to a language.

nls/doc/<locale>/

20 TeamConnection and NLS/DBCS topics

* All documentation: PostScript, HTML, online, etc.

nls/cfg/<locale>/
* All configuration files, such as config.ld, and files for
the configurable fields.
* The original teamc20.ini file

Installation issues for UNIX
____________________________

During the installation process for TeamConnection in UNIX, it is
necessary to select the appropriate language version to install.
The code is not bundled together with the language sensitive
information. That is, there is an individual installable package
just for the language sensitive information that could be
installed independently.

Because AIX 4 and HP-UX 10 operating systems already include the
explicit support for the XPG/4 I18N locale model, the
TeamConnection installation process will not install additional
files for this matter (as in OS/2 and Windows).

The message catalog that contains the language sensitive informa-
tion is located by the executable code by means of the combina-
tion of the NLSPATH and LANG environment variable. By default,
this variable is set to:

set NLSPATH=/usr/lib/nls/msg/%L/%N

Where:
%L is a variable that at runtime represents the value of the
LANG environment variable; it must be in uppercase.
%N is a variable that at runtime represents the name of the
message catalog to be used; it must be in uppercase.

Installation issues with OS/2 and Windows
_________________________________________

During the installation process for TeamConnection in OS/2 and
Windows, , it is necessary to select the appropriate language
version to install. The code and the language sensitive informa-
tion is bundled together in a package and it is installed appro-
priately. That is, there is not an individual package just for
the language sensitive information that can be installed inde-
pendently.

Because the OS/2 and Windows operating systems do not include at
this moment explicit support for the XPG/4 I18N locale model, the
TeamConnection installation process will install the necessary
support for this model if necessary.

Installation, administration and runtime issues 21

The message catalog that contains the language sensitive informa-
tion is located by the executable code by means of the NLSPATH
environment variable. By default, this variable is set to:

set NLSPATH=c:\teamc\nls\%N

Where:
c:\teamc represents the appropriate drive and top directory where
the TeamConnection code is installed in your system
nls is the directory that contains the NLS related files
%N is a variable that at runtime represents the name of the
message catalog to be used; it must be in uppercase.

FAMILY ADMINISTRATION ISSUES

A family should use the same language all the time
__________________________________________________

Although technically it could be possible for a family to be
created using the en_US locale and then change it later on to
another language, we consider that this process has the potential
to cause a lot of confusion with the users, specially for the
mapping of code points.

Therefore, this is treated as a limitation and if the customers
try it, it is at their own risk and we will not help them.
However, the customer may decide to delete the family, change the
language by reinstalling the code for Intel and specify the new
language, or to install the new language message catalogs for
UNIX and change the LANG variable, and then create a new family
to use the new setting.

This decision affects the arrangement of the subdirectories of a
family: there is no provision in neither UNIX or Intel to have
language dependent directories inside the family directory.

The following sections contain examples that will clarify this
point.

UNIX

o An AIX customer installed the TeamConnection server, using
the en_US locale. The config.ld file (which is language
dependent) resides in:

/usr/lib/nls/cfg/en_US/config.ld

22 TeamConnection and NLS/DBCS topics

o The "testfam" TeamConnection family is created, and the
config.ld file is copied from the system directory mentioned
above, to the top directory of the family:

/home/testfam/config.ld

Notice that there is no "/home/testfam/en_US/config.ld" path.

Intel

o An OS/2 customer installed the TeamConnection server, using
the en_US locale. The config.ld file (which is language
dependent) resides in:

c:\teamc\nls\cfg\en_US\config.ld

o The "testfam" TeamConnection family is created, and the
config.ld file is copied from the system directory mentioned
above into the top directory of the family:

c:\testfam\config.ld

Notice that there is no "c:\testfam\en_US\config.ld" path.

CLIENT RUNTIME ISSUES

A client should use the same language all the time
__________________________________________________

Although technically it could be possible for a TeamConnection
client to be installed with one language (such as the IBM-850
code page in OS/2 or the en_US locale in AIX) and then change the
language in the middle, we consider that this process has the
potential to cause a lot of confusion with the users, specially
for the mapping of code points with the teamc20.ini file, as
explained below.

In the UNIX platforms, thanks to the use of the LANG variable, it
would be possible to install additional message catalogs for
other languages and the user could setup the language to use by
setting the variable LANG. However, the teamc20.ini file for the
GUI will NOT be changed, and this file may contain characters
that were valid in the original setup but that cannot be dis-
played in the new setup.

Because the Intel platforms do not provide the LANG variable,
then it is not possible to have message catalogs for multiple
languages for TeamConnection. This means that if the customer

Installation, administration and runtime issues 23

decides to change the language then it is necessary to reinstall
the code specifying the new language.

The following sections contain examples that will clarify this
point.

UNIX

o A Japanese AIX customer installs the TeamConnection client
using the ja_JP and en_US message catalogs.

o The teamc20.ini file (which is language dependent) resides
in:

/usr/lib/nls/cfg/ja_JP/teamc20.ini
/usr/lib/nls/cfg/en_US/teamc20.ini

o The customer uses the Japanese GUI for the first time
(LANG=ja_JP), and the GUI detects that the following file
does not exist:

$HOME/teamc20.ini

o The customer uses the GUI and creates several entries written
in Japanese in the task list which are stored in the
teamc20.ini file.

The customer exists the GUI.

o The user invokes the GUI again, and the GUI detects that the
teamc20.ini file exists in $HOME and therefore the GUI uses
it, and does not try to overwrite it with the file in the
directory /usr/lib/nls/cfg/ja_JP.

o The customer decides then to switch the locale to en_US, by
setting LANG=en_US, exits and logs in again.

o The user brings up the English TeamConnection GUI and now the
task list shows entries that may not be legible because their
original code points were set with the ja_JP locale.

Intel

o A Japanese OS/2 customer installs the TeamConnection client
and specifies the ja_JP language only, because she cannot
install multiple languages. The code page is IBM-932.

The PATH and the NLSPATH variables point to the ja_JP direc-
tories.

24 TeamConnection and NLS/DBCS topics

o The teamc20.ini file (which is language dependent) resides
in:

c:\teamc\nls\cfg\ja_JP\teamc20.ini

o The customer uses the Japanese GUI for the first time
(LANG=ja_JP), and the GUI detects that the following file
does not exist:

c:\os2\teamc20.ini

o The GUI copies the original teamc20.ini file from the appro-
priate ja_JP directory ...

c:\teamc\nls\cfg\ja_JP\teamc20.ini

... into ...

c:\os2\teamc20.ini

o The customer uses the GUI and creates several entries written
in Japanese in the task list, and this list is stored in the
teamc20.ini file.

The customer exists the GUI.

o The user invokes the GUI again, and the GUI detects that the
teamc20.ini file exists in c:\os2 and therefore the GUI uses
it, and does not try to overwrite it with the file in the
directory c:\teamc\nls\cfg\ja_JP.

o The customer decides then to switch the locale to en_US, by
uninstalling the TeamConnection client and reinstalling it
again specifying now the language en_US, and reboots.

The PATH and the NLSPATH variables are updated and they do
not point to the non-existing ja_JP directories, but point to
the new en_US directories.

o If the customer keeps the same code page, IBM-932, then when
the user brings up the English TeamConnection GUI, the task
list shows entries that are legible because their original
code points were set with the IBM-932 code page.

o If the customer changes the code page, let's say to IBM-850,
then when the user brings up the English TeamConnection GUI
the task list shows entries that may not be legible because
their original code points were set with the IBM-932 code
page.

Installation, administration and runtime issues 25

26 TeamConnection and NLS/DBCS topics

MISCELLANEOUS TOPICS THAT ARE SPECIFIC TO OPERATING SYSTEMS

PROBLEM RESOLUTION

Potential problems if the language locale is not set properly
_____________________________________________________________

Potential problems if the language locale is not set properly:

Unexpected message catalogs would be picked up.

NOTE: Default hard coded messages are in English.

o GUI labels, titles, and messages could be unreadable.

o Data conversion errors could be resulted.

If any of the above listed presents the symptom of the problem,
verify the locale and reset appropriately.

When using LANG=C in AIX, the message catalogs are ignored!
___________________________________________________________

In the IBM red book "AIX 3.2 National Language Support",
GG24-3850, says in page 16: "when the default C locale is the
current locale, the hardcoded default message catalogs in the
executable code will be used instead of the translated message
file." The main point for confusion is that there is a directory
in /usr/lib/nls/msg/C which is totally ignored! Thus, the user
can place the message catalogs there, but they will never be
used! This means that if the TeamConnection Server is using the
LANG=C locale, then the output for "teamc report -testServer"
will always be that the message catalog is not available and
thus, the server will use the internal English messages which are
embedded during compilation and used as default.

Miscellaneous topics that are specific to operating systems 27

Using misc/tcmsgcat to verify the NLS message catalog settings
______________________________________________________________

The utility "misc/tcmsgcat.aix" provided in the CD-ROM for
TeamConnection can be used to verify that all the NLS variables
related to the message catalog for TeamConnection are properly
configured and that the message catalog itself can be opened;
furthermore, the first message in the message catalog is read,
and it contains the name of the language used with the strings in
the message catalog.

A sample output with the English en_US message catalog is shown
in Figure 7.

Actually, you can use the TeamConnection utility "showmsg" which
is a front end to the AIX utility "dspmsg"; for more information
see "Using misc/showmsg to display a given message from the
catalog" on page 29.

28 TeamConnection and NLS/DBCS topics

Using misc/showmsg to display a given message from the catalog
______________________________________________________________

The utility "misc/showmsg" provided in the CD-ROM for
TeamConnection can be used to display a particular message from
the TeamConnection message catalog.

This utility is actually more helpful for our development team,
because in order to display a given message we need to do the to
find out the actual number to use with the utility showmsg. The
utility uses dummy positional input variables which will be
replaced, if needed, when displaying the message.

If we want to display the message "0011-209" from the message
catalog, we need to identify which is the mnemonic and the index
for the message, which can be obtained from the file
src/inc/tcmsgdef.hpp which is generated during the construction
of the message catalog. For example, the search for "0011-209"
gives the following entry:

... "msgLicenseMonitorInvalidDateRange","0011-209",2530);
**** --> index
******** --> message number
********************************* --> mnemonic

Then, we use the index 2530 with the utility "showmsg" to verify
if indeed we obtain the text for the message 0011-209, as shown
in Figure 8.

+---------------------------------------------------------------+
| |
| message 2530 from message catalog: /usr/lib/nls/msg/en_U|/teamcv2.cat
| 0011-209 The date range from s1 to s2 |
| is not valid. The end date must be greater than|the begin date.
| |
+---------------------------------------------------------------+
Figure 8. Sample output of "showmsg"

Problems when the UNIX teamcgui window does not show up
_______________________________________________________

When using UNIX, if you start the GUI by using "teamcgui" or
"teamcgui &" (to send the process to the background), it takes
several seconds for the GUI to actually appear in your display.

However, if after several minutes of waiting and still you do not
see a window for the TeamConnection window, you can kill the
runaway process:

Miscellaneous topics that are specific to operating systems 29

ps -ef | grep teamcgui
Identify the process id for teamcgui
kill -15 processIdforTeamcgui

Then check the following:

o Ensure that the DISPLAY variable is properly set to your X
server.

o The teamc20.ini file might be corrupted. You can delete it
or rename it, and start again teamcgui.

TOPICS RELATED TO THE MESSAGE CATALOG USED BY TEAMCONNECTION

Using the "teamc report" command to test the NLS settings
_________________________________________________________

You can use the commands to verify if TeamConnection is accessing
the message catalog:

o For the server: "teamc report -testServer"

A sample output is shown in Figure 9.

+---------------------------------------------------------------+
| |
| Connect to Family Name: tcocto |
| Server TCP/IP Name: carcps22.raleigh.ib|.com
| Server IP Address: 9.67.238.38 |
| Server TCP/IP Port Number: 1300 |
| |
| Server Specific Information ----------------------------|-----
| Product Version: 2.0.4 |
| Operating System: AIX |
| Message catalog language: English |
| Server Mode: non-maintenance |
| Authentication Level: HOST_ONLY |
| |
+---------------------------------------------------------------+
Figure 9. Sample output of "teamc report -testServer"

o For the client: "teamc report -testClient"

A sample output is shown in Figure 10 on page 31.

30 TeamConnection and NLS/DBCS topics

+---------------------------------------------------------------+
| Product Version: 2.0.5 |
| Message catalog language: English |
| Environment variables: |
| Variable: Setting: |
| -------------------- ----------------------------------- |
| TC_USER rivera |
| TC_BECOME rivera |
| TC_FAMILY tcocto@carcps22@1300 |
| TC_RELEASE v205 |
| TC_TOP |
| TC_WORKAREA |
| TC_BUILDPOOL |
+---------------------------------------------------------------+
Figure 10. Sample output of "teamc report -testClient"

How to know when TeamConnection is not using the message catalog
________________________________________________________________

If the output of the commands "teamc report -testServer" or
"teamc report -testClient" produce an output line that is similar
to the following:

Message catalog language: English (Internal)

Then, this means that TeamConnection cannot find the message
catalog and is using the internal default English messages that
are embedded in the executables during compilation. The most
likely cause for this problem is an improper definition of the
NLSPATH environment variable.

SETTING AND VERIFY THE CURRENT LOCALE SETTING IN UNIX

o To set the language locale to something different from the
current setting, issue the following depending on what SHELL
environment you are in:

- Korn Shell

export LANG=Ja_JP (or) export LANG=ja_JP

- To verify the current locale setting, issue the following
command:

locale

Miscellaneous topics that are specific to operating systems 31

The output of the command looks something similar to the
following:

LANG=Ja_JP
LC_COLLATE="Ja_JP"
LC_CTYPE="Ja_JP"
LC_MONETARY="Ja_JP"
LC_NUMERIC="Ja_JP"
LC_TIME="Ja_JP"
LC_MESSAGES="Ja_JP"
LC_ALL=

HOW TO ENTER SBCS EXTENDED CHARACTERS USING AN ENGLISH KEYBOARD

It is possible to enter any SBCS character defined in the current
code page, including characters that are not available from the
layout of your keyboard in the following environments:

o In OS/2 windows.

o In the DOS command prompt in Windows

o In AIX "aixterm".

o In AIX "dtterm" for non-English locales.

Strange enough, if using English locales, you cannot enter
these extended characters, but if using Ja_JP for example,
you can!

For example, the US English keyboard does not have accented char-
acters, but it is possible to enter them by means of the fol-
lowing procedure:

1. Ensure that the "Num Lock" mode is activated in the numeric
keypad, which is located in the right side of the standard
keyboard. If your keyboard has a LED indicator for this
mode, then it should be on.

2. Press and hold the Alt key.

3. Enter the 3 digits that correspond to the code point in
decimal, such as 252: entering the digits 2, followed by 5
and 2.

4. Finally, release the Alt key.

This action can be summarized as "Alt-XXX", such as "Alt-252" for
the above example.

Of course, if you have a keyboard that can enter extended charac-
ters, then you do not have to use the Alt-XXX method.

32 TeamConnection and NLS/DBCS topics

HOW TO SPECIFY NLS SETTINGS FOR AIX GUI ON AIXTERM/DTTERM WINDOWS

If you are going to use the TeamConnection line commands and the
TeamConnection GUI in Motif in AIX and using different locales,
then you may need to open a new window with the aixterm or dtterm
(which is provided by the Common Desktop Environment) utilities.

Although these utilities provide a similar function, they differ
considerably with respect to the NLS support.

Using aixterm
_____________

1. Open an X-window session with aixterm with the desired locale
(code-page) and the appropriate font. The -T "string" param-
eter for aixterm will determine the title for the window.

Some examples are shown below:

For IBM-850:
aixterm -T "IBM-850" -lang En_US -fn Rom14 &

For ISO-8859-1:
aixterm -T "ISO-8859-1" -lang en_US -fn Rom14.iso1 &

For Ja_JP:
aixterm -T "Ja_JP" -lang Ja_JP -fn *gothic-*-19* &

For ja_JP:
aixterm -T "ja_JP" -lang ja_JP -fn *gothic-*-19* &

2. Perform the quick test for the code page, by entering
Alt-252. If code page IBM-850, then you will see
3-superscript; if code page ISO-8859-1, you will see
u-umlaut.

3. For DBCS, ensure that the aixterm window has the keyboard
status area located at the bottom left corner of the window;
also, ensure that you can enter SBCS and DBCS characters.

Miscellaneous topics that are specific to operating systems 33

Using dtterm
____________

1. Open an X-window session with dtterm with the desired locale
(code-page) and the appropriate font. The -name "string"
parameter for dtterm will determine the title for the window.

Some examples are shown below:

For IBM-850:
LANG=En_US dtterm -name "IBM-850" -fn Rom14 &

For ISO-8859-1:
LANG=en_US dtterm -name "ISO-8859-1" -fn Rom14.iso1 &

For Ja_JP:
LANG=Ja_JP dtterm -name "Ja_JP" -fn *gothic-*-19* &

For ja_JP:
LANG=ja_JP dtterm -name "ja_JP" -fn *gothic-*-19* &

2. Perform the quick test for the code page, by entering
Alt-252. If code page IBM-850, then you will see
3-superscript; if code page ISO-8859-1, you will see
u-umlaut.

3. For DBCS, ensure that the aixterm window has the keyboard
status area located at the bottom left corner of the window;
also, ensure that you can enter SBCS and DBCS characters.

CREATING A TEAMCGUI RESOURCE FILE FOR AIX

You can create a resource file for the TeamConnection GUI for
AIX, called "Teamcgui" (the first T of this file name is in
uppercase, and the rest of the string is in lowercase) in your
home directory to specify the appropriate font.

For example, for Japanese, you can specify the following small
size font:

*fontList: *gothic-*-19*:
*XmText*fontList: *gothic-*-19*:
*XmList*fontList: *gothic-*-19*:

You could use these other fonts for Japanese:

Small font: *gothic-*-19*:
Medium font: *mincho-*-27*:
Large font: *mincho-*-35*:

IMPORTANT NOTE: You must specify the colon at the end of the
font specification; if the colon is not present, such as in:

34 TeamConnection and NLS/DBCS topics

*gothic-*-19*

instead of:

*gothic-*-19*:

otherwise the keyboard status area will not be shown in the
bottom left corner of the TeamConnection GUI.

USING ICONV TO CONVERT FILES TO OTHER CODE PAGES

The source files for the message catalog and other source files
such as config.ld for TeamConnection were created in US English,
using code page IBM-850 in OS/2. Then these files were sent to
the translation centers and the translation was done using the
corresponding code pages for OS/2.

This means that in order to support the code pages in UNIX, we
needed to convert the code pages for certain files. This conver-
sion can be accomplished by installing the appropriate locales
and using the utility "iconv", as shown below:

from EN_US to en_US:
iconv -f IBM-850 -t ISO8859-1 input-file > output-file

from Ja_JP to ja_JP:
iconv -f IBM-932 -t IBM-eucJP input-file > output-file

ko_KR:
not needed

from Pt_PT to pt_BR:
iconv -f IBM-850 -t ISO8859-1 input-file > output-file

zh_CN:
not needed

from Big-5 to zh_TW:
iconv -f big5 -t IBM-eucTW input-file > output-file

HOW TO INSTALL ADDITIONAL LOCALES FOR AIX

1. Insert the appropriate CD-ROM with the installation images
for the AIX operating system.

2. Login as root

3. Invoke smit (or smitty)

Miscellaneous topics that are specific to operating systems 35

4. Select: System Environments

5. Select: Manage Language Environment

6. Select: Add Additional Language Environments

7. Select: CULTURAL convention to install

This item includes the locale information and the conversion
files between code pages related to the locale.

User F4 to list the choices from the CD-ROM. The following
entries were installed in our build and testing machines:

IBM-850 English (USA) [En_US]
ISO8859-1 English (USA) [en_US]
IBM-eucCN Chinese (Simplified EUC) [zh_CN]
IBM-eucTW Chinese (Traditional) [zh_TW]
IBM-eucJP Japanese (EUC) [ja_JP]
IBM-932 Japanese (PC) [Ja_JP]
IBM-eucKR Korean [ko_KR]
ISO8859-1 Portuguese (Brazil) [pt_BR]

8. Select: LANGUAGE translation to install

This item includes the message catalogs that will be stored
in /usr/lib/nls/msg.

Use F4 to list the choices from the CD-ROM.

9. Press enter to install the desired locales and/or message
catalogs.

10. Press F10 to exit from smit.

HOW TO CHANGE THE KEYBOARD FOR AN AIX HOST

NOTE: You MUST use the RISC keyboard and NOT a PC keyboard
(which will not work, you will need to telnet from another host
to reconfigure smit, shutdown, change keyboard again and boot)

1. Insert the appropriate CD-ROM with the installation images
for the AIX operating system.

2. Login as root

3. Invoke smit (or smitty)

4. Select: System Environments

5. Select: Manage Language Environment

36 TeamConnection and NLS/DBCS topics

6. Select: Change/Show Primary Language Environment

7. Select: Change/Show Cultural Convention, Language, or Key-
board

8. Enter the desired values for the following items:

Primary CULTURAL convention
Primary LANGUAGE translation
Primary KEYBOARD

Use F4 to list the choices from the CD-ROM.

The choices must match, otherwise there will be an error.
For example, if installing a Japanese keyboard but keeping
the English cultural convention, then this combination does
not match and will not succeed.

9. Press enter to make the change.

10. Exit smit, by pressing F10.

11. Shutdown the machine and DO NOT REBOOT yet:

shutdown -F

12. Change the physical keyboard.

13. Boot the machine

14. Verify that you can use the new keyboard

HOW TO INSTALL A NON-ENGLISH PC KEYBOARD TO AN X-STATION

The AIX hosts that run on RISC boxes require keyboards that are
not compatible with the PC standard keyboards.

This means that if you have a Japanese keyboard for a PC, for
example, you cannot use this keyboard with a RISC machine. That
is, you must get a Japanese keyboard that is specifically
designed for the RISC machine.

However, it is possible to connect a PC keyboard to an X-station
which can communicate with a RISC server. Follow these
instructions to accomplish this task:

1. The PC <language> keyboard (where: <language> is the sup-
ported language) C Posix Language, and C Posix cultural con-
vention seems to be the most versitile for using different
keyboard definitions from X-stations.

This convention can be set via smitty:

Miscellaneous topics that are specific to operating systems 37

a. smitty

b. Devices

c. Xstation Configuration

d. Add an Xstation

e. Select the desired model

f. From the "Add an Xstation" window, specify the following
values that are related to NLS settings.

CULTURAL convention <the desired locale>
LANGUAGE ISO8859-1 C (POSIX) [C]
KEYBOARD ISO8859-1 C (POSIX) keyboard [C]

Then press enter to activate.

g. Exit smitty

2. Once the correct keyboard definition is configuered for the
X-station changing cultural convention, and language settings
are as simple as changing the LC_ALL and LOCALE environment
variables.

3. Try not to use the dtlogin panel form X-stations.

When configuring the X-station do not use the /etc/dt/config
instructions from x_sta_mgr install for CDE. Use the default
x session to bring up a dtsession from /usr/dt/bin/dtsession
instead, after setting the desired language environment vari-
ables

The is because dt has 2 required fixes for dt to work in an
X-station configuration from the default system. These fixes
are not guaranteed to fix all the problems, though.

How to specify a different keyboard mapping
___________________________________________

Let's suppose that you have installed the Ja_JP locale and you
only have an English keyboard. You can still enter Japanese
characters using the English keyboard by doing the following:

o export LANG=Ja_JP

o xmodmap /usr/lpp/X11/defaults/xmodmap/$LANG/keyboard

o You may need to find out what is the actual keyboard mapping
in order to activate the different input modes and to enter
Japanese characters.

38 TeamConnection and NLS/DBCS topics

COPYRIGHTS, TRADEMARKS AND SERVICE MARKS

The following terms used in this technical report, are trademarks
or service marks of the indicated companies:

END OF DOCUMENT