[Top] [Previous] [Next] [End of Book]

# Chapter 5 . Administering BEA Connect TCP for IMS

## Starting BEA Connect TCP for IMS

BEA Connect TCP for IMS is started by submitting the JCL for an IMS BMP (Batch Message Processing program). Before attempting to start BEA Connect TCP for IMS, make sure that the PSB is not stopped; if it is, the job will immediately abend.

During operation, BEA Connect TCP for IMS writes all messages to the Message Log dataset (DDNAME=MSGLOG). The Message Log is primarily useful for historical purposes after BEA Connect TCP for IMS has ended, because 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 MVS 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 MVS console.

## Initialization

During initialization, the following activities occur:

- The run-time datasets (Configuration File, Message Log, and Server Response Log) are opened

- The Configuration File is read and processed to establish the configuration

- BEA Connect TCP for IMS establishes a TCP/IP Listener for each defined local gateway (port)

- If requested, outbound sessions are established with remote gateway(s)

- BEA Connect TCP for IMS puts up an outstanding WTOR on the MVS console by means of which operator commands can be entered

If any errors are detected during initialization, BEA Connect TCP for IMS issues the appropriate error messages and initialization fails. If this occurs, correct the indicated error(s) and restart BEA Connect 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

- BEA Connect TCP for IMS 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 through the IMS Message Queue

- The IMS Message Queue is polled for requests and responses from IMS Client and Server transactions

- Outbound requests issued by IMS Client transactions are received through the IMS Message Queue and relayed to the appropriate remote systems through the TCP/IP network

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

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 (that is, BEA Connect TCP for IMS executes as a non-ending BMP) until a SHUTDOWN command is received or a fatal error is encountered. Under normal circumstances, BEA Connect 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:

- BEA Connect TCP for IMS stops accepting requests for new inbound connections (from remote systems)

- Active inbound and outbound sessions are terminated

- The Message Log and Server Response Log datasets are closed

- BEA Connect TCP for IMS terminates and returns control to MVS

## Testing Connectivity with Remote Systems

When you start BEA Connect 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 Connect gateway.

By specifying a minimum number (greater than 0) of outbound sessions for a remote gateway, you can cause outbound session(s) to be automatically established with that gateway during initialization. This can be handy to 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.

## The Configuration File

BEA Connect TCP for IMS uses a configuration file to establish the configuration at run-time. The configuration file is a simple text file that is easily edited using any desired text editor, such as ISPF Edit.

The configuration is defined in terms of the local (IMS) gateway, remote (for example, TPS) gateway(s), and remote service(s) offered by various remote gateways to which BEA Connect TCP for IMS may have access.

## Local Gateways

The local (IMS) gateway defines the access points that remote gateways can use to connect to the IMS gateway.

The local gateway may be defined as having a single physical IP address and port number, or multiple physical IP addresses and/or port numbers. Furthermore, each physical port may be defined as accepting one or more concurrent inbound TCP/IP connections from remote gateways.

One or more GATEWAY TYPE=LOCAL statements are used in the configuration file to define the local gateway. Each GATEWAY TYPE=LOCAL statement defines a specific IP address and port number through which BEA Connect TCP for IMS will accept inbound connection requests from remote gateways. Inbound connections are used by a remote gateway to send client requests to the IMS gateway for processing by IMS Server transactions. Each local gateway (as defined by a GATEWAY TYPE=LOCAL statement) must have a unique Logical Machine ID (a symbolic name used to identify a gateway).

There must be at least one GATEWAY TYPE=LOCAL statement in the configuration file. However, there may be multiple GATEWAY TYPE=LOCAL statements, provided each specifies a different IP address and/or port number and Logical Machine ID.

Remote systems attempting to establish an inbound session with the local gateway may optionally be required to supply a valid Account ID and/or Password.

Refer to Chapter 4, "Configuring BEA Connect TCP for IMS," for details on how to code the GATEWAY TYPE=LOCAL statement. Also, refer to Appendix C, "Example Configuration File," for examples of the GATEWAY TYPE=LOCAL statement.

## Remote Gateways

A remote gateway is another BEA Connect gateway (TPS, CICS, or IMS) to which BEA Connect TCP for IMS can be connected by one or more TCP/IP connections. A remote gateway definition defines the access points that BEA Connect TCP for IMS uses to connect to the remote gateway.

The remote gateway is defined by its IP address and port number. The remote gateway may be defined as accepting one or more concurrent outbound TCP/IP connections initiated by the local (IMS) gateway. Outbound connections are used by the IMS gateway to send IMS client requests to a remote gateway for processing by the requested service.

One or more GATEWAY TYPE=REMOTE statements are used in the configuration file to define remote gateways. Each GATEWAY TYPE=REMOTE statement defines the IP address and port number that BEA Connect TCP for IMS will use to establish an outbound connection with a remote gateway. The GATEWAY TYPE=REMOTE statement also identifies a remote gateway by a unique Logical Machine ID.

The configuration file may contain multiple GATEWAY TYPE=REMOTE statements, each defining a different remote gateway. If no GATEWAY TYPE=REMOTE statements are present, then BEA Connect TCP for IMS cannot establish outbound connections with remote gateways, and therefore cannot process IMS client requests.

BEA Connect TCP for IMS may optionally be configured to supply a valid Account ID and/or Password when establishing an outbound session with a remote gateway.

Refer to Chapter 4, "Configuring BEA Connect TCP for IMS," for details on how to code the GATEWAY TYPE=REMOTE statement. Also, refer to Appendix C, "Example Configuration File," for examples of the GATEWAY TYPE=REMOTE statement.

## Remote Services

A remote service is a service offered by a remote gateway to which BEA Connect TCP for IMS has access. IMS client transactions can make requests for services offered by remote gateways.

One or more SERVICE TYPE=REMOTE statements are used in the configuration file to define remote services. Each SERVICE TYPE=REMOTE statement defines the local service name (used by the IMS client transaction to request the service), the remote service name (used to invoke the service on the remote system), and the Logical Machine ID of a remote gateway that offers the service. There must be a corresponding GATEWAY TYPE=REMOTE statement in the Configuration File for the specified Logical Machine ID.

The configuration file may contain multiple SERVICE TYPE=REMOTE statements for a given (local) service name, each pointing to a different Logical Machine ID (that is, remote gateway). In this case, BEA Connect TCP for IMS attempts to distribute requests for the service among the available service providers, thus maximizing throughput during busy periods.

Refer to Chapter 4, "Configuring BEA Connect TCP for IMS," for details on how to code the SERVICE TYPE=REMOTE statement. Also, refer to Appendix C, "Example Configuration File," for examples of the SERVICE TYPE=REMOTE statement.

## The BEA Connect TCP for IMS Message Log

BEA Connect TCP for IMS 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 BEA Connect TCP for IMS activity after-the-fact. The Message Log remains open for output during the entire execution of BEA Connect 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 MVS.

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 BEA Connect TCP for IMS) by coding DISP=MOD in the MSGLOG DD statement in the JCL for BEA Connect TCP for IMS. Alternatively, coding DISP=OLD (or DISP=SHR) causes the log to be overwritten, discarding any messages from a previous execution of BEA Connect TCP for IMS.

Each message written to the Message Log has the following general format:
mm-dd-yyyy hh:mm:ss msgid ssss text where:
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 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, of 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.

Refer to Appendix B, "Error and Informational Messages," for additional information on messages issued by BEA Connect TCP for IMS.

## MVS Console Messages

BEA Connect TCP for IMS also logs messages to the MVS console so that operators may monitor the operation of BEA Connect TCP for IMS and respond to any conditions requiring their attention.

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

## The Server Response Log File

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

It is possible that BEA Connect 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:

- BEA Connect TCP for IMS was restarted after the request was sent to IMS but before the response was received. In this case, the response is usually received when BEA Connect 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.

- BEA Connect TCP for IMS was unable to identify an IMS client request, and processed it as an IMS server response. In order for BEA Connect 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), BEA Connect TCP for IMS writes the response to a Server Response Log File (DDNAME=SVRLOG). The information in the Server Response Log File may 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 Chapter 3, "Installing BEA Connect TCP for IMS," for additional information.

## Operator Commands

During normal operation, BEA Connect 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: that is,

R nn,command
where nn is the MVS-assigned reply ID and command is the text of the command.

### SHUTDOWN Command

The SHUTDOWN command allows an operator to initiate termination of BEA Connect TCP for IMS, and is entered as follows:

R nn,SHUTDOWN

Note: The SHUTDOWN command must be entered exactly as shown.

When the SHUTDOWN command is recognized and accepted, BEA Connect TCP for IMS begins the process of terminating. New inbound sessions are no longer accepted; active inbound and outbound sessions are terminated; datasets are closed; and BEA Connect TCP for IMS returns to MVS.

## A Client-Initiated Shutdown

BEA Connect TCP for IMS may 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 BEA Connect TCP for IMS from a remote system, rather than by operator command from an MVS 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:

F jobname TERM=type where

jobname is the MVS jobname assigned to BEA Connect TCP for IMS
type is the type of shutdown to be performed:
STOP - Normal shutdown
DUMP - Abend with dump

You must format the command exactly as shown. If you do not, or if the job name specified is incorrect, BEA Connect TCP for IMS simply ignores the command and processes the request or response in the usual way.

If TERM=STOP is specified, BEA Connect TCP for IMS initiates normal shutdown processing, as if an operator had entered the SHUTDOWN command from an MVS console.

If TERM=DUMP is specified, BEA Connect TCP for IMS issues a U3166 abend. If a SYSUDUMP DD statement is included in the JCL, a standard MVS dump will be produced.

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

[Top] [Previous] [Next] [End of Book]