Monitoring BEA eLink TCP for IMS

The following topics explain operating and monitoring the BEA eLink for Mainframe TCP for IMS (hereafter referenced as eLink TCP for IMS) product:

• Testing Connectivity with Remote Systems

• Operating BEA eLink TCP for IMS

• The BEA eLink TCP for IMS Message Log

• The Server Response Log File

Testing Connectivity with Remote Systems

When you start eLink TCP for IMS for the first time, you should do so in a controlled environment, using a small, simple configuration that allows you to methodically test the system to verify your installation and the configuration.

An appropriate test configuration would include the IMS gateway (one port) and one remote gateway. The SOURCE distribution library includes several sample IMS client and server transactions that can be used to test connectivity with a remote BEA eLink gateway.

By specifying a minimum number (greater than 0) of outbound sessions for a remote gateway, you can cause outbound sessions to be automatically established with that gateway during initialization. This can help verify outbound connectivity without having to make use of test transactions.

Execute test client and server transactions from both sides of the configuration to verify bidirectional connectivity. If errors are encountered, use the diagnostic messages issued by both sides of the configuration (that is, the IMS gateway and the remote BEA TUXEDO gateway) to identify and correct the problem.

For a description of the eLink TCP for IMS error messages, refer to "Error and Informational Messages."

Monitoring and Troubleshooting OTMA

The following commands are a few of the available IMS commands that may assist you in monitoring or troubleshooting problems with the OTMA connection. For definitions and command syntax for these IMS commands, refer to the IMS/ESA Operator's Reference or the Open Transaction Manager Access Guide.

• /SEC OTMA security-level

  Specify FULL for security-level to check security on all messages.

  Specify PROFILE for security-level to check security only when requested.

  Specify NONE for security-level to disable security checking.

• /DIS OTMA

  Displays the OTMA status.

• /STO OTMA

  Stops OTMA messaging.

• /STA OTMA

  Enables OTMA messaging.

• /DIS TMEMBER name TPIPE ALL

  Displays the status of the client.

• /STO TMEMBER name TPIPE ALL

  Stops an individual client from accessing a service.

• /STA TMEMBER name TPIPE ALL

  Enables an individual client and allows access to a service.

Operating BEA eLink TCP for IMS

The eLink TCP for IMS product is started by submitting JCL. For sample JCL, refer to "Sample JCL and User Exits."

Note: Before attempting to start eLink TCP for IMS as a BMP, make sure that the program specification block (PSB) is not stopped; if it is, the job immediately abends.

During operation, eLink TCP for IMS writes all messages to the message log dataset (DDNAME=MSGLOG). The message log is primarily useful for historical purposes after eLink TCP for IMS has ended. The message log remains open for output during execution and recent messages cannot be viewed (using ISPF Browse, for example) until the dataset is closed at termination.

However, informational and error messages are also written to the OS/390 console, where they can be viewed in real time by a system operator. When MSGLEVEL=4 is specified in the configuration file (the normal mode), all messages written to the message log are also displayed on the OS/390 console.

Initialization

During initialization, the following activities occur:

• The runtime datasets (configuration file, message log, and server response log) are opened

• The configuration file is read and processed to establish the configuration

• The eLink TCP for IMS product establishes a TCP/IP Listener for each defined local gateway (port)

• If requested, outbound sessions are established with remote gateways

• The eLink TCP for IMS product puts up an outstanding write-to-operator with reply (WTOR) on the OS/390 console by means of which operator commands can be entered

If any errors are detected during initialization, eLink TCP for IMS issues the appropriate error messages and initialization fails. If initialization fails, correct the indicated errors and restart eLink TCP for IMS.

Normal Operation

If initialization is successful, normal operation begins, during which the following activities occur:

• Requests for new inbound sessions, initiated by remote systems, are accepted.

• New outbound sessions are requested and established with remote systems as required.

• The eLink TCP for IMS product monitors the TCP/IP network for requests and responses from remote systems.

• Inbound requests are received from remote systems through the TCP/IP network and are relayed to the appropriate IMS server transactions.

• IMS is polled for requests and responses from IMS client and server transactions.

• Outbound requests issued by IMS client transactions are relayed to the appropriate remote systems through the TCP/IP network.

• The eLink TCP for IMS product monitors requests-in-progress to ensure that a response (if required) is received within a specified period of time.

• Operator commands (entered through a reply to the outstanding command WTOR) are processed.

Operator Commands

During normal operation, eLink TCP for IMS puts up an outstanding WTOR (message ID BEA2113I) that can be used to enter commands. A command is entered by simply replying to the outstanding WTOR in the format in Listing 5-1.

Listing 5-1 Syntax for Replying to WTOR

---

In Listing 5-1, nn is the OS/390-assigned reply ID and command is the text of the command.

Issuing Session-related Messages

During normal operation, only messages for session-related events are issued. These include requests to establish a TCP/IP connection, requests to establish a session between two gateways, session disconnect, and session termination. This minimizes the amount of console traffic that occurs under normal operating conditions. Messages associated with TCP/IP connections include the 4-digit TCP/IP socket ID (immediately following the message ID).

Termination

Normal operation continues until a SHUTDOWN command is received. Under normal circumstances, eLink TCP for IMS is terminated by entering an operator SHUTDOWN command (through the outstanding command WTOR).

When a SHUTDOWN command is received and accepted, the following activities occur:

1. The eLink TCP for IMS gateway stops accepting requests for new inbound connections (from remote systems).

2. Active inbound and outbound sessions are terminated without permitting in progress transactions to complete.

3. The Message Log and Server Response Log datasets are closed.

4. The eLink TCP for IMS gateway terminates and returns control to OS/390.

The SHUTDOWN command allows an operator to initiate termination of eLink TCP for IMS, and is entered in the format in Listing 5-2.

Listing 5-2 Syntax for Termination Initiation

---

The eLink TCP for IMS product can be configured to allow shutdown to be initiated by a remote client request or a response to a remote client request. This may be useful if it is necessary to shut down eLink TCP for IMS from a remote system, rather than by operator command from an OS/390 console.

Shutdown is requested by embedding a modify command into the user request data of an IMS server request, or the user response data of an IMS server response in the following format.

Format the command as shown in Listing 5-3. If the jobname specified is incorrect, eLink TCP for IMS simply ignores the command and processes the request or response in the usual way.

Note: To use this feature, the configuration file must specify the CLIENTSHUTDOWN=YES option on the SYSTEM statement (the default is NO). Otherwise, eLink TCP for IMS ignores a remote client request to initiate shutdown processing.

Listing 5-3 Syntax for Client-Initiated Shutdown

---

jobname

is the OS/390 jobname assigned to eLink TCP for IMS.

TERM=type

is the method for shutting down the system. The values for type are as follows.

STOP

is a normal shutdown. If TERM=STOP is specified, eLink TCP for IMS initiates normal shutdown processing, as if an operator had entered the SHUTDOWN command from an OS/390 console.

DUMP

is an abend with a dump. If TERM=DUMP is specified, eLink TCP for IMS issues a U3166 abend. If a SYSUDUMP DD statement is included in the JCL, a standard OS/390 dump is produced.

The eLink TCP for IMS product uses a message log dataset to record all messages issued. Normally, the message log (DDNAME=MSGLOG) is allocated to a disk dataset, but it can be allocated to another destination (such as sysout) if desired.

The message log is primarily intended for historical use; that is, as a means to review eLink TCP for IMS activity after-the-fact. The message log remains open for output during the entire execution of eLink TCP for IMS. Consequently, messages cannot ordinarily be viewed interactively (for example, using ISPF Browse) due to the dataset disposition and/or buffering of messages by OS/390.

The MSGLEVEL parameter of the SYSTEM statement in the configuration file controls the type of messages written to the log. Specifying a MSGLEVEL of 4 causes all informational and error messages to be recorded. Specifying a MSGLEVEL of 2 records only error messages. A MSGLEVEL of 0 (zero) suppresses all logging. Under normal circumstances, a MSGLEVEL of 4 (the default) should be specified.

You may elect to have messages appended to the existing log (thus preserving messages from previous executions of eLink TCP for IMS) by coding DISP=MOD in the MSGLOG DD statement in the JCL for eLink TCP for IMS. Alternatively, coding DISP=OLD or DISP=SHR causes the log to be overwritten, discarding any messages from a previous execution of eLink TCP for IMS.

Message Format

Each message written to the message log has the general format as in Listing 5-4.

Listing 5-4 Message Log Format

---

mm-dd-yyyy

mm is the month of the year (1-12) in which the message was logged.

dd is the day of the month (1-31) on which the message was logged.

yyyy is the year that the message was logged.

hh:mm:ss

hh is the hour of the day during which the message was logged.

mm is the minute of the hour during which the message was logged.

ss is the second of the minute during which the message was logged.

msgid

is the message ID, in the form BEAnnnnt, where nnnn is a unique message number and t is the message type.

ssss

is the socket number for the TCP/IP connection with which the message is associated. If the message is not associated with a TCP/IP connection, this field is blank.

text

is the text of the message.

For additional information on messages issued by the gateway, refer to "Error and Informational Messages."

OS/390 Console Messages

The eLink TCP for IMS product also logs messages to the OS/390 console so that operators can monitor the operation of eLink TCP for IMS and respond to any conditions requiring their attention.

In general, eLink TCP for IMS logs the same messages to the console that are recorded in the message log (that is, informational and error messages). However, because eLink TCP for IMS issues few informational messages during normal operation, console traffic is minimized.

The Server Response Log File

When eLink TCP for IMS receives a client request from a remote system, the request is inserted into the IMS message queue for delivery to the specified IMS server transaction. The IMS server transaction processes the request and inserts the response (if required) into the IMS message queue for delivery to eLink TCP for IMS. When the response is received, it is returned to the requesting remote system.

Each IMS server request and the associated response contains a unique request/response ID, consisting of the date and time that eLink TCP for IMS was started, and a serial number. The eLink TCP for IMS gateway uses the request/response ID to correlate each response with a pending server request.

It is possible that eLink TCP for IMS may receive a response from an IMS server transaction for which no pending request exists. This can occur under any of the following conditions:

• The eLink TCP for IMS gateway was restarted after the request was sent to IMS but before the response was received. In this case, the response is usually received when eLink TCP for IMS is subsequently restarted.

• The TCP/IP connection with the remote gateway was lost after the request was sent to IMS but before the response was received.

• The request was sent to IMS, but timed out and was aborted before the response was received from IMS.

• The IMS server transaction returned a response to a request that did not require a response.

• The eLink TCP for IMS BMP was unable to identify an IMS client request, and processed it as an IMS server response. In order for eLink TCP for IMS to reliably distinguish between an IMS client request and a server response, the BEA-RESERVED-1 field (BEA_Reserved1 in the C header file) in the request header must be initialized to binary zero by the IMS client transaction. This problem is usually identified by an invalid date and time in the request/response ID (displayed by message BEA2033E).

When a response cannot be correlated with a pending request (that is, a pending request with a matching request/response ID cannot be found), eLink TCP for IMS writes the response to a server response log file (DDNAME=SVRLOG). The information in the server response log file can be useful as part of a manual recovery procedure. Message BEA2033E is also issued, indicating that a server response has been logged and specifying the reason ("Server Request not found" or "No response was expected").

Server responses are logged as two separate records: the BEA server request/response header (containing the unique request/response ID), and the response data.

Note: The dataset attributes of the server response Log File are fixed by architecture. Refer to the BEA eLink TCP Installation Guide for additional information.