CICS User Guide

Introducing Tuxedo Mainframe Adapter for TCP (CICS)

BEA Tuxedo Mainframe Adapter for TCP (CICS) (hereafter referenced as TMA TCP for CICS) is a gateway connectivity feature that makes it possible for non-transactional tasks within BEA Tuxedo regions to access services provided by CICS application programs and vice-versa. A BEA Tuxedo region, or administrative domain, is a single computer or network of computers that shares a single BEA Tuxedo configuration.

The TMA TCP for CICS software is designed to provide transparent CICS program access from within a BEA Tuxedo domain and BEA Tuxedo access from within a CICS region.

The following information introduces the TMA TCP for CICS product:

BEA TMA TCP for CICS Architecture

BEA TMA TCP for CICS is composed of four CICS programs running within a CICS region:

Handler
Application Handler
Pre-requester
Requester

It uses the Sockets Interface and Sockets for CICS Listener that is shipped with the IBM TCP/IP for CICS TS Sockets Interface. There are two different processing scenarios to consider:

Requests that originate in a remote BEA Tuxedo domain and request services offered by CICS
Requests that originate in a CICS region and request services offered by a remote BEA Tuxedo domain

BEA TMA TCP Functionality

The following functionality is available in the TMA TCP product.

Domains-based Gateway Connectivity

The TMA TCP product has a domains-based architecture supporting bidirectional communications, request/response support, and concurrent support for the CICS interface.

Security

The TMA TCP product grants access to Tuxedo services based on a user name supplied by CICS.

The TMA TCP for CICS product can start CICS transactions or link to programs. BEA Tuxedo provides the user ID to the TMA TCP product to check for appropriate security prior to initiating the transactions.

Domain Name Server Support

The TMA TCP product supports domain name server (DNS) resolution of IP addresses. This support allows you to change the IP address at the Domain Name Server to implement address changes without reconfiguring the TMA TCP gateway.

Dynamic Configuration

The TMA TCP product supports dynamic configuration updates for some of the TMA TCP configuration parameters. You can modify the configuration without shutting down and restarting the TMA TCP product. For more information about dynamic configuration, refer to the Dynamically Configuring TMA TCP for CICS section.

BEA TMA TCP for CICS Components

There are four programs used in processing remotely and locally initiated requests.

Handler
Application Handler
Pre-requester
Requester

Two administrative tools are also available:

An online CICS administrative tool for configuring and maintaining the TMA TCP for CICS gateway
An administrative tool (BDWN) for terminating the four programs listed above

The TMA TCP for CICS Handler

An TMA TCP Handler is a CICS program that communicates with the TMA TCP gateway Requester over TCP/IP; specifically, the Handler communicates BEA Tuxedo requests to a CICS region. A Handler is started automatically within a CICS region when a Requester within BEA Tuxedo issues the first service request destined for that CICS region.

The Handler is responsible for accepting a connection request, taking control of the socket connection, and continuing communication with the Requester in the BEA Tuxedo domain for the life of the socket connection. The Handler interfaces as necessary with the Application Handler to process service requests originating from the TMA TCP gateway Requester. If multiplexing or security is enabled, the Handler starts the Application Handler and waits for the next service request. The Handler periodically checks for completed requests. When a request has been completed, the Handler retrieves the response data from the Application Handler and transmits that data back to the Requester. The Handler also periodically checks to ensure that no active service requests have timed out.

If the multiplex count is 1 and security is disabled, or if the service request originated from a version of TMA TCP gateway prior to Version 3.0, the Handler executes the target user application, waits for the application to return data, transmits that data back to the Requester, then waits for the Requester to send another service request.

The TMA TCP for CICS Application Handler

The Application Handler is started by and receives request information from the Handler. The Application Handler executes the target user application, waits for the application to return data, and returns the data to the Handler.

The TMA TCP for CICS Pre-requester

The Pre-Requestor program is used as an interface between your CICS client program and the TMA TCP for CICS Requester. The CICS Requester, which is described in the next section, is the program that talks with the remote BEA Tuxedo domain. From your CICS client program you call the Pre-requester by issuing an EXEC CICS LINK.

The TMA TCP for CICS Requester

The Requester program is responsible for making and maintaining the sockets connection with the remote BEA Tuxedo region. After receiving request information from the Pre-requester, the Requester sends that information to BEA Tuxedo. The Requester then receives any response data returned by BEA Tuxedo and sends it back to the Pre-requester, which in turn gives the information back to the client program that had called it.

IBM TCP/IP Sockets Interface

The sockets interface must be enabled before TMA TCP for CICS can communicate over TCP/IP. This procedure is true for any CICS program which uses the sockets API. The IBM TCP/IP Sockets Interface is not supplied by BEA Systems, Inc. You can purchase it directly from IBM. The supplied transaction that accompanies the IBM TCP/IP Sockets for CICS product is used to enable the sockets interface under CICS. Complete documentation is provided with the IBM product.

Using Other Supported TCP/IP Sockets Products

This document refers to the IBM TCP/IP sockets interface product. If you are using another supported TCP/IP product consult that product's documentation for equivalent components.

IBM TCP/IP Sockets for CICS Supplied Listener

The IBM TCP/IP Sockets for CICS Supplied Listener is responsible for capturing the initial connection request and passing that request along to the TMA TCP for CICS Handler. It is a piece of the IBM TCP/IP Sockets for CICS product which you must purchase directly from IBM. The listener should be installed and configured as outlined in the manual shipped with the product.

IBM User Maintained Tables (UMT)

The Connection file, BEAVCON, defaults to a user maintained table (UMT). If you choose to change this file to a VSAM file you must add the transaction BDWN to PLTSI for CICS. This transaction's primary function is to shut down all the active Requesters, but one of its secondary functions is to remove all the entries from the Connection file. The Connection file must be empty before initializing activity.

Processing Scenarios

This section describes the TMA TCP for CICS processing scenarios.

Requests from within a BEA Tuxedo Domain

Because of the way BEA Tuxedo maps services to servers, service requests from remote BEA Tuxedo regions to TMA TCP are transparent to the user, the BEA Tuxedo developer, and the CICS programmer.

As Figure 1-1 shows, TMA TCP for CICS extends this transparent access by routing BEA Tuxedo's requests for CICS program services through TCP/IP network software.

Figure 1-1 BEA Tuxedo to TMA TCP for CICS Routing

BEA Tuxedo to TMA TCP for CICS Routing

As Figure 1-1 shows, TMA TCP for CICS fits between the CICS user application and TCP/IP.

When BEA Tuxedo client programs send requests to remote systems (in this case, CICS) TMA TCP gateway transforms those requests into messages formatted appropriately for transmission to the remote system. Also, when remote systems respond, TMA TCP gateway transforms these responses into replies that local client programs can process.

The TMA TCP for CICS software is implemented as an ordinary CICS program which communicates with the Sockets Interface. It accepts connection requests from the TMA TCP gateway and returns standard replies.

Simultaneous socket connections can exist between one TMA TCP for CICS gateway (a set of TMA Handlers within a single CICS region) and all remote TMA TCP gateway Requesters. Each socket connection is established automatically when a new TMA TCP gateway Requester in the BEA Tuxedo domain establishes communication with the TMA TCP for CICS gateway.

Requests from within CICS

The mechanism used to send requests initiated from a CICS program to a remote BEA Tuxedo domain is invisible to the user and significantly abstracted from the CICS programmer. Your company's CICS program issues an EXEC CICS LINK command to the BEA TMA gateway. In the data passed with the EXEC CICS LINK command, the programmer supplies the name of the service and the data to be used as input to that service. When the EXEC CICS LINK command returns, the reply to the request is placed in that same data area. If there was a problem satisfying the service request, meaningful return codes are sent back.

Figure 1-2 BEA TMA Client Gateway Configuration

BEA TMA Client Gateway Configuration

Figure 1-2 shows the configuration of the BEA TMA client gateway. A client program (your CICS program) issues an EXEC CICS LINK command to the Pre-requester. The Pre-requester verifies that the service name is valid and identifies the Requester to which it should it should pass the request. The Pre-requester starts a different Requester for each configured remote endpoint. The Requester then sends the request to the remote BEA Tuxedo domain and waits for a response. Once the response is returned, the Requester notifies the Pre-requester and hands the response to the Pre-requester, which then returns the response to the client program.

Getting Started with TMA TCP for CICS

The following list describes all the tasks you must perform before you can begin using TMA TCP for CICS.

Ensure that MVS TCP/IP is installed and configured.
Ensure that the Sockets for CICS interface and supplied listener are installed and configured. The listener product comes with the Sockets for CICS interface.
From the MVS TCP/IP administrator, find out at which port and address your supplied listener should listen. Give this information to the BEA Tuxedo administrator so that the remote TMA TCP gateway component knows where to find the CICS TCP/IP listener.
Find out on which ports TMA TCP gateway is listening. This information is necessary when you begin setting up services.
Follow the installation instructions for TMA TCP given in the BEA TMA TCP Installation Guide.
Using the administration tool (described in Configuring and Administering BEA TMA TCP for CICS) define the services and remote endpoints for use by TMA TCP. The best way to approach this is to talk to the BEA Tuxedo administrator and choose one service only. Attempting to set up all the services at once would be a complex task, but after you learn how to set up one service, you should have no difficulty setting up the others.
Add an EXEC LINK statement to one of your CICS programs and set up the data area as described in Understanding How BEA TMA TCP for CICS Works.
Consult your BEA Tuxedo administrator about service names (what to call a service and what BEA Tuxedo names it) and the layout of data each service expects to ensure there are no consistency problems.