HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | GLOSSARY | INDEX
|
|
|
BEA eLink TCP for IMS 3.1 Information Center |
|
HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW |
||
|
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | GLOSSARY | INDEX |
||
BEA eLink for Mainframe TCP for IMS (hereafter referenced as eLink 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 eLink 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.
An eLink TCP for IMS server request or response has the following message format when using the BMP.
Programming Your Application
Programming Interface
IMS Server Requests
Message Format
Listing 6-1
Sample Message using BMP
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...)
When running the eLink 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-2 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.
10 FILL-CHAR PIC X VALUE SPACES.
05 USER-REQUEST-DATA.
10 (user-defined...)
05 USER-RESPONSE-DATA REDEFINES USER-REQUEST-DATA.
10 (user-defined...)
The request messages contain the following fields.
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 |
If a response is required, the server transaction formats a BMP or client response message.
Because the request message is generated by the eLink TCP for IMS BMP, there is no associated LTERM (the LTERM field of the I/O PCB has spaces).
The transaction code field should be set to that of the eLink TCP for IMS BMP.
Note: 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 issues a CHNG call to set the destination to the eLink 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. The eLink TCP for IMS gateway can handle either format.
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 eLink 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 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 "Sample JCL and User Exits."
An eLink 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.
An eLink TCP for IMS client request or response has the following message format.
Listing 6-3 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...)
The client request or response messages contain the following fields.
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 |
Every client request must designate a response transaction (even though the request itself may not require an application-level response). The eLink 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 eLink 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 eLink 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 BEA TUXEDO system sends data to (or receives data from) a service routine on a different model of computer, eLink TCP for TUXEDO 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 eLink TCP for TUXEDO gateway adheres to the following data translation rules:
BEA TUXEDO Buffer Types
Data Translation Rules
The following table summarizes the rules for translating between C and IBM 370 data types.
This section provides the following information:
Strings and Numeric Data: A Closer Look
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 eLink TCP for TUXEDO does not require strings to be NULL-terminated, it respects NULL termination. Therefore, when eLink TCP for TUXEDO 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 eLink TCP for TUXEDO are fully localizable, in accordance with the X/Open XPG Portability Guides. ASCII and EBCDIC translations are loadable from message files. The eLink TCP for TUXEDO 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 eLink TCP for TUXEDO 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 In addition, you can convert numeric values into strings (and the reverse). For example, while FML buffers do not directly support the Including NULL Characters in String Length Calculations
Converting Numeric Data
dec_t type VIEW element.
dec_t type, you can place decimal values in string fields and map these to dec_t fields within VIEW definitions.