HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC
|
|
|
BEA eLink for Mainframe SNA 3.2 Information Center |
|
HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW |
||
|
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC |
||
This section discusses the following aspects of data translation:
The following subsections provide suggestions to help you develop VIEW definitions for input and output buffers and records. It also explains how string data and numeric data are treated by default in the eLink SNA environment.
If you do not specify string transformation (please refer to "Programming Language String Transformation"), the rules in Table 7-1 apply.
Default Data Translation Rules
Table 7-1 Default Data Translation Rules
Note:
BEA TUXEDO provides a field type named The translation rules between C and IBM/370 data types are listed in the following table.
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 7-2 Data 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 eLink 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 eLink SNA are fully localizable, in accordance with the X/Open XPG Portability Guides. ASCII and EBCDIC translations are loaded from message files. Refer to "Programming Language String Transformation" for more information.
The eLink SNA software contains default behaviors which should meet the requirements of most English-language applications. However, you may find it necessary to customize tables. Refer to "Code Page Translation Tables" for more information.
You can convert numeric data into different data types easily, as long as 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 In addition, you can convert numeric values into strings, vice versa. For example, while FML buffers do not directly support the Like other domain gateways, the eLink SNA gateway uses the BEA TUXEDO Typed Buffer to transmit and receive data. When communication is between an eLink SNA application and a remote host region, there are some special considerations.
Since the remote host application does not understand the typed buffer, the BEA TUXEDO 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 typed buffer must be represented to the host application as a record and the record must be represented to the BEA TUXEDO application as a typed buffer. In addition, string data must be in EBCDIC format for the host region and in ASCII format for the BEA TUXEDO application.
The data may be manipulated into the correct format by the BEA TUXEDO application or remote host application, or it may be formatted prior to transmission by the eLink 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. These parameters are The parameter definitions are made from the perspective of the receiver of the buffer, the BEA TUXEDO application which receives a typed buffer, or the remote host application which receives record data. That is, The BEA TUXEDO application buffer is a typed buffer that must be communicated to the remote host as a record containing aggregate data fields. The eLink SNA gateway looks at the service definition to determine what, if any, conversion must be applied to the data buffer. The service definition uses the In this parameter definition, The Only one The null terminated string is converted to EBCDIC. The null character is part of the converted record.
No data conversion is performed on these typed buffers. The BEA TUXEDO application or remote host application performs all conversion of data fields in the record. This includes 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 SNA 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). The A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The BEA TUXEDO 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.
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 SNA converts the buffer to a record described by the view; this includes EBCDIC conversion.
The BEA TUXEDO 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
An aggregate data type known as a record is received from the remote host application. The record must be converted to a BEA TUXEDO typed buffer by eLink SNA before it is passed to the BEA TUXEDO application. eLink SNA looks at the service definition to determine what, if any, conversion must be applied to the host data buffer. The service definition uses the In this parameter definition, The Only one The null terminated string is converted to ASCII. The converted string is moved to a BEA TUXEDO STRING typed buffer.
No data conversion is performed on these typed buffers. The remote host application or the BEA TUXEDO application converts the data fields in the record. This includes 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 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). The 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 a BEA TUXEDO 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 BEA TUXEDO application using a C structure.
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 BEA TUXEDO 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.
The eLink SNA system supports remote CICS services as Distributed Program Link (DPL) programs, as described in "Introducing the BEA eLink SNA System." The DPL support is performed as if the BEA TUXEDO 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 A basic DPL request API looks like this:
In the preceding example, the requester sends the The difference between a DPL program and a BEA TUXEDO service is that a receiving BEA TUXEDO service can resize a reply buffer, while the DPL program expects a reply buffer of a designated size. Also, a BEA TUXEDO requester can receive a resized buffer in a buffer different from the original reply buffer.
eLink SNA performs the manipulation described in the following subsections to smoothly adjust to the requirements of both types of applications.
The eLink SNA software must determine what size To determine the The remote DPL application receives a buffer of Strings and Numeric Data
Converting Numeric Data
dec_t type VIEW element.
dec_t type, you can place decimal values in string fields and map these to dec_t fields within VIEW definitions.
Application-to-Host Communications
INBUFTYPE and OUTBUFTYPE.
INBUFTYPE is used to format a typed buffer into a record for the remote host application; OUTBUFTYPE is used to format a host record into a typed buffer for the BEA TUXEDO application.
Buffers Going To The Remote Host Application
INBUFTYPE in both the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES section of the DMCONFIG file to describe the type of buffer manipulation.
INBUFTYPE Parameter Definition
INBUFTYPE = type:subtype
type must be one of the designated BEA TUXEDO typed buffers described in the following subsections.
subtype value names a view and is required for certain BEA TUXEDO typed buffers.
type:subtype may be entered for the INBUFTYPE parameter.
Data Conversion for STRING Typed Buffer
Data Conversion for X_OCTET/CARRAY Typed Buffers
INBUFTYPE parameter is limited to one type:subtype.
Data Conversion for VIEW/VIEW32/X_C_TYPE/X_COMMON Typed Buffers
Data Conversion for FML/FML32 Typed Buffers
Buffers Coming From The Remote Host Application
OUTBUFTYPE in both the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES section of the DMCONFIG file to describe the host record, and how to convert the record to the BEA TUXEDO typed buffer.
OUTBUFTYPE Parameter Definition
OUTBUFTYPE=type:subtype
type must be one of the designated BEA TUXEDO typed buffers described in the following subsections. The type not only determines the typed buffer, but also describes the host record.
subtype value names a view and is required for certain BEA TUXEDO typed buffers.
type:subtype may be entered for the OUTBUFTYPE parameter.
Data Conversion for STRING Typed Buffer
Data Conversion for X_OCTET/CARRAY Typed Buffers
OUTBUFTYPE parameter is limited to one type:subtype.
Data Conversion for VIEW/VIEW32/X_C_TYPE/X_COMMON Typed Buffers
Data Conversion for FML/FML32 Typed Buffers
Data Conversion For DPL Services
COMMAREA.
EXEC CICS LINK
PROGRAM()
DATALENGTH()
LENGTH()
COMMAREA()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 then the LENGTH size, but the requester expects and receives the response in the original COMMAREA buffer the size of LENGTH.
DPL Requests Originating From A TUXEDO Application
COMMAREA the remote DPL service is expecting because there is no corresponding LENGTH parameter on a BEA TUXEDO request.
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 7-3.
LENGTH size and returns a buffer of LENGTH size.
If no The eLink SNA software receives a When considering the interaction between TUXEDO and host applications, you must attend 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 TUXEDO VIEW buffer. This is shown in Listing 7-1, which demonstrates the three ways that the same two strings are coded (LENGTH can be determined, then the largest value allowed by the CICS application is allocated. Refer to the "Data Mapping Tool" section.
DPL Requests Originating From a CICS DPL
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.
Programming Language String Transformation
string1 and string2).
Listing 7-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 -
ENDCOBOL 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 eLink SNA gateway provides a software switch to control the mapping of string data between C and COBOL applications. This switch enables you to automatically compensate for the differences in null termination and padding characteristics of the two languages.
Note: The switch operates on string fields in TUXEDO VIEW buffers only. STRING buffers are not affected by this switch.
To set the switch, use the CLOPT parameter when you configure the gateway server definition in the UBBCONFIG file. If you set the -t option of the CLOPT parameter to one of the values listed in Table 7-4, the gateway performs the corresponding string transformation. Use the following syntax format:
CLOPT="-- -t {number}"
where:
CLOPT
--
-t option, to the server.
-t
number
Note:
If you do not set the -t option of the CLOPT parameter in your server definition, by default the eLink SNA gateway performs no string transformation.
Table 7-4 C to COBOL String Transformation
| CLOPT -t Parameter Value | TUXEDO Application Language | Host Application Language |
|---|---|---|
|
Not Set |
No string transformation established | |
|
1 |
C |
COBOL |
|
2 |
COBOL |
C |
|
3 |
C |
C |
|
4 |
COBOL |
COBOL |
The following is an example of a server definition using the switch to establish string transformations between a TUXEDO application written in C and a host application written in COBOL.
*SERVERS
GWSNAX SRVGRP=GROUP1 SRVID=5 CLOPT="-A -- -t 1"
The eLink SNA software includes translation tables which enable conversions between ASCII character sets and EBCDIC character sets. This gives you 12 standardized tables to facilitate operations between TUXEDO applications using the Latin-1 ASCII code set (CP-00819) and host applications using a national language code set.
Note: Code Page Translation Tables are not supported for BEA WebLogic Enterprise 4.0. However, they are supported for BEA WebLogic Enterprise 4.2.
Each translation table consists of two mapping tables, one for outbound conversions (TUXEDO to host) and one for inbound conversions (host to TUXEDO). You do not have to specify the direction of a translation. All you have to determine is the national language in which the host application is written. Figure 7-1 illustrates code page translation.
Figure 7-1 eLink SNA Code Page Translation
The figure demonstrates how a TUXEDO 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 SNA translation table 00819x00273 provides both the inbound and outbound conversions.
To designate the translation table for your applications, make an entry in the TUXEDO DMCONFIG file definition for each remote domain. Use the CODEPAGE parameter with the following format:
*DM_LOCAL_DOMAINS
{ldom} TYPE={type}*DM_REMOTE_DOMAINS
{rdom} TYPE={type} CODEPAGE={"cpname"}where:
ldom
ldom must be unique across both local and remote domains.
type
TYPE can be set to one of the following values: TDOMAIN, OSITP or SNAX.
rdom
rdom must be unique across both local and remote domains.
cpname
Note:
The DMCONFIG file entries in the previous format description are intended for example only. All required entries are not shown. Refer to dmconfig in Appendix A for complete syntax requirements.
Table 7-5 lists the translation tables provided with eLink SNA software.
Table 7-5 eLink SNA Code Page Translation Tables
1. The default TUXEDO ASCII and EBCDIC code pages are slightly different than 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.
The eLink SNA translation tables are based on IBM-defined code sets. At start up, the eLink SNA 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 TUXEDO tables, which are hard-coded. Refer to Appendix F, "Code Page Translation Tables" for detailed table contents. You must restart the gateway to change any translation table definitions.
Note: Replicas of the default TUXEDO translation tables are included with your product software. These are provided for you to modify, if desired. They are not the actual default tables. You cannot modify the default TUXEDO tables.
The eLink SNA translation tables are located in the following sub-directory:
$TUXDIR/udataobj/codepage
If no CODEPAGE specification is made for a remote domain, the eLink SNA software uses the TUXEDO 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 D, "Error Messages" for explanations of the reason codes.) If the software cannot read the translation table file, it generates an Invalid or Corrupt message and the gateway fails to start. If the software cannot read a translation table file because of access permission, it generates a Permission Denied message and the gateway fails to start.
Listing 7-2 depicts entries defining one local domain (CIXA) and two remote domains (CISA and IMSA). In all cases, it is assumed 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 7-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"
The eLink SNA gateway supports use of the BEA eLink Data Integration Option (DIO) to perform data mapping. If your system includes the eLink DIO as a data mapping tool, read this section to understand it and how it is configured.
The eLink DIO operates in conjunction with the eLink Mercator Integrator for DIO, hereafter referred to as eLink Integrator. This integrator can be configured to map Field Manipulation Language (FML) buffers to COBOL data buffers. The eLink Integrator implements this functionality via TUXEDO platform and eLink SNA gateway configuration settings.
The following subsections provide:
When a TUXEDO client sends a service request with an attached FML buffer to a mainframe server via the eLink SNA gateway, the request is routed through the eLink Integrator. (See Figure 7-2.) The eLink Integrator maps the FML buffer data to a corresponding COBOL data buffer. The gateway then passes the COBOL data buffer to the mainframe. The response from the mainframe is routed in the reverse manner and the eLink Integrator maps from COBOL data back to FML data. This method of conversion applies in both directions, no matter which side initiates the transaction.
Before using the eLink Integrator, you must configure the BEA TUXEDO server and the eLink SNA gateway.
As shown in Listing 7-3, the eLink SNA gateway must be configured to recognize the eLink Integrator to do the data mapping. The For parameter definitions and syntax of the SERVERS section in the UBBCONFIG file required to specify the alternate data mapping product, refer to "Defining a Data Mapping Tool (Optional)," located in "Configuring the System."
Define the
Note:
You must specify Advertise the service for data mapping by defining it in the SERVICES section of the UBBCONFIG file. For parameter definitions and syntax requirements, refer to the "Configuring the System" section and the BEA TUXEDO Reference Manual.
Note:
The name of each of the services must match the map names in the CLOPT parameter in the Listing 7-3 is a sample UBBCONFIG file for Windows NT in which the eLink Integrator is specified as an alternate data mapping tool. In this sample, the Data Mapping Overview
Figure 7-2 Data Mapping Process Flow
Setting Up the eLink Integrator in the UBBCONFIG File
-e gateway option in the CLOPT parameter of the SERVERS section in the UBBCONFIG file sets up the gateway to recognize this external tool. The value for alternate data mapping is -eMERC. Listing 7-3 is a sample UBBCONFIG file that contains this definition.
Defining the elinkmerc Server
elinkmerc server as the server responsible for the data mapping operation. To define this server, add the elinkmerc information in the SERVERS section of the UBBCONFIG file. For parameter and syntax definitions, refer to the section "Configuring the System" and the BEA TUXEDO Reference Manual.
elinkmerc as the file to execute for the data mapping process. Within this server definition, you must also specify the -s option in the CLOPT parameter.
Advertising the Services for Data Mapping
elinkmerc server definition.
Sample UBBCONFIG File for Data Mapping
elinkmerc server is defined in the SERVERS section with the required CLOPT -s option specified. Also, the -eMERC option is specified in the CLOPT parameter of the GWSNAX server definition.
Listing 7-3
Sample UBBCONFIG File for Data Mapping
*RESOURCES
IPCKEY 123791
DOMAINID simpapp
MASTER simple
*MACHINES
DALNT6
LMID = simple
TUXDIR = "\tuxedo"
TUXCONFIG = "\myappdir\tuxconfig"
APPDIR = "\myappdir"
FIELDTBL = "sample.fml"
FIELDTBL32 = "sample.fml"
FLDTBLDIR = "\myappdir"
FLDTBLDIR32 = "\myappdir"
ULOGPFX = "\myappdir\ULOG"
# LD_LIBRARY_PATH=\dio
# SHLIB_PATH=\dio
PATH=\dio
*GROUPS
eLINK
LMID=simple GRPNO=1
*SERVERS
DEFAULT:
CLOPT="-A"
elinkmerc
SRVGRP=eLINK SRVID=10
REPLYQ=N
CLOPT="-sFML2COB:XLATE_SERVICE -sCOB2FML:XLATE_SERVICE -- -WUD -TIO -AE"
GWSNAX
SRVGRP=eLINK SRVID=21
CLOPT="-A -- -eMERC"
*SERVICES
FML2COB
COB2FML
*ROUTING
Before running the eLink SNA gateway with the eLink Integrator, you must edit the TUXEDO DMCONFIG file to specify the local and remote services and buffer types used for data mapping, as shown in Listing 7-4
In the sample configuration, local service INFML and remote service OUTFML contain FML views that the eLink Integrator translates to mainframe COBOL data buffers (FML2COB, specified in the INBUFTYPE definitions). These services also contain FML views that the eLink Integrator translates to FML buffers (COB2FML, specified in the OUTBUFTYPE definitions).
Listing 7-4 Sample DMCONFIG File for Alternate Data Mapping
*DM_LOCAL_DOMAINS
LOCAL GWGRP=GROUP
TYPE=IDOMAIN
DOMAINID="LOCAL"
*DM_REMOTE_DOMAINS
REMOTE TYPE=IDOMAIN
DOMAINID="REMOTE"
*DM_LOCAL_SERVICES
INFML RNAME="TV16X"
INBUFTYPE="FML:FML2COB"
OUTBUFTYPE="FML:COB2FML"
*DM_REMOTE_SERVICES
OUTFML RDOM=REMOTE
LDOM=LOCAL
INBUFTYPE="FML:FML2COB"
OUTBUFTYPE="FML:COB2FML"
RNAME="ZOUTFML"
For transactions originated by the mainframe, this is done in the DM_LOCAL_SERVICES section of the DMCONFIG file. See Listing 7-4 for an example.
The advertised input service (INFML) includes an INBUFTYPE and an OUTBUFTYPE. Use the INBUFTYPE to specify an FML view for encoding FML buffers to COBOL data buffers (FML2COB). Use the OUTBUFTYPE to specify an FML view for decoding COBOL data buffers to FML buffers (COB2FML).
In terms of request/response exchanges, the settings result in the following conditions:
OUTBUFTYPE that
the eLink DIO decodes from COBOL to FML.
Note:
If the -eMERC option is not set, the INBUFTYPE and OUTBUFTYPE parameters operate as described in the dmconfig section of Appendix A, "Reference Pages."
For transactions originated by the TUXEDO platform, this is done in the DM_REMOTE_SERVICES section of the DMCONFIG file. See Listing 7-4 for an example.
The advertised output service (OUTFML) includes an INBUFTYPE and an OUTBUFTYPE. Use the INBUFTYPE to specify an FML view for encoding FML buffers to COBOL data buffers (FML2COB). Use the OUTBUFTYPE to specify an FML view for decoding COBOL data buffers to FML buffers (COB2FML).
In terms of request/response exchanges, these settings result in the following conditions:
INBUFTYPE that the eLink DIO encodes from FML to COBOL.
Note:
If the -eMERC option is not set, the INBUFTYPE and OUTBUFTYPE parameters operate as described in the dmconfig section of Appendix A, "Reference Pages."
Note: The current size limit of remote host messages is limited to approximately 32K bytes. Any conversions resulting in records larger than 32756 bytes are not supported.
