Monitoring Oracle TMA TCP for IMS

The following topics explain operating and monitoring the Oracle Tuxedo Mainframe Adapter for TCP (IMS) (hereafter referenced as TMA TCP for IMS) product:

•	Testing Connectivity with Remote Systems

•	Operating Oracle TMA TCP for IMS

•	The Oracle TMA TCP for IMS Message Log

•	The Server Response Log File

Testing Connectivity with Remote Systems

When you start TMA 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 Oracle Tuxedo Mainframe Adapter 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 Oracle Tuxedo gateway) to identify and correct the problem.

For a description of the TMA TCP for IMS error messages, refer to the “Error and Informational Messages” section.

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 Oracle TMA TCP for IMS

The TMA TCP for IMS product is started by submitting JCL. For sample JCL, refer to the “Sample JCL and User Exits” section.

During operation, TMA TCP for IMS writes all messages to the message log dataset (DDNAME=MSGLOG). The message log is primarily useful for historical purposes after TMA 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 z/OS 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 z/OS 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 TMA 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 TMA TCP for IMS product puts up an outstanding write-to-operator with reply (WTOR) on the z/OS console by means of which operator commands can be entered

If any errors are detected during initialization, TMA TCP for IMS issues the appropriate error messages and initialization fails. If initialization fails, correct the indicated errors and restart TMA 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 TMA 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 TMA 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, TMA 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

R nn,command

 

In Listing 5‑1, nn is the z/OS-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, TMA 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 TMA 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 TMA TCP for IMS gateway terminates and returns control to z/OS.

SHUTDOWN Command

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

Listing 5‑2 Syntax for Termination Initiation

R nn,SHUTDOWN

 

A Client-Initiated Shutdown

The TMA 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 TMA TCP for IMS from a remote system, rather than by operator command from an z/OS 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, TMA 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, TMA TCP for IMS ignores a remote client request to initiate shutdown processing.

Listing 5‑3 Syntax for Client-Initiated Shutdown

F jobname TERM=type

 

jobname

is the z/OS jobname assigned to TMA 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, TMA TCP for IMS initiates normal shutdown processing, as if an operator had entered the SHUTDOWN command from an z/OS console.

DUMP

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

The Oracle TMA TCP for IMS Message Log

The TMA 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 TMA TCP for IMS activity after-the-fact. The message log remains open for output during the entire execution of TMA 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 z/OS.

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 should be specified.

You may elect to have messages appended to the existing log (thus preserving messages from previous executions of TMA TCP for IMS) by coding DISP=MOD in the MSGLOG DD statement in the JCL for TMA TCP for IMS. Alternatively, coding DISP=OLD or DISP=SHR causes the log to be overwritten, discarding any messages from a previous execution of TMA 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 hh:mm:ss msgid ssss text

 

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.

Figure 5‑1 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 the “Error and Informational Messages” section.

z/OS Console Messages

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

In general, TMA 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 TMA TCP for IMS issues few informational messages during normal operation, console traffic is minimized.

The Server Response Log File

When TMA 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 TMA 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 TMA TCP for IMS was started, and a serial number. The TMA TCP for IMS gateway uses the request/response ID to correlate each response with a pending server request.

It is possible that TMA 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 TMA 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 TMA 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.

When a response cannot be correlated with a pending request (that is, a pending request with a matching request/response ID cannot be found), TMA 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 Oracle Tuxedo Mainframe Adapter for TCP Installation Guide for additional information.