Chapter 6 . Programming BEA Connect TCP for IMS

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

Programming Your Application

IMS Client and Server transactions are ordinary IMS Message Processing Programs (MPPs) and 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 based on the assumption that COBOL is the language used. However, these examples may be translated easily to other supported programming languages (such as C).

Programming Interface

BEA Connect TCP for IMS and user-written IMS Client and Server transactions communicate by exchanging standard IMS messages (using the IMS Message Queue).

IMS Server Requests

An IMS Server Transaction is one that services requests originated by a remote system.

The request message is inserted into the IMS Message Queue 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

A BEA Connect TCP for IMS Server request or response has the following message format:

      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.
          10 FILL-CHAR      PIC  X   VALUE SPACES.
          10 BEA-RESERVED   PIC  X(8) VALUE LOW-VALUES.
      05 USER-REQUEST-DATA.
          10 (user-defined...)
      05 USER-RESPONSE-DATA REDEFINES USER-REQUEST-DATA.
           10 (user-defined...)

Field Descriptions


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 BEA Connect TCP for IMS BMP.
FILL-CHAR	Message fill character (space).
BEA-RESERVED	Reserved for use by BEA Connect TCP for IMS. This field must be copied intact from the request message to the associated response message.
USER-REQUEST-DATA	For a request message, user-defined data specific to the request. The request data must immediately follow the BEA Request Header with no intervening (slack) bytes.
USER-RESPONSE-DATA	For a response message, user-defined data specific to the response. The response data must immediately follow the BEA Response Header with no intervening (slack) bytes.

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

Because the request message is generated by the BEA Connect TCP for IMS BMP, there is no associated LTERM (the LTERM field of the I/O PCB will be spaces).

If a response is required, the server transaction formats a response message as shown above. The Transaction Code field should be set to that of the BEA Connect TCP for IMS BMP. Note that the BEA-RESERVED field must be copied intact from the request message.

The response message is inserted into the IMS Message Queue using a (modifiable) Alternate PCB. Typically, the server transaction would issue a CHNG call to set the destination to the BEA Connect TCP for IMS BMP transaction code, followed by an ISRT call to insert the response message into the IMS Message Queue.

The response message can be inserted either as a single segment, or as multiple segments. BEA Connect TCP for IMS is capable of handling either format.

IMS Client Requests

An IMS Client Transaction is one that issues a request for a service provided by a remote system.

Message Format

A BEA Connect TCP for IMS Client request or response message consists of three contiguous "sections": a BEA-defined Request/Response Header, user-defined Context Data, and user-defined request or response data.

A BEA Connect TCP for IMS Client request or response has the following 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


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 BEA Connect TCP for IMS BMP. 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 BEA Connect 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 should/will be 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 should/will be 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, BEA Connect 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), BEA Connect 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) the Response Header, 2) User Context Data, and 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 was successfully processed. Otherwise, the error code indicates the nature of the error that occurred. Error Codes are documented in Appendix F, "Error and Reason Codes," of this document.
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 Appendix F, "Error and Reason Codes," of this document.
SERVICE-NAME	Specifies the name of the service (as locally defined to BEA Connect 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 (i.e., 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 (i.e., IMS LTERM) associated with this request. For example, if the request is issued by a transaction processing a terminal message, this is the name of the associated terminal.
BEA-RESERVED-2	Reserved for use by BEA Connect 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 (i.e., saved) by BEA Connect TCP for IMS and returned in the response message. This data may be used for any purpose desired; for example, the response transaction may 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). BEA Connect TCP for IMS 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 or not the request was successfully processed.

Error Code

An Error Code value of zero indicates that the request was processed successfully. Otherwise, the value of the Error Code indicates the type of error that occurred. Refer to Appendix F, "Error and Reason Codes," for a description of the Error Codes returned by BEA Connect TCP for IMS.

Reason Code

For certain kinds of errors, a Reason Code may be returned that provides additional information about the nature of the error that occurred (if the Reason Code value is zero, it indicates that no additional information is available). Refer to Appendix F, "Error and Reason Codes," for a description of the Reason Codes returned by BEA Connect TCP for IMS.

Types of Errors

BEA Connect TCP for IMS recognizes a wide variety of error conditions that may prevent successful processing of a client request. These are briefly summarized below.

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, or the remote gateway may be unable to invoke the requested service.

Other Errors

Although unlikely, it is possible that BEA Connect 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 Connect TPS Translates Data

Process Overview

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, BEA Connect TPS 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

BEA TUXEDO Terminology


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	FML (Fielded Manipulation Language) buffers are variable length, dynamic, self-describing buffers. Each field in the buffer has its own descriptive header. In BEA TUXEDO, FML buffers can be tied closely to VIEW buffers so that conversion from one to the other is direct.

Data Translation Rules

BEA Connect TPS 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: BEA TUXEDO provides a field type named dec_t that supports decimal values within VIEWs. BEA Connect TCP for IMS 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)	Alpha-Numeric Characters	string / n
PIC X	Single Alpha-Numeric Character	char
PIC X(n)	Raw Bytes	carray / n
PIC X	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 BEA Connect TPS 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 BEA Connect TPS does not require strings to be NULL-terminated, it respects NULL termination. Therefore, when BEA Connect TPS 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 BEA Connect TPS for BEA TUXEDO are fully localizable, in accordance with the X/Open XPG Portability Guides. ASCII and EBCDIC translations are loadable from message files. BEA Connect TPS contains default behaviors that should meet the requirements of most English-language applications. However, you may find it necessary to customize tables. See Appendix B in the BEA Connect TPS User Guide for complete instructions.

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.

[Top] [Previous] [Next] [End of Book]