Bidirectional application support

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.

Software environment

In order to support correct bidirectional data input in the Run on Server, follow these steps:

Working with the host terminal

The HATS host terminal allows Host On-Demand bidirectional-specific keystrokes, so you can perform the following bidirectional functions. The following host function keys are available for both 3270, 5250 and VT sessions:

Host terminal limitations

For Arabic users only the following limitations appear with both System keyboard layout English and Arabic 101:

In order to correctly display any of these characters, you will need to switch the keyboard layer to English.

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.

Capturing screens

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.

Recognizing bidirectional host components

Usually 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 Component orientation opposite to screen orientation is added to the Insert Host Component wizard. When you add a host component to a transformation, check this box if the host component's orientation is the opposite of the screen orientation. Checking the box enables HATS to recognize command prompts, function keys, selection lists, subfile, and InputWithHints whose orientation is the opposite of the screen orientation.

Mixed bidirectional text may be used in Selection lists and Function keys settings. It 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 uncustomized screens (as in an English session). However, selection of "recognition of RightToLeft components" property in the Project Settings dialog, under the Rendering Settings tab will enable recognition of both left-to-right and right-to-left components in uncustomized screens ( default rendering).

Controlling the orientation of widgets

There are two special check boxes that provide you, the bidirectional application developer, control over widget presentation when your application runs in the WebSphere Application Server:

On a left-to-right screen, when the Widget Orientation check box is selected, the GUI image is changed to be right-to-left. Similarly, when the Text Orientation check box is selected, the text within the GUI image is changed to left-to-right. By default, selection of the Widget Orientation check box causes the Text Orientation check box to be selected also. However, you can deselect this check box if desired.

For example, suppose you have the left-to-right screen that contains following text (capital letters are bidirectional data and lower case letters remain as English data):

You will customize this screen as RTL. When your application runs, the screen is displayed as:

From the end user 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, select the Widget Orientation opposite to Screen Orientation check box when inserting the function key host component into a customized screen. By default, the Text Orientation opposite to Screen Orientation check box is also selected.

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

Customized components and widgets bidirectional support

Bidirectional counterparts should be used when customizing new components and widgets, for example:

Global variables

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 customization are inserted according to the screen orientation.

Text replacement

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:

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 checked, as follows:

Global Rules

When you use global rules in bidirectional sessions, there are three additional check boxes you can use (similar to text replacement):

Enabling the user to reverse the screen direction

You can provide a Screen Reverse button on bidirectional Web pages for the convenience of your end users. The button appears on the application keypad in the template. Clicking the button toggles the screen orientation--the operation performed on legacy systems by pressing the Alt+Enter keys.

When you create a new HATS project and select a bidirectional code page, two additional check boxes appear: Enable screen reverse for uncustomized screens and Enable screen reverse for customized screens. These check boxes determine whether the Screen Reverse button appears on these screens. Initially, only the first box is enabled. If you check the first box, the second box is enabled. There is no way to check only the second box.

An uncustomized screen is one that was not matched by any screen customization. An uncustomized screen, when viewed by the end user, has the same screen orientation as the previous screen. If the first screen is uncustomized, it defaults to left-to-right. If the screen orientation was changed on a previous screen, it is inherited by the next uncustomized 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 uncustomized screens, clicking Screen Reverse changes the screen orientation. During screen recognition, a reversed screen is considered different from the same screen before the screen has been reversed. Therefore, Screen Reverse could 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.

Table 10. Bidirectional text replacement options and results
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 reversed screen	yes on	no sey
Match RTL screen and match reversed screen	NO sey	yes ON
Match LTR and RTL screen and match reversed screen	yes sey	yes sey

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

VT bidirectional display options

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:

Prompt action orientation

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.

Macro SQL query bidirectional options

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:

Right-To-Left printing support

Bidirectional files could be either RTL or LTR files and in order to print correct RTL data, the developer should check the Enable RTL printing check box which appears in the Advanced tab under Connection > Main settings in bidirectional 3270 sessions

In case of Arabic Applications, enabling RTL printing will enable the following two check boxes.

BMS Maps support

The check box will only appear if the BMS map is imported as a bidirectional map.

Integration Objects support

Integration Objects bidirectional support means the correct reordering of extracted/inserted data in runtime and full control by the application developer over screen and extraction/insertion controls orientation using high level GUI.

Note:

The alignment of text in tables for (2) and (3) may not render correctly when working with JSF Web pages. This is a limitations of the JSF design.

Information for end users

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:

Alt+Shift: Language selection: This key combination toggles the language layer back and forth between Latin and the bidirectional language.
Alt+Enter: Screen reverse: This key combination reverses the direction of the screen.
Shift+NumLock: Push: You can enter and edit text whose direction is opposite from the field direction.
Shift+NumPad "/" character: End push: Push mode is ended and the cursor moves to the end of the push segment.
Alt+NumPad "/" character: Auto push: You can type mixed left-to-right and right-to-left text by changing the language layer. Autopush is especially useful for typing digits in right-to-left fields. The push and end push functions are automatically activated according to the language of the text being typed. In right-to-left fields, typing a digit or a Latin letter causes the automatic initiation of push, without a language change. Additional Latin letters or digits will continue the push mode; any other character automatically terminates push mode. This feature allows you to type bidirectional text with imbedded numbers or Latin words without using push and end push. 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 end user to type Latin text with imbedded bidirectional words by using language layer selection rather than push and end push.

Auto Field Reverse

Alt+NumPad 5

When auto field reverse is enabled, upon initial entry to an alphanumeric field, the field orientation will be set to right-to-left (for both left-to-right and right-to-left screen orientations).
When auto field reverse is enabled, upon initial entry to a numeric field, the field orientation will be set to left-to-right (for both left-to-right and right-to-left screen orientations).
When auto field reverse is disabled, upon initial entry to a field (whether numeric or alphanumeric), the field orientation is always set equal to the screen orientation.

When Auto Field Reverse is activated all fields, with the exception of password fields will have the same (described above) behavior. In 3270 sessions right-to-left screens, auto field reverse is the default mode of operation.

Field Reverse

Alt+Numlock: When field reverse is activated, typing orientation in current (focused) field will be changed. If the field is empty, cursor will be adjusted to the opposite side of the field. When field is not empty, the cursor position will not change. Field reverse is active only in the current field. When focus is lost, the typing orientation returns to its previous value.

Clipboard functions

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.

Operator Information Area (OIA)

In addition to session related information being displayed in English 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. When the Turn OIA support on check box in Project settings is unchecked, the HATS bidirectional status area will be presented in the status bar which contains the same data as the OIA.

iSeries 5250 Unicode support

Bidirectional text that appears in Unicode fields that use 5250 systems will now be processed correctly. Instead of using visual input field these fields will have a contextual orientation (according to first strong character).

Portal limitation

Multiple bidirectional HATS portlets are not supported in the same browser page. Only a single bidirectional HATS portlet can run in a browser page.

Functions for Arabic code pages

These functions are specific to projects using Arabic code pages.

Shaping Direction

In some cases users would like to edit a file in both screen orientations. In the previous HATS release the shaping of submitted Arabic data was dependent on runtime screen orientation. So that a LTR file "File initially created and saved in a LTR screen" should be edited only in a LTR screen and a RTL file "File initially created and saved in a RTL screen" should be edited only in RTL screen to ensure correct shaping of Arabic data.

A RTL Shaping button has been added in HATS V6 on Windows to remove this limitation. Clicking this 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 could be submitted correctly in both screen orientations, without the drawback of submitting wrong shapes in previous release.

Arabic users should ensure before editing and submitting LTR file that RTL shaping is turned off. They should also ensure that RTL shaping is turned on before editing and submitting RTL file. This button appears only if you enable the screen reverse button while configuring the application in Rational Studio.

Arabic selective shaping

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 2 check boxes:

Disable shaping for password fields:
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.
Disable field shaping:
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

Symmetric and numeric swapping

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 Connection Settings tab of the project editor. HATS host terminal is affected by symmetric and numeric swapping parameters set by the user when creating the application. The parameters are identified respectively as symmetricSwapEnabled and numericSwapEnabled, and the values of the parameters are either true or false.

Screen captures

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. With WebSphere Studio Application Developer Version 4, to correctly view Arabic numbers, the digit substitution should be set to "Contextual" in the regional settings.

Note:

In Arabic sessions, the Euro sign is displayed as a block in a captured screen.

Setting Arabic printing sessions on iSeries Access for Web

Following is a summary of the settings to present Arabic data properly on iSeries Access for Web.

For Global settings:

System value QCCSID (37). This is for the English language to allow the HTTP, TomCat, and background server to start properly if they need to use POSIX characters not represented in code page 420.

SCS reports:

The report's code page is picked up from spool file's Character set identifier (CHRID) reflected in the printer file parameter (CHRID) that is picked up from the device description then system value. To display Arabic characters properly if the system value QCCSID is not set to 420 perform the following:
1. CHGPRTF or OVRPRTF with the Character identifier parameter CHRID(235 420). Graphic character set 235 and Code page 420.
2. Regenerate the spool file.

AFP reports:

Add the fonts and overlay report to the resource library list in one of the two methods:
- Add the library QFNTAR3 to system library list system value QSYSLIBL
- Add the resource libraries containing the overlays and fonts to the printer file parameter: User resource library list USRRSCLIBL. This parameter overrides the system value setting above and does not check the rest of the libraries defined in system library list
Regenerate the spool file.

Other considerations

To view Arabic numbers correctly in widget previews and in the deployed HATS application, digit substitution should be set to "None" in the regional settings.
Screen recognition should always be done with whole Arabic words and not with a part of an Arabic word.
Bidirectional functions are not supported in the transformation design, this is due to a limitation in the WebSphere Studio V5 JSP design with bidirectional data.
Bidirectional i5/OS input restrictions are not supported in password fields in Arabic sessions.

Additions to HATS files

When a project uses an Arabic code page, screen customization 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:

(blank): The Screen Reverse button is not placed on any screens.
NotCustomized: The Screen Reverse button is placed only on screens that do not match a screen customization.
Customized: The Screen Reverse button is placed on all screens.

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 checked 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:

matchLTR: Text is to be replaced when the screen orientation is left-to-right.
matchRTL: Text is to be replaced when the screen orientation is right-to-left.
matchReverse: Text is to be replaced when the screen orientation is reversed.