This chapter explains how to use the functions provided by HATS for developing applications in bidirectional languages. Generally its contents apply to both Hebrew and Arabic application developers. The functions that are specific to Arabic users are described separately.
HATS provides these functions to support bidirectional languages:
This chapter explains all these features.
Following are requirements for bidirectional application support:
To support correct bidirectional data input, UTF-8 must be specified. For instructions about how to do this, see Encoding settings.
The HATS host terminal allows Host On-Demand bidirectional-specific keystrokes, therefore you can perform the following bidirectional functions. The following host function keys are available for both 3270, 5250 and VT sessions:
The following host function keys are available only for 3270 sessions:
The following host function key is available only for 5250 sessions:
The following host function keys are available only for Arabic VT sessions:
The following host function keys are available only for Hebrew VT sessions:
There is no support for Unicode fields in the Host Terminal; therefore, switching languages in Unicode fields is not possible.
Complex text, containing both bidirectional text and numbers, should not be used as screen recognition criteria.
In bidirectional sessions, screens can be captured either as left-to-right screens or as right-to-left screens. Captured screens are displayed exactly as they were captured. To capture a screen as a right-to-left screen, press Ctrl+S (Screen reverse) in a left-to-right screen and click Create Screen Capture.
Typically the orientation of a host component is the same as the screen orientation. However, in some cases, the orientation of a host component is the opposite of the general orientation of the screen. When a HATS project uses a bidirectional code page, a check box labeled Recognize component oriented opposite to screen is added to the Insert Host Component wizard and the Create a Screen Combination wizard. When you add a host component to a transformation, select this box if the host component's orientation is the opposite of the screen orientation. Selecting the box enables HATS to recognize command prompts, function keys, selection lists, subfile, and input fields with hints whose orientation is the opposite of the screen orientation.
Mixed bidirectional text may be used in function key and selection list settings. This means that strings like: BIDI1 = BIDI2, where BIDI1 and BIDI2 are segments of bidirectional text, may be recognized as function keys and selection lists .
By default, only left-to-right components may be recognized in default rendering of screens (as in an English session). However, selection of the Recognize component oriented opposite to screen property in the Project Settings editor, on the Rendering tab in the Default Rendering section will enable recognition of both left-to-right and right-to-left components in default rendering.
Also by default, components on a screen transformation are recognized only according to the screen orientation. At the project level you can specify that if a component is not recognized, HATS should try to recognize it using the opposite screen orientation. To make this specification, in the Project editor on the Rendering tab in the Advanced section under Default Rendering, select the Recognize component oriented opposite to screen check box. If this selection is made and the component is still not recognized, then rendering will follow the specification made with the setting, Use default rendering on component rendering failure.
You can also specify this setting at the component level. To do so, when you add a component to a transformation using the Insert Host Component wizard, on the Rendering Options panel, click the Advanced settings for rendering button, and select the Recognize component oriented opposite to screen box. The value of this setting at the component level is not inherited from the project setting. The following table shows the possible combinations of this setting at the project and component levels and which setting is used. For more general information see Advanced rendering.
| Project setting | Component setting | Setting used |
|---|---|---|
| cleared | cleared | component |
| cleared | selected | component |
| selected | cleared | project |
| selected | selected | component |
There are two special check boxes that provide you control over widget presentation when your application runs in the WebSphere® Application Server. This control applies to:
These two check boxes are:
On a left-to-right screen, when the Reverse widget's orientation check box is selected, the GUI image is changed to be right-to-left. Similarly, when the Reverse text in widget check box is selected, the text within the GUI image is changed to right-to-left.
For example, suppose you have the left-to-right screen that contains the following text (upper case letters are bidirectional data and lower case letters remain as English data):
BIDI TEXT pf01=help
When you customize this screen as RTL. it is displayed as:
TXET IDIB pleh=10fp
From the user's point of view, everything is correct except the function key. The function key is recognized, but it is displayed backwards.
For the customized screen to appear correctly, you must select both the Reverse widget's orientation and the Reverse text in widget check boxes when inserting the function key host component into a customized screen.
When you do this, the screen is displayed as:
TXET IDIB pf01=help
When you replace a text input field with a drop-down list in a bidirectional project, the captions of the drop-down list items are not affected by the screen orientation . The captions will always appear in visual LTR format, unless you select the Reverse text in widget check box for the widget. In that case the captions will be appear in visual RTL format.
Also, when creating bidirectional HATS applications, and copying and pasting multiple lines of text from a protected field into a visual input field, the text may be reversed. If you copy and paste one line at a time, the orientation will be preserved.
To assign the proper alignment of widgets containing HATS component elements, a Component Alignment setting is available on the following HATS configuration panels:
In addition, to assign the proper alignment of individual widgets, Field Alignment and Table Alignment settings are available in the widget settings dialog of the Rendering Options wizard for the Field and Table widgets.
The values of these settings are left and right. The Component Alignment setting in the project settings affects the alignment of all widgets in the project. The value set in the project settings becomes the default for the Create a Transformation and Create a Screen Customization wizards. The alignment specified for an individual widget overrides the value specified for default rendering.
Bidirectional counterparts should be used when customizing new components and widgets, for example in Web projects:
import com.ibm.hats.transform.widgets.BIDI.LabelWidgetBIDI
public class newBIDILabel extends LabelWidgetBIDI implements HTMLRenderer
When global variables are extracted, the extracted data is exactly the data that appears on the screen, including the orientation of the current screen. Any global variables inserted onto a screen as an action of a screen event are inserted according to the screen orientation.
In both Web and rich client applications, bidirectional data from static text and input fields is stored in global variables in visual format, in both the Rational SDP and runtime environments.
When you use the Insert Global Variable wizard to insert a global variable value as static text into a transformation for a bidirectional screen, you have the option to Insert global variable in visual format. Select this option to insert the global variable value as static text in visual format. Clear this option to insert the value as static text in logical format.
When global variables are extracted from logical VT sessions, the extracted data is converted to visual format. Any global variables inserted onto a VT logical sessions, are converted to logical format. Text direction is set according to screen orientation.
When you use text replacement in bidirectional sessions on a project level or HATS component tag level, there are three additional check boxes you can use:
If you select this box and the Match on RTL screens check box, the reversed string would match in a left-to-right screen. When the Screen reverse button is clicked on a right-to-left screen, data is consistent.
You must select either Match on LTR screen or Match on RTL screens.
For example, suppose a left-to-right host screen contains the text: NO on. If you define text replacement to replace no with yes and ignore the case, the results depend on the boxes you selected, as follows:
| Options selected | LTR screen | RTL screen |
|---|---|---|
| Match LTR screen only | yes on | no ON |
| Match RTL screen only | NO on | yes ON |
| Match LTR screen and RTL screen | yes on | yes ON |
| Match LTR screen and match screen reverse | yes on | no sey |
| Match RTL screen and match screen reverse | NO sey | yes ON |
| Match LTR and RTL screen and match screen reverse | yes sey | yes sey |
When you use either project-level or screen-level global rules in bidirectional sessions, there are three additional check boxes you can use (similar to text replacement):
If you select this box and the Match on RTL screens check box, the reversed string would match in a left-to-right screen. When the Screen reverse button is clicked on a right-to-left screen, the data is consistent.
For more information, see Table 17.
In the application keypad settings you can provide a Screen reverse button on bidirectional transformations for the convenience of your users. The button appears on the application keypad (for Web applications) and on the Transformation view toolbar (for rich client applications). Clicking the button toggles the screen orientation--the operation performed on host systems by pressing the Alt+Enter keys.
At the project level you can include the Screen reverse button in the Application keypad section of the Rendering tab in the Project editor. At the transformation level you can include the Screen reverse button using the Insert Application Keypad functions in the transformation editor.
When you create a new HATS project and select a bidirectional code page, two additional check boxes appear on the Connection Setting panel: Enable screen reverse for non-customized screens and Enable screen reverse for customized screens. These check boxes determine whether the Screen reverse button you provide appears on these screens. By default, both boxes are selected. If you select the first box, the second box is enabled. There is no way to select only the second box.
A non-customized screen is one that is not matched by any screen customization. A non-customized screen, when viewed by the user, has the same screen orientation as the previous screen. If the first screen is non-customized, its screen orientation is left-to-right. If the screen orientation is changed on a previous screen, it is inherited by the next non-customized screen and reset by the next customized screen.
The initial screen orientation of customized screens is the same as it was when the screens were customized. For both customized and non-customized screens, clicking the Screen reverse button changes the screen orientation. During screen recognition, a reversed screen is considered different from the same screen before the screen has been reversed. Therefore, the Screen reverse button can cause a screen not to be recognized. If the developer is confident that all host components that appear on a customized screen are oriented properly, there is no need to enable the Screen reverse button for that screen. It is advisable to disable the Screen reverse button for customized screens.
Enabling the Screen reverse button to the user of an Arabic application will enable another check box to control shaping orientation. For more information see: Functions for Arabic code pages
For VT bidirectional sessions, some specific bidirectional properties need to be set to the terminal to work correctly for bidirectional users. A VT BIDI display options button which appears in the Connection Settings panel is added to access these options:
For VT bidirectional logical sessions, there are two radio buttons (LTR direction or RTL direction) which provide the application developer control over input control orientation (LTR implicit or RTL implicit) for prompt action while recording a macro.
The default input control orientation is the LTR direction which implies that the prompt value is in LTR implicit format.
In the SQL wizard for bidirectional languages (Arabic and Hebrew), specific bidirectional properties need to be set. You can access these settings by clicking the Advanced button in the Advanced Macro editor panel. This panel is visible only if your workstation is configured for a bidirectional language. The following settings are available:
Bidirectional files can be either RTL or LTR files and in order to print correct RTL data, you must select the Enable RTL Printing check box which appears on the Printing tab of the Connection editor for the bidirectional 3270E default connection. Both PDF and non-PDF files are supported.
This check box is enabled if printing is enabled.
In the case of Arabic applications, enabling RTL printing enables the following two check boxes.
Bidirectional support for BMS maps includes:
Integration Object support includes extending the Integration Object bean with bidirectional-specific properties that allow such things as reordering extracted text. For more information see the chapter, Using the HATS bidirectional API, in the HATS Web Application Programmer's Guide.
Support for Integration Object Web pages (Model 1 and JSF) includes the correct reordering of extracted/inserted data in runtime and full control by the application developer over screen and extraction/insertion controls orientation using a high level GUI.
Support includes the following capabilities:
You are also provided the ability to select either a Visual or Logical text interface using the Input Text and Output Text radio button options.
Selecting the Visual interface for input text allows data to be entered into input field prompts in visual input field format. Selecting the Visual interface for output text allows extracted results to be displayed in visual field format.
If Logical output is chosen, then you can select the Prevent Round Trip option to use bidirectional marks to achieve correct reordering of mixed bidirectional text.
Extraction from the host screen can cause four common situations:
In addition to supporting Model 1 and JSF Web pages generated from Integration Objects, HATS provides bidirectional support for bottom-up Web services generated from Integration Objects. In this case, the Web service inherits all of the bidirectional functionality of the Integration Object. The Web service is extended by properties that allow such things as reordering extracted text. For more information see the chapter, Using the HATS bidirectional API, in the HATS Web Application Programmer's Guide. These properties can be tested using tools such as sample JSP pages and the Web services explorer.
Because sample JSP pages generated by the HATS Toolkit are Logical LTR applications, they display the results of the Web service properly only if you set to invoke prompt and extract reordering, and set RTL reordering in both cases to False. Otherwise, the result will display incorrectly. However, you may want to see the "incorrect" result to verify how changes of the properties' values affect the Web service.
If you need to see correct results for extract reordering other than Logical LTR with sample JSP pages, you may need to manually edit the Result.jsp file generated by the HATS Toolkit. Following the line with the <body> tag, insert the line, <div dir=rtl> for Logical RTL, <bdo dir=ltr> for Visual LTR, or <bdo dir=rtl> for Visual RTL.
Use of the Web services explorer for cases of reordering other than Logical LTR, is not recommended.
You may want to predefine values of bidirectional-specific properties, and control the possibility to override these values by the user. To set these values, click BIDI Options when service support files are generated from Integration Objects. If Allow user to override the values is selected, the predefined values are noticed if null or empty strings are set as parameters for corresponded properties.
HATS applications using bidirectional code pages offer a special input field called a visual input field. Unlike regular fields, which implement logical data input and presentation, the visual field implements visual data input and presentation. When entering data in a visual field, you can use these functions:
In left-to-right fields, typing a bidirectional character causes the automatic initiation of push. Typing any digit or Latin character causes the automatic termination of the mode. This enables the user to type Latin text with embedded bidirectional words by using language layer selection rather than push and end push.
You can initially enable or disable auto push mode using the Enable Auto Push mode initially setting. This setting is available in two places within the project editor. On the Overview tab, click the link to the current theme and use the Enable Auto Push mode initially setting. On the Other tab select the Client Settings section and use the Enable Auto Push mode initially setting.
Clipboard operations (such as copy, paste, and cut) with bidirectional data from platform logical editors into HATS visual field, and from HATS visual fields (including static text) into platform logical editors are enabled on Windows® platforms. Users working in Windows can use the clipboard to exchange data between HATS and other applications that use logical data.
Internet Explorer clipboard operations are supported both from the Edit option on the menu bar or with the help of shortcuts (Ctrl+C, Ctrl+X, Ctrl+V).
Clipboard bidirectional data support on Mozilla browsers on Windows platforms will be enabled only if these functions are invoked using the shortcuts.
In addition to session related information being displayed in the Operation Information Area (OIA), bidirectional sessions include information about screen and typing direction, active layer, auto field reverse mode status and shaping status (in Arabic sessions).
Bidirectional session (keyboard) related information is presented in a form similar to that used on the host system. To display this information in the OIA of a HATS transformation, in the Project Settings editor on the Rendering tab, select Operator Information Area and then select the Show OIA check box. When the Show OIA check box in the Project Settings editor is cleared, the HATS bidirectional status area is displayed in the status bar for Web applications, but not displayed anywhere for rich client applications.
For HATS Web projects, with this function you can simulate switching the keyboard layer between bidirectional and Latin languages automatically when the screen is reversed. The simulation is performed through the use of keyboard remapping. This forces insertion of Arabic/Hebrew or Latin characters in accordance with the field typing direction. For example, in a reversed screen, when text typing takes place from right to left, Arabic/Hebrew characters are inserted irrespective of the actual keyboard layer state. To enable this function, in the Project Settings editor, on the Overview tab, click the current theme and select Enable automatic keyboard layer switch. This setting can also be selected in the Project Settings editor on the Other tab in the Client Settings section.
HATS rich client projects always behave as if this function is enabled.
Bidirectional text that appears in Unicode fields that use 5250 systems is displayed and edited using contextual ordering scheme (according to the first strong character) instead of using visual input field.
These functions are specific to projects using Arabic code pages.
If you enable the Screen reverse button in the application keypad settings, the RTL Shaping button is also displayed for Arabic code page projects. Clicking the RTL Shaping button switches the state of RTL shaping on or off. Turning RTL shaping off informs HATS that the user is currently editing a LTR file independent of screen orientation. Turning RTL shaping on informs HATS that the user is currently editing a RTL file independent of screen orientation, thus the same Arabic shaped data can be submitted correctly in both screen orientations. You should ensure before editing and submitting an LTR file that RTL shaping is turned off and ensure that RTL shaping is turned on before editing and submitting an RTL file.
In some cases you may need to send your data to the host in isolated format. To meet such requirements a field disable shaping property has been added for Arabic sessions through two check boxes:
When you create a new HATS project and select an Arabic code page, this check box appears. It determines whether the shaping for password fields is enabled or disabled. Hence it determines if the Arabic data of password fields will be submitted to the host in isolated or shaped form.
This check box appears in the Insert Host Component wizard . It determines if the Arabic data, inside input fields in this selected region, will be submitted to the host in isolated or shaped form
These options are effective only in Arabic 3270 sessions. If symmetric swapping is enabled, swapping characters are swapped in right-to-left screens. If numeric swapping is enabled, English numerals are replaced by Arabic numerals in right-to-left screens and Arabic numerals are replaced by English numerals in right-to-left screens. These parameters are set on the Advanced tab of the connection editor in the Configure optional, advanced connection settings section. The parameters are identified as symmetricSwapEnabled and numericSwapEnabled, and the values of the parameters are either true or false.
The HATS host terminal is also affected by symmetric and numeric swapping parameters.
When you create a new HATS project, or when you create or edit a HATS connection, and select the Arabic Speaking code page 420, the setting, Disable entry of Arabic-Western digits in RTL screens, is displayed. Select this option to disable entry of Arabic-Western numbers, that is, allow entry of only Arabic-Indic numbers in RTL screens. Do this so that, when submitted, all numbers are submitted as Arabic-Western numbers.
The Arabic keyboard has two layouts, 101 keyboard layout and 102 keyboard layout, which are slightly different in some keys. When using the automatic keyboard layer switching function, the following mappings are performed:
The following limitations appear with both system keyboard layout English and the Arabic 101 keyboard:
These limitations disappear with the Arabic 102 keyboard.
When using an Arabic 102 keyboard, the following keyboard limitations appear:
In order to correctly display any of these characters, you will need to switch the keyboard layer to English.
For an Arabic session with right-to-left captured screens, brackets and numerals are affected by the symmetric and numeric swapping options of the application.
Following is a summary of the settings to present Arabic data properly on System i® Access for Web.
For Global settings:
SCS reports:
AFP reports:
When a project uses an Arabic code page, screen event (.evnt) files have an additional <orientation>true</orientation> tag within the description tag. A value of true indicates that the screen is customized as a right-to-left screen; otherwise it is customized as left-to-right.
When a project uses any bidirectional code page, the connection (.hco) file has an additional enableScrRev attribute of the <hodconnection> tag, that can have the following values:
When a project uses any Arabic code page, the connection (.hco) file has an additional disableFldShp attribute of the <hodconnection> tag that can have either true or false values
If printing is selected in 3270 session an additional printRTLSupport setting will appear in <classSetttings> tag. For Arabic 3270 sessions, another two settings will appear for symmetric and numeric swapping which are printSymSwapSuppot and printNumSwapSupport. All these printing settings have values of true or false equivalent to enable or disable of the feature.
When a project uses any bidirectional code page, the application (.hap) file has additional attributes for the <replace> tag within the <textReplacement> tag: