Understanding How Oracle TMA TCP for CICS Works

To understand how the Oracle Tuxedo Mainframe Adapter for TCP (CICS) (hereafter referenced as TMA TCP for CICS) product works, you should know how the product performs the following functions:

•	Starting the Listener Program

•	Running Oracle TMA TCP for CICS

•	Initializing the Handler

•	Processing Remote Service Requests

•	Shutting Down the Handler

•	Starting the Requester Program

•	Processing TMA TCP for CICS Originated Service Requests

•	Shutting Down the Requester

•	Translating Data with TMA TCP gateway

Each of these operations is described in the following sections. Additionally, this document describes some programming considerations that may be useful when you develop or change programs that interoperate with TMA TCP for CICS.

Starting the Listener Program

The Listener program is supplied by IBM and is part of the Sockets for CICS software product which must be purchased from IBM.

Note:

Before you can use TMA TCP for CICS, you must install and configure both IBM TCP/IP and the Sockets for CICS product as outlined in the documentation that accompanies those products.

The Listener’s job is to wait for connection requests at a particular network address and port of your choosing. When the Listener receives a connection request it invokes the appropriate CICS program automatically, based on the name supplied as part of the Listener’s connection protocol buffer. For example, if the Listener receives a connection request from TMA TCP gateway running on a remote Oracle Tuxedo node, it processes the connection and invokes the TMA TCP Handler.

Running Oracle TMA TCP for CICS

The TMA TCP Handler is invoked automatically by the Listener process. Once invoked, the Handler takes control of the socket connection and retains control until either the Handler is shut down or until there is a network problem that affects the socket connection. The Handler processes service requests up to the configured multiplex count. To process more service requests than the configured multiplex count, TMA TCP gateway starts more than one Handler. For limitations of the IBM Sockets for CICS Listener, refer to the appropriate IBM product documentation.

Initializing the Handler

The very first service request that is sent from the TMA TCP gateway gateway running on a remote Oracle Tuxedo node causes the following to occur.

1.	CICS Sockets Listener starts the TMA TCP for CICS Handler

2.	Listener issues a givesocket() function call

3.	Handler issues a takesocket() function call

4.	Listener resumes listening for new connection requests

5.	Handler communicates directly with the remote TMA TCP gateway gateway using TCP/IP

Processing Remote Service Requests

1.	The TMA TCP Handler receives the request from the remote TMA TCP gateway gateway (in the Oracle Tuxedo region) over TCP/IP. If necessary, the data is translated and/or converted into the proper data format or layout.

2.	If the multiplex count is 1 and security is disabled, or if the service request came from a version of TMA TCP gateway prior to Version 3.0, then the following tasks occur.

a.	The Handler issues a CICS LINK command to execute the program specified in the TMA TCP protocol header. With the LINK command it also passes along any request data provided by the client application that made the original Oracle Tuxedo service request.

b.	The Handler waits for the CICS program to finish and receives any returned data from the CICS program.

c.	The Handler transmits the response to the remote TMA TCP gateway gateway.

d.	The Handler stays connected to the remote gateway awaiting another service request.

3.	If the multiplex count is greater than 1 or security is enabled, then the following tasks occur.

a.	The Handler issues an EXEC CICS START TRANS call with the transaction specified in the Inbound Service File for the service specified in the TMA TCP protocol header. The transaction should be the same as the Application Handler program.

Note:

If security is enabled, the EXEC CICS START TRANSID call uses the user ID specified in the TMA TCP protocol header.

b.	For any completed service requests, the Handler retrieves the response data from the Application Handler.

c.	The Handler transmits the response to the remote TMA TCP gateway gateway.

d.	The connection between the Handler and the gateway remains and the Handler waits for another service request.

For tpacall/TPNOREPLY requests, the remote program is invoked by a CICS START TRANSID command and no data is returned to the original caller. In this case, a unique transaction must be defined for the service. Use the Inbound Service Information screen to enter this unique transaction name rather than using the transaction name that starts the Application Handler.

Shutting Down the Handler

When the network connection is lost, the Handler process automatically shuts down. The next service request sent causes the Listener to automatically start a new Handler, if necessary.

Use the supplied shutdown transaction BDWN to terminate active TMA TCP for CICS programs. Depending on the options specified, this causes all Handlers to shut down gracefully. The name of the BDWN transaction may have been changed at your site during installation, so verify the name.

Using BDWN to Shut Down the Handler

You can use the BDWN transaction in a CICS region with the following parameters to shut down Handlers in various ways. The command line syntax for BDWN is illustrated in the following listing.

Listing 2‑1 BDWN Command Line Syntax for Handlers

BDWN [ALL | CLEANUP | HANDLER I | HANDLER]

 

BDWN

Shuts down all Handlers or all Requesters or both. It also frees shared memory that was allocated by a Handler that has abended without freeing the shared memory that it allocated. You can specify optional parameters with the BDWN transaction to shut down Handlers immediately or after the processing of all requests has completed. The default is ALL.

ALL

Shuts down all Handlers and Requesters gracefully allowing them to complete all processing of all requests that were received before the execution of the BDWN transaction. Specifying ALL also frees any shared memory.

 

This is the default for BDWN.

CLEANUP

Frees any shared memory of Handlers that have abended. CLEANUP does not shut down any Handlers or Requesters.

HANDLER I

Shuts down all Handlers immediately and frees any shared memory of Handlers that have abended. This parameter does not shut down any Requesters.

HANDLER

Shuts down all Handlers gracefully allowing them to complete all processing off all requests that were received before the execution of the BDWN transaction. This parameter also frees any shared memory of Handlers that have abended. It does not shut down any Requesters.

Starting the Requester Program

The Requester is started automatically when the first service request for it is made by a CICS client program. At that point, the Requester establishes a connection with its remote endpoint and updates its control tables with run-time information for use by subsequent requests. If the connection with the remote endpoint is lost for any reason, the Requester attempts to re-establish the connection automatically. After a configured number of unsuccessful connection attempts, the Requester marks itself disabled.

If the gateway receives additional service requests, they are accommodated as long as the maximum multiplex count for the existing connection is not exceeded. Also, additional connections are opened, as necessary, until the configured maximum connection count is reached or all requests are accommodated.

Processing TMA TCP for CICS Originated Service Requests

1.	The CICS client program (your program) issues an EXEC CICS LINK command to the TMA TCP for CICS Pre-requester.

2.	The Pre-requester verifies that the request is valid, and then determines whether a Requester has been started for the specific endpoint for which this request is destined. If a Requester is not already running, the Pre-requester starts one.

3.	The request is then handed over to the Requester.

4.	The Requester transmits the request information to the remote Oracle Tuxedo domain.

5.	If the request is a type that needs a response, the Requester receives that response back from Oracle Tuxedo, and hands the data over to the Pre-requester.

6.	The Pre-requester issues an EXEC CICS RETURN command to the client program (your program). The client receives its response in the COMMAREA.

Shutting Down the Requester

There are two ways to shut down the Requester:

•

Use the administrative tool (described in “Configuring and Administering Oracle TMA TCP for CICS”) to disable the Requester. This method causes the selected Requester to clean up its tables and shut down gracefully. It also prohibits any service requests invoking it. When you are ready, use the administrative tool to enable the Requester.

•	Use the supplied shutdown transaction BDWN. This method causes ALL Requesters to shut down gracefully. The name of the BDWN transaction may have been changed at your site during installation. Check with the person who installed TMA TCP for CICS at your site.

Using BDWN to Shut Down the Requester

You can use the BDWN transaction in a CICS region with the following parameters to shut down Requesters in various ways. The command line syntax for BDWN is illustrated in the following listing.

Listing 2‑2 BDWN Command Line Syntax for Requesters

BDWN [ALL | REQUESTER I | REQUESTER]

 

BDWN

Shuts down all Handlers or all Requesters or both. It also frees shared memory used by the Requesters associated with each logical machine ID (LMID). You can specify optional parameters with the BDWN transaction to shut down Handlers or Requesters immediately or after processing of all requests has completed. The default is ALL.

ALL

Shuts down all Handlers and Requesters gracefully allowing them to complete all processing of all requests that were received before the execution of the BDWN transaction. Specifying ALL also frees any shared memory.

 

This is the default for BDWN.

REQUESTER I

Shuts down all Requesters immediately and frees memory associated with each LMID. This parameter does not shut down any Handlers.

REQUESTER

Shuts down all Requesters gracefully allowing them to complete all processing off all requests that were received before the execution of the BDWN transaction. It also frees memory associated with each LMID. This parameter does not shut down any Handlers.

Translating Data with TMA TCP gateway

Due to the way TMA TCP gateway translates and converts data on the remote Oracle Tuxedo system, the CICS programmer does not need to do anything to prepare data that is destined for the remote Oracle Tuxedo system.

The key to this high degree of transparency is the TMA TCP gateway configuration. It is through this mechanism that environmental differences, such as naming conventions and data formats, are concealed from programmers and programs.

Although all data is converted and translated automatically by the remote TMA TCP gateway gateway, the rules implemented are outlined in the following subsections to assist the CICS programmer in understanding how the data is manipulated. It is important for the CICS programmer to remember that this information is written from the point of view of the Oracle Tuxedo environment.

When a client program on the remote Oracle Tuxedo system sends data to (or receives data from) a service routine on a different model of computer, TMA TCP gateway automatically translates data as required. Translation involves changing the representation of intrinsic data types by changing attributes such as word length and byte order.

The following subsections describe the basic rules that TMA TCP gateway follows when it translates data and provide detailed information about how TMA TCP gateway handles string and numeric data.

Oracle Tuxedo Terminology

The following terms are some commonly used Oracle Tuxedo terms for buffer types.

 

Table 2‑1 Oracle Tuxedo Terminology

Term	Definition
STRING	A buffer of character data that is terminated by the first null character in the buffer. Typically, character string buffers undergo translation when sent to a system that is different from the sending system.
CARRAY	A CARRAY is a buffer of raw data that contains no terminating character and that undergoes no conversion or translation; the data is sent from one system to another without modification. A CARRAY is an exemplary buffer type for a graphics file.
VIEW	A VIEW buffer is a collection of field definitions that can be treated as a single entity. It is comparable to a record layout in COBOL or a structure in C.
FML	FML (Fielded Manipulation Language) buffers are variable length, dynamic, self-describing buffers. Each field in the buffer has its own descriptive header. In Oracle Tuxedo, FML buffers can be tied closely to VIEW buffers so that conversion from one to the other is direct.

Data Translation Rules

The following table lists the data translation rules that TMA TCP gateway follows.

 

Table 2‑2 Data Translation Rules

Field Type	Translation Rules
CARRAY	Passed untranslated as sequences of bytes
STRING and CHAR	Translated from ASCII to EBCDIC (if needed)
SHORT	Translated to S9(4) COMP
LONG	Translated to S9(9) COMP
FLOAT	Translated to COMP‑1
DOUBLE	Translated to COMP‑2

Note:

Oracle Tuxedo provides a field type named dec_t that supports decimal values within VIEWs. The TMA TCP gateway product translates these fields into machine independent representations of packed decimals. For example, dec_t(m,n) becomes S9(2*m-(n+1))V9(n) COMP-3. Therefore, a decimal field with a size of 8,5 corresponds to S9(10)V9(5) COMP-3.

The following table summarizes the translation rules between C and IBM/370 data types.

 

Table 2‑3 Translation Rules Between C and IBM/370 Data Types

Remote Data Type	Description	View Field Type/Length
PIC X(n)	Alpha-numeric Characters	string / n
PIC X	Single Alpha-numeric Character	char
PIC X(n)	Raw Bytes	carray / n
PIC X	Single Numeric Byte	carray / 1
PIC S9(4) COMP	16-bit Integer	short
PIC S9(9) COMP	32-bit Integer	long
COMP-1	Single-precision Floating Point	float
COMP-2	Double-precision Floating Point	double
PIC S9((m+(n+1))/2)V9(n) COMP-3	Packed Decimal	dec_t / m,n

Strings and Numeric Data: A Closer Look

This subsection provides suggestions that help you develop VIEW definitions for input and output buffers and records. It also explains how string data and numeric data are treated in the TMA TCP gateway environment.

Including NULL Characters in String Length Calculations

When you create VIEW definitions for input and output records that are used by CICS applications, do not specify an extra position for the terminating NULL characters that are used in string fields.

For example, when a CICS application program expects 10 characters in an input record, specify 10 for that field, not 10 plus 1.

Note:

Although TMA TCP gateway does not require strings to be NULL-terminated, it respects NULL termination. Therefore, when TMA TCP gateway detects a NULL (zero) character within a string, it does not process any subsequent characters. To pass full 8-bit data that contains embedded NULL values, use a CARRAY type field or buffer.

The character set translations performed by TMA TCP gateway can be fully localized, in accordance with the X/Open XPG Portability Guides. ASCII and EBCDIC translations are loadable from message files. The TMA TCP gateway software contains default behaviors which should meet the requirements of most English-language applications. However, you may find it necessary to customize tables. See the Oracle TMA TCP gateway User Guide for complete instructions.

Converting Numeric Data

You can convert numeric data into different data types easily, provided that you have enough range in the intermediate and destination types to handle the maximum value you need to represent.

For example, you can convert an FML field of double into a packed decimal field on the remote target system by specifying an appropriate dec_t type VIEW element.

In addition, you can convert numeric values into strings (and the reverse). For example, while FML buffers do not directly support the dec_t type, you can place decimal values in string fields and map these to dec_t fields within VIEW definitions.