BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
eLink Adapter for Mainframe Documentation | eLink Adapter for Mainframe User Guide | Previous Topic | Next Topic | Contents | Index

Setting Up Data Translations

Due to differences in platforms, operating systems, and programming languages, the data format used by applications in the ATMI domain differs significantly from that expected by applications in the remote domain. In the ATMI domain, applications are typically written in the C language, using C structures and ATMI typed buffers, such as VIEW and FML. In the remote domain, the C and COBOL programming languages are commonly used, with C structures or COBOL copybook definitions. The translation between these data types for both inbound and outbound messages occurs in the eLink Adapter for Mainframe Gateway. The Gateway has a number of configuration options for dealing with data conversion between domain types.

This section discusses the following data translation topics:

- Data Conversion

- Translation Rules for VIEW Data Types

Note: All references to ATMI files, functions, and documentation apply to Tuxedo files, functions, and documentation.

Data Conversion

Like other domain gateways, the eLink Adapter for Mainframe Gateway uses ATMI typed buffers to transmit and receive data. Since the remote host application does not understand the typed buffer, the ATMI application must communicate with the host application by using an aggregate data type known as a record. A record is a flat data area defined by a template that describes the data type and length of each field in the record.

The application developer should determine the format and content of the record structure used on the remote host, as well as the ATMI typed buffer to be used, before configuring the Gateway.

In most cases the conversion between ATMI typed buffers and record formats is handled by the eLink Adapter for Mainframe Gateway. The service definitions in the DM_LOCAL_SERVICES and the DM_REMOTE_SERVICES section of the DMCONFIG file provide parameters to describe the typed buffer/record combination required for successful communications between the applications.

Note: The current size of remote host messages is limited to approximately 32K bytes. Any conversions resulting in records larger than 32756 bytes are not supported.

Conversion of ATMI Typed Buffers to Records

When an ATMI application sends a typed buffer to a remote host application, the buffer must be converted to a record by the eLink Adapter for Mainframe Gateway before it is passed to the remote host application. The Gateway uses the service definition to determine what, if any, conversion must be applied to the buffer. The service definition uses the INBUFTYPE in both the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES section of the DMCONFIG file to describe the desired conversion.

INBUFTYPE is specified in the following way:

>     INBUFTYPE = type:subtype

In this parameter definition, type must be one of the designated ATMI typed buffers described in the following subsections.

The subtype value names a view and is required for certain ATMI typed buffers.

Only one type:subtype may be entered for the INBUFTYPE parameter.

The following sections describe the conversions performed for each ATMI typed buffer.

Data Conversion for STRING Typed Buffer

By default, a null-terminated string is converted to EBCDIC. The null character is part of the converted record. See the "Translation Rules for Strings" section for information about using strings in View and FML data types.

Data Conversion for XML Typed Buffer

The XML typed buffer is converted to EBCDIC for the length of the buffer.

Data Conversion for X_OCTET/CARRAY Typed Buffers

No data conversion is performed on these typed buffers. The ATMI application or remote host application performs all conversion of data fields in the record, including all numeric and EBCDIC conversions.

These typed buffers are used when a data record cannot be described or converted using one of the other strong typed buffers. Strong means that eLink Adapter for Mainframe Gateway can understand all data fields and perform the required data conversions.

These typed buffers are also options when the remote service expects many styles of data aggregation (multiple record types), because the INBUFTYPE parameter is limited to one type:subtype.

Data Conversion for VIEW/VIEW32/X_C_TYPE/X_COMMON Typed Buffers

A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The ATMI buffer is converted from a C structure to the record, including EBCDIC conversion, using the compiled VIEW file. By default, the record is a COBOL structure, mapped by the remote host application using a COBOL copybook. See "Translation Rules for VIEW Data Types" for more conversion options.

Data Conversion for FML/FML32 Typed Buffers

A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The data in the typed buffer is Field Manipulation Language (FML) data. The eLink Adapter for Mainframe Gateway converts the buffer to a record described by the view, including EBCDIC conversion.

The ATMI buffer is converted from an FML typed buffer to a C structure using the subtype compiled VIEW file. The C structure is then converted to the record using the same subtype compiled VIEW file. By default, the record is a COBOL structure that is mapped by the remote host application using a COBOL copybook.

Conversion of Records to ATMI Typed Buffers

When a remote application sends a record to an ATMI application, the record must be converted to an ATMI typed buffer by the eLink Adapter for Mainframe Gateway before it is passed to the ATMI application. The Gateway uses the service definition to determine what, if any, conversion must be applied to the host record. The service definition uses the OUTBUFTYPE in both the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES section of the DMCONFIG file to describe the desired conversion.

OUTBUFTYPE is specified in the following way:

>     OUTBUFTYPE=type:subtype

In this parameter definition, type must be one of the designated ATMI typed buffers described in the following subsections. The type not only determines the typed buffer, but also describes the host record.

The subtype value names a view and is required for certain ATMI typed buffers.

Only one type:subtype may be entered for the OUTBUFTYPE parameter.

The following sections describe the conversions performed for each ATMI typed buffer.

Data Conversion for STRING Typed Buffer

The null terminated string is converted to ASCII. The converted string is moved to an ATMI STRING typed buffer. See the "Translation Rules for Strings" section for information about using strings in View and FML data types.

Data Conversion for XML Typed Buffer

The XML typed buffer is converted to ASCII for the length of the buffer. For DPL services, refer to Data Conversion For DPL Services.

Data Conversion for X_OCTET/CARRAY Typed Buffers

No data conversion is performed on these typed buffers. The remote host application or the ATMI application converts the data fields in the record, including all numeric and ASCII conversions.

These typed buffers are used when the data record cannot be described or converted using one of the other strong type buffers. Strong means eLink Adapter for Mainframe can understand all data fields and perform the required data conversion.

These typed buffers are also options when the remote service expects many styles of data aggregation (multiple record types), because the OUTBUFTYPE parameter is limited to one type:subtype.

Data Conversion for VIEW/VIEW32/X_C_TYPE/X_COMMON Typed Buffers

A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The remote host record is converted to an ATMI typed buffer. The compiled VIEW file is used to perform the data and ASCII conversion on the host record. By default, the host record is a COBOL data aggregate and the converted typed buffer is mapped by the ATMI application using a C structure. See the "Translation Rules for VIEW Data Types" section for more conversion options.

Data Conversion for FML/FML32 Typed Buffers

A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The host record is converted to an FML buffer that is passed to the ATMI application.

By default, the host record is a COBOL record aggregate data type. The data is converted to a C structure, including ASCII conversion, using the compiled VIEW file. This data is then converted to an FML buffer using the field definitions associated with the VIEW.

Data Conversion For DPL Services

The eLink Adapter for Mainframe system supports remote CICS services as Distributed Program Link (DPL) programs. The DPL support is performed as if the ATMI service is a peer CICS/ESA service.

In a DPL program, the application is protected from all Distributed Transaction Processing (DTP). The DPL application is a request/response service, with all data communication performed by the passing of a COMMAREA.

A basic DPL request API looks like this:

>     EXEC CICS LINK

>            PROGRAM()
>            DATALENGTH()
>            LENGTH()
>            COMMAREA()

In the preceding example, the requester sends the COMMAREA of DATALENGTH size and the receiving application receives the COMMAREA data contents in a buffer the size of LENGTH. The DATALENGTH size might be smaller than the LENGTH size, but the requester expects and receives the response in the original COMMAREA buffer the size of LENGTH.

The difference between a DPL program and an ATMI service is that a receiving ATMI service can resize a reply buffer, while the DPL program expects a reply buffer of a designated size. Also, an ATMI requester can receive a resized buffer in a buffer different from the original reply buffer.

The eLink Adapter for Mainframe software performs the manipulation described in the following subsections to smoothly adjust to the requirements of both types of applications.

DPL Requests Originating From an ATMI Application

The eLink Adapter for Mainframe software must determine what size COMMAREA the remote DPL service is expecting because no corresponding LENGTH parameter exists on an ATMI request.

To determine the LENGTH value for a DPL request, the software uses the larger potential size of the INBUFTYPE or the OUTBUFTYPE parameter definitions, as described in Table 5-1.

The remote DPL application receives a buffer of LENGTH size and returns a buffer of LENGTH size.

Table 5-1 DPL Request LENGTH Calculation

INBUFTYPE or OUTBUFTYPE

LENGTH CALCULATION

STRING/X_OCTET/ CARRAY

For these typed buffers, the INBUFTYPE parameter definition is used to determine the LENGTH and then add any null character.

VIEW/VIEW32/ X_COMMON/ X_C_TYPE

LENGTH is the maximum size of the VIEW file. This calculation takes in the potential size of both the C structure and the target record.

FML/FML32

The maximum size of the VIEW file. This calculation takes in the potential size of both the C structure, and the target record. The length of the FML buffer is not taken into account.

XML

When returning XML typed data, a DPL program may resize an XML typed reply buffer by appending null characters to the end of the XML string. To prevent errors in length of the reply buffer for XML typed data, any null characters appended to the XML string are removed before the data is returned.

If no LENGTH can be determined, then the largest value allowed by the CICS application is allocated.

DPL Requests Originating From a CICS DPL

The eLink Adapter for Mainframe software receives a LENGTH value and COMMAREA data of DATALENGTH size from the requesting CICS DPL. The software allocates a buffer of LENGTH size and moves the COMMAREA data into this buffer before performing the conversions.

Translation Rules for VIEW Data Types

The following sections on default data translation rules provide suggestions to help you:

- Develop VIEW definitions for input and output buffers and records

- Understand how string data and numeric data are treated with the VIEW data type

Table 5-2 lists VIEW data translation rules.

Table 5-2 VIEW Data Translation Rules

Field Type | Translation Rules
--- | ---
CARRAY | Passed without translation as sequences of bytes.
STRING and CHAR | Translated from ASCII to EBCDIC (If needed. Refer to "Translation Rules for Strings.")
SHORT | Translated to S9(4)COMP
LONG | Translated to S9(9)COMP
FLOAT | Translated to COMP-1
DOUBLE | Translated to COMP-2

Note: The ATMI platform provides a field type named dec_t that supports decimal values within VIEWs. The Gateway translates these fields into machine independent representations of packed decimals. For example, dec_t(m,n) becomes S9(2*m-(n+1))V9(n) COMP-3. Therefore, a decimal field with a size of 8,5 corresponds to S9(10)V9(5) COMP-3.

Table 5-3 lists the translation rules between C and IBM/370 data types.

Table 5-3 Data Translation Rules between C and IBM/370 Data Types

Remote Data Type | Description | View Field Type/Length
--- | --- | ---
PIC X(n) | Alpha-numeric Characters | string / n
PIC X | Single Alpha-numeric Character | char
PIC X(n) | Raw Bytes | carray / n
PIC X | Single Numeric Byte | carray / 1
PIC S9(4) COMP | 32-bit Integer | short
PIC S9(9) COMP | 64-bit Integer | long
COMP-1 | Single-precision Floating Point | float
COMP-2 | Double-precision Floating Point | double
PIC S9((m+(n+1))/2)V9(n) COMP-3 | Packed Decimal | dec_t / m,n

String Considerations

When you create VIEW definitions for input and output records that are used by CICS/ESA applications, do not specify an extra position for the terminating null characters that are used in string fields. For example, when a CICS/ESA application program expects 10 characters in an input record, specify 10 for that field, not 10 plus 1.

Note: Although eLink Adapter for Mainframe software does not require strings to be null-terminated, it respects null termination. When the Gateway software detects a null (zero) character within a string, it does not process any subsequent characters. To pass full 8-bit data that contains embedded null values, use a CARRAY type field or buffer.

The character set translations performed by eLink Adapter for Mainframe are fully localizable, in accordance with the X/Open XPG Portability Guides. ASCII and EBCDIC translations are loaded from message files. Refer to the "Translation Rules for Strings" section for more information.

The eLink Adapter for Mainframe software contains default behaviors that should meet the requirements of most English-language applications. However, you may find it necessary to customize the translation. Refer to the "Translation Rules for Strings" section for more information.

Converting Numeric Data

You can convert numeric data into different data types easily, if you specify enough range in the intermediate and destination types to handle the maximum value needed.

For example, you can convert a Field Manipulation Language (FML) field of double into a packed decimal field on the remote target system by specifying an appropriate dec_t type VIEW element.

You can also convert numeric values into strings. For example, while FML buffers do not directly support the dec_t type, you can place decimal values in string fields and map these to dec_t fields within VIEW definitions.

Translation Rules for Strings

When planning the interaction between the ATMI platform and host applications, consideration must be given to the programming languages in which the applications are written. A character string is represented differently in the COBOL language than in the C language and associated ATMI platform VIEW buffer. Listing5-1 demonstrates the three ways that the same two strings are coded (string1 and string2).

Listing 5-1 Three Representations of Strings

>     C Structure:

>     struct text

>     {
>     	char	rbufsize[5];
>     	char	testnum[2];
>     	char	sendnum;
>     	char	sysid[4];
>     	char	textfld[10];
>     	char	string1[10];
>     	char	string2[16];
>     };

>     VIEW text

>     #type		cname		fbname	count	flag	size	null
>     char		rbufsize		-	5	-	-	-
>     char		testnum		-	2	-	-	-
>     char		sendnum		-	1	-	-	-
>     char		sysid		-	4	-	-	-
>     char		textfld		-	10	-	-	-
>     string		string1		-	1	-	10	-
>     string		string2		-	1	-	16	-
>     END

>     COBOL Record

>     	01  TEXT.
>     	    05  RBUFSIZE		PIC X(5).
>     	    05  TEXTNUM		PIC X(2).
>     	    05  SENDNUM 		PIC X.
>     	    05  SYSID   		PIC X(4).
>     	    05  STRING1 		PIC X(9).
>     	    05  STRING2		PIC X(15).

The listing shows that, in the C structure and VIEW buffer, the sizes of string1 and string2 are represented as 10 and 16 characters, respectively. However, in the COBOL record, the sizes are 9 and 15 characters, respectively. This incompatibility can cause code misalignment between C and COBOL programs if not anticipated in the source code.

To avoid such incompatibilities, the Gateway provides a software option to control the mapping of string data between C and COBOL applications. This option enables you to automatically compensate for the differences in null termination and padding characteristics of the two languages.

Note: The option affects string fields in the ATMI platform VIEW buffers only. STRING buffers are not affected by this switch.

Setting the Option to Perform String Transformation

To set the string transformation option, use the CLOPT parameter when you configure the Gateway server (GWSNAX) definition in the UBBCONFIG file. If you set the -t option of the CLOPT parameter to one of the values listed in Table 5-4, the Gateway performs the corresponding string transformation. Use the following syntax format:

CLOPT="-- -t {number}"

In this parameter, arguments and options are defined in the following way:

  CLOPT specifies the ATMI parameter which enables you to provide command-line options in a server definition.

  -- marks the end of system-recognized arguments and the start of arguments passed to a subroutine within the server. This option is required if you supply application-specific arguments, such as the -t option, to the server.

-t is the eLink Adapter for Mainframe option to establish C-to-COBOL string transformation.

  {number} indicates the type of string transformation the Gateway performs as shown in Table 5-4.

Note: If you do not set the -t option of the CLOPT parameter in your server definition, by default the Gateway performs no string transformation.

Table 5-4 C to COBOL String Transformation

CLOPT -t Parameter Value | ATMI Application Language | Host Application Language
--- | --- | ---
Not Set | No string transformation established
1 | C | COBOL
2 | COBOL | C
3 | C | C
4 | COBOL | COBOL

  These options function in the following ways:

  Option value 1:

  For outbound messages to the host, C string fields are converted to COBOL string fields. All available characters, up to the defined length of the string and beginning with the null character, are converted to spaces and the length of the field is reduced by one.

  For inbound messages from the host, COBOL string fields are converted to C string fields, trailing blanks are converted to null characters (zero value) and the length of the field is increased by one.

  Option value 2:

  For outbound messages to the host, COBOL string fields are converted to C string fields, trailing blanks are converted to null characters (zero value) and the length of the field is increased by one.

  For inbound messages from the host, C string fields are converted to COBOL string fields. All available characters, up to the defined length of the string and beginning with the null character, are converted to spaces and the length of the field is reduced by one.

  Option values 3 and 4:

  No string transformations are made between programs written in compatible languages.

Example:

The following example of a server definition uses the switch to establish string transformations between an ATMI application written in C and a host application written in COBOL.

>     *SERVERS

>     GWSNAX SRVGRP=GROUP1 SRVID=5 CLOPT="-A -- -t 1"

Code Page Translation Tables

The eLink Adapter for Mainframe software includes translation tables that enable conversions between ASCII character sets and EBCDIC character sets. The code pages provide 12 standardized tables to facilitate operations between ATMI applications using the Latin-1 ASCII code set (CP-00819) and host applications using a national language code set.

Each translation table consists of two mapping tables, one for outbound conversions (ATMI platform-to-host) and one for inbound conversions (host to ATMI platform). You do not have to specify the direction of a translation. You only need to determine the national language in which the host application is written. Figure5-1 illustrates code page translation.

Figure 5-1 eLink Adapter for Mainframe Code Page Translation

The figure demonstrates how an ATMI application using the Latin-1 ASCII code page CP-00819 character set operates with a host application using German EBCDIC code page CP-00273. The eLink Adapter for Mainframe translation table 00819x00273 provides both the inbound and outbound conversions.

Specifying a Translation Table

To designate the translation table for your applications, make an entry in the ATMI platform DMCONFIG file definition for each remote domain. Use the CODEPAGE parameter with the following format:

For example:

>     *DM_REMOTE_DOMAINS

>     BEAS TYPE=SNAX CODEPAGE="cpname"

In this parameter, cpname identifies the translation table for the remote domain, from Table 5-5. It must be enclosed by double quotes.

Table 5-5 lists the translation tables provided with eLink Adapter for Mainframe software.

Table 5-5 eLink Adapter for Mainframe Code Page Translation Tables

Country | File Name | ASCII Code Set | EBCDIC Code Set
N/A | none | No translation | No translation
ATMI platform default 1 | tuxedo | ATMI ASCII | ATMI EBCDIC
United States | 00819x00037 | CP-00819 2 | CP-00037
Great Britain | 00819x00285 | CP-00819 | CP-00285
France | 00819x00297 | CP-00819 | CP-00297
Portugal | 00819x00860 | CP-00819 | CP-00860
Spain | 00819x00284 | CP-00819 | CP-00284
Belgium | 00819x00500 | CP-00819 | CP-00500
Germany | 00819x00273 | CP-00819 | CP-00273
Finland | 00819x00278 | CP-00819 | CP-00278
Sweden | 00819x00278 | CP-00819 | CP-00278
Latin-1 | 00819x01047 | CP-00819 | CP-01047
Latin-2 | 00912x00870 | CP-00912 | CP-00870

1 The default ATMI ASCII and EBCDIC code pages are slightly different from CP-00819 and CP-00037. 2 CP-00819 is exactly equivalent to ISO-8859-1 (also called Latin-1 ASCII), and is used as the ASCII code page in all of the countries listed in this table.

How the Translation Tables Work

The eLink Adapter for Mainframe translation tables are based on IBM-defined code sets. At start up, the Gateway loads a translation table for each remote domain.

You can modify any of the tables to suit your application translation needs, except the default ATMI tables, which are hard-coded. Refer to Appendix D, "Code Page Translation Tables" for detailed table contents. You must restart the Gateway to change any translation table definitions.

Note: Replicas of the default ATMI translation tables are included with your product software. These tables are provided for you to modify, if desired. They are not the actual default tables. You cannot modify the default ATMI tables.

The eLink Adapter for Mainframe translation tables are located in the following sub-directory:

>     $TUXDIR/udataobj/codepage

If no CODEPAGE specification is made for a remote domain, the eLink Adapter for Mainframe software uses the ATMI default translation tables. If the software cannot find the translation table file, it generates a message 2241:ERROR Unable to access codepage table with a reason code and the Gateway fails to start. Refer to this message in Appendix B, "Error Messages" for explanations of the reason codes.

Listing5-2 depicts entries defining one local domain (CIXA) and two remote domains (CISA and IMSA). In all cases, the assumption is made that the local domain uses ASCII code page CP-00819. In the example, the two remote domains use the German and French EBCDIC code pages CP-00273 and CP-00297, respectively.

Listing 5-2 Code Page Definition Example

>     # DMCONFIG
>     *DM_LOCAL_DOMAINS
>     CIXA TYPE=SNAX
>     *DM_REMOTE_DOMAINS
>     CISA TYPE=SNAX CODEPAGE="00819X00273"
>     IMSA TYPE=SNAX CODEPAGE="00819X00297"

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.