|
|
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:
| Note: | All references to ATMI files, functions, and documentation apply to Tuxedo files, functions, and documentation. |
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. |
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.
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.
The XML typed buffer is converted to EBCDIC for the length of the buffer.
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.
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.
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.
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.
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.
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.
The XML typed buffer is converted to ASCII for the length of the buffer. For DPL services, refer to Data Conversion For DPL Services.
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.
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.
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.
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.
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.
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.
If no LENGTH can be determined, then the largest value allowed by the CICS application is allocated.
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.
The following sections on default data translation rules provide suggestions to help you:
Table 5-2 lists VIEW data translation rules.
Translated from ASCII to EBCDIC (If needed. Refer to “
Translation Rules for Strings.”)
|
|
| 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.
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.
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.
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.
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).
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 Record01 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. |
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:
In this parameter, arguments and options are defined in the following way:
CLOPT
-- 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. |
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”
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.
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.
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:
*DM_REMOTE_DOMAINS
BEASTYPE=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.
ATMI platform default 1
|
|||
CP-00819 2
|
|||
1The default ATMI ASCII and EBCDIC code pages are slightly different from CP-00819 and CP-00037. 2CP-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. |
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.
# DMCONFIG
*DM_LOCAL_DOMAINS
CIXA TYPE=SNAX
*DM_REMOTE_DOMAINS
CISA TYPE=SNAX CODEPAGE=”00819X00273”
IMSA TYPE=SNAX CODEPAGE=”00819X00297”
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"
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.
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.
|