Appendix A - Internationalization

This appendix describes how to customize the Advanced 3270/SNA software to use alternative language character sets in place of the U.S. English character set. To accomplish this task, you must use the BLDTABLE and GENX configuration programs.

BLDTABLE generates translation tables that can be used to internationalize the Advanced 3270/SNA emulation software. There are two kinds of translation tables: an ASCII-to-EBCDIC table and a 3270 device buffer code-to-ASCII table.

The ASCII-to-EBCDIC table allows characters typed at your keyboard to be translated into EBCDIC codes that can be understood by the host computer. It also allows EBCDIC characters generated by the host computer to be translated into ASCII characters that can be displayed on your PC screen.

The 3270 device buffer code-to-ASCII table is used by developers of LLAPI applications. This table translates the 3270 device buffer codes, used by the LLAPI calls Write Keystroke and Copy String, into ASCII codes.

GENX is a configuration program that modifies the file transfer programs SNA_SND and SNA_RCV. GENX is also used to modify the ASCII-to-ASCII table within HLLAPI.EXE.

U.S. English, Code Page 437, is the default language code set for File Transfer. GENX modifies the SNA_SND and SNA_RCV functions separately. This allows you to send a file in one language, and receive the file in another language.

BLDTABLE

The BLDTABLE program builds translation tables that let you run Advanced 3270/SNA using a customized character set. By modifying the BLDTABLE input files, you can control the characters that appear on your PC display screen.

When To Use BLDTABLE

If you are running Advanced 3270/SNA in an environment that requires a character set other than the US ASCII, Code Page 437, you must run BLDTABLE. For example, if you are running the Advanced 3270/SNA software in France, you would want to use a character set that supports French characters.

Modifying the ASCII-to-EBCDIC Table

Advanced 3270/SNA uses the BLDTABLE ASCII-to-EBCDIC translation table in two ways. It converts the ASCII characters you type at your keyboard into the EBCDIC characters used by the host, and it converts the host EBCDIC characters into ASCII characters for display on your screen.

For example, suppose you press a capital A at your keyboard. Figure A-1 below illustrates the role of the EBCDIC-to-ASCII table in the transmission of the character through the SNA network.

1. You press a capital A on your keyboard. Capital A is 41 hexadecimal (base 16) in ASCII. The character must be translated into EBCDIC so that the host can understand it.

2. The emulator refers to position 41 on the ASCII-to-EBCDIC translation table. (See Table A-3 for an example of a typical translation table.) Position 41 contains the value C1 hexadecimal. C1 hexadecimal is sent to the host.

3. The host determines that the character it receives is to be echoed to the screen. It returns the value C1 back to the emulator software.

4. Advanced 3270/SNA captures the value C1, and looks at the C1 position of the EBCDIC-to-ASCII conversion chart. Position C1 contains the value 41 hexadecimal. The emulator puts the ASCII equivalent of 41 hexadecimal on the screen (capital A).

The ASCII-EBCDIC and EBCDIC-ASCII tables translates all character codes, not just those that represent text characters. These include characters that are never displayed on your PC screen, such as data stream commands, order codes, screen addresses, and nonprinting characters such as Line Feed (LF) and Carriage Return (CR). Therefore, your translation affects all communication between your PC and the host.

Banyan recommends that you modify only displayable characters in your tables. Table A-1 contains some commonly-used characters with their hexadecimal representations in ASCII and EBCDIC. Table A-2 contains the same characters with their hexadecimal values in ASCII and 3270 device buffer code.

Running BLDTABLE

Follow the steps below to run the BLDTABLE program:

1. Insert the Advanced 3270/SNA International Diskette into the A drive of your PC. Copy the contents of the diskette to your hard disk.

2. To display a list of the available character sets you can use as BLDTABLE input files, type this command at the DOS prompt:

DIR *.TXT

3. Select one of these files as an input file for BLDTABLE. Type this command at the DOS prompt:

BLDTABLE infile.txt outfile.tbl

where infile.txt is the input file containing the conversion tables and outfile.tbl is a file name you specify. If this file does not exist when you run BLDTABLE, the program creates it. If a file with the specified name already exists, BLDTABLE overwrites it.

4. If you are running LLAPI applications and you require a Buffer Code-to-ASCII translation table, type this command at the DOS prompt:

BLDTABLE infile.txt outfile.scn

See the Chapter 7 on Application Programming Interfaces for more information on Buffer Code-to-ASCII translation tables.

5. Run ACONFIG. Select EDIT Translation Table Names from the Advanced 3270 Configuration menu. The screen in Figure A-2 appears.

6. Enter the names of your BLDTABLE ouput files in the appropriate fields. Press <F10> when you have finished.

7. Select Save Configuration from the Advanced 3270 Configuration menu, and exit to DOS.

How to Edit a BLDTABLE Input File

The following procedure shows how to change a character definition within a BLDTABLE input file, such as the one in Table A-3 above. The same procedure applies to modifications to the LLAPI Buffer Code-to-ASCII table.

Input File Format

The BLDTABLE input file consists of two tables of hexadecimal values.

Each table has a keyword (ASCII or EBCDIC) and 16 rows of values or null values. There are 16 values per line.

The values in the table labeled EBCDIC are the hexadecimal codes for ASCII characters. When data is coming from the host to be displayed on the PC screen, the values in the EBCDIC table are the hexadecimal codes of the characters to be displayed. For example, if an EBCDIC A (C1 in EBCDIC) is returned from the host, it is translated into a hexadecimal 41, which is the ASCII value for a capital A. The line below is taken from the EBCDIC table in Table A-3 and is for the EBCDIC values C0 through CF.

7B 41 42 43 44 45 46 47 48 49 XX XX XX XX XX XX ; C0-CF

Note that the hexadecimal code in position C1 (A in EBCDIC) is 41 (A in ASCII).

The values in the table labeled ASCII are the hexadecimal codes for EBCDIC characters. When data is being sent to the host from Advanced 3270/SNA, the values in the ASCII table are the hexadecimal codes of the characters to be sent. For example, if an ASCII A (41 in ASCII) is sent to the host, it is translated into a hexadecimal C1, which is the EBCDIC value for a capital A. The line below is taken from the ASCII table in Table A-3 and is for the ASCII values 40 through 4F.

7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 ; 40-4F

Note that the hexadecimal code in position 41 (A in ASCII) is C1 (A in EBCDIC).

The following guidelines apply to BLDTABLE input files:

	The keyword ASCII must precede the ASCII-to-EBCDIC table, and the keyword EBCDIC must precede the EBCDIC-to-ASCII table.
	The values are expressed in either one-digit or two-digit hexadecimal values. For example, F and 0F are the same value. Use XX or xx instead of a hexadecimal value to denote a null value.
	You can include blank lines anywhere in the file.
	Precede comments with a semicolon. BLDTABLE ignores all characters to the right of a semicolon in processing.

The Advanced 3270/SNA Internatonal diskette includes numerous files with the extension .TXT to use as input files with BLDTABLE. Table A-3 shows one such file, which contains the U.S. English ASCII-to-EBCDIC and EBCDIC-to-ASCII conversion tables.

Input File Editing Procedure

To change the values in a BLDTABLE input file, follow this procedure.

1. Select a .TXT file that most closely represents the language or character translations you need.

2. Use a text editor to edit the .TXT file.

3. Starting with the ASCII values at the bottom of the file, locate the hexadecimal character you need to translate. Use the right-hand column as a reference. For example, here is the first line in Table A-3 and is for the ASCII values 00 through 0F:

00 XX XX XX XX XX XX XX XX 05 15 XX 0C XX XX XX ; 00-0F

The notation to the right of the semicolon means that the first position in the column is numbered 00, and the last position in the column is numbered 0F. The line below shows a line with each position numbered.

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ;position

4. After finding the corresponding hexadecimal value, locate that same value in the EBCDIC table above it.

5. The corresponding value in the EBCDIC table is what the emulator displays. Edit this table. If the character value in the EBCDIC table is XX, nothing displays.

Example

Suppose you want to edit your translation table so that a dollar sign ($ = 24 hexadecimal) displays as a pound sign (£ = 9C hexadecimal).

1. Edit the file using any standard text editor. In location 24 in the US ASCII table (See Table A-3) you will find the value 5B.

40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61 ; 20-2F

2. Find location 5B in the EBCDIC table.

26 XX XX XX XX XX XX XX XX XX 21 24 2A 29 3B AA ; 50-5F

Change it to 9C. The line should now look like this:

26 XX XX XX XX XX XX XX XX XX 21 9C 2A 29 3B AA ; 50-5F

3. Save the file with any name and a .TBL extension.

4. Run BLDTABLE with the modified .TXT file as input. Use the following syntax:

BLDTABLE infile.txt outfile.tbl

5. Run ACONFIG and specify the new .TBL file name as your translation table.

After completing these steps, you would run the Advanced 3270/SNA software. Each time you pressed the $ character on your keyboard during emulation, a pound sign (£) would appear on the screen.

Program Messages

One of the following messages appears after you run BLDTABLE. In most cases, the message is "Tables written to filename," indicating that the procedure was successful. Other messages describe a specific error. These messages are listed below with accompanying explanations.

Duplicate keywords in file.

You used the keyword ASCII or the keyword EBCDIC twice in the input file.

Error writing to output file. Check your disk; it may be full.

DOS diskette might not have enough space to hold the output file.

File cannot be opened. You may want to check your file name.

Your input file does not conform to valid DOS file name specifications.

File too short. Table(s) missing.

An ASCII or EBCDIC table is missing from the input file.

Illegal digit found in file.

You included non-hexadecimal digits in your input file tables.

More than 2 consecutive hex digits found. 2 is the limit.

An input value in one of the tables is longer than two characters.

Syntax of keyword is incorrect. Expecting 'ASCII' or 'EBCDIC'.

You used a word other than than ASCII or EBCDIC in the header line preceding the input tables.

Table incomplete. File too short.

Each input table must be 16 rows long. Check input table lengths.

Tables written to file name

This message indicates the successful completion of the BLDTABLE procedure.

The row is too short. 16 values are required on a line.

One or more rows in the input file tables contain less than 16 values.

Running GENX

To start the GENX program:

1. Check your working directory to see if it contains the following files:

GENX.EXE
SNA_SND.LAN
SNA_RCV.LAN
SNA_SND.MAP
SNA_RCV.MAP

If any one of these files is missing, copy it from the distribution diskette into your working directory.

Note: When changing language character sets, you must start with the original SNA_SND program that contains the default US English character set before selecting a new set. Use a copy of SNA_SND.EXE and SNA_RCV.EXE from the distribution diskette each time you run GENX.

2. Enter GENX at the DOS prompt:

GENX

GENX first displays the program copyright notice and the first line of the dialogue shown below in Figure A-3.

3. Respond to the prompts as shown. Each time you press <ENTER>, the next prompt appears. You can enter new file names if you choose, but Banyans recommend choosing the defaults.

The prompts show the default names in square brackets.

The values in square brackets [ ] define the following files:

[Nul.exe] This is a place holder. You can answer only SNA_SND, SNA_RCV, or HLLAPI to this prompt.

[SNA_SND.MAP] The SNA_SND symbol file. The symbol file tells the file transfer software where to find the customization information in PC memory.

[SNA_SND.LAN] The SNA_SND language file customization menus and values.

[SNA_SND.EXE] The file transfer program.

If you renamed SNA_SND.EXE, SNA_RCV.EXE, or HLLAPI.EXE to a new name, you must enter the new name.

Creating Customized GENX Files

There are two ways to answer the New Program Name prompt. You can press <ENTER> to confirm the default file name, or you can enter any valid DOS file name.

Entering a new DOS file name allows you to create SNA_SND programs with different parameters for different uses. The original SNA_SND program retains the SNA_SND defaults. The new program you create contains your GENX customization.

When you respond to the New Program Name prompt, GENX writes the file (using the file name you choose) to the default drive. Then GENX displays the Language Selection menu, as shown in Figure A-4.

When this menu appears, follow these steps:

1. Enter the number corresponding to the character set you want.

2. Enter 98, to confirm the language you select.

3. Enter 99 to exit GENX.

Refer to the IBM 3270 Information Display System Character Set Reference for more information on character sets supported by the 3270 PC.