Double-byte character set support

This chapter explains the functions and considerations that are unique to developing ZIETrans applications that provide double-byte character set (DBCS) support.

In addition to general functions, ZIETrans provides the following specific functions to support DBCS:

This chapter explains these specific functions and special considerations when using ZIETrans general functions to support DBCS.

DBCS and SBCS field support

ZIETrans supports the following types of DBCS and SBCS fields.

Table 15. DBCS and SBCS field support
Field type Allowable field contents Platform
DBCS mix SBCS and DBCS characters with Shift Out/Shift In (SO/SI) characters 3270
DBCS only (G) DBCS characters without SO/SI 3270
Alphanumeric only All SBCS characters but no DBCS characters 3270
Numeric only Only digits 0 through 9, comma (,), period (.), plus sign (+), minus sign (-), and space ( ) 3270
DBCS open (O) SBCS and DBCS characters with SO/SI 5250
DBCS graphic (G) DBCS graphic characters without SO/SI 5250
DBCS only (J) DBCS characters with SO/SI 5250
DBCS either (E) Either DBCS with SO/SI or SBCS characters 5250
Alphabetic only (X) Only characters A through Z, comma (,), period (.), hyphen (-), and space ( ) 5250
Alphanumeric shift (A) All SBCS characters but no DBCS characters 5250
Numeric shift (N) All SBCS characters but no DBCS characters 5250
Signed numeric (S) Only digits 0 through 9 5250
Numeric only (Y) Only digits 0 through 9, comma (,), period (.), plus sign (+), minus sign (-), and space ( ) 5250
Katakana field (W) All SBCS characters but no DBCS characters 5250
Inhibit keyboard entry (I) No input from the keyboard except from special devices, for example a light pen 5250
Digits only (D) Only digits 0 through 9 5250
Numeric only character (M) Only digits 0 through 9, comma (,), period (.), plus sign (+), minus sign (-), and space ( ) 5250

Data type checking

Each type of DBCS field must contain only the allowable type of data. For example, the DBCS graphic (G) field must contain only DBCS graphic characters without SO/SI characters. ZIETrans performs data type checking to ensure that only allowable data types can be entered into DBCS fields.

Field length checking

In a field on a host screen, DBCS characters have a length of two. In a field on a GUI page, DBCS characters have a length of one. This ZIETrans function checks the length of DBCS characters being entered into a GUI field and does not allow more characters than will fit into the corresponding host field.

Copy-and-paste prevention

This ZIETrans function prevents a user from copying and then pasting data with an incorrect data type into a field. If mixed data is pasted, all characters after the first illegal character is trimmed. For example, if the user tries to paste abc&cde into a field, and the & is an illegal character for the field type, only abc is pasted.

Note:
This function is supported only for ZIETrans Web applications using Internet Explorer on Windows platforms.

Input Method Editor (IME)

The Input Method Editor (IME) is a front-end-processor (FEP) which handles keyboard input and generates DBCS strings. Typically, the IME is a component of the operating system, but it may be a single product or a part of another application like a word processor.

DBCS users can generate thousands of different characters using a regular-sized keyboard. Typically a user types a sequence of characters and then uses the IME to convert the sequence to double-byte characters. The conversion may have to be retried because there may be several possible translations, or candidates, for the same sequence of characters. While this conversion process is going on, the text logically belongs to the IME. After the conversion process, the user then uses the IME to commit the converted double-byte characters to the application. ZIETrans supports use of the IME for committing double-byte characters into ZIETrans fields.

If the user tries to enter characters into the IME that exceed the maximum length of the rendered ZIETrans field, then the behavior differs depending on the Eliminate maximum length in DBCS fields and Eliminate maximum length in SBCS fields settings. For more information about the Eliminate maximum length in DBCS fields setting, see Eliminate maximum length in DBCS fields. For more information about the Eliminate maximum length in SBCS fields setting, see SBCS eliminate maximum length.

AutoIME switching

Host screens may often contain both DBCS and SBCS fields. ZIETrans will automatically turn on IME when the cursor is located on a DBCS field and turn off IME when the cursor is located on an SBCS field.

Notes:
  1. Support is provide only for ZIETrans Web applications using Internet Explorer.
  2. AutoIME is supported for DBCS sessions for all fields except DBCS mix (3270), DBCS open (O), DBCS either (E), and Inhibit keyboard entry (I) .
  3. Support is provided at the field level and not at the character level.
  4. Support is not provide in the Combo widget.
  5. In ZIETrans Web applications on Japanese Windows platforms, the IME will switch to DBCS (or Zenkaku) hiragana mode when the cursor is in a katakana(W) field. Users can input DBCS (or Zenkaku) katakana characters, then use function key F8 to get halfwidth katakana characters, or use function key F10 to get alphanumeric characters.

Shift Out/Shift In considerations

For DBCS mix, DBCS open (O), DBCS only (J), and DBCS either (E) fields, if the Show unprotected Shift Out/Shift In characters as spaces setting in the DBCS section of the Rendering tab is selected, the SO/SI characters are displayed as spaces in the GUI. If not selected, the SO/SI characters are not displayed in GUI.

To configure this property for connections used for ZIETrans Integration Objects, use the omitSOSI Host On-Demand session parameter. This parameter can have a value of true or false. If true, the ZIETrans Integration Object omits the SO/SI characters for the connection. If false (the default), the ZIETrans Integration Object replaces the SO/SI characters with a space, as is the case normally. For information about how to add the omitSOSI property to your Integration Object connection, see Configure optional, advanced connection settings.

Other considerations

This section explains other considerations to understand when using the general ZIETrans functions to develop applications that support DBCS.

Project theme settings

DBCS eliminate maximum length

Eliminate maximum length in DBCS fields
Use this setting at the theme level to select whether to eliminate the maximum length attribute in DBCS fields. You can also select this setting in the project settings editor. For more information about this setting, see the Eliminate maximum length in DBCS fields setting on the Rendering tab of the project settings editor.

Project settings editor

The following settings are available in the project settings editor for DBCS projects. See Modifying a ZIETrans project for other project settings.

Rendering tab

DBCS

On the Rendering tab you can configure the following DBCS options for your project if your default connection specifies a DBCS code page.

Show unprotected Shift Out/Shift In characters as spaces
Select this box to display unprotected Shift Out and Shift In characters as spaces in the GUI for DBCS mix, DBCS open (O), DBCS only (J), and DBCS either (E) fields. If not selected, SO/SI characters are not displayed in the GUI.
Automatically convert SBCS characters to DBCS for G-type and J-type fields
Select this box if you want to automatically convert single byte characters to double byte characters for 3270 and 3270E G-type or 5250 G-type and J-type fields.
Eliminate maximum length in DBCS fields  Web-only 

If not selected, then characters that exceed the maximum length of the DBCS field cannot be entered into the IME.

If selected, then

This setting is supported for the following field types:

Notes:
  1. This setting is available only for DBCS code pages in Web projects.
  2. This setting is supported only for Internet Explorer.

Other tab

In the Client Settings section of the Other tab, consider the following settings for DBCS projects.

Enable automatic field advance

For ZIETrans Web applications, the auto advance feature depends on the current character count and field length to decide the time of advance. When the Show unprotected Shift Out/Shift In characters as spaces setting in the DBCS section of the Rendering tab is not selected, the character count never reaches the field limit if a DBCS character is in the field. So for ZIETrans Web applications, if you need the auto advance function in the DBCS environment, you must select the Show unprotected Shift Out/Shift In characters as spaces setting.

When using the IME to input data into a field, two tables in the KBS.js file are used to define keys that trigger auto advance. A set of default triggering keys is provided. If necessary, you can edit the tables in the KBS.js file to change the defaults. To edit the KBS.js file, from the Navigator view double-click the file, which is located in the project_name\Web Content\common folder. The following example shows the default keys defined in the two tables. For example, the ALT + SBCS/DBCS (keycode 25) key combination is a default triggering key. To add a key, enter its keycode (either its variable name defined in the KBS.js file or its numeric value) and a key modifier (ALT, CTRL, or Shift) as appropriate. For how to determine the keycode value for a given key on the keyboard, see Determining keycode values.

var IMEkeysForKeyUp = [ 
//-Keycode----ALT-CTRL-Shift----// 
[  CODE_ENTER,  0,  0,  0  ],
[  CODE_M,      0,  1,  0  ],
[  CODE_ENTER,  0,  1,  0  ]
];

var IMEkeysForKeyDown = [ 
//-Keycode----ALT-CTRL-Shift----// 
[  25,          1,  0,  0  ] //ALT + SBCS/DBCS key
];
Overwrite mode (initial)

The overwrite mode (initial) feature is not supported for DBCS input.

Notes:
  1. When you type into a browser, the browser controls whether you can overwrite. Some browser implementations do not allow any overwriting, while others allow overwriting only for SBCS.
  2. One DBCS character is inserted before any SBCS or DBCS character regardless of whether overwrite mode is enabled.
  3. An SBCS character can overwrite one DBCS character, including SO/SI characters.
Select all text on focus

If this setting is selected, when a user tabs to a 5250 J-field, all the text in the field is selected when the field receives focus. If the user then inputs DBCS characters, and uses the Field Exit function to exit the field, the last character of the string may be deleted.

To avoid this behavior, clear the Select all text on focus box and select the Show unprotected Shift Out/Shift In characters as spaces box. In this case, the cursor is positioned properly in the first input position of the field. The user can begin typing at this position and then use the Field Exit function to exit the field.

Note:
These considerations only apply to 5250 J-fields in Web applications.

Screen event editor

Screen recognition criteria / Begin screen

You should not select screen recognition criteria which contains half of a double-byte (DBCS) character. Any DBCS character selected must be completely included in the selection region. See Screen Recognition Criteria or Begin Screen for more.

Host components

Selection list

The following setting is available for the selection list component for DBCS projects. See Selection list for other selection list component settings.

Convert action number (DBCS only)
If your host displays full-width characters for the list items' leading token, but it expects the item to be entered into the target input field as a single-byte character, then this parameter must be enabled. This will cause ZIETrans to convert the DBCS item into a SBCS item before it is sent to the host. This setting does not apply for items which are displayed as single-byte characters on the host.

Subfile

Following is a consideration when using the Column Breaks setting of the Subfile component. See Subfile for other Subfile component settings.

Column Breaks
Column breaks cannot split a DBCS character.

Table

Following is a consideration when using the Column Breaks setting of the Table component. See Table for other Table component settings.

Column Breaks
Column breaks cannot split a DBCS double-byte character.

Widgets

SBCS eliminate maximum length

Eliminate maximum length in SBCS fields (DBCS codepage only)

If not selected, then characters that exceed the maximum length of the SBCS field cannot be entered into the IME.

If selected, then

This setting is supported for the following widgets:

This setting is supported for the following field types:

Notes:
  1. This setting is supported only for DBCS code pages in Web projects.
  2. This setting is supported only for Internet Explorer V6 and V7.
  3. When this setting and the Enable automatic field advance setting are both selected, if a user inputs characters using the keyboard, instead of using the IME, the automatic field advance feature does not work for the supported field types listed above.

Macro support

Following are considerations when using macro support in DBCS projects.

Recording a macro

When recording a macro you can use the Add Extract Action to extract information from the host screen. See more information about the Add Extract Action Add Extract Action. Consider the following case when extracting DBCS characters.

When you extract a region of the host screen into a table, you can modify the format of the table. One of the modifications you can make is to divide a table column into two columns. When you click Divide, ZIETrans divides the selected column. If the column contains double-byte (DBCS) characters, the division can split a DBCS character into two columns. In this case, the DBCS character will not appear in either column. If you see this happen while editing an extract action, use the Right and Left buttons to adjust the columns. The divided DBCS character will reappear when it is contained in a single column.

Exporting a macro

If you export a macro containing DBCS characters to a HOD macro, and then import it into Host On-Demand , the DBCS characters may become unreadable. To avoid this problem, you can open the exported macro with an editor that supports UTF-8 encoding, such as Notepad, save the macro using native encoding, and then import the macro into Host On-Demand.

Creating an Integration Object

Following is a consideration when creating an Integration Object in a DBCS project. For more information, see Creating an Integration Object.

When naming a macro used to create an Integration Object, double-byte (fullwidth) characters are not allowed.

Working with mobile device applications

On Internet Explorer Mobile, changes to input fields for DBCS supported features are made when the input field loses focus, that is, when the blur event occurs. This is different from support on desktop browsers where changes are made in real time using the key event.

For data type checking, all characters beginning with the first illegal character are stripped from the input field when the input field loses focus, that is, when the blur event occurs.

For more information, see Developing ZIETrans applications for mobile devices.

Remapping keyboard and display characters

You can use ZIETrans support for Host On-Demand custom tables to remap the user's keyboard and display characters by customizing the code page conversion tables. For more information, see Remapping keyboard and display characters.

Working with user-defined characters

DBCS languages consist of ideographic characters instead of phonetic alphabets. Thousands of ideographic characters are used in these languages, and currently defined code pages or fonts do not always meet the requirements for these characters. User-defined characters (UDCs) are used to support the necessary characters that are not defined in code pages or fonts. Using the UDC mapping editor, you can assign a local code point from the User-Defined Area (UDA) to a specified host code point that is reserved for this character.

The ZIETrans UDC functions support 3270, 3270E, and 5250 connection types. You use ZIETrans UDC mapping support to display UDCs for 3270, 3270E, and 5250 connections, and you use ZIETrans font-image support to print UDCs in either PDF or PDT mode for 3270E connections.

Display support

To enable UDC display support for 3270, 3270E, and 5250 connections, follow these steps:

  1. Launch the UDC wizard.
    1. In the ZIETrans Projects view, edit the connection in your DBCS project.
    2. In the connection editor, click the Advanced tab.
    3. On the Advanced tab, click Set Up User-Defined Characters (UDC) Files.
  2. On the Select default mapping table page:
    1. Select Enable UDC mapping support.
    2. To launch the mapping editor for the code page defined for the connection, select Launch UDC mapping editor and click Launch. Use the mapping editor to make your changes. When you save your UDC changes, a mapping table file with the .gtt file extension is stored in the <RationalSDP_install_directory>\ZIETrans\UDC\udctransl\ directory. The following code pages are supported:
      Table 16. UDC mapping editor supported code pages
      Code page Location or usage
      930 Japanese (Katakana)
      930 Japan (Katakana Extended)
      933 Korea (Extended)
      937 Taiwan (Traditional Chinese Extended)
      939 Japanese (Latin Extended)
      1364 Korea Euro
      1371 Taiwan (Traditional Chinese) Euro
      1388 PRC (Simplified Chinese Extended; GB18030)
      1390 Japanese (Katakana Unicode Extended)
      1399 Japanese (Latin Unicode Extended)
    3. To import an existing mapping table directory, for example, one that was created using the Host On-Demand product, select Import available UDC mapping table directory and click Browse. A valid mapping table directory must contain one mapping index file (udctables.inx) and some mapping table files (*.gtt).
    4. From the Select default mapping table section, select the table to use as the default. If necessary, click Refresh List to refresh the list of tables displayed.
    5. Click Next.
  3. On the Summary page, notice all of the setup information. Click Back to make any changes. Otherwise, click Finish.

When you click Finish in the UDC wizard, ZIETrans copies the related UDC files to the appropriate ZIETrans project and updates the UDC_SETTING and UDC_TABLE_SELECTION advanced connection settings in your project.

Print support

To enable UDC print support for 3270E connections, follow these steps:

  1. Launch the UDC wizard.
    1. In the ZIETrans Projects view, edit the connection in your DBCS project.
    2. In the connection editor, click the Advanced tab.
    3. On the Advanced tab, click Set Up User-Defined Characters (UDC) Files.
  2. On the Select default mapping table page, click Next.
  3. On the Select font-image file page:
    1. To convert Windows user-defined fonts into a usable font-image file, select the appropriate conversion tool from the UDC font-image conversion tool drop-down, and click Launch.
      Notes:
      1. For the Japanese Windows 2000 operating system, select the Japanese Windows 2000 conversion tool, otherwise, select the Standard conversion tool.
      2. If you use the Japanese Windows 2000 tool to convert the UDCs on Windows 2000, all the UDCs defined by Unicode are converted. ZIETrans can print not only the UDCs defined in local workstation codes (a total of 1880 characters), but also those defined in Unicode including the host UDCs (0x6941-0x89BD for code pages 930 and 939, and 0x6941-0x7FFE for code pages 1390 and 1399).
    2. Using the conversion tool, click Convert to create a font-image file and save it. The name of the file depends on the operating system platform as shown in the following table.
      Table 17. Font-image filenames
      Platform Font-image filename
      Japanese Windows jpn24.fnt
      Korean Windows kor24.fnt
      Simplified Chinese Windows chs24.fnt
      Traditional Chinese Windows cht24.fnt
    3. To select the font-image file to use in your ZIETrans application, click Browse and browse for the file you created using the conversion tool. If you want to use a font-image file previously created using the Host On-Demand product, browse for it instead.
    4. Click Next.
  4. On the Summary page, notice all of the setup information. Click Back to make any changes. Otherwise, click Finish.

When you click Finish, ZIETrans copies the related UDC files to the appropriate ZIETrans project.

Printing UDCs in Adobe PDF mode

To print UDCs in Adobe PDF mode, configure these settings on the Printing tab of the connection settings editor:

  1. Select Default printing (Adobe PDF Format) from the drop-down list in the Initialize Print Settings section.
  2. Click Initialize.
  3. Use the following default values in the Name/Value table:
    Table 18. Name/Value table settings
    Name Value
    printDestination false
    printMimeType application/pdf
    printSaveAsExtension .pdf
    separateFiles true
    useAdobePDF true
    usePDT false
    useWindowsPrinter false

Printing UDCs in PDT mode

To print UDCs in PDT mode, configure these settings on the Printing tab of the connection settings editor:

  1. Select Basic text files (Plain text format) from the drop-down list in the Initialize Print Settings section.
  2. Click Initialize.
  3. Set the following values in the Name/Value table:
    Table 19. Name/Value table settings
    Name Value
    PDTFile The path to the PDTfile, for example, MyPDT/PDTFileName.hodpdt. See below the table of PDT file names to use depending on your code page and supported PDT printers.
    printDestination false
    printMimeType application/octet-stream
    printSaveAsExtension .out
    separateFiles true
    useAdobePDF false
    usePDT true
    useWindowsPrinter false
    Note:
    The following table shows the PDT file names to use for the PDTFile setting in the Name/Value table, depending on your code page and supported PDT printers. For information about using the Host On-Demand PDT compiler, see Using the Host On-Demand PDT compiler.
    Table 20. PDT file names
    Code page Supported PDT printer PDT file name
    930 Japanese (Katakana)
    930 Japan (Katakana Extended)
    939 Japan (Latin Extended)
    1390 Japanese
    (Katakana Unicode Extended)
    1399 Japanese
    (Latin Unicode Extended)
    ASCII text mode /pdfpdt/basic_dbcs.hodpdt
    Printers based on ESC/P 24-J84 /pdfpdt/esc_p.hodpdt
    IBM® 5577-B02,F02,G02,H02 /pdfpdt/ibm5577.hodpdt
    IBM 5585-H01 Printer /pdfpdt/ibm5585.hodpdt
    IBM 5587-G01,H01 (without advanced function) /pdfpdt/ibm5587.hodpdt
    Lips3a4 Printer /pdfpdt/lips3a4.hodpdt
    Lips3b4 Printer /pdfpdt/lips3b4.hodpdt
    933 Korea (Extended)
    1364 Korea Euro
    Korea IBM 5577 Printer /pdfpdt/ibm5577k.hodpdt
    Ks_jo Printer /pdfpdt/ks_jo.hodpdt
    Ks_wan Printer /pdfpdt/ks_wan.hodpdt
    Kssm_jo Printer /pdfpdt/kssm_jo.hodpdt
    Kssm_wan Printer /pdfpdt/kssm_wan.hodpdt
    937 Taiwan
    (Traditional Chinese Extended)
    1371 Taiwan
    (Traditional Chinese) Euro
    Traditional Chinese ESC/P Printer (5550) /pdfpdt/esc_5550.hodpdt
    Traditional Chinese ESC/P Printer (big-5) /pdfpdt/esc_big5.hodpdt
    Traditional Chinese ESC/P Printer (cns) /pdfpdt/esc_cns.hodpdt
    Traditional Chinese ESC/P Printer (tca) /pdfpdt/esc_tca.hodpdt
    Traditional Chinese IBM 5577 Printer (without advanced function) /pdfpdt/ibm5577t.hodpdt
    Traditional Chinese IBM 5585 Printer /pdfpdt/ibm5585t.hodpdt
    1388 PRC (Simplified Chinese Extended; GB18030) Simplified Chinese ESC/P Printer /pdfpdt/esc_pp.hodpdt

To print the file content in PDT mode with a local PDT printer, follow these steps:

  1. Download the PDT file from the ZIETrans print job list.
  2. At a DOS prompt, enter type xxxx.out > prn to send the file to the local PDT printer.

Limitations