Programming Oracle TMA TCP for IMS

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:

•	Programming Your Application

•	Programming Interface

•	Returning a Response

•	IMS Client Requests

•	Error Handling

•	How Oracle TMA TCP Gateway Translates Data

Programming Your Application

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.

Programming Interface

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).

IMS Server Requests

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.

Message Format

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.

Listing 6‑1 Sample Message using OTMA

01 BEA-SERVER-REQUEST-RESPONSE-MESSAGE.
05 BEA-SERVER-HEADER
10 LL PIC 9(4) COMP VALUE 0.
10 ZZ PIC 9(4) COMP VALUE 0.
10 TRAN-CODE PIC X(8) VALUE SPACES.
REQUEST-DATA.

 

Field Descriptions

The request messages contain the following fields.

 

Field	Description
LL	The length of the complete request or response message (including this field).
ZZ	Reserved for use by IMS; normally zero.
TRAN-CODE	For a request message, the transaction code of the IMS server transaction. For a response message, the transaction code of the TMA TCP for IMS gateway.
FILL-CHAR	Message fill character (space).

Header Files and Copybooks

The INCLUDE distribution library contains the following header files and copybooks for use by IMS server transactions.

 

Member Name	Description
BEATCPI	C Header file
SERVER	COBOL copybook

Returning a Response

If a response is required, the server transaction formats a client response message.

OTMA Client Gateway

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 USERID and 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.

IMS Client Requests

An IMS client transaction is one that issues a request for a service provided by a remote system. You must install the DFSYPRX0 and 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 “Sample JCL and User Exits” section.

Message Format

An TMA TCP for IMS client request or response message consists of three contiguous “sections”:

•	BEA-defined request/response header

•	User-defined context data

•	User-defined request or response data

An TMA TCP for IMS client request or response has the following message format.

Listing 6‑2 Client Request/Response Message Format

01 BEA-CLIENT-REQUEST-RESPONSE-MESSAGE.
05 BEA-CLIENT-HEADER.
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-CONTEXT-DATA.
10 (user-defined...)|
05 USER-REQUEST-DATA.
10 (user-defined...)
05 USER-RESPONSE-DATA REDEFINES USER-REQUEST-DATA.
10 (user-defined...)

 

Field Descriptions

The client request or response messages contain the following fields.

 

Field	Description
LL	The length of the complete request or response message (including this field).
ZZ	Reserved for use by IMS; normally zero.
TRAN-CODE	For a request message, the transaction code of the TMA TCP for IMS gateway. For a response message, the transaction code of the IMS client response transaction.
FILL-CHAR	Message fill character (space).
BEA-RESERVED-1	Reserved for use by TMA TCP for IMS. For a request message, this field must be initialized to binary zero (low values).
HEADER-LENGTH	The length of the BEA request/response header.
CONTEXT-LENGTH	The length of user context data, if any. If there is no context data, the length is set to zero.
DATA-LENGTH	The length of user request or response data, if any. If there is no request or response data, the length is set to zero.
MAX-RESPONSE-LENGTH	For a request, the maximum length of user response data that can be accepted. If the response data exceeds this length, it is truncated as necessary and appropriate return codes are set.
REQUEST-TYPE	For a request, indicates whether or not a response is required. 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. Otherwise, the response transaction is scheduled when the required response has been received from the remote system.
RESPONSE-FORMAT	For a request, specifies the type or response message format desired. 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. 1. response header 2. user context data 3. user response data
ERROR-CODE	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. Error codes are documented in the “Error and Reason Codes” section.
REASON-CODE	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. Reason Codes are documented in the “Error and Reason Codes” section.
SERVICE-NAME	Specifies the name of the service (as locally defined to TMA TCP for IMS) that processes the request. Note that the local service name may not be the same as the remote system name.
RESPONSE-TRAN	The name of the transaction (IMS transaction code) that is to be scheduled to process the response to a request. A response transaction must be specified for all requests, even if an application-level response is not required.
ORIGIN-TERMINAL	The name of the terminal (IMS LTERM) associated with this request. For example, if the request is issued by a transaction processing a terminal message, this name is the name of the associated terminal.
BEA-RESERVED-2	Reserved for use by TMA TCP for IMS. For a request message, this field must be initialized to binary zero (low values).
USER-CONTEXT-DATA	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.
USER-REQUEST-DATA	For a request message, user-defined data specific to the request. The request data, if present, must immediately follow the context data (if any), with no intervening (slack) bytes.
USER-RESPONSE-DATA	For a response message, the user-defined data specific to the response. The response data, if any, must immediately follow the context data (if any) with no intervening (slack) bytes.

Header Files and Copybooks

The INCLUDE distribution library contains the following header files and copybooks for use by IMS client transactions.

 

Member Name	Description
BEATCPI	C Header file
SERVER	COBOL copybook

Error Handling

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.

Types of Errors

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.

Invalid Request Format

The TMA TCP for IMS gateway validates a client request prior to sending it to a remote system for processing. Types of validation errors include invalid service name, invalid length values, etc.

Remote System Not Available

The TMA TCP for IMS gateway may be unable to process a request because the required remote system is either inaccessible or currently busy processing other requests.

Request Timeout

The TMA TCP for IMS gateway monitors each request sent to a remote system for processing. If a response is required and is not received within a prescribed period of time, the request times out.

Remote System Errors

The request may fail due to an error that occurs on the remote system. For example, the requested service may detect an application-level error, a security authorization failure, or the remote gateway may be unable to invoke the requested service.

Other Errors

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.

How Oracle TMA TCP Gateway Translates Data

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:

•	Word length

•	Byte order

Oracle Tuxedo Buffer Types

The following table contains definitions for buffer types.

 

Term	Definition
STRING	A buffer of character data that is terminated by the first null character in the buffer. Typically these character string buffers undergo translation when sent to a system that is dissimilar from the sending system.
CARRAY	A CARRAY is a buffer of raw data that contains no terminating character. The data in the array undergoes no conversion or translation; it is sent from one system to another without modification. (A CARRAY is an exemplary buffer type for a graphics file.)
VIEW	A VIEW buffer is a collection of field definitions that can be treated as a single entity. It is comparable to a record layout in COBOL or a structure in C.
FML	Fielded manipulation language (FML) buffers are variable length, dynamic, self-describing buffers. Each field in the buffer has its own descriptive header. In the Oracle Tuxedo product, FML buffers can be tied closely to VIEW buffers so that conversion from one to the other is direct.

Data Translation Rules

The TMA TCP Gateway adheres to the following data translation rules:

•	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 are translated to COMP‑1 and COMP‑2, respectively.

Note:

The Oracle Tuxedo product provides a field type named dec_t that supports decimal values within VIEWs. The TMA TCP for IMS 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 rules for translating between C and IBM 370 data types.

 

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	32-bit integer	short
PIC S9(9) COMP	64-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

 

Strings and Numeric Data: A Closer Look

This section provides the following information:

•	Suggestions that help you develop VIEW definitions for input and output buffers and records

•	Explanations of how TMA TCP Gateway treats string data and numeric data

Including NULL Characters in String Length Calculations

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 CARRAY type field or buffer.

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.

Converting Numeric Data

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 VIEW definitions.