Oracle Tuxedo Mainframe Adapter for TCP (IMS) (hereafter referenced as TMA TCP for IMS) allows user-written IMS application transactions to service requests received from remote systems (server requests) and to initiate requests for services provided by remote systems (client requests).
The following topics are programming considerations:
IMS client and server transactions are ordinary IMS message processing programs (MPPs) and with the use of OTMA, server transactions can also be FastPath programs. These programs may be written in any programming language supported by IMS. Because COBOL is the traditional language used for this purpose, the examples in this document are written in COBOL. However, these examples may be translated easily to other supported programming languages such as C.
The TMA TCP for IMS product and user-written IMS client and server transactions communicate by exchanging standard IMS messages (using the IMS message queue directly or through OTMA).
An IMS server transaction is one that services requests originated by a remote system. The request message is inserted directly into the IMS message queue or indirectly through OTMA as a single segment. The IMS server transaction retrieves the request message from the IMS message queue and processes the request as required.
When running the TMA TCP gateway as an OTMA client, the request or response message is in the standard IMS message format. The following message is a sample when using OTMA.
10 LL PIC 9(4) COMP VALUE 0.
10 ZZ PIC 9(4) COMP VALUE 0.
10 TRAN-CODE PIC X(8) VALUE SPACES.
The request messages contain the following fields.
INCLUDE distribution library contains the following header files and copybooks for use by IMS server transactions.
If a response is required, the server transaction formats a client response message.
The request message presented to the server transaction contains the name of the transaction pipe (
tpipe) in the
LTERM field of the I/O PCB. If the security feature is in use, the
GROUPID fields of I/O PCB also contain relevant data.
If a response is required, the response message is inserted into the IMS message queue and routed back to the gateway by OTMA. The response message is inserted either as a single segment, or as multiple segments. The TMA TCP for IMS gateway can handle either format.
An IMS client transaction is one that issues a request for a service provided by a remote system. You must install the
DFSYDRU0 IMS user exits prior to using an IMS client transaction with the OTMA client gateway. Refer to the IBM document, Open Transaction Manager Access Guide for additional information on these user exits. Basic samples of these exits are in the section.
An TMA TCP for IMS client request or response message consists of three contiguous “sections”:
An TMA TCP for IMS client request or response has the following message format.
10 LL PIC 9(04) COMP VALUE 0.
10 ZZ PIC 9(04) COMP VALUE 0.
10 TRAN-CODE PIC X(08) VALUE SPACES.
10 FILL-CHAR PIC X VALUE SPACES.
10 BEA-RESERVED-1 PIC X(03) VALUE LOW-VALUES.
10 HEADER-LENGTH PIC 9(08) COMP VALUE 0. .
10 CONTEXT-LENGTH PIC 9(08) COMP VALUE 0.
10 DATA-LENGTH PIC 9(08) COMP VALUE 0.
10 MAX-RESPONSE-LENGTH PIC 9(08) COMP VALUE 0.
10 REQUEST-TYPE PIC 9(08) COMP VALUE 0.
88 REQUEST-RESPONSE-REQUIRED VALUE 1.
88 REQUEST-NO-RESPONSE VALUE 2.
10 RESPONSE-FORMAT PIC 9(08) COMP VALUE 0.
88 RESPONSE-SINGLE-SEGMENT VALUE 0.
88 RESPONSE-MULTI-SEGMENT VALUE 1.
10 ERROR-CODE PIC S9(08) COMP VALUE +0.
88 ERR_NO_ERROR VALUE +0.
88 ERR_RESPONSE_TRUNCATED VALUE +4.
88 ERR_HOST_NOT_AVAILABLE VALUE +8.
88 ERR_HOST_BUSY VALUE 12.
88 ERR_TIMEOUT VALUE 16.
88 ERR_SERVICE_NAME VALUE 20.
88 ERR_NO_STORAGE VALUE 24.
88 ERR_REQUEST_FORMAT VALUE 28.
88 ERR_HOST_ERROR VALUE 32.
88 ERR_TP_ERROR VALUE 36.
88 ERR_INTERNAL_ERROR VALUE 40.
10 REASON-CODE PIC S9(08) COMP VALUE +0.
88 RSN_NO_REASON VALUE 0.
88 RSN_HEADER_LENGTH VALUE 4.
88 RSN_HEADER_LENGTHS VALUE 8.
88 RSN_REQUEST_TYPE VALUE 12.
88 RSN_NO_RESPONSE_TRAN VALUE 16.
88 RSN_CONTEXT_LENGTH VALUE 20.
88 RSN_DATA_LENGTH VALUE 24.
88 RSN_MAX_DATA_LENGTH VALUE 28.
88 RSN_NO_SERVICE_NAME VALUE 32.
88 RSN_SERVICE_NAME_UNDEFINED VALUE 36.
10 SERVICE-NAME PIC X(16) VALUE SPACES.
10 RESPONSE-TRAN PIC X(08) VALUE SPACES.
10 ORIGIN-TERMINAL PIC X(08) VALUE SPACES.
10 BEA-RESERVED-2 PIC X(16) VALUE LOW-VALUES.
05 USER-RESPONSE-DATA REDEFINES USER-REQUEST-DATA.
The client request or response messages contain the following fields.
If no response is required, TMA TCP for IMS schedules the specified response transaction as soon as the request has been sent to the remote system.
If the single segment option is specified (the default), TMA TCP for IMS inserts the complete response message into the IMS message queue as a single message segment.
If the multi-segment option is requested, the response message is inserted into the IMS message queue in three separate segments.
This field is set in the response message to indicate that an error occurred. If this field is zero, the request successfully processed. Otherwise, the error code indicates the nature of the error that occurred.
For certain kinds of errors, this field may be set to provide additional information about the error. If this field is zero, no additional information is available.
This user-defined data area is preserved by TMA TCP for IMS and returned in the response message. This data can be used for any purpose; for example, the response transaction can use this data to correlate the response with the original request. The context data, if present, must immediately follow the BEA request header with no intervening (slack) bytes.
INCLUDE distribution library contains the following header files and copybooks for use by IMS client transactions.
Every client request must designate a response transaction (even though the request itself may not require an application-level response). The TMA TCP for IMS product schedules the response transaction if an error is encountered that prevents processing of the request (for example, the request may be improperly formatted, or the specified service may be unavailable).
The response transaction should always check the error code to determine whether the request was successfully processed.
The TMA TCP for IMS product recognizes a wide variety of error conditions that may prevent successful processing of a client request. These are briefly summarized in the following sections.
Although unlikely, it is possible that TMA TCP for IMS may be unable to process a request due to an internal or system error, such as a temporary storage shortage.
When a client program on the remote Oracle Tuxedo system sends data to (or receives data from) a service routine on a different model of computer, TMA TCP Gateway automatically translates data as required. Translation involves changing the representation of intrinsic data types by changing attributes such as the following:
The following table contains definitions for buffer types.
The TMA TCP Gateway adheres to the following data translation rules:
|Note:||The Oracle Tuxedo product provides a field type named
The following table summarizes the rules for translating between C and IBM 370 data types.
This section provides the following information:
When you create
VIEW definitions for input and output buffers that are used by IMS applications, do not specify extra characters for terminating NULL characters that are used in string fields.
For example, when a remote IMS application program expects 10 characters in an input record, 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
The character set translations performed by TMA TCP Gateway are fully localizable, in accordance with the X/Open XPG Portability Guides. ASCII and EBCDIC translations are loadable from message files. The TMA TCP Gateway product contains default behaviors that should meet the requirements of most English-language applications. However, you may find it necessary to customize tables. For complete instructions, see the Oracle Tuxedo Mainframe Adapter for TCP Gateway User Guide.
You can convert numeric data easily 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 an FML field of double into a packed decimal field on the remote target system by specifying an appropriate
dec_t type VIEW element.
In addition, 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