Configuring BEA eLink TCP for TUXEDO for Data Mapping

The key to the high degree of transparency between systems is the eLink for Mainframe TCP for TUXEDO (hereafter referenced as eLink TCP for TUXEDO) configuration. It is through this mechanism that environmental differences, such as data formats, are concealed from programmers and programs.

This document provides information about the following topics:

• Converting Input and Output Data

• Managing Parameters for Buffer and Record Conversion

• Translating Data

• Encoding COBOL Data Types

• Using Code Page Translation Tables

• Configuring the Gateway for Alternate Data Mapping Tools

This document also provides information about creating VIEW definitions. VIEW definitions are descriptions of data structures that are used for input and output in the BEA TUXEDO environment. The eLink TCP for TUXEDO product uses VIEW definitions to determine how to convert input data and output data into formats that are acceptable to target systems.

For detailed information about updating the eLink TCP for TUXEDO configuration files (GWICONFIG and DMCONFIG), see "Configuring BEA eLink TCP for TUXEDO."

Note: The task of configuring data mappings could be considered a programming activity because it requires knowledge of the BEA TUXEDO programming environment. However, because configuration parameters affect many application programs, configuration is usually an administrator's responsibility.

Converting Input and Output Data

This section introduces procedures that eLink TCP for TUXEDO follows to process and convert input and output data.

Buffers and Records

In this guide, the following terms are used to describe input and output data.

Buffer

Input or output data as it exists inside the local BEA TUXEDO region. This includes all the buffer types that BEA TUXEDO software supports-both BEA TUXEDO ATMI buffer types and X/Open XATMI buffer types.

Record

Input or output data as it exists outside the local BEA TUXEDO region-on different kinds of systems.

These terms make it easier to understand how eLink TCP for TUXEDO handles input and output data.

Buffers Received from Local Programs

The eLink TCP for TUXEDO gateway processes buffers from local programs in the following manner.

1. When eLink TCP for TUXEDO receives a buffer from a local program, it automatically determines the buffer's type.

   The eLink TCP for TUXEDO product automatically "types" input buffers that local client programs send to remote services.

   The eLink TCP for TUXEDO product automatically "types" output buffers that local services return to remote client programs.

2. After eLink TCP for TUXEDO determines a buffer's type, it consults the configuration file (GWICONFIG) to determine whether the buffer needs to be converted to a different format.

   Client requests sent to remote services may need to be converted to record formats that are meaningful to those services.

   Server responses returned to remote client programs may need to be converted to record formats that are meaningful to those programs.

3. If the configuration indicates that conversion is required, eLink TCP for TUXEDO transforms the buffer into the record format that is specified in the configuration.

The eLink TCP for TUXEDO gateway processes buffers from remote programs in the following manner.

1. When eLink TCP for TUXEDO receives a record from a remote system, it consults the configuration file (GWICONFIG) to determine the record's type.

2. After eLink TCP for TUXEDO determines a record's type, it consults the domain configuration (DMCONFIG) to determine whether the record needs to be converted to a different format.

   Client requests from remote client programs may need to be converted to buffer formats that are acceptable to local service routines.

   Server responses returned from remote services may need to be converted to buffer formats that are acceptable to local client programs.

3. If the configuration indicates that conversion is required, eLink TCP for TUXEDO transforms the record into the buffer format that is specified in the configuration.

The eLink TCP for TUXEDO product provides four configuration parameters you can use to map buffers and records. For more information about buffers and records, see section "Buffers and Records."

Specify the following buffer configuration parameters in the domain configuration file (DMCONFIG).

INBUFTYPE

Identifies the type, and in some cases the format, of a buffer received from a TUXEDO client or server

OUTBUFTYPE

Identifies the type, and in some cases the format, of a buffer to be sent to a TUXEDO client or server

Specify the following record configuration parameters in the gateway configuration file (GWICONFIG).

INRECTYPE

Identifies the type, and in some cases the format, of a buffer to be sent to a remote gateway

OUTRECTYPE

Identifies the type, and in some cases the format, of a buffer received from a remote gateway

Each of these four parameters has two possible meanings or interpretations-one for service requests that originate locally, and one for service requests that originate on remote systems.

The following sections, "Parameters for Locally Originated Calls" and "Parameters for Remotely Originated Calls", explore these different meanings in detail.

Parameters for Locally Originated Calls

This section takes a closer look at how eLink TCP for TUXEDO handles service calls that originate locally, within the immediate BEA TUXEDO region. Also, it explains how the INBUFTYPE, INRECTYPE, OUTRECTYPE, and OUTBUFTYPE parameters can be used to manage the conversion of buffers and records that flow between local client programs and remote services.

In Figure 3-1, a local BEA TUXEDO client program issues a service call that a local eLink TCP for TUXEDO gateway routes to a remote server through eLink TCP for TUXEDO.

Figure 3-1 How Parameters Are Mapped During Locally Originated Calls

In this situation, the four configuration parameters that are shown in the figure have the following meanings:

• The INBUFTYPE parameter describes the BEA TUXEDO input buffer that the local client program provides to the eLink TCP for TUXEDO gateway through BEA TUXEDO software.

• The INRECTYPE parameter describes the input record that is sent to the service on the remote system.

• The OUTRECTYPE parameter describes the output record that is received from the service on the remote system.

• The OUTBUFTYPE parameter describes the BEA TUXEDO output buffer that is returned to the local client program.

Guidelines for Mapping Input Buffers to Input Records

The following sections provide detailed information explaining how to use the INBUFTYPE and INRECTYPE parameters for service calls that originate locally (where local client programs call remote services).

INBUFTYPE

The INBUFTYPE parameter is used to specify the request buffer type that is provided to a local eLink TCP for TUXEDO gateway when a local client program issues a service request.

Because the gateway determines the type of client request buffers automatically at runtime, this parameter is described here for conceptual completeness only.

INRECTYPE

The INRECTYPE parameter is used to specify the type, and in some cases the format, of the request record that a particular remote service requires. The eLink TCP for TUXEDO gateway uses this information to convert BEA TUXEDO request buffers into records that remote services can process.

You must specify the INRECTYPE parameter when one of the circumstances described in the following table is true.

Circumstance	Explanation
The remote service uses an input record that is structured differently than the client program's request buffer.	In this circumstance, the remote service uses a record that is structured differently than the client program's VIEW, X_C_TYPE, or X_COMMON buffer. For example, the remote service may expect structure members to be sequenced differently.
The remote service uses a request record that differs from the client program's request buffer in both type and structure.	In this case, the client program uses a BEA TUXEDO FML buffer and the remote service expects a corresponding record with an appropriate structure.

The INRECTYPE parameter may be omitted if the request buffer is identical, in type and structure, to the request record the remote service expects.

The following sections provide detailed information explaining how to use the OUTRECTYPE and OUTBUFTYPE parameters for service calls that originate locally (where local client programs call remote services and receive output from those services).

OUTBUFTYPE

The OUTBUFTYPE parameter is used to specify the type, and in some cases the structure, of the reply buffer that a local client program expects. The eLink TCP for TUXEDO gateway uses this information to map reply records from remote services to the appropriate kinds of reply buffers.

OUTRECTYPE

The OUTRECTYPE parameter is used to specify the type, and in some cases the format, of the reply record that a particular remote service returns to the local eLink TCP for TUXEDO gateway.

You must specify the OUTRECTYPE parameter when one of the circumstances described in the following table is true.

Circumstance	Explanation
The remote service returns a reply record that is structured differently than the reply buffer the local client program expects.	In this circumstance, the remote service returns a record that is structured differently than the client program's VIEW, X_C_TYPE, or X_COMMON buffer. For example, the structure members of the output record may be sequenced differently than the structure members of the output buffer.
The remote service returns a reply record that differs in both type and structure from the reply buffer the client program expects.	In this case, the remote service returns a particular record and the local client program expects a corresponding BEA TUXEDO FML buffer.

The OUTRECTYPE parameter may be omitted if the remote service returns a reply record that is identical, in type and structure, to the reply buffer the local client program expects.

This section takes a closer look at how eLink TCP for TUXEDO handles service calls that originate on remote computers, outside the local BEA TUXEDO region. Also, it explains how the INRECTYPE, INBUFTYPE, OUTBUFTYPE, and OUTRECTYPE parameters can be used to manage the conversion of buffers and records that flow between remote client programs and local services.

In Figure 3-2, a remote client program issues a service request that a remote eLink TCP gateway routes to the local eLink TCP for TUXEDO gateway. The gateway receives the request from the network and passes the request to a local BEA TUXEDO server.

Figure 3-2 How Parameters Are Mapped During Remotely Originated Calls

In this situation, the four configuration parameters that are shown in the figure have the following meanings:

• The OUTRECTYPE parameter describes the output record that the remote client sends to the eLink TCP for TUXEDO gateway.

• The OUTBUFTYPE parameter describes the BEA TUXEDO output buffer that is provided to the local server.

• The INBUFTYPE parameter describes the BEA TUXEDO input buffer that the local server returns to the eLink TCP for TUXEDO gateway.

• The INRECTYPE parameter describes the input record that the local eLink TCP for TUXEDO gateway returns to the remote client program.

Guidelines for Mapping Input Records to Input Buffers

The following sections provide detailed information explaining how to use the INRECTYPE and INBUFTYPE parameters for service calls that originate on remote systems (where remote client programs call local services).

INBUFTYPE

The INBUFTYPE parameter is used to specify the type, and in some cases the structure, of the reply buffer that the eLink TCP for TUXEDO gateway expects from a local server. The eLink TCP for TUXEDO gateway uses this information to map reply buffers from local server programs to the appropriate kind of reply records.

Because the gateway determines the type of incoming buffers automatically at runtime, this parameter is described here for conceptual completeness only.

INRECTYPE

The INRECTYPE parameter is used to specify the type, and in some cases the format, of the reply record that the local eLink TCP for TUXEDO gateway sends to the remote client.

You must specify the INRECTYPE parameter when one of the circumstances described in the following table is true.

Circumstance	Explanation
The remote client program requires a reply record that is structured differently than the reply buffer the local service provides.	In this circumstance, the remote client program sends a record that is structured differently than the local service's VIEW, X_C_TYPE, or X_COMMON buffer. For example, the structure members of the input record may be sequenced differently than the structure members of the input buffer.
The remote client program requires a reply record that differs in both type and structure from the reply buffer the local service provides.	In this case, the remote client program requires a particular record and the local service provides a corresponding BEA TUXEDO FML buffer.

You can omit the INRECTYPE parameter if the local server program sends a reply buffer that is identical in type and structure to the reply record the remote client expects.

The following sections provide detailed information explaining how to use the OUTBUFTYPE and OUTRECTYPE parameters for service calls that originate on remote computers (where remote client programs call local services and receive output from those services).

OUTBUFTYPE

The OUTBUFTYPE parameter specifies the request buffer type that the local eLink TCP for TUXEDO gateway provides to the local server.

OUTRECTYPE

The OUTRECTYPE parameter is used to specify the type, and in some cases the format, of the request record a particular remote client program sends to the eLink TCP for TUXEDO gateway. The eLink TCP for TUXEDO gateway uses this information to convert request records from remote clients into buffers that local server programs can process.

You must specify the OUTRECTYPE parameter when one of the circumstances described in the following table is true.

Circumstance	Explanation
The remote client program provides a request record that is structured differently than the local service's request buffer.	In this circumstance, the remote client program provides a record that is structured differently than the local service's VIEW, X_C_TYPE, or X_COMMON buffer. For example, the local server program may expect structure members to be sequenced differently.
The remote client program provides an request record that differs from the local service's request buffer in both type and structure.	In this case, the remote client outputs a record and the local client program expects a corresponding BEA TUXEDO FML buffer.

The OUTRECTYPE parameter may be omitted if the local service's request buffer is identical, in type and structure, to the request record the remote client program provides.

Figure 3-3 shows all the possibilities for mapping buffers to records. The eLink TCP for TUXEDO gateway is responsible for mapping buffers to records, based on information it finds in the eLink TCP for TUXEDO configuration. This mapping occurs for TUXEDO client requests and TUXEDO server responses.

Figure 3-3 Buffer to Record Mappings

Setting the INBUFTYPE and INRECTYPE Parameters

Here are some comments about the mapping possibilities that are shown in Figure 3-3 and some suggestions for setting the INBUFTYPE and INRECTYPE parameters.

Mapping Records to Buffers

Figure 3-4 shows all the possibilities for mapping records to buffers. The eLink TCP for TUXEDO gateway is responsible for mapping records to buffers, based on information it finds in the eLink TCP for TUXEDO configuration. This mapping occurs for remote client requests and remote server responses.

Figure 3-4 Record to Buffer Mappings

Setting the OUTRECTYPE and OUTBUFTYPE Parameters

Here are some comments about the mapping possibilities that are shown in Figure 3-4 and some suggestions for setting the OUTRECTYPE and OUTBUFTYPE parameters (for service calls that originate locally).

Creating VIEW Definitions to Facilitate Buffer Conversion

VIEW definitions are used to describe input and output records that are sent to and received from remote systems. They describe data elements and indicate how data elements are typed and sequenced. Based on these descriptions, eLink TCP for TUXEDO translates field data types as required to maintain transparency between dissimilar systems.

You should create VIEW definitions before you configure eLink TCP for TUXEDO. For complete information about VIEW definitions and related topics, see the BEA TUXEDO Programmer's Guide.

The eLink TCP for TUXEDO buffer and record conversion capabilities are extremely powerful and flexible. The key to maximizing these capabilities is to thoroughly understand the BEA TUXEDO VIEW definition mechanism.

VIEW definitions make it possible to specify composite data structures that can be used:

• On different kinds of machines

• With different programming languages

Preparing VIEW Definitions

After determining the input and output record layouts for the remote application programs you are working with, you need to prepare VIEW definitions and specify these definitions in the configuration files.

Note: FML fields must be specified for all VIEWs that eLink TCP for TUXEDO converts. In other words, any VIEW that you specify as an INRECTYPE, OUTRECTYPE, INBUFTYPE, or OUTBUFTYPE must be defined with appropriate FML fields (no dashes in the FNAME column of the VIEW definition). For the FML fields to match, you must compile these VIEWs without the -n option specified.

1. Create standard BEA TUXEDO VIEW definitions in files.

2. Run the viewc or viewc32 VIEW compiler.

3. Set the VIEWFILES, VIEWDIR, FIELDTBLS, and FLDTBLDIR environment variables, using a BEA TUXEDO ENVFILE if necessary (so that eLink TCP for TUXEDO servers can locate binary VIEW files and field table files at runtime).

4. After these tasks are complete, you can specify VIEW definitions in the GWICONFIG and DMCONFIG files (by associating names of VIEW definitions with the INRECTYPE, OUTRECTYPE, INBUFTYPE, and OUTBUFTYPE parameters, as required).

   For detailed information about configuring eLink TCP for TUXEDO, see "Configuring BEA eLink TCP for TUXEDO."

When a local client program sends data to (or receives data from) a service routine on a different kind of computer, eLink TCP for TUXEDO automatically translates data as required. Translation involves changing the representation of intrinsic data types by changing attributes such as word length and byte order.

The eLink TCP for TUXEDO gateway automatically translates input and output data as required, following rules that are described in the following section. Read the information carefully before you create VIEW definitions (to facilitate buffer conversion) and configure eLink TCP for TUXEDO.

Basic rules for how eLink TCP for TUXEDO translates data are described in the following subsection. For detailed information about how eLink TCP for TUXEDO handles string and numeric data, refer to the "NULL Characters in String Length Calculations (C Programs)" section.

Data Translation Rules

The following information outlines the data translation rules that eLink TCP for TUXEDO follows:

• CARRAY fields are passed untranslated as sequences of bytes.

• STRING and CHAR fields undergo ASCII-to-EBCDIC translation (if needed).

• SHORT and LONG fields are translated to S9(4) COMP and S9(9) COMP, respectively.

• FLOAT and DOUBLE fields translate to COMP-1 and COMP-2, respectively.

  Warning: dec_t cannot be used with VIEW translations.

  Note: BEA TUXEDO provides a field type named dec_t that supports decimal values within VIEWs. The eLink TCP for TUXEDO 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.

The following table summarizes the relationships.

NULL Characters in String Length Calculations (C Programs)

When you create VIEW definitions for input and output buffers that are used by C language applications, you must specify extra characters for terminating NULL characters that are used in string fields.

For example, when a local application program expects a 10-byte string in an output buffer, you would specify 11 for that field-10 for the string plus 1 for the terminating NULL character.

NULL Characters in String Length Calculations (COBOL Programs)

When you create VIEW definitions for input and output buffers that are used by COBOL language applications, do not specify extra characters for terminating NULL characters that are used in string fields.

For example, when a remote COBOL application program expects 10 characters in an input record, you would specify 10 for that field, not 10 plus 1 (for the terminating NULL character).

Note: Although eLink TCP for TUXEDO does not require strings to be NULL-terminated, it respects NULL termination. Therefore, when eLink TCP for TUXEDO 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 eLink TCP for TUXEDO product provides standard character translation from ASCII-to-EBCDIC and EBCDIC-to-ASCII. eLink TCP for TUXEDO automatically performs this translation on the string data type.

Converting Numeric Data

Numeric data can easily be converted into different data types, provided that you have enough range in the intermediate and destination types to handle the maximum value you need to represent.

For example, you can convert numeric values into strings (and the reverse). 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.

Encoding COBOL Data Types

An additional encoding library, ConvMVSC, has been included for TUXEDO clients using COBOL data types. This library, ConvMVSC, is similar to the default library, ConvMVS, but differs in the following ways:

• For the STRING data type, both ConvMVSC and ConvMVS perform ASCII-to-EBCDIC and EBCDIC-to-ASCII translation.

  • For strings sent to a remote gateway, both libraries perform ASCII-to-EBCDIC conversion, and forward the string to the mainframe.

  • For strings received from a remote gateway, the ConvMVS library performs EBCDIC-to-ASCII translation, truncates any trailing space characters and adds a NULL terminator. The ConvMVSC library performs the translation, but does not truncate spaces or add the terminator.

• For the VIEW data type, the ConvMVS and ConvMVSC libraries treat all field types except STRING the same.

  • For STRING fields within a view sent to a remote gateway, ConvMVS performs ASCII-to-EBCDIC conversion and appends space to `pad' the string with space characters to the size of the field. ConvMVSC performs the character conversion, but does not perform any `padding'.

  • For STRING fields within a view received from a remote gateway, ConvMVS performs EBCDIC-to-ASCII conversion, truncates any trailing space characters, and adds a NULL terminator. The ConvMVSC library performs the character conversion, but does not truncate spaces or add the terminator.

Using the COBOL Data Encoding Library

There are two methods for enabling the COBOL data encoding library:

• COBOL data encoding for all services

• COBOL data encoding for messages to and from a specific host

Encoding for All Services

To enable COBOL data encoding for every service in the gateway, set the parameter DFLTTYPE="MVSC" in the GLOBAL section of the GWICONFIG file.

Listing 3-1 Encoding for All Services

---

To enable COBOL data encoding for messages to and from a specific host, set the parameter TYPE="MVSC" for that hosts FOREIGN entry in the GWICONFIG file.

Listing 3-2 Encoding for Messages To and From a Specific Host

---

The eLink TCP software includes translation tables which enable conversions of single byte character sets (SBCS) between ASCII and EBCDIC. These tables are based on IBM-defined code sets and include the default TUXEDO code page, which is the default code page translation table used in previous releases of eLink TCP.

Note: Code page translation tables are only supported with BEA TUXEDO and BEA WebLogic Enterprise 4.2.

Each translation table consists of two mapping tables, one for outbound conversions (TUXEDO to mainframe) and one for inbound conversions (mainframe to TUXEDO). You do not have to specify the direction of a translation; however, you must determine the national language in which the host application is written. Figure 3-5 illustrates code page translation.

Figure 3-5 eLink TCP 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 TCP 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 DMCONFIG file definition for each remote domain. Use the CODEPAGE parameter in the DM_REMOTE_DOMAINS section of the DMCONFIG file. Specify the translation table to use.

To specify a default code page translation for remote hosts to use, specify the translation table filename in the CODEPAGE parameter for the local gateway entry in the DM_LOCAL_DOMAINS section of the DMCONFIG file.

Note: To use code page translations with eLink TCP, be sure the remote host names in the DM_REMOTE_DOMAINS section match corresponding entries in the GWICONFIG file. Also, local host names in the DM_LOCAL_DOMAINS section must match corresponding values in the GWICONFIG file.

Table 3-1 lists the translation tables provided with the eLink TCP software.

Table 3-1 eLink TCP Code Page Translation Tables

Note: The TUXEDO default ASCII and EBCDIC code pages differ slightly from CP-00819 and CP-00037.

How the Translation Tables Work

At start up, the eLink TCP for TUXEDO 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. You must restart the gateway to change any translation table definitions. The eLink TCP translation tables are located in $TUXDIR/udataobj/codepage. For table contents, refer to "Code Page Translation Tables."

If no CODEPAGE specification is made for a remote domain, the eLink TCP for TUXEDO software uses the TUXEDO default translation tables.

Note: Copies of the default TUXEDO translation tables are included with your product software in $TUXDIR/udataobj/codepage. These copies are provided for you to apply modifications if necessary for your applications. These copies are not the actual default tables used by the gateway. You cannot modify the default TUXEDO tables because they are hard-coded.

Troubleshooting Translation Table Errors

The following information assists you in resolving errors associated with translation tables that cause the gateway to fail. The gateway issues the following message when encountering an error associated with the specified translation table.

1072:ERROR Cannot read CODEPAGE <filename> for <LOCAL | REMOTE> DOMAIN <domainname>

For a description of error messages, refer to "Error and Informational Messages." The following causes may be responsible for the gateway issuing the previous error.

• The gateway cannot find the translation table file.

  Verify that you specified the correct codepage name in the CODEPAGE parameter in the DM_REMOTE_DOMAIN section of the DMCONFIG file and that the file resides in $TUXDIR/udataobj/codepage.

• The software cannot read the translation table file.

  Verify that the file name specified for the CODEPAGE parameter is valid. Also, verify that the specified file is not corrupt.

• The software cannot read the translation table file because of access permissions.

  Verify that the specified translation table file in the $TUXDIR/udataobj/codepage directory has read permissions.

Sample DMCONFIG Definition for ASCII to EBCDIC Translations

Listing 3-3 depicts entries defining one local domain (CIXA) and two remote domains (CISA and IMSA). In the following example, it is assumed that the local domain uses ASCII code page CP-00819 and the two remote domains use the German and French EBCDIC code pages CP-00273 and CP-00297, respectively.

Listing 3-3 Code Page Definition Example

---

The eLink TCP for TUXEDO gateway supports use of an alternate data mapping tool such as TSI Soft's Mercator product and BEA eLink Adapter for Mercator component to perform data conversion.

The eLink TCP for TUXEDO gateway passes typed buffers from TUXEDO servers and clients to an alternate data mapping tool for encoding before being passed to the mainframe. It also passes COBOL data buffers from mainframe clients and servers to the alternate data mapping tool for decoding before being passed to TUXEDO servers or clients.

Before running an alternate data mapping product, you must configure the BEA TUXEDO server and the eLink TCP for TUXEDO gateway.

Specifying the Alternate Data Mapping Product in the UBBCONFIG File

As shown in Listing 3-4, the eLink TCP for TUXEDO gateway must be configured to recognize an alternate data mapping product to do the data mapping. The -e gateway option in the CLOPT parameter of the SERVERS section in the UBBCONFIG sets up the gateway to recognize this external product. The only valid type value for alternate data mapping is -eMERC (for use with the eLink Adapter for Mercator). Listing 3-4 is a sample UBBCONFIG file that contains a gateway server definition.

For parameter definitions and syntax of the SERVERS section of the UBBCONFIG file for the gateway server to recognize the alternate data mapping product, refer to "Configuring BEA eLink TCP for TUXEDO."

Advertise the Services for Data Mapping

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 "Configuring BEA eLink TCP for TUXEDO" 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 elinkmerc server definition.

Sample UBBCONFIG File for Data Mapping

Listing 3-4 is a sample UBBCONFIG file for Windows NT in which the eLink Adapter is configured as an alternate data mapping tool. In this sample, the elinkmerc server is defined in the SERVER section with the required CLOPT -s option specified. Also, the -eMERC option is specified in the CLOPT parameter of the GWIDOMAIN server definition.

Listing 3-4 Sample UBBCONFIG File for Data Mapping

---

Before running the eLink TCP for TUXEDO gateway, which invokes an alternate data mapping product, you must edit the DMCONFIG file to recognize the alternate data mapping product to use for data mapping.

As shown in Listing 3-5, within the eLink TCP for TUXEDO domain configuration, the client calls the advertised mainframe service and the DMCONFIG file specifies the buffer type and the service to use for the data conversion.

Note: When the use of an alternate data mapping product is turned on, the internal encoding features of the gateway are bypassed. This means that some parameters in the GWICONFIG file, such as INRECTYPE, OUTRECTYPE, and TYPE, have no effect. For information about the GWICONFIG file, refer to "Configuring BEA eLink TCP for TUXEDO."

In the sample configuration in Listing 3-5, local service INFML and remote service OUTFML send FML buffers that are translated to mainframe COBOL copybooks by external encode routine FML2COB. The services receive FML buffers that are translated from COBOL copybooks by external decode routine COB2FML.

Listing 3-5 Sample DMCONFIG File for Alternate Data Mapping

---

If the alternate data mapping option is turned on by setting the -eMERC gateway option in the CLOPT parameter and the buffer type is FML, then remotely originated requests are sent to the TUXEDO service (advertised by the alternate data mapping product) specified in OUTBUFTYPE for decoding. Responses are sent to the TUXEDO service specified in INBUFTYPE for encoding.

If the alternate data mapping option is off, the INBUFTYPE and OUTBUFTYPE parameters operate as described in the "Configuring BEA eLink TCP for TUXEDO."

Specifying the Alternate Data Mapping Service in DM_REMOTE_SERVICES

If the alternate data mapping option is turned on by setting the -eMERC gateway option in the CLOPT parameter (in the UBBCONFIG file) and the buffer type is FML, then locally originated requests are sent to the TUXEDO service (advertised by the alternate data mapping product) specified in INBUFTYPE for encoding. Responses are sent to the TUXEDO service specified in OUTBUFTYPE for decoding.

If the alternate data mapping option is off, the INBUFTYPE and OUTBUFTYPE parameters operate as described in "Configuring BEA eLink TCP for TUXEDO."

Configuring the elinkmerc Server to Run with eLink Adapter

The TSI Soft's Mercator product and the BEA eLink Adapter for Mercator component can act as an alternate data mapping tool. The eLink Adapter for Mercator data conversion is implemented as a TUXEDO server, which performs two functions-encoding TUXEDO typed buffers into data buffers matching COBOL copybooks, and decoding COBOL data buffers into TUXEDO typed buffers.

Before running the eLink Adapter, you must edit the UBBCONFIG file to recognize the services being used for the data mapping. For UBBCONFIG parameter syntax and definitions, refer to the BEA TUXEDO Reference Manual.

Define the elinkmerc Server

Define the elinkmerc server as the server responsible for the data mapping operation. To define this server, add the elinkmerc information in the SERVER section of the UBBCONFIG file. For parameter and syntax definitions, refer to "Configuring BEA eLink TCP for TUXEDO" and the BEA TUXEDO Reference Manual.

Note: You must specify 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.