[Top] [Previous] [Next] [End of Book]

# Appendix B . Customizing Character Set Mapping Tables

## Introduction

To allow maximum flexibility when configuring Connect TPS to support various applications, the mapping tables used for character set translation are stored in external files. These files use the X/Open XPG standard format (and tools) for nationalizable message catalogs.

Although the map tables provided should handle the majority of English-language applications, it may be necessary to produce customized tables to support specific operating environments or applications.

To modify any nationalizable message catalog, a source text file is prepared (using any text editor) which follows the XPG standard format. Then, this text file is converted to a catalog file by using the gencat command.

Our discussion begins with an overview of the layout of the source text files that are used to produce the Connect TPS map catalogs. An explanation of how to customize the catalog files follows.

## The Character Set Mapping Table

A Connect TPS map table file consists of two sections (or "sets") of entries:

- The first set describes mappings that are applied to characters before they are transmitted to remote systems.

- The second set describes mappings that are applied to characters when they are received from remote systems.

## Customizing a Character Set

The procedure for customizing character set mappings includes the following steps:

1. Copy a map table source file as a starting point.

2. Edit the mappings as desired.

3. Validate the changes you make.

4. Generate the map catalog file.

5. Set parameters in the TPSINIT file to implement the new file.

The following subsections provide detailed information about each of these steps.

### Step 1: Copy the Appropriate Source File

There are two character set maps that are supplied with Connect TPS. To facilitate customization, Connect TPS provides both source text files and ready-to-use catalog files.

Table B-1 describes the character sets and lists Connect TPS catalog files and source files that contain the character sets.

> Table B-1 Character Sets and Corresponding Connect TPS Files

Character Set | Range | Catalog File | Source File
--- | --- | --- | ---
ASCII | AIl 8-bit characters (from 0 through 255) | TPS-ASC_CAT | TPS-ASC.text
EBCDIC | All 8-bit characters (from 0 through 255) | TPS-EBC_CAT | TPS-EBC.text

To begin the customization process, determine what character set you need to map. This requires an understanding of what character set a remote system can accept. If the remote system is another BEA Connect TPS gateway, you can use any character set, provided that both gateways are configured for the same range of characters.

Once you have selected a character set, make a copy of the source file. For example, to customize the EBCDIC mapping, you might copy the Connect TPS character map source file (TPS-EBC.text) to a file named MyEBC.text by issuing the following command:

>     cp TPS-EBC.text MyEBC.text

Caution: Do not rename or modify the original source files.

### Step 2: Edit the Source File Copy

The following subsections explain how to edit the source file copy.

#### Introduction

As explained above, a Connect TPS map table file consists of two sets of entries:

- Set 1

Mappings applied to characters before transmission to remote systems

- Set 2

  Mappings applied to characters after characters are received from remote systems

Each line of a given set pairs a decimal character number with a string representing the mapped character. The string can contain a single literal character or an escape sequence representing the character. Escape sequences can be expressed in hexidecimal or octal. For example, the character "A" is "\\x41" in hexidecimal and "\\101" in octal.

In addition, there are several predefined values you can use to represent control characters. These include:

- \\a (bell)

- \\b (backspace)

- \\f (formfeed)

- \\n (newline)

- \\r (return)

- \\t (tab)

- \\v (vtab)

#### Contents of Set 1

Set 1 describes mappings that are applied to characters before being sent to remote systems. Each line of set 1

- Begins with a decimal character number that represents how a character in the local system's character set is encoded.

- Ends with a string that contains the target character (i.e., the character to which the local character is mapped).

For example, assuming that the Connect TPS gateway is installed on a system that uses an ASCII character set, the following line in set 1 causes every instance of a caret character (which has an ASCII decimal value of 94) in an outgoing string to be mapped to an ASCII tilde character before transmission:

>     94   "~"

This mapping is expressed in hexidecimal as follows:

>     94 "\\x7e"

Finally, here is the same mapping in octal:

>     94 "\\176"

#### Contents of Set 2

Set 2 describes mappings that are applied to characters after characters are received from remote systems. Each line of set 2

- Begins with a decimal character number that represents the character that is received from a remote system.

- Ends with a string that contains the target character-that is, the local character to which a character from a remote system is mapped.

For example, assuming that the local system uses an ASCII character set, the following line in set 2 causes every instance of an incoming tilde character (which has an ASCII decimal value of 126) to be mapped to a caret character.

>     126  "^"

This mapping is expressed in hexidecimal as follows:

>     126 "\\x5e"

Finally, here is the same mapping in octal:

>     126 "\\136"

#### Editing Character Mappings

Using your choice of text editor, open the copy of the source text file you want to modify. For example

>     vi MyEBC.text

As you scroll through the file, you will notice two sections (sets of map entries) that are labeled as follows:

>     $set 1
>     .
>     .
>     .
>     $set 2

Do not modify the lines that contain "$set 1" and "$set 2." These are required for proper catalog generation.

To begin, modify the contents of set 1 as follows:

1. Add or delete lines so that each character in the remote system's character set is represented by one line.

2. Modify the mapping strings as required, so that each local character number is paired with a valid character in the remote system's character set.

3. Next, modify the contents of set 2 by modifying the mapping strings so that each remote character number is paired with a valid character in the local system's character set.

### Step 3: Validate the Source File Copy

At this point, you must examine the modified file to ensure that changes to character set mappings

- Are in keeping with standards

- Contain only valid characters

- Are complete

- Handle both incoming and outgoing strings

Remember that mapping strings must not contain any characters that are excluded from the remote system's character set. Additionally, the remote application may impose additional restrictions (for example, accepting only 7-bit character values).

You should be looking for any instances where characters are

- Missing

- Duplicated

- Invalid for the specified character set

### Step 4: Generate the Catalog File

After you validate a text file, you must convert it into a catalog file by using the gencat command. The gencat command is used to generate XPG-standard nationalized message catalogs from appropriately formatted text files.

Here is an example:

    gencat TPS-EBC CAT MyEBC.text

In this example, the TPS-EBC_CAT message catalog is created out of the MyEBC.text source file.

For more detailed information about the gencat command, see your operating system documentation.

### Step 5: Configure Connect TPS to Use the New Catalog File

Connect TPS enables administrators to select the treatment that is applied to string data by installing updated copies of the mapping table files that are used to translate string and char fields.

As installed, the location of the files is the default directory from which BEA TUXEDO message catalogs are read. This starts out as the locale/C directory under the BEA TUXEDO installation directory (ROOTDIR).

However, if you set the LANG environment variable, the final subdirectory in this path is not searched. Instead, the subdirectory you specify with LANG is searched. For example, if you set LANG to "Esperanto," the directory locale/Esperanto (under ROOTDIR) would be searched for mapping table files, as well as BEA TUXEDO and Connect TPS message catalogs.

Caution: Do not modify the LANG environment variable unless you intend to change the location of every message catalog.

To configure the example that is featured in this appendix (the customized EBCDIC map) for use in mapping string fields, place the new TPS-EBC_CAT catalog in the directory where other Connect TPS map catalog files reside.

[Top] [Previous] [Next] [End of Book]