Double-byte character set support

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

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

• Data type checking
• Field length checking
• Copy-and-paste prevention
• Input Method Editor (IME)
• AutoIME switching
• Shift Out/Shift In considerations

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

DBCS and SBCS field support

HATS supports the following types of DBCS and SBCS fields.

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. HATS 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 HATS 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 HATS 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.

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. HATS supports use of the IME for committing double-byte characters into HATS fields.

If the user tries to enter characters into the IME that exceed the maximum length of the rendered HATS 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. HATS 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.

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 HATS Integration Objects, use the omitSOSI Host On-Demand session parameter. This parameter can have a value of true or false. If true, the HATS Integration Object omits the SO/SI characters for the connection. If false (the default), the HATS 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 HATS 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 HATS 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

• If the Enable automatic field advance setting in the Project settings editor on the Rendering tab in the Client Settings section is selected, then characters that exceed the maximum length of the DBCS field can be entered into the IME. Also, when the user selects the IME candidate for the field, the excess characters are cut and pasted into the next field.
• If the Enable automatic field advance setting is not selected, then characters that exceed the length of the DBCS field can be entered into the IME. However, when the user selects the IME candidate for the field, the excess characters are removed and not entered into any other field.

This setting is supported for the following field types:

• 3270
  • DBCS mix
  • DBCS only (G)
• 5250
  • DBCS only (J)
  • DBCS graphic (G)
  • DBCS either (E)
  • DBCS open (O)

Notes:

1. This setting is available only for DBCS code pages in Web projects, including portlet projects.
2. This setting is supported only for Internet Explorer.

Set default ATOK Input Mode to Roman  RCP-only 

Select this box to set the ATOK default input mode to Roman. If not selected, the ATOK default input mode is set to Hanji. Valid only for rich client platform applications.

Other tab

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

Enable automatic field advance

For HATS 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 HATS 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.

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.

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 HATS 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

• If the Enable automatic field advance setting in the Project settings editor on the Rendering tab in the Client Settings section is selected, then characters that exceed the maximum length of the SBCS field can be entered into the IME. Also, when the user selects the IME candidate for the field, the excess characters are cut and pasted into the next field.
• If the Enable automatic field advance setting is not selected, then characters that exceed the length of the SBCS field can be entered into the IME. However, when the user selects the IME candidate for the field, the excess characters are removed and not entered into any other field.

This setting is supported for the following widgets:

• Calendar
• Field
• Popup
• Subfile (check box)
• Subfile (drop-down)
• Subfile (popup)
• Table
• Text input

This setting is supported for the following field types:

• 3270
  • Alpha numeric
• 5250
  • Katakana (W)
  • Alpha numeric (A)
  • Float (F)
  • Numeric shift (N)

Notes:

1. This setting is supported only for DBCS code pages in Web projects, including portlet 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, HATS 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 HATS applications for mobile devices.

Remapping keyboard and display characters

You can use HATS 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 HATS UDC functions support 3270, 3270E, and 5250 connection types. You use HATS UDC mapping support to display UDCs for 3270, 3270E, and 5250 connections, and you use HATS 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 HATS 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>\hats\UDC\udctransl\ directory. The following code pages are supported:

      Table 20. 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, HATS copies the related UDC files to the appropriate HATS 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 HATS 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. HATS 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 21. 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 HATS 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, HATS copies the related UDC files to the appropriate HATS 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 22. 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 23. 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 24. 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 HATS print job list.
2. At a DOS prompt, enter type xxxx.out > prn to send the file to the local PDT printer.

Limitations

• UDC conversion tool limitations:
  • In a Traditional Chinese Windows environment, there are 13 more UDCs than IBM's Big5 UDCs. Therefore, if the last 13 UDCs are defined in the range of 0xC8F2-0xC8FE, they are ignored by the utility and cannot be used.
  • In a Korean Windows environment, only local code page 949 is supported. You can define and print 188 UDCs in the ranges of 0xC9A1-0xC0FE and 0xFEA1-0xFEFE.
• Since User-Defined Area (UDA) ranges are defined based on Windows platforms, UDCs can only be displayed in Windows platforms.