Data conversion

Because of differences in how data is interpreted in different runtime environments, your program may need to convert the data that passes from one environment to another. Data moving from Java™ environments to COBOL environments, and from COBOL to Java™, always need data conversion. Data conversion occurs at COBOL preparation time and at COBOL or Java™ run time.

Programs supporting bidirectional languages such as Arabic or Hebrew can use bidi conversion tables to specify the reordering of text data in addition to code page conversion. See the topic "Bidirectional language text" for information on creating bidi conversion tables.

The COBOL preparation process converts file content, file-path information, and values of environment variables when transferring workstation-based files to a build server. For this situation, the steps needed to establish a data conversion table are described later in this topic.

Your program also uses a conversion table in the following runtime situations:
  • Your generated Java™ code calls a program on another system that uses a different code page (for example, a Java™ program calls a program on z/OS®).

    In this case, you can specify the conversion table in a callLink element that refers to the called program. Alternatively, you can indicate (in that callLink element) that the sysVar.callConversionTable system variable identifies the conversion table at run time.

  • Your generated Java™ code invokes a service using an EGL remote binding.

    In this case, you can specify the conversion table in an EGL binding, in the EGL deployment descriptor (.egldd) file. You specify the conversion table by setting the conversionTable property for any protocol other than local.

  • Your generated COBOL program calls a program residing on a remote platform that supports the ASCII character set.

    In this case, you can specify the conversion table in a callLink element that refers to the called program. Alternatively, you can indicate (in that callLink element) that the sysVar.callConversionTable system variable identifies the conversion table at run time.

  • Your generated CICS® COBOL program (on a platform that supports the EBCDIC character set) starts a program asynchronously on a platform that supports the ASCII character set, as might occur when a program invokes the vgLib.startTransaction system function.

    In this case, you can specify the conversion table in an asynchLink element that refers to the record used in the vgLib.startTransaction system function. Alternatively, you can indicate (in that asynchLink element) that the sysVar.callConversionTable system variable identifies the conversion table at run time.

    This is not possible for Java™ programs, because the vgLib.startTransaction function for Java™ can only start programs that are on the local system; because all programs are local, no conversion is needed.

  • Your generated CICS® COBOL program accesses a VSAM file or CICS® transient data queue on a platform that supports the ASCII character set.

    In this case, you can specify the conversion table in a fileLink element that refers to the file or data queue. Alternatively, you can indicate (in that fileLink element) that the sysVar.callConversionTable system variable identifies the conversion table at run time.

  • Your generated Java™ program shows a text or print form that includes series of Arabic or Hebrew characters; or presents a text form that accepts a series of such characters from the user. In these cases, you specify the bidirectional conversion table in the sysVar.formConversionTable system variable.
You might use runtime conversion in the following situations:
  • You do not know the runtime language and therefore do not know which conversion table to specify at generation time. In this case, do the following:
    1. Set the conversionTable property in the callLink, asynchLink, or fileLink element to specify PROGRAMCONTROLLED.
    2. In your program, set the value of the sysVar.callConversionTable system variable at runtime based on input from the user.
  • Your program passes a record to another program, but other record variables redefine the record that is being passed. The record and its redefinitions all refer to the same area of memory, but the actual structure and types of data in the record vary depending on which redefinition you are actually using for the call. Therefore, the requirements of data conversion also vary at runtime based on the redefinition that is being used. In this case, do the following:
    1. Set the conversionTable property in the callLink, asynchLink or fileLink element to specify PROGRAMCONTROLLED.
    2. In your program, set the value of the sysVar.callConversionTable system variable to blanks to indicate that automatic conversion should not be done.
    3. In your program, invoke the sysLib.convert system function to convert the record variable that corresponds to the record structure that you require. The sysLib.convert function also enables you to specify the conversion table that you need based on input from the user.
The next sections provide the following details:

For information on customizing a conversion table in the z/OS® COBOL environment, see the IBM® Rational® COBOL Runtime Guide for zSeries®.

Data conversion when you generate a COBOL program

When COBOL is generated on a workstation and prepared on a z/OS® or an iSeries® build server, conversion is handled on the build server in accordance with your specification in the clientCodeSet and serverCodeSet build descriptor options. Each of those build descriptor options must identify a code set that is defined to the ICONV conversion service on z/OS® and iSeries®, and default settings are used in the absence of a specification.

Programs that support bidirectional languages like Arabic or Hebrew may also require reordering of text literals in addition to code page conversion. For more information, see the topic "Bidirectional language text."

Data conversion at run time in a generated COBOL program

When a generated COBOL program accesses a program or file on a remote CICS® region that supports the ASCII character set, a conversion occurs in the caller, in accordance with a conversion table. The conversion table in this case is a load module that contains information on code page translation.

The next table lists the conversion tables that are shipped with EGL and can be accessed by a generated COBOL program at run time. These conversion tables convert data between EBCDIC format and the Windows™ 2000/NT/XP ASCII code pages.

Language Table name
Brazilian Portugese ELACNPTB
Chinese, simplified ELACNCHS
Chinese, traditional ELACNCHT
English, uppercase ELACNENP
English, USA ELACNENU
French ELACNFRA
German ELACNDEU
Italian ELACNITA
Japanese, Katakana (single-byte character set) ELACNJPN
Korean ELACNKOR
Spanish ELACNESP
Swiss German ELACNDES

Data conversion at run time in a generated Java™ program

The following rules pertain to Java™ code:
  • When a generated Java™ program or wrapper calls a generated Java™ program, conversion occurs in the calling program, in accordance with a set of EGL classes initiated at run time. In most cases no conversion at all is needed, even if the caller is accessing a remote platform that uses a code page that is different from the code page used by the invoker. However, you must specify a conversion table in the following situation:
    • The calling program is Java™ code and is on a system that supports one code page
    • The called program is a non-Java program and is on a system that supports another code page

    The table name in this case is a symbol that indicates the kind of conversion that is required at run time.

  • When a generated Java™ program accesses a remote WebSphere® MQ message queue, conversion occurs in the caller, in accordance with a set of EGL classes started at run time. If the caller is accessing a remote platform that uses a code page that is different from the code page used by the invoker, specify a conversion table in the association element that refers to the WebSphere® MQ message queue.
The next table lists the conversion tables that generated Java™ code can access at run time. Each name has the format CSOcx. Variables are explained in the following list:
c
This variable represents the character set supported on the called program's platform. Select one of these:
  • J for Java™ (if the called program is an EGL-generated Java™ program)
  • E for EBCDIC (if the called program is an EGL-generated COBOL program)
x
This variable represents the code page number for the specified language on the remote program's platform. Each number is specified in the Character Data Representation Architecture Reference and Registry, SC09-2190. The registry identifies the coded character sets supported by the conversion tables.

Remote Platforms
Language Linux™ UNIX™ Windows™ 2000/NT/XP z/OS® UNIX™ System Services or iSeries® Java™ z/OS® or iSeries® COBOL
Arabic CSOJ1046 CSOJ1046 CSOJ1256 CSOJ420 CSOE420
Chinese, simplified CSOJ1381 CSOJ1381 CSOJ1386 CSOJ1388 CSOE1388
Chinese, traditional CSOJ950 CSOJ950 CSOJ950 CSOJ1371 CSOE1371
Cyrillic CSOJ866 CSOJ866 CSOJ1251 CSOJ1025 CSOE1025
Danish CSOJ850 CSOJ850 CSOJ850 CSOJ277 CSOE277
Eastern European CSOJ852 CSOJ852 CSOJ1250 CSOJ870 CSOE870
English (UK) CSOJ850 CSOJ850 CSOJ1252 CSOJ285 CSOE285
English (US) CSOJ850 CSOJ850 CSOJ1252 CSOJ037 CSOE037
French CSOJ850 CSOJ850 CSOJ1252 CSOJ297 CSOE297
German CSOJ850 CSOJ850 CSOJ1252 CSOJ273 CSOE273
Hebrew CSOJ856 CSOJ856 CSOJ1255 CSOJ424 CSOE424
Japanese CSOJ943 CSOJ943 CSOJ943 CSOJ1390 (Katakana SBCS), CSOJ1399 (Latin SBCS) CSOE1390 (Katakana SBCS), CSOE1399 (Latin SBCS)
Korean CSOJ1363 CSOJ1363 CSOJ1363 CSOJ1364 CSOE1364
Portuguese CSOJ850 CSOJ850 CSOJ1252 CSOJ037 CSOE037
Spanish CSOJ850 CSOJ850 CSOJ1252 CSOJ284 CSOE284
Swedish CSOJ850 CSOJ850 CSOJ1252 CSOJ278 CSOE278
Swiss German CSOJ850 CSOJ850 CSOJ1252 CSOJ500 CSOE500
Turkish CSOJ920 CSOJ920 CSOJ1254 CSOJ1026 CSOE1026

When you are calling a program from Java™, if you do not specify a value for the conversion table in the linkage options part, the default conversion tables are those for English (US).

Conversion algorithm

Data conversion of records and structures is based on the declarations of the structure fields that do not have a substructure.

No conversion is performed for variables that have no name (indicated by an asterisk in a structured record), or for variables of type BIN, BIGINT, BOOLEAN, INT, SMALLINT, DECIMAL, MONEY, PACF, HEX, STRING, or UNICODE. However, if you are using a bidirectional conversion table, UNICODE and STRING variables will be reversed as defined in the table. For more information, see Working with bidirectional data.

Data of type CHAR, DBCHAR, or MBCHAR is converted in accordance with the COBOL or Java™ conversion tables.

For variables of type FLOAT and SMALLFLOAT, the conversion routine converts from Java™ to zSeries® COBOL and back using the IEEE 754 format for Java™ and the IBM® 370 format for zSeries® COBOL. No conversion is necessary for FLOAT and SMALLFLOAT variables between Java™ and iSeries® COBOL.

On EBCDIC-to-ASCII conversion for MBCHAR data, the conversion routine deletes shift-out/shift-in (SO/SI) characters and inserts an equivalent number of blanks at the end of the variable. On ASCII-to-EBCDIC conversion, the conversion routine inserts SO/SI characters around double-byte strings and truncates the value at the last valid character that can fit in the field. If the MBCHAR field is in a variable length record and the current record end is in the MBCHAR field, the record length is adjusted to reflect the insertion or deletion of SO/SI characters. The record length indicates where the current record ends.

For variables of type NUM or NUMC items, the conversion routine converts all but the last byte using the CHAR algorithm. The sign half-byte, which is the first half-byte of the last byte in the field, is converted according to the hexadecimal values shown in the next table.
Table 1. Conversion for NUM and NUMC variables
EBCDIC for type NUM EBCDIC for type NUMC ASCII
F (positive sign) C 3
D (negative sign) D 7

For variables of type DATE, INTERVAL, TIME, or TIMESTAMP, EGL converts the values using the CHAR algorithm and the string form of the variable.

You can find more information on the sysLib.convert() system function and the sysVar.callConversionTable system variable in the topics "convert()" and "callConversionTable" in the EGL Language Reference.