3 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 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
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.This chapter provides information about the following topics:
3.1 Converting Input and Output Data
This section introduces procedures that TMA TCP Gateway follows to process and convert input and output data.
Parent topic: Configuring Oracle TMA TCP Gateway for Data Mapping
3.1.1 Buffers and Records
- 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.
Parent topic: Converting Input and Output Data
3.1.2 Buffers Received from Local Programs
The TMA TCP Gateway processes buffers from local programs in the following manner.
- 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. - 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.
- If the configuration indicates that conversion is required, TMA TCP Gateway transforms the buffer into the record format that is specified in the configuration.
Parent topic: Converting Input and Output Data
3.1.3 Records Received from Remote Programs
The TMA TCP Gateway processes buffers from remote programs in the following manner.
- When TMA TCP Gateway receives a record from a remote system, it
consults the configuration file (
GWICONFIG
) to determine the record’s type. - 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.
- If the configuration indicates that conversion is required, TMA TCP Gateway transforms the record into the buffer format that is specified in the configuration.
Parent topic: Converting Input and Output Data
3.2 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
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 topics, Parameters for Locally Originated Calls and Parameters for Remotely Originated Calls, explore these different meanings in detail.
Parent topic: Configuring Oracle TMA TCP Gateway for Data Mapping
3.2.1 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.
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
- 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
- Guidelines for Mapping Output Records to Output Buffers
Parent topic: Managing Parameters for Buffer and Record Conversion
3.2.1.1 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.
Parent topic: Parameters for Locally Originated Calls
3.2.1.2 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.
Parent topic: Parameters for Locally Originated Calls
3.2.2 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.
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.
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
- 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
- Guidelines for Mapping Output Buffers to Output Records
Parent topic: Managing Parameters for Buffer and Record Conversion
3.2.2.1 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.
Parent topic: Parameters for Remotely Originated Calls
3.2.2.2 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.
Parent topic: Parameters for Remotely Originated Calls
3.3 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
Parent topic: Configuring Oracle TMA TCP Gateway for Data Mapping
3.3.1 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.
No | 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.
|
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 the Mapping Buffers to Records ) differs from the data structure the client program uses (designated as VIEW ‘A’ in Mapping Buffers to Records). Consequently, you must
|
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 theDMCONFIG file, if FML or FML32 are specified as INBUFTYPE or OUTBUFTYPE , the type must be followed by a colon (:). (Example: INBUFTYPE="FML32:" )
|
Parent topic: Mapping Buffers to Records
3.4 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
- Creating VIEW Definitions to Facilitate Buffer Conversion
- Translating Data
Parent topic: Configuring Oracle TMA TCP Gateway for Data Mapping
3.4.1 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).
No | OUTRECTYPE and OUTBUFTYPE Parameters
|
---|---|
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 |
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 Figure 3-4) differs from the data structure the client program expects (designated as VIEW ‘A’ in Figure Figure 3-4). To facilitate the conversion process, perform the following tasks.
|
6 | Oracle Tuxedo VIEW output records can be mapped to FML output buffers. To facilitate the conversion process, you must perform the following tasks.
|
Parent topic: Mapping Records to Buffers
3.4.2 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
Parent topic: Mapping Records to Buffers
3.4.2.1 Preparing VIEW Definitions
VIEW
definitions and specify these definitions in the configuration files.
Note:
FML fields must be specified for allVIEW
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 VIEWs
without the -n
option specified.
- Create standard Oracle Tuxedo
VIEW
definitions in files. - Run the
viewc
orviewc32
VIEW
compiler. - Set the
VIEWFILES
,VIEWDIR
,FIELDTBLS
, andFLDTBLDIR
environment variables, using a Oracle TuxedoENVFILE
if necessary (so that TMA TCP Gateway servers can locate binaryVIEW
files and field table files at runtime). - After these tasks are complete, you can specify
VIEW
definitions in theGWICONFIG
andDMCONFIG
files (by associating names ofVIEW
definitions with theINRECTYPE
,OUTRECTYPE
,INBUFTYPE
, andOUTBUFTYPE
parameters, as required).
For detailed information about configuring TMA TCP Gateway, see the Configuring Oracle TMA TCP Gateway
3.4.3 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).
- Data Translation Rules
- NULL Characters in String Length Calculations (C Programs)
- NULL Characters in String Length Calculations (COBOL Programs)
- Converting Numeric Data
Parent topic: Mapping Records to Buffers
3.4.3.1 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
andCHAR
fields undergo SBCS (ASCII-to-EBCDIC) translation, if needed.SHORT
andLONG
fields are translated to S9(4)COMP
and S9(9)COMP
, respectively.FLOAT
andDOUBLE
fields translate toCOMP‑1
andCOMP‑2
, respectively.- XML fields undergo SBCS (ASCII-to-EBCDIC) translation, if needed.
dec_t
cannot be used with VIEW
translations.
Note:
Oracle Tuxedo provides a field type nameddec_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
The following table summarizes the 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 |
Parent topic: Translating Data
3.4.3.2 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.
Parent topic: Translating Data
3.4.3.3 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.
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 aCARRAY
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.
Parent topic: Translating Data
3.4.3.4 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.
Parent topic: Translating Data
3.5 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, bothConvMVSC
andConvMVS
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. TheConvMVSC
library performs the translation, but does not truncate spaces or add the terminator.
- For the
VIEW
data type, theConvMVS
andConvMVSC
libraries treat all field types exceptSTRING
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. TheConvMVSC
library performs the character conversion, but does not truncate spaces or add the terminator.
- For
Parent topic: Configuring Oracle TMA TCP Gateway for Data Mapping
3.5.1 Using the COBOL Data Encoding Library
There are two methods for enabling the COBOL data encoding library:
Parent topic: Encoding COBOL Data Types
3.5.1.1 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”
Parent topic: Using the COBOL Data Encoding Library
3.5.1.2 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”
Parent topic: Using the COBOL Data Encoding Library
3.6 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
- How the Translation Tables Work
- Troubleshooting Translation Table Errors
- Sample DMCONFIG Definition for ASCII to EBCDIC Translations
Parent topic: Configuring Oracle TMA TCP Gateway for Data Mapping
3.6.1 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.
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.Parent topic: Using Code Page Translation Tables
3.6.2 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
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.
Parent topic: Using Code Page Translation Tables
3.6.3 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. 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 theDM_REMOTE_DOMAIN
section of theDMCONFIG
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.
Parent topic: Using Code Page Translation Tables
3.6.4 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”
Parent topic: Using Code Page Translation Tables
3.7 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"
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 and DM_REMOTE_DOMAINS
Parent topic: Configuring Oracle TMA TCP Gateway for Data Mapping
3.7.1 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"
Parent topic: Using Multibyte Character Set (MBCS) Translations