> IMS User Guide > Programming BEA TMA TCP for IMS

IMS User Guide

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Programming BEA TMA TCP for IMS

BEA 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

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":

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 BEA TMA TCP Gateway Translates Data

When a client program on the remote BEA 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:

BEA 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 BEA 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:

Note: The BEA 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:

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


  Back to Top       Previous  Next