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.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.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: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.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.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.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: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.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.”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.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.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 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.
Table 5‑1 DPL Request LENGTH Calculation For these typed buffers, the INBUFTYPE parameter definition is used to determine the LENGTH and then add any null character. 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. 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. 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.Table 5‑2 lists VIEW data translation rules.
Table 5‑2 VIEW Data Translation Rules
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.
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.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.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 StringsThe 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 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:-- 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.
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 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.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: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.
ATMI platform default 1 CP-00819 2
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.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 ExampleBesides 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: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: