Introducing Oracle Tuxedo Mainframe Adapter for TCP (CICS)

Oracle 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 Oracle Tuxedo regions to access services provided by CICS application programs and vice-versa. An Oracle Tuxedo region, or administrative domain, is a single computer or network of computers that shares a single Oracle Tuxedo configuration.

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

The following information introduces the TMA TCP for CICS product:

•	What You Need to Know

•	Oracle TMA TCP for CICS Architecture

•	Oracle TMA TCP Functionality

•	Oracle TMA TCP for CICS Components

•	Processing Scenarios

•	Getting Started with TMA TCP for CICS

What You Need to Know

This document is primarily for CICS system administrators who configure and administer TMA TCP. In addition, programmers can find useful pointers for developing client programs and service routines that send data through to the remote TMA TCP gateway.

Programmers who work with TMA TCP should be familiar with CICS applications development.

System administrators who work with TMA TCP should be familiar with the following concepts, tools, and procedures:

•	TCP/IP networking

•	IBM CICS Sockets Interface

•	Defining new resources to CICS

•	Standard CICS monitoring tools

Oracle TMA TCP for CICS Architecture

Oracle 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 Oracle Tuxedo domain and request services offered by CICS

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

Oracle 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. Oracle 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.

Load Balancing of a Requester

The TMA TCP for CICS supports Requester load balancing. TMA TCP for CICS provides configuration for multiple services with the same name and the ability to associate them with different unique LMIDs. This configuration enables load balancing of the Requesters.

Automatic Enabling of LMID

The TMA TCP for CICS supports automatic enabling of a given Requester which is already disabled. The AUTO ENABLE LMID option is provided in the Requester configuration. When the option is set to E (Enable), the Pre-Requester automatically enables the LMID and starts the Requester and processes the request.

Oracle 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

A TMA TCP Handler is a CICS program that communicates with the TMA TCP gateway over TCP/IP. Specifically, the Handler communicates Oracle Tuxedo requests to a CICS region. A Handler is started automatically within a CICS region when Oracle 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 Oracle 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 TMA TCP gateway, then waits for the TMA TCP gateway 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 Oracle 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 Oracle Tuxedo region. After receiving request information from the Pre-requester, the Requester sends that information to Oracle Tuxedo. The Requester then receives any response data returned by Oracle 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 Oracle 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 an Oracle Tuxedo Domain

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

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

Figure 1‑1 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle TMA Client Gateway Configuration

Figure 1‑2 shows the configuration of the Oracle 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 Oracle 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 Oracle 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 Oracle TMA TCP Installation Guide.

•

Using the administration tool (described in “Configuring and Administering Oracle 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 Oracle 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 Oracle TMA TCP for CICS Works”.

•	Consult your Oracle Tuxedo administrator about service names (what to call a service and what Oracle Tuxedo names it) and the layout of data each service expects to ensure there are no consistency problems.