2 Understanding How Oracle TMA TCP Gateway Works
To understand how Tuxedo Mainframe Adapter for TCP Gateway (hereafter referenced as TMA TCP Gateway) works, you need to understand how it performs the following tasks. These tasks are described in the following topics:
2.1 Planning Your Configuration
One of the major benefits of using Tuxedo Mainframe Adapter for TCP Gateway to connect dissimilar systems is the degree to which different programming environments can be isolated. Oracle Tuxedo programmers rarely need to know that services are handled by dissimilar systems or by systems in remote regions. Application programs do not need to be developed in any special way.
The key to this high degree of transparency is the TMA TCP Gateway configuration. Through TMA TCP Gateway configuration, environmental differences, such as naming conventions and data formats, are concealed from programmers and programs.
Three kinds of environmental differences are isolated in the TMA
TCP Gateway configuration files (GWICONFIG
and
DMCONFIG
). They are:
- Service names
Different systems have different rules for naming services. Service names can differ in length, allowable characters, and even conventions as to how they are constructed or chosen.
- Input and output data formats
Different systems have different conventions for formatting input and output data (such as structure, character set, and so forth).
- Error handling
Different systems report application errors in different ways.
The technique that hides these differences is called mapping. Generally, when you map things, you associate local values or entities with values or entities that are meaningful to programs on remote systems.
The procedure for mapping service names is self-explanatory; you create a configuration file record in which a local name for a service is paired with a remote name for that service. On the other hand, procedures for mapping input data, output data, and application errors are more complex. Conceptual information and other background information are required.
For detailed information about updating the TMA TCP Gateway configuration files (GWICONFIG
and DMCONFIG
), see the Configuring Oracle TMA TCP Gateway
Note:
All TMA TCP Gateway configuration parameters are described in the Configuring Oracle TMA TCP Gateway This document focuses on complex parameters that require a separate introduction.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.
Parent topic: Understanding How Oracle TMA TCP Gateway Works
2.2 Initializing TMA TCP Gateway
When you boot Oracle Tuxedo software using the
tmboot
command, TMA TCP Gateway initializes in the
following manner.
- The TMA TCP Gateway software parses the
GWICONFIG
configuration file and initializes all parameters. If syntax errors are encountered during parsing, TMA TCP Gateway writes a message to theULOG
file and initialization fails. - After reading the
GWICONFIG
file, TMA TCP Gateway advertises remote services that are named in the file dynamically. These services includes services for all remote gateways.
Parent topic: Understanding How Oracle TMA TCP Gateway Works
2.3 Processing Local Service Requests
When TMA TCP Gateway receives an Oracle Tuxedo service request from a local client program, it processes the request in the following manner.
- Step 1: Receiving a Service Request from Oracle Tuxedo Software
- Step 2: Connecting to a Remote System
- Step 3: Converting Input Buffer Types
- Step 4: Translating Input Data
- Step 5: Transmitting the Service Request
- Step 6: Receiving a Reply
- Step 7: Translating the Reply
- Step 8: Converting Output Data
- Step 9: Sending the Reply to the Caller
Parent topic: Understanding How Oracle TMA TCP Gateway Works
2.3.1 Step 1: Receiving a Service Request from Oracle Tuxedo Software
When a client program sends a request for a remote service that is accessible through TMA TCP Gateway, Oracle Tuxedo forwards the request to the gateway pending the requested service.
Parent topic: Processing Local Service Requests
2.3.2 Step 2: Connecting to a Remote System
The TMA TCP Gateway will determine which remote system will process each request. Data-dependent routing rules may be used to determine the desired remote system.
If no connection to the target remote system exists or an existing connection has been broken, the TMA TCP Gateway opens a new connection at this time.
If the remote system returns a connection failure indication,
the Oracle Tuxedo service request fails and an error is returned to
the caller. The actual error value returned depends on the timing
of the connection failure. Information about failures is written to
the ULOG
file.
Parent topic: Processing Local Service Requests
2.3.3 Step 3: Converting Input Buffer Types
In some circumstances, typed buffers associated with service requests must be converted before service requests can be sent to remote systems. Type conversion involves changing the layout of a buffer to a format that is acceptable to a remote service.
For example, if a local client program places user input in an FML buffer that a remote service cannot process, the buffer must be converted into the structure the remote service expects.
In situations where input type conversion is required, programmers or administrators must perform the following tasks:
- Determine the format of the input data the remote service expects.
- If necessary, create a
VIEW
definition that describes the format of the input data.VIEW
definitions are descriptions of data structures that are used for input and output in the Oracle Tuxedo environment. - Specify this information in the TMA TCP Gateway configuration
files (
GWICONFIG
andDMCONFIG
).
Once these tasks have been completed, TMA TCP Gateway performs all necessary type conversions automatically.
For information about creating VIEW
definitions to facilitate type conversion, see Configuring Oracle TMA TCP Gateway for Data Mapping. For information about the TMA TCP Gateway configuration file, see Configuring Oracle TMA TCP Gateway.
Parent topic: Processing Local Service Requests
2.3.4 Step 4: Translating Input Data
The TMA TCP Gateway software automatically translates data as required. Translation refers to a change in how intrinsic data types are represented with respect to word length, byte ordering, and character encoding.
To facilitate data translation, administrators must specify certain parameters in the GWICONFIG
configuration file. For detailed information about how TMA TCP Gateway translates data, see Configuring Oracle TMA TCP Gateway for Data Mapping
Parent topic: Processing Local Service Requests
2.3.5 Step 5: Transmitting the Service Request
The TMA TCP Gateway product constructs a request message. This message includes the following items and is sent to the remote system:
- The remote service name
- The input data record that TMA TCP Gateway has converted and translated, as required
- An indication of whether the remote service should return a reply to the caller
Parent topic: Processing Local Service Requests
2.3.6 Step 6: Receiving a Reply
After sending a request message, TMA TCP Gateway performs a
receive operation. If the TMA TCP Gateway receive timeout expires
before a message arrives from the remote system, a
TPETIME
error is returned to the caller.
Parent topic: Processing Local Service Requests
2.3.7 Step 7: Translating the Reply
After TMA TCP Gateway receives a reply, data representations are translated as needed, in the reverse of the input translation. For details, see the Step 4: Translating Input Data
Parent topic: Processing Local Service Requests
2.3.8 Step 8: Converting Output Data
If the format of the reply is not suitable for the local client program, TMA TCP Gateway converts the reply into an appropriate buffer format.
In situations where output conversion is required, programmers or administrators must do the following:
- Determine the type and the format of the output buffer the local client program expects
- If necessary, create a
VIEW
definition that describes the format of the output buffer - Specify this information in the TMA TCP Gateway configuration
files (
GWICONFIG
andDMCONFIG
)
Once these tasks have been completed, TMA TCP Gateway performs all necessary conversions automatically.
For information about creating VIEW
definitions to facilitate type conversion, see the Configuring Oracle TMA TCP Gateway for Data Mapping. For information about the TMA TCP Gateway configuration file, see the Configuring Oracle TMA TCP Gateway.
Parent topic: Processing Local Service Requests
2.3.9 Step 9: Sending the Reply to the Caller
The Oracle Tuxedo buffer resulting from output type conversion
and output data translation is returned to the caller with a
TPSUCCESS
or TPFAIL
indication.
Parent topic: Processing Local Service Requests
2.4 Processing Remote Service Requests
The TMA TCP Gateway software processes remote service requests (those which originate on remote systems) in much the same way that it processes local requests. The following list offers a brief summary.
- The TMA TCP Gateway receives the service request and, if necessary, the input record associated with the request is translated and converted into the specified input buffer format.
- Acting as a client program, the gateway passes the service request to Oracle Tuxedo software.
- When the service routine is complete, the output buffer is converted into the specified output record format and/or translated, when required.
- Finally, the output is sent to the requester on the remote system.
For more detailed information about record and buffer conversion, and data translation, see the Processing Local Service Requests
Parent topic: Understanding How Oracle TMA TCP Gateway Works
2.5 Processing Shut Down Requests
When you send a shutdown request to TMA TCP Gateway using the tmshutdown
command, TMA TCP Gateway performs the following tasks:
- Completes outstanding requests
- Drops all open connections
- Terminates
Parent topic: Understanding How Oracle TMA TCP Gateway Works
2.6 Programming Considerations
In general, Oracle Tuxedo application programs that send requests through TMA TCP Gateway are developed the same as other Oracle Tuxedo application programs.
The TMA TCP Gateway product supports all request/reply communications functions that are included in the ATMI and XATMI interfaces. In addition, all supported functions can be used in the standard manner documented in the Oracle Tuxedo documentation.
- All XATMI and ATMI buffer types are supported.
- All system errors are reported in the standard manner as documented in the Oracle Tuxedo documentation.
Parent topic: Understanding How Oracle TMA TCP Gateway Works
2.6.1 Input and Output Issues
This subsection describes several input and output issues that programmers need to consider when developing application programs that use TMA TCP Gateway.
- Preparing Input and Output Data with TMA TCP Gateway
- Service Request Parameters
- Output Data Considerations
Parent topic: Programming Considerations
2.6.1.1 Preparing Input and Output Data with TMA TCP Gateway
The Processing Local Service Requests topic describes many circumstances that require conversion of input and output parameters into formats acceptable to remote systems or regions and the local system.
The TMA TCP Gateway product provides powerful configuration capabilities that make it possible for you to convert or map parameters easily rather than requiring you to program in a different way.
The TMA TCP Gateway configuration files (GWICONFIG
and DMCONFIG
) are a centralized mechanism that you can
use to define and maintain relationships between the local system
and remote systems or regions. In addition to input and output
parameter mappings, these relationships include service name
mappings (where remote service names are mapped to local service
names) and error record mappings.
For more information about the GWICONFIG
configuration file, see the Configuring Oracle TMA TCP Gateway
Parent topic: Input and Output Issues
2.6.1.2 Service Request Parameters
Oracle Tuxedo application programs can request the following two categories of remote services through TMA TCP Gateway:
- Existing application programs that were originally developed for traditional OLTP environments and have been adapted for use with Oracle Tuxedo.
- Services that were developed specifically for the XATMI or ATMI (Oracle Tuxedo) environments. Included in this category are services that reside in remote Oracle Tuxedo regions.
If a remote service was developed specifically for the Oracle Tuxedo environment, the input it requires is shaped by three factors:
- Application-specific requirements
- Normal ATMI or XATMI requirements for defining and sending input
- Machine-specific requirements for how input is formatted (such as those described in Processing Local Service Requests
On the other hand, if a remote service is an existing OLTP application program, additional requirements for input are often required. For example, many systems require input that includes terminal data.
Often, by creative use of the TMA TCP Gateway configuration
capabilities previously introduced, you can eliminate the need to
include control information, such as terminal data, in the Oracle
Tuxedo application source code that you develop. For instance, you
can include terminal control codes in VIEW
definitions
that are associated with the TMA TCP Gateway configuration.
For information about the normal input requirements of Oracle Tuxedo services, see Oracle Tuxedo Programmer’s Guide.
Parent topic: Input and Output Issues
2.6.1.3 Output Data Considerations
To maintain the location transparency of the Oracle Tuxedo environment, TMA TCP Gateway does not preserve data from Oracle Tuxedo input buffers in the associated output buffers. Hence, the consequences of using the same buffer for input and output must be understood to avoid problems.
In particular, some existing Oracle Tuxedo applications may use FML buffers to accumulate results or to maintain application context across service requests. Developers adding TMA TCP Gateway to such an application must do one of the following:
- Maintain a copy of the necessary data in the client program (or service routine) that makes requests.
- Ensure that the remote service returns input data with the output record.
This requirement is no different from the requirement that existed before the use of TMA TCP Gateway. That is, application programs that accumulate output data in FML buffers must ensure that services return replies in original FML input buffers (with output data added)—not in new or re-initialized buffers.
Parent topic: Input and Output Issues
2.6.2 Limitations on the Use of Certain ATMI Functions
The ATMI interface includes several features and functions—related primarily to conversations, transactions and client identities—that application programs cannot propagate to other application programs through TMA TCP Gateway.
Note:
In this discussion, a local application program is one that resides within the immediate Oracle Tuxedo region. A remote application program is one that resides outside the immediate Oracle Tuxedo region.- Conversational Communication Functions
- Non-Transactional Communications
- The tpsprio( ) and tpgprio( ) Functions
- The tpbroadcast() and tpnotify() Functions
Parent topic: Programming Considerations
2.6.2.1 Conversational Communication Functions
Conversational communication functions are subject to the following operational considerations:
- Local client and server programs cannot use the
tpconnect()
function to establish conversations with remote services. - Remote client and server programs cannot use the
tpconnect()
function to establish conversations with local services. - Similarly, the
tpsend()
,tprecv()
, andtpdiscon()
functions may not be used for communication through TMA TCP Gateway.
Parent topic: Limitations on the Use of Certain ATMI Functions
2.6.2.2 Non-Transactional Communications
The TMA TCP Gateway product supports only non-transactional communications. Therefore, all communications via TMA TCP Gateway are subject to the following operational considerations:
- Remote services called by local client or server programs are always invoked outside the boundaries of any local transaction.
- Local services called by remote client or server programs are always invoked outside the boundaries of any local transaction.
- Local client or server programs calling remote services should
invoke the
tpcall()
function, or thetpacall()
andtpgetrply()
functions, outside the boundaries of any local transaction, such astx_begin()
/tx_commit()
ortpbegin()
/tpcommit()
pair. - If local client or server programs must call remote services
within the boundaries of a local transaction,
TPNOTRAN
must be specified as one of the flags to thetpcall()
ortpacall()
function.
Parent topic: Limitations on the Use of Certain ATMI Functions
2.6.2.3 The tpsprio( ) and tpgprio( ) Functions
The tpsprio()
and tpgprio()
functions
are subject to the following operational considerations:
- Local client and server programs cannot use the
tpsprio()
function to set the priority at which remote services are processed. Instead, a call to thetpsprio()
function causes the priority of a local TMA TCP Gateway to be set. - Remote client and server programs cannot use the
tpsprio()
function to set the priority at which local services are processed. - When local client or server programs use the
tpgprio()
function to determine the priority of a remote service, the priority of a local TMA TCP Gateway is returned.
Parent topic: Limitations on the Use of Certain ATMI Functions
2.6.2.4 The tpbroadcast() and tpnotify() Functions
The tpbroadcast()
and tpnotify()
functions are subject to the following operational
considerations:
- Local client programs cannot use the tpbroadcast() function to send unsolicited messages to remote client programs (and the reverse).
- Local services cannot use the
tpbroadcast()
ortpnotify()
functions to send messages to remote client programs (and the reverse).
Parent topic: Limitations on the Use of Certain ATMI Functions
2.6.3 Error Handling
Three kinds of errors can be encountered by local application programs when they send requests through TMA TCP Gateways. The following topics explain how TMA TCP Gateway handles these different kinds of errors.
2.6.3.1 Gateway Errors
When local or remote gateway errors occur, they are logged in
the Oracle Tuxedo ULOG
file and associated service
requests fail. Also, appropriate error codes are returned to
callers.
Parent topic: Error Handling
2.6.3.2 Remote System Failures
When remote systems encounter problems, service requests may fail or time out. The exact outcome depends on whether the remote system provides a means for TMA TCP Gateway to detect failure.
If the remote target system does not make it possible for TMA TCP Gateway to detect particular types of failure, the TMA TCP Gateway blocking timeout parameter can be tuned to provide timely detection of the problem.
For more information about the blocking timeout parameter, see the Configuring Oracle TMA TCP Gateway
Parent topic: Error Handling
2.6.3.3 Application Errors
Application errors are similar to remote system failures. Remote systems may or may not use error indicators to pass information back to the local TMA TCP Gateway resulting in the generation of error messages. If no such error indicators exist, service routines typically use their own mechanisms to report failures to callers.
When application errors occur, some service routines may not return their usual output records at all. Instead, they may return some other data indicating that there has been an error, such as a string that contains a failure message.
When TMA TCP Gateway receives a service failure message from a remote system, it:
- Converts the output buffer as required based on instructions it
finds in the
GWICONFIG
file - Writes an error record in the
ULOG
file if the configuration directs it to do so - Returns the appropriate type of Oracle Tuxedo buffer to the caller
Note:
When Oracle Tuxedo applications detect service failures, they should not assume that returned buffers are the expected type. Oracle Tuxedo application programs may ignore return buffers when failures occur. If you need to check a buffer type, use the Oracle Tuxedotptypes()
function. When the type is known, the buffer can be handled accordingly (for example, by displaying a window containing an error string).
Parent topic: Error Handling