Working with bidirectional data

Bidirectional (bidi) languages such as Arabic and Hebrew are languages in which the text is presented to the user ordered from right to left, but numbers and Latin alphabetic strings within the text are presented left to right. In addition, the order in which characters appear within program variables can vary. In COBOL environments, the text in program variables is usually in visual order, which is the same order in which the text appears on the user interface. In Java™ environments, the text is usually stored in logical order, the order in which the characters are entered in the input field.

These differences in the ordering scheme, text orientation, and other bidirectional format characteristics require the program to convert bidirectional text strings from one format to another:
  • To control the format of bidirectional text strings in FormGroup fields, use a bidirectional runtime file.
  • To control the format of bidirectional text strings between a server and client, use a bidirectional conversion table.
Note:
When migrating bidirectional literal strings from another programming language into EGL, the strings must be in logical (input) order before migration.

Bidirectional runtime file

The bidiRuntime build descriptor option specifies a bidirectional runtime file. This file, in XML format, contains a set of options that control the bidirectional behavior for the fields in the form groups associated with an application. Several of these options correspond to existing bidi properties:

Before the bidirectional runtime file was added to EGL (prior to version 7.5), individual properties controlled this behavior. Those properties are still part of EGL. If your code associates these individual properties with a FormGroup, changing the runtime file will cause EGL to change the values of the individual properties accordingly. If you change the individual properties, EGL uses the new values, but does not update the runtime file.

For information on how to set up the bidirectional runtime file, see Creating a bidirectional runtime file.

Bidirectional conversion table

EGL uses a bidirectional conversion table (BCT) to perform conversions between "server" and "client" formats. The file is in XML format and has a file extension of .bct. You can create multiple BCTs to support different bidi format conversions, using an EGL wizard. The program references the name of the conversion table to indicate how attribute conversion should be performed.

In all cases, the bidi conversion table reference is specified as the 1- to 4-character file name with the .bct extension. For example, if you have created a bidi conversion table named hct1.bct, you can set the value of formConversionTable in a program by adding the following statement at the beginning of the program:
  sysVar.formConversionTable = "hct1.bct" ;
To use a bidi conversion table, you must do the following:
  • Create bidi conversion tables that specify the transformations that should occur. Note that different tables are needed for converting data being passed between a Java™ client and a COBOL host and for converting data to be displayed in a text or print form in a Java™ environment. You build the bidi conversion table file using the bidi conversion table wizard. For more information, see Creating a bidirectional conversion table.
  • Specify the bidi conversion table for use in generation. The way in which you specify the bidi conversion table differs depending on the code you are generating:
    • When you generate for a COBOL environment, do the following:
      1. Set the bidiConversionTable build descriptor option to the name of the bidi conversion table you created for COBOL generation. The bidi conversion table controls the transformation of literal text from logical to visual order for the COBOL environment, along with any other formatting transformation requested in the table.
      2. Set the clientCodeSet and serverCodeSet build descriptor options to control the conversion of the code page from ASCII to EBCDIC as shown in the next table.
        Table 1. clientCodeSet and serverCodeSet build descriptor option values
        Language clientCodeSet serverCodeSet
        Arabic IBM-864 IBM-420
        Hebrew IBM-1255 IBM-424
    • When you generate a Java™ program that calls a remote COBOL program, customize the linkage options part so that the conversionTable property is in the callLink element for the called program, using one of the following options:
      • Specify a bidi conversion table as the value of that property (for example, conversionTable="hct.bct")
      • Set the property to PROGRAMCONTROLLED, which means that the calling program specifies the bidi conversion table before calling the other program. The caller specifies the table by assigning the bidi conversion table name to the sysVar.callConversionTable system variable. You can find more information about the sysVar.callConversionTable system variable in the topic "callConversionTable" in the EGL Language Reference.
    • When specifying EGL bindings for a service in an EGL deployment descriptor (.egldd) file, specify the .bct file name for the conversionTable property (for example, conversionTable="hct1.bct") in any protocol other than local.
    • When developing a program that you plan to generate to Java™ and that program uses text or print forms with bidi language text, add a statement to the program that assigns the conversion table name to the sysVar.formConversionTable system function before showing the form.