Gateway User Guide
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Get Adobe Reader |
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:
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 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 BEA TMA TCP Gateway section.
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.
This section introduces procedures that TMA TCP Gateway follows to process and convert input and output data.
In this guide, the following terms are used to describe input and output data.
Input or output data as it exists inside the local BEA Tuxedo region. This definition includes all the buffer types that BEA Tuxedo software supports—both BEA Tuxedo ATMI buffer types and X/Open XATMI buffer types.
These terms make it easier to understand how TMA TCP Gateway handles input and output data.
The TMA TCP Gateway processes buffers from local programs in the following manner.
The TMA TCP Gateway processes buffers from remote programs in the following manner.
GWICONFIG
) to determine the record's type.
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
).
Identifies the type, and in some cases the format, of a buffer received from a Tuxedo client or server
Specify the following record configuration parameters in the gateway configuration file (GWICONFIG
).
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.
This section takes a closer look at how TMA TCP Gateway 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 the following figure, a local BEA 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:
INBUFTYPE
parameter describes the BEA Tuxedo input buffer that the local client program provides to the TMA TCP Gateway through BEA Tuxedo software. INRECTYPE
parameter describes the input record that is sent to the service on the remote system. OUTRECTYPE
parameter describes the output record that is received from the service on the remote system.OUTBUFTYPE
parameter describes the BEA Tuxedo output buffer that is returned to the local client program. 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).
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.
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 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.
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).
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.
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.
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 TMA TCP Gateway 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 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 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:
OUTRECTYPE
parameter describes the output record that the remote client sends to the TMA TCP Gateway. OUTBUFTYPE
parameter describes the BEA Tuxedo output buffer that is provided to the local server. INBUFTYPE
parameter describes the BEA Tuxedo input buffer that the local server returns to the TMA TCP Gateway. INRECTYPE
parameter describes the input record that the local TMA TCP Gateway returns to the remote client program. 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).
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.
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.
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).
The OUTBUFTYPE
parameter specifies the request buffer type that the local TMA TCP Gateway provides to the local server.
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.
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.
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
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.
BEA Tuxedo
|
|
BEA Tuxedo |
|
BEA Tuxedo |
|
BEA Tuxedo |
|
BEA Tuxedo |
|
Before a BEA 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: Note: In the |
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
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).
BEA Tuxedo BEA Tuxedo |
|
BEA Tuxedo |
|
BEA Tuxedo |
|
BEA Tuxedo |
|
BEA Tuxedo 2. If the name given to the |
|
BEA Tuxedo 2. If the name given to the Note: In the |
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 the BEA Tuxedo Programmer's Guide.
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 BEA Tuxedo VIEW
definition mechanism.
VIEW
definitions make it possible to specify composite data structures that can be used:
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 VIEW
s 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 VIEW
s without the -n
option specified.
VIEWFILES
, VIEWDIR
, FIELDTBLS
, and FLDTBLDIR
environment variables, using a BEA Tuxedo ENVFILE
if necessary (so that TMA TCP Gateway servers can locate binary VIEW
files and field table files at runtime).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 BEA TMA TCP Gateway section.
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.
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 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 VIEW
s. 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.
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.
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.
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.
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:
STRING
data type, both ConvMVSC
and ConvMVS
perform ASCII-to-EBCDIC and EBCDIC-to-ASCII translation. 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.VIEW
data type, the ConvMVS
and ConvMVSC
libraries treat all field types except STRING
the same. 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'. 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.There are two methods for enabling the COBOL data encoding library:
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"
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"
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.
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 translation tables provided with the TMA TCP software.
Table 3-1 TMA TCP Code Page Translation Tables
Note: The Tuxedo default ASCII and EBCDIC code pages differ slightly from CP-00819 and CP-00037.
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.
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.
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
.
Verify that the file name specified for the CODEPAGE
parameter is valid. Also, verify that the specified file is not corrupt.
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"
![]() ![]() |
![]() |
![]() |