Translate tables

Background

Janus Connectivity products like Janus Web Server and Janus SOAP typically communicate with applications on remote computers. In many cases, these remote computers use different encodings for symbols, numerals, and letters or "characters." A character usually occupies a single byte of memory on any computer, but the character displayed for a particular bit value may vary.

For example, in an ASCII encoding, the numeral "1" is represented by the hexadecimal value X'31'. On a computer that uses an EBCDIC encoding (IBM mainframes), the representation is X'F1'. Therefore a numeral "1" transmitted from an ASCII-based computer to an EBCDIC-based computer, or vice versa, will be misinterpreted. To avoid such misinterpretation, a method of converting a byte from one encoding to another is needed. Janus translate tables were implemented to solve this problem.

In early Janus versions, a fixed translate table provided the most common type of translation: that is, it converted ASCII to EBCDIC when receiving, and it converted EBCDIC to ASCII when sending. In most cases, this was adequate for the Janus products.

However, to work with the many different types of EBCDIC and ASCII character sets, designed to display foreign language characters, currency, and other special symbols, a more flexible approach was introduced. The translate table facility was expanded to allow the simultaneous use of many different translate tables, and further, to allow user-written or customized translate tables.

Using translate tables

To provide backward compatibility with earlier releases, a standard translate table (named "STANDARD") is loaded during Model 204 initialization. The STANDARD table is an exact copy of the translate table used with earlier Janus releases. This is the default translate table for all Janus ports, unless you define Web ports with DBCS support. In this case, the "JAPANIBM" translate table (loaded during Model 204 initialization) is used.

As described on this page, the JANUS DISPXT and JANUS LOADXT commands let you view (or copy for modification purposes) and reload these translate tables.

To use a Janus translate table other than the default tables, you can do any of the following:

Code your own translate table source.
Use an external translate table.
Use or modify a Rocket-provided translate table.

You then use the JANUS LOADXT command to validate the new table, convert it to an internal format, and name and add it (replacing any existing table with the same name).

Using the Unicode tables

To use the most up-to-date Rocket-provided translation file, specify the following to load and name the Unicode table that handles Janus SOAP XML document translations:

JANUS LOADXT xtabname UNICODE

To view the translations in effect after issuing this LOADXT command:

Determine the codepage in use at your site for translations between Unicode and EBCDIC:
UNICODE Display Table Standard

The result of this UNICODE command begins with something like:

* The following commands produce the current Unicode translation tables: UNICODE Table Standard Base Codepage pppp

where pppp is the codepage in use. Such a Unicode codepage is displayed in Example table, below, where it is shown being used as a Janus translate table. The initial Model 204 default Unicode table is codepage 1047.

Note: The Standard keyword in the command above references the Unicode standard translation table, which is not to be confused with the initial default Janus translation table (whose name is typically shown in uppercase as "STANDARD").
Using the above codepage, issue:
UNICODE Display Codepage pppp

The result will be many lines of single-character translations, one line for each character translated between EBCDIC and Unicode. This format differs entirely from that described below in Example table.

Defining your own translate table

You can define your own translate tables and load them with the JANUS LOADXT command. These tables can be defined in a Model 204 procedure file or group, or in a sequential file or z/OS Partitioned Data Set (PDS).

Basic rules

A translate table must include a 256-byte EBCDIC-to-ASCII table, followed by a 256-byte ASCII-to-EBCDIC table. Comment lines are allowed, and they can begin with a semicolon (;) or an asterisk (*).

Comments are allowed on the same line as definition lines, provided they are preceded by either of the two comment characters.

You can define any number of bytes of the translate table on a single line, but it is easier to read and maintain if you define 16 bytes per line.

Certain characters must be translated to their equivalent values in EBCDIC and ASCII for basic Janus functions to work correctly. Therefore, these characters are reserved for use by Janus, and they may not be translated to any other characters. These reserved characters are the following:

0-9 a-z A-Z . period < less than ( left parenthesis + plus & ampersand ! exclamation * asterisk ) right parenthesis ; semicolon / forward slash , comma % percent > greater than ? question mark : colon # pound sign ' single quote = equal sign " double quote

JANUS LOADXT validates any table it attempts to load, and if these characters are not preserved when translating to ASCII and back, the table is not loaded.

Each character in the translate table is coded in hexadecimal format and must be two bytes long. Each two-byte hexadecimal string must be separated by one or more blanks.

Example table

Following is an abbreviated example of translate table source code. Each of the rows of hexadecimal characters define the EBCDIC encoding for an ASCII character at that offset in the table. So for example, to find out how this table would translate an ASCII 2 (hexadecimal X'32'), you locate offset X'32' in the table, which is in the fourth row, third pair of characters. Note that the top and right-side comments (shown in bold) help to locate offsets quickly. At offset X'32' in this table, you find the value X'F2', which is the EBCDIC encoding for the numeral 2.

Of course, to send characters, you would want to translate EBCDIC encoding back into ASCII. Therefore, an EBCDIC to ASCII section must also be coded. This is not shown in the example.

; ; ASCII-to-EBCDIC table for English (US) CECP Code Page 037 ; 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ; 00 01 02 03 37 2D 2E 2F 16 05 25 0B 0C 0D 0E 0F ; 00 ; 10 11 12 13 3C 3D 32 26 18 19 3F 27 1C 1D 1E 1F ; 10 ; 40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61 ; 20 ; F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F ; 30 ; 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 ; 40 ; D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 BA E0 BB B0 6D ; 50 ; 79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96 ; 60 ; 97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 4F D0 A1 07 ; 70 ; 68 DC 51 42 43 44 47 48 52 53 54 57 56 58 63 67 ; 80 ; 71 9C 9E CB CC CD DB DD DF EC FC 70 B1 80 BF FF ; 90 ; 45 55 CE DE 49 69 9A 9B AB AF 5F B8 B7 AA 8A 8B ; A0 ; 2B 2C 09 21 28 65 62 64 B4 38 31 34 33 4A B2 24 ; B0 ; 22 17 29 06 20 2A 46 66 1A 35 08 39 36 30 3A 9F ; C0 ; 8C AC 72 73 74 0A 75 76 77 23 15 14 04 6A 78 3B ; D0 ; EE 59 EB ED CF EF A0 8E AE FE FB FD 8D AD BC BE ; E0 ; CA 8F 1B B9 B6 B5 E1 9D 90 BD B3 DA FA EA 3E 41 ; F0 ;

Initial default STANDARD table

If never modified at your site, this is the STANDARD Janus translate table pair:

* ASCII to EBCDIC table * 00 01 02 03 37 2D 2E 2F 16 05 25 0B 0C 0D 0E 0F 10 11 12 13 3C 3D 32 26 18 19 3F 27 1C 1D 1E 1F 40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D 79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96 97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 6A D0 A1 07 00 01 02 03 37 2D 2E 2F 16 05 25 0B 0C 0D 0E 0F 10 11 12 13 3C 3D 32 26 18 19 3F 27 1C 1D 1E 1F 40 5A 4A 7B 5B 6C 6A 7D 4D 5D 5C 4E 6B 60 4B 61 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D 79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96 97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 6A D0 A1 07 * * EBCDIC to ASCII table * 00 01 02 03 14 09 3A 7F 3A 3A 3A 0B 0C 0D 0E 0F 10 11 12 13 3A 0A 08 00 18 19 3A 3A 1C 1D 1E 1F 3A 3A 3A 3A 3A 0A 17 1B 3A 3A 3A 3A 3A 05 06 07 3A 3A 16 3A 12 13 3A 04 53 3A 3A 3A 14 15 3A 1A 20 5B 5D 23 25 3A 3A 3A 3A 3A A2 2E 3C 28 2B 7C 26 3A 3A 3A 3A 3A 3A 3A 3A 3A 21 24 2A 29 3B 5E 2D 2F 3A 3A 3A 3A 3A 3A 3A 3A 7C 2C 25 5F 3E 3F 3A 3A 3A 3A 3A 3A 3A 3A 3A 60 3A 23 40 27 3D 22 3A 61 62 63 64 65 66 67 68 69 3A 7B 3A 3A 3A 2B 3A 6A 6B 6C 6D 6E 6F 70 71 72 3A 7D 3A 3A 3A 3A 3A 7E 73 74 75 76 77 78 79 7A 3A 2B 2B 5B 3A 3A 3A 3A 3A 3A 3A 3A 3A 3A 3A 3A 5B 5D 2B 5D 3A 2D 7B 41 42 43 44 45 46 47 48 49 3A 3A 3A 3A 3A 3A 7D 4A 4B 4C 4D 4E 4F 50 51 52 3A 3A 3A 3A 3A 3A 5C 3A 53 54 55 56 57 58 59 5A 3A 3A 3A 3A 3A 3A 30 31 32 33 34 35 36 37 38 39 3A 3A 3A 3A 3A 3A

Notes:

You may want to use a Unicode table as your Janus translate table. See Using the Unicode tables.
In the ASCII to EBCDIC table, ASCII square brackets (X'5B'/X'5D') are translated to EBCDIc X'AD'/X'BD', which is the same as codepage 1047.
In the EBCDIC to ASCII table, EBCDIC X'AD'/X'BD', X'BA'/X'BB', and X'41'/X'42' are all translated to ASCII square brackets. The X'BA'/X'BB' translations are the same as codepage 0037. X'41'/X'42' are not in any codepage supported by the UNICODE command, but on some obsolete TN3270 terminals they were used for square brackets.

Loading an external translate table

You can specify existing, external, translate table source to load as the Janus translate table. For example, IBM supplies many translate tables with its TCP/IP product under z/OS. You can use those tables directly with JANUS LOADXT:

Allocate the data set and member you want to load, using the Model 204 ALLOCATE command:
ALLOCATE IBMXTAB WITH SCOPE=SYSTEM DSN=TCPIP.AEZAXLT1 - MEMBER=US OLD SEQUENTIAL VOLUME=OS260R
Use the JANUS LOADXT command to load the translate table:
JANUS LOADXT name DDNAME IBMXTAB

Modifying a Rocket-provided translate table

You can obtain source copies of any previously loaded translate table (including internal tables) by using the JANUS DISPXT command and the Model 204 USE command.

For example, to place a copy of the current "STANDARD" translate table into a USE device, issue the following commands:

USE ddname JANUS DISPXT STANDARD

After modifying the copy as you need as described earlier on this page, reload the modified table using the JANUS LOADXT command. For ease of editing, you might want to use the approach shown in JANUS DISPXT to copy the STANDARD table to a procedure, edit, then load the procedure with JANUS LOADXT.

Note: Because the STANDARD table in the example above may already be a modified version of the STANDARD table distributed with Janus TCP/IP Base, if you definitely want to copy the distributed STANDARD table, issue the USE and JANUS DISPXT commands in a "private" Online where you are confident the table has not been modified.