|
|
The following topics explain operating and monitoring the BEA Tuxedo Mainframe Adapter for TCP (IMS) (hereafter referenced as TMA TCP for IMS) product:
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 BEA 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 BEA 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.
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/STO OTMA/STA OTMA/DIS TMEMBER name TPIPE ALLDisplays the status of the client.
/STO TMEMBER name TPIPE ALLStops an individual client from accessing a service.
/STA TMEMBER name TPIPE ALLEnables an individual client and allows access to a service.
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.
During initialization, the following activities occur:
WTOR) on the z/OS console by means of which operator commands can be enteredIf 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.
If initialization is successful, normal operation begins, during which the following activities occur:
WTOR) are processed.
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.
R nn,command
In
Listing 5-1, nn is the z/OS-assigned reply ID and command is the text of the command.
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).
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:
The SHUTDOWN command allows an operator to initiate termination of TMA TCP for IMS, and is entered in the format in
Listing 5-2.
R nn,SHUTDOWNThe 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. |
F jobname TERM=type
jobname
TERM=type
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.
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 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.
Each message written to the message log has the general format as in Listing 5-4.
mm-dd-yyyy hh:mm:ss msgid ssss textmm-dd-yyyy
hh:mm:ss
ssss
text
For additional information on messages issued by the gateway, refer to the Error and Informational Messages section.
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.
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:
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 BEA Tuxedo Mainframe Adapter for TCP Installation Guide for additional information. |
|