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=helpWhen you customize this screen as RTL. it is displayed as:
TXET IDIB
pleh=10fpFrom 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=helpWhen 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.LabelWidgetBIDIpublic 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:
When editing a macro prompt (or extract) in the Visual Macro Editor or the host terminal, you can define the host screen orientation to use for the prompt (or extract) during macro playback at runtime. Options are Inherit from host screen capture, LTR, and RTL. Selecting Inherit from host screen capture uses the same screen orientation value defined for the host screen associated with the macro prompt (or extract). If no host screen is associated, this option is not available, and you must specify either LTR or RTL.
If a pre-HATS V8.0 macro is copied into a HATS V9.5 project, or if a pre-HATS V8.0 project is migrated to HATS V9.5, then if a host screen is associated with the macro prompt (or extract), the Inherit from host screen capture option is used. Otherwise, the default value of LTR is used.
For Hebrew VT bidirectional logical sessions, there are two cursor direction radio buttons (Left to right and Right to left) which provide control over input control orientation for prompt action while recording a macro. In the editor for the VT connection, click BIDI display options to display the radio buttons.
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.
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.
In addition to supporting Model 1 and JSF Web pages generated from Integration Objects, HATS provides bidirectional support for bottom-up traditional (WSDL-based) 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. These properties can be tested using tools such as sample JSP pages and the Web services explorer. For more information see the chapters, Creating traditional (WSDL-based) Web services and Using the HATS bidirectional API, in the HATS Web Application Programmer's Guide.
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.
When creating or updating Web service support files, on the Choose Properties page, where you select the input and output properties that you want exposed in the Web service, the following bidirectional input and output properties are selected by default. When exposed to the Web service, these properties can be changed by the consumer of the Web service.
RESTful Web services are supported for bidirectional sessions. When creating or updating RESTful service resources, on the Configure JAX-RS Resource Method page, where defaults are set that reflect the HTTP method and Integration Object you selected, the following bidirectional input and output method parameters are also set to their defaults.
You can change the settings for these method parameters to meet your requirements. For more information see the chapters, Creating RESTful Web services and Using the HATS bidirectional API, in the HATS Web Application Programmer's Guide
Communication between portlets is implemented in HATS using global variables. HATS global variables are stored in visual LTR format, which is typical for 3270 and 5250 systems. However, data stored in other operating system environments is typically stored in logical LTR format. This means that by default HATS portlets use bidirectional text strings stored in the visual LTR format, while non-HATS portlets may use logical LTR format for bidirectional text strings.
To enable the exchange of bidirectional text strings between HATS portlets (using visual LTR format) and non-HATS portlets (using logical LTR format), you must specify to HATS that format conversion is required. To do this in a sending HATS portlet, when adding or editing the Send Global Variable action, select Convert to logical bidi format. For more information, see Send global variable action. To do this in a receiving HATS portlet, when adding or editing the received property (JSR168) or event (JSR286), select Convert from logical bidi format. For more information, see Portlet settings.
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.
To start the HATS Toolkit development environment using the desired screen orientation, you can use the HATS Toolkit start menu items. Use of the Arabic translation of the HATS Toolkit is dependent on Arabic support provided by the underlying Rational SDP platform. When installed on an Arabic translation of Rational SDP, two HATS Toolkit start menu items are provided, HATS Toolkit (Arabic), which starts the Arabic translation of HATS Toolkit, and HATS Toolkit (English), which starts the English translation of HATS Toolkit. Search the Knowledge Center for your Rational SDP platform to determine if Arabic is supported.
If not using the HATS Toolkit start menu items, to specify the orientation to use for the HATS Toolkit , use the -nl or -dir Eclipse startup arguments as shown in the table below.
| Eclipse startup argument | HATS Toolkit orientation |
|---|---|
| -nl <BIDI locale> and the BIDI language pack is installed | right-to-left |
| -nl <BIDI locale> and the BIDI language pack is not installed | left-to-right |
| -nl <BIDI locale> -dir rtl | right-to-left |
| -dir rtl | right-to-left |
| -nl <BIDI locale> -dir ltr | left-to-right |
| -nl <non-BIDI locale> | left-to-right |
| -dir ltr | left-to-right |
For example, start the HATS Toolkit using eclipse.exe -OpenHatsPerspective -nl ar -dir rtl for Arabic. If no Eclipse startup arguments are specified, the HATS Toolkit orientation is left-to-right regardless of the development workstation locale.
In some cases, you might need to customize a template, transformation, or other JSP page, for example, the stop.jsp page, to create the desired direction. To do this, add the attributes dir=rtl and align=rtl to the HTML tags as appropriate. For example, for the stop.jsp page you could add dir=rtl to the <table> tag that surrounds the text of the stop.jsp page.
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: