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 Oracle Tuxedo Mainframe Adapter for SNA 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

•	Translation Rules for RECORD Data Types

•	Translation Rules for Strings

•	Multi-byte Character Set (MBCS) Support

•	ART for CICS Integration Consideration

Note:

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

Data Conversion

Like other domain gateways, the Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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.

Data Conversion for RECORD Typed Buffers

A subtype is required for this typed buffer. The subtype is the name of the RECORD that describes the remote host record. The ATMI buffer is converted from a RECORD typed buffer to the record, including EBCDIC conversion, using the compiled RECORD file. By default, the record is a COBOL structure, 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 Oracle Tuxedo Mainframe Adapter for SNA 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 �$paratext>.�

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 Oracle Tuxedo Mainframe Adapter for SNA 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 RECORD Typed Buffers

A subtype is required for this typed buffer. The subtype is the name of the RECORD that describes the remote host record. The remote host record is converted to an ATMI typed buffer. The compiled RECORD 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 RECORD type.

Data Conversion For DPL Services

The Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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.
RECORD	For this typed buffer, the INBUFTYPE parameter definition is used to determine the LENGTH.

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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 RECORD Data Types

The data in RECORD buffer is always in original format - COBOL internal representation. For more information, see Data Type and Conversion in Programming an Oracle Tuxedo ATMI Application Using FML.

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. Listing 5‑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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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. Figure 5‑1 illustrates code page translation.

Figure 5‑1 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA software.

 

Table 5‑5 Oracle Tuxedo Mainframe Adapter for SNA 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
Italy	00819x00280	CP-00819	CP-00280
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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA translation tables are located in the following sub-directory:

$TUXDIR/udataobj/codepage

If no CODEPAGE specification is made for a remote domain, the Oracle Tuxedo Mainframe Adapter for SNA 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.

Listing 5‑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”

 

Multi-byte Character Set (MBCS) Support

Besides single-byte character set (SBCS) character set translation, TMA SNA supports multi-byte character set (MBCS) translation to meet Asian customer's requirement. This translation does not depend on translation tables under directory $TUXDIR/udataobj/codepage, instead, it is based on ICU libraries, which contains more than 200 different SBCS and MBCS character sets.

To use this translation, CODEPAGE in DMCONFIG DM_REMOTE_DOMAINS should be specified as following format:

CODEPAGE="ASCII_CHAR_SET:EBCDIC_CHAR_SET"

ASCII_CHAR_SET is for local domain and EBCDIC_CHAR_SET is for remote domain. They are separated by a colon.

Both ASCII_CHAR_SET and EBCDIC_CHAR_SET must be available character sets known by ICU. A utility uconv can be used to retrieve relevant information of these character sets.

For example, local domain uses ASCII Chinese code set gb2312-1980, and remote domain uses EBCDIC Chinese code set ibm-1388:

# DMCONFIG

*DM_REMOTE_DOMAINS

CICA TYPE=SNAX CODEPAGE="gb2312-1980:ibm-1388"

ART for CICS Integration Consideration

Tuxedo ATMI applications are mostly in C while ART for CICS applications are in COBOL; though both C and COBOL use the same VIEW32 definitions, there are two major differences.

•	In C, the size of long type is 8 bytes; in COBOL, the size of long type is usually 4 bytes.

•	C has an alignment requirement while COBOL does not.

Consequently, when it comes to ART for CICS integration, viewc32 needs two special compile flags. For example, on Linux,

CFLAGS="-m32 -fpack-struct=1" viewc32 myview.v

"-m32" is specified to use 32-bit long for COBOL "S9(9) COMP", and "-fpack-struct=1" is specified for non-alignment for COBOL. Ensure that only GWSNAX can use the VIEW32 binary (other C applications cannot use it).

In terms of ART for CICS integration, GWSNAX -t parameter can be omitted or set as "-t 4", for the null terminator is not needed.