|  | BEA eLink TCP for IMS 3.0 Information Center
HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW
| TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | GLOSSARY | INDEX

# Programming BEA eLink TCP for IMS

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:

- Programming Your Application

- Programming Interface

- Returning a Response

- IMS Client Requests

- Error Handling

- How BEA eLink TCP for TUXEDO 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

  BEA eLink TCP for IMS 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

  A BEA eLink TCP for IMS server request or response has the following message format when using the BMP.

  > Listing 5-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 BEA 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 5-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...)

  ### 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 BEA eLink TCP for IMS BMP.
  FILL-CHAR | Message fill character (space).
  BEA-RESERVED | Reserved for use by BEA eLink TCP for IMS BMP. Note: This field must be copied intact from the request message to the associated response message. This field is only used in conjunction with the eLink TCP gateway running as a BMP.
  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

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

  ### Batch Message Program Gateway

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

  The transaction code field should be set to that of the BEA 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 BEA 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. BEA eLink TCP for IMS can handle either format.

  ### 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 BEA eLink 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 "Sample JCL and User Exits."

  ### Message Format

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

  A BEA eLink TCP for IMS client request or response has the following message format.

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

  ### 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 BEA eLink 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 eLink 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, BEA eLink 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 eLink 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: response header user context data

- 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 "Error and Reason Codes."

  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 "Error and Reason Codes."

  SERVICE-NAME

  Specifies the name of the service (as locally defined to BEA eLink 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 eLink 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 eLink 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). BEA eLink 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 the request was successfully processed.

  ### Types of Errors

  BEA eLink TCP for IMS 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
    BEA eLink TCP for IMS 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
    BEA eLink TCP for IMS may be unable to process a request because the required remote system is either inaccessible or currently busy processing other requests.

  Request Timeout
    BEA eLink TCP for IMS 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 BEA eLink 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 eLink TCP for TUXEDO 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, BEA 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:

  - Word length

  - Byte order

  ### 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

  BEA eLink TCP for TUXEDO 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 BEA TUXEDO product provides a field type named `dec_t` that supports decimal values within VIEWs. BEA eLink 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) | Alphanumeric characters | string / n
  PIC X | Single alphanumeric 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 eLink TCP for TUXEDO 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 eLink TCP for TUXEDO does not require strings to be NULL-terminated, it respects NULL termination. Therefore, when BEA 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 BEA 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. BEA eLink TCP for TUXEDO 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.

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

  TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | GLOSSARY | INDEX