Configuring Oracle TMA TCP Gateway for Data Mapping

The key to the high degree of transparency between systems is the Tuxedo Mainframe Adapter for TCP Gateway (hereafter referenced as TMA TCP Gateway) configuration. Environmental differences, such as data formats, are concealed from programmers and programs through this mechanism.

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

•	Using Multibyte Character Set (MBCS) Translations

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 Oracle Tuxedo environment. The TMA TCP Gateway 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 TMA TCP Gateway configuration files (GWICONFIG and DMCONFIG), see the “Configuring Oracle TMA TCP Gateway” section.

Note:

The task of configuring data mappings could be considered a programming activity because it requires knowledge of the Oracle 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 TMA TCP Gateway 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 Oracle Tuxedo region. This definition includes all the buffer types that Oracle Tuxedo software supports—both Oracle Tuxedo ATMI buffer types and X/Open XATMI buffer types.

Record

Input or output data as it exists outside the local Oracle Tuxedo region—on different kinds of systems.

These terms make it easier to understand how TMA TCP Gateway handles input and output data.

Buffers Received from Local Programs

The TMA TCP Gateway processes buffers from local programs in the following manner.

1.	When TMA TCP Gateway receives a buffer from a local program, it automatically determines the buffer's type.

The TMA TCP Gateway product automatically “types” input buffers that local client programs send to remote services.

The TMA TCP Gateway product automatically “types” output buffers that local services return to remote client programs.

2.	After TMA TCP Gateway 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, TMA TCP Gateway transforms the buffer into the record format that is specified in the configuration.

Records Received from Remote Programs

The TMA TCP Gateway processes buffers from remote programs in the following manner.

1.	When TMA TCP Gateway receives a record from a remote system, it consults the configuration file (GWICONFIG) to determine the record’s type.

2.	After TMA TCP Gateway 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, TMA TCP Gateway transforms the record into the buffer format that is specified in the configuration.

Managing Parameters for Buffer and Record Conversion

The TMA TCP Gateway product provides four configuration parameters you can use to map buffers and records. For more information about buffers and records, see the “Buffers and Records” section.

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 TMA TCP Gateway handles service calls that originate locally, within the immediate Oracle 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 the following figure, a local Oracle Tuxedo client program issues a service call that a local TMA TCP Gateway routes to a remote server through TMA TCP Gateway.

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 Oracle Tuxedo input buffer that the local client program provides to the TMA TCP Gateway through Oracle 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 Oracle 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 TMA TCP 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 TMA TCP Gateway uses this information to convert Oracle 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 an Oracle 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.

Guidelines for Mapping Output Records to Output Buffers

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 TMA TCP 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 TMA TCP 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 Oracle 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.

Parameters for Remotely Originated Calls

This section takes a closer look at how TMA TCP Gateway handles service calls that originate on remote computers, outside the local Oracle 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 the following figure, a remote client program issues a service request that a remote TMA TCP gateway routes to the local TMA TCP Gateway. The gateway receives the request from the network and passes the request to a local Oracle 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 TMA TCP Gateway.

•	The OUTBUFTYPE parameter describes the Oracle Tuxedo output buffer that is provided to the local server.

•	The INBUFTYPE parameter describes the Oracle Tuxedo input buffer that the local server returns to the TMA TCP Gateway.

•	The INRECTYPE parameter describes the input record that the local TMA TCP 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 TMA TCP Gateway expects from a local server. The TMA TCP 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 TMA TCP 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 Oracle 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.

Guidelines for Mapping Output Buffers to Output Records

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 TMA TCP 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 TMA TCP Gateway. The TMA TCP 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 Oracle 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.

Mapping Buffers to Records

The following figure shows all the possibilities for mapping buffers to records. The TMA TCP Gateway is responsible for mapping buffers to records, based on information it finds in the TMA TCP Gateway 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

The following table lists some of the mapping possibilities that are shown in the previous figure and some suggestions for setting the INBUFTYPE and INRECTYPE parameters.

 

1	Oracle Tuxedo CARRAY input buffers can be copied to CARRAY input records. A CARRAY buffer contains raw data that is not converted or translated. Set the INBUFTYPE parameter to CARRAY, and omit the INRECTYPE parameter. CARRAY input buffers can also be copied to STRING input records. This creates a string that goes through no conversion and no translation. The resultant buffer is the length of the original CARRAY buffer. Since all characters are copied, if the CARRAY buffer contains null characters, it affects the buffer when later handled as a STRING. The INBUFTYPE parameter should be set to CARRAY and the INRECTYPE parameter should be set to STRING.
2	Oracle Tuxedo STRING input buffers can be mapped to CARRAY input records. No data conversion or translation is performed. The STRING buffer is copied through the leftmost null character only. Set the INBUFTYPE parameter to STRING and the INRECTYPE parameter to CARRAY.
3	Oracle Tuxedo STRING input buffers can be mapped to STRING input records. The buffer goes through data type translation (such as ASCII to EBCDIC). Set the INBUFTYPE parameter to STRING, and omit the INRECTYPE parameter.
4	Oracle Tuxedo VIEW input buffers can be mapped to identical Oracle Tuxedo VIEW input records. In this situation, the data structure that the remote service expects is identical to the data structure the client program uses. There is no need to create a new VIEW definition. Instead, specify the input record type (VIEW) and the name of the existing VIEW definition (the one the client program currently uses) for both the INBUFTYPE parameter, and omit the INRECTYPE parameter.
5	Oracle Tuxedo VIEW input buffers can be mapped to VIEW input records—in any combination. However, in this situation, the data structure that the remote service expects (designated as VIEW ‘B’ mapping possibilities in Figure 3‑3) differs from the data structure the client program uses (designated as VIEW ‘A’ in Figure 3‑3). Consequently, you must 1. Create a VIEW definition for the data structure that the remote service expects. 2. Specify the desired record type and the name of this VIEW definition with the INRECTYPE parameter. 3. Set the INBUFTYPE parameter to VIEW:original-viewname.
6	Before an Oracle Tuxedo FML input buffer can be sent to a remote service that does not support FML, it must be mapped to one of the following input record types: VIEW, X_C_TYPE, or X_COMMON. Also, you must create a VIEW definition for the input data structure that the remote service expects. Set INBUFTYPE to FML and INRECTYPE to VIEW:viewname. Note: In the DMCONFIG file, if FML or FML32 are specified as INBUFTYPE or OUTBUFTYPE, the type must be followed by a colon (:). (Example: INBUFTYPE="FML32:")

Mapping Records to Buffers

The following figure shows all the possibilities for mapping records to buffers. The TMA TCP Gateway is responsible for mapping records to buffers, based on information it finds in the TMA TCP Gateway 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

The following table lists some of the mapping possibilities that are shown in the previous figure and some suggestions for setting the OUTRECTYPE and OUTBUFTYPE parameters (for service calls that originate locally).

 

1	Oracle Tuxedo CARRAY output records can be copied to CARRAY output buffers. A CARRAY buffer contains raw data that is not converted or translated. Set the OUTBUFTYPE parameter to CARRAY. The OUTRECTYPE parameters need not be set. Oracle Tuxedo CARRAY output records can also be copied to STRING output buffers. This creates a string that goes through no conversion and no translation. The resultant buffer is the length of the original CARRAY buffer. Since all characters are copied, if the CARRAY buffer contains null characters, it affects the buffer when later handled as a STRING. The OUTRECTYPE should be set to CARRAY and OUTBUFTYPE should be set to STRING.
2	Oracle Tuxedo STRING output records can be mapped to CARRAY output buffers. There is no data conversion or translation performed. The STRING buffer is copied through the leftmost null characters only. Set OUTRECTYPE to STRING and OUTBUFTYPE to CARRAY.
3	Oracle Tuxedo STRING output records can be mapped to STRING output buffers. The buffer goes through datatype translation (such as ASCII to EBCDIC). OUTBUFTYPE and OUTRECTYPE parameters are set to STRING.
4	Oracle Tuxedo VIEW output records can be mapped to identical Oracle Tuxedo VIEW output buffers. In this situation, the data structure that the remote service returns is identical to the data structure the local client program expects. There is no need to create a new VIEW definition. Instead, specify the VIEW buffer type and the name of the existing VIEW definition with the OUTBUFTYPE parameter. The OUTRECTYPE parameter can be set to VIEW:viewname, but it is not mandatory.
5	Oracle Tuxedo VIEW output records can be mapped to VIEW output buffers—in any combination. However, in this situation, the data structure that the remote service returns (designated as VIEW ‘B’ in Figure 3‑4) differs from the data structure the client program expects (designated as VIEW ‘A’ in Figure 3‑4). To facilitate the conversion process, perform the following tasks. 1. Create a VIEW definition for the data structure that the remote service returns. 2. If the name given to the VIEW definition is different than the name that the remote service returns (that is, ATMI buffer subtype), specify the output record type and the name of VIEW ‘B’ with the OUTRECTYPE parameter. (By doing this, you override the value the TMA TCP Gateway requester automatically detects.) 3. Specify the output buffer type and the name of an existing view (VIEW ‘A’ in the figure) specified in the OUTBUFTYPE parameter.
6	Oracle Tuxedo VIEW output records can be mapped to FML output buffers. To facilitate the conversion process, you must perform the following tasks. 1. Create a VIEW definition that describes the data structure that the remote service returns. 2. If the name given to the VIEW definition is different than the name that the remote service returns (that is, the ATMI buffer subtype), specify the output record type and the name of your VIEW definition with the OUTRECTYPE parameter. (By doing this, you override the value the TMA TCP Gateway requester automatically detects.) 3. Set the OUTBUFTYPE parameter to FML. Note: In the DMCONFIG file, if FML or FML32 are specified as INBUFTYPE or OUTBUFTYPE, the type must be followed by a colon (:). (Example: INBUFTYPE="FML32:")

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, TMA TCP Gateway translates field data types as required to maintain transparency between dissimilar systems.

You should create VIEW definitions before you configure TMA TCP Gateway. For complete information about VIEW definitions and related topics, see Oracle Tuxedo documentation.

The TMA TCP Gateway buffer and record conversion capabilities are extremely powerful and flexible. The key to maximizing these capabilities is to thoroughly understand the Oracle 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 TMA TCP Gateway 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 Oracle 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 Oracle Tuxedo ENVFILE if necessary (so that TMA TCP Gateway 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 TMA TCP Gateway, see the “Configuring Oracle TMA TCP Gateway” section.

Translating Data

When a local client program sends data to (or receives data from) a service routine on a different kind of computer, TMA TCP Gateway 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 TMA TCP 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 TMA TCP Gateway.

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

TMA TCP Gateway also supports multibyte character set (MBCS) translations. For more information, see Using Multibyte Character Set (MBCS) Translations.

Data Translation Rules

The following information outlines the data translation rules that TMA TCP Gateway follows:

•	CARRAY fields are passed untranslated as sequences of bytes.

•	STRING and CHAR fields undergo SBCS (ASCII-to-EBCDIC) translation and MBCS 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.

•	XML fields undergo SBCS (ASCII-to-EBCDIC) translation, if needed.

WARNING:

dec_t cannot be used with VIEW translations.

Note:

Oracle Tuxedo provides a field type named dec_t that supports decimal values within VIEWs. The TMA TCP 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.

 

Table 3‑1 Data Translation Relationships

Remote Data Type	Description	View Field Type/Length
PIC X(n)	Alphanumeric characters	string / n
PIC X	Single alphanumeric character	char
PIC X(n)	Raw bytes	carray / n
PIC 9	Single numeric byte	carray / 1
PIC S9(4) COMP	16-bit integer	short
PIC S9(9) COMP	32-bit integer	long
COMP-1	Single-precision floating point	float
COMP-2	Double-precision floating point	double
PIC S9((m+(n+1))/2)V9(n) COMP-3	Packed decimal	dec_t / m,n

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 TMA TCP Gateway does not require strings to be NULL-terminated, it respects NULL termination. Therefore, when TMA TCP Gateway 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 TMA TCP Gateway product provides standard character translation from ASCII-to-EBCDIC and EBCDIC-to-ASCII. TMA TCP Gateway 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

*GLOBAL

DFLTTYPE=”MVSC”

 

Encoding Messages To and From a Specific Host

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

*FOREIGN

HOST_NAME
TYPE=”MVSC”

 

Using Code Page Translation Tables

The TMA 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 TMA TCP.

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. The following figure illustrates code page translation.

Figure 3‑5 TMA 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 TMA 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.

The following table lists the SBCS translation tables provided with the TMA TCP software.

 

Table 3‑2 TMA TCP Code Page SBCS Translation Tables

Country	File Name	ASCII Code Set	EBCDIC Code Set
Tuxedo default	TUXEDO	TUXEDO-ASCII	TUXEDO-EBCDIC
United States	00819x00037	CP-00819	CP-00037
Great Britain	00819x00285	CP-00819	CP-00285
France	00819x00297	CP-00819	CP-00297
Portugal	00819x00860	CP-00819	CP-00860
Spain	00819x00284	CP-00819	CP-00284
Belgium	00819x00500	CP-00819	CP-00500
Germany	00819x00273	CP-00819	CP-00273
Finland	00819x00278	CP-00819	CP-00278
Sweden	00819x00278	CP-00819	CP-00278
Latin-1	00819x01047	CP-00819	CP-01047
Latin-2	00912x00870	CP-00912	CP-00870

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 TMA TCP 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 TMA TCP translation tables are located in $TUXDIR/udataobj/codepage. For table contents, refer to the “Code Page Translation Tables” section.

If no CODEPAGE specification is made for a remote domain, the TMA TCP Gateway 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 the “Error and Information Messages” section. 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

The following listing shows 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

# DMCONFIG

*DM_LOCAL_DOMAINS
CIXA
TYPE=IDOMAIN

*DM_REMOTE_DOMAINS
CISA
TYPE=IDOMAIN
CODEPAGE=00819X00273
IMSA
TYPE=IDOMAIN
CODEPAGE=“00819X00297”

 

Using Multibyte Character Set (MBCS) Translations

Besides SBCS character set translation, TCP GWIDOMAIN supports multibyte 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, specify the CODEPAGE parameter in DMCONFIG DM_REMOTE_DOMAINS in the following format:

CODEPAGE="ASCII_CHAR_SET:EBCDIC_CHAR_SET"

Note:

You can specify a default translation for remote hosts to use in this CODEPAGE parameter in DMCONFIG DM_LOCAL_DOMAINS.

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, when you want to translate MBCS to a remote domain, define CODEPAGE="utf-8:ibm-1388". Consequently, for outbound calls, GWIDOMAIN translates the client input from UTF-8 to ibm-1388; on the other hand, the inbound calls are translated from ibm-1388 to UTF-8.

For more information, see DM_LOCAL_DOMAINS Section and DM_REMOTE_DOMAINS Section.

Sample DMCONFIG Definition for MBCS Translations

The following listing shows 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 UTF-8 and the both the two remote domains use Simplified Chinese Mixed EBCDIC ibm-1388.

Listing 3‑4 Sample DMCONFIG Definition for MBCS Translations

# DMCONFIG

*DM_LOCAL_DOMAINS

CIXA

TYPE=IDOMAIN

CODEPAGE="UTF-8:ibm-1388"

 

*DM_REMOTE_DOMAINS

CISA

TYPE=IDOMAIN

CODEPAGE="UTF-8:ibm-1388"

IMSA

TYPE=IDOMAIN

CODEPAGE="UTF-8:ibm-1388"