Oracle Audio Technologies Network Router Oracle Tuxedo User Manual

Oracle® Tuxedo® Mainframe Adapter for TCP  
CICS User Guide  
Release 10.0  
June 2008  
 
Contents  
Introducing Tuxedo Mainframe Adapter for TCP (CICS)  
What You Need to Know. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1  
Oracle TMA TCP for CICS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2  
Oracle TMA TCP Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2  
Domains-based Gateway Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2  
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3  
Domain Name Server Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3  
Dynamic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3  
Load Balancing of a Requester. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3  
Automatic Enabling of LMID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3  
Oracle TMA TCP for CICS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3  
The TMA TCP for CICS Handler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4  
The TMA TCP for CICS Application Handler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4  
The TMA TCP for CICS Pre-requester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5  
The TMA TCP for CICS Requester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5  
IBM TCP/IP Sockets Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5  
Using Other Supported TCP/IP Sockets Products. . . . . . . . . . . . . . . . . . . . . . . . 1-5  
IBM TCP/IP Sockets for CICS Supplied Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5  
IBM User Maintained Tables (UMT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5  
Processing Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6  
Requests from within an Oracle Tuxedo Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6  
Requests from within CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8  
OracleTuxedo Mainframe Adapter for TCP CICS User Guide  
iii  
 
Getting Started with TMA TCP for CICS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10  
Understanding How Oracle TMA TCP for CICS Works  
Starting the Listener Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1  
Running Oracle TMA TCP for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2  
Initializing the Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2  
Processing Remote Service Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2  
Shutting Down the Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3  
Using BDWN to Shut Down the Handler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4  
Starting the Requester Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5  
Processing TMA TCP for CICS Originated Service Requests . . . . . . . . . . . . . . . . . 2-5  
Shutting Down the Requester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5  
Using BDWN to Shut Down the Requester . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6  
Translating Data with TMA TCP gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7  
Oracle Tuxedo Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7  
Data Translation Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8  
Strings and Numeric Data: A Closer Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10  
Including NULL Characters in String Length Calculations . . . . . . . . . . . . . . . 2-10  
Converting Numeric Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10  
Configuring the TMA TCP Security  
Service Request Processing with Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1  
Security Checking from UNIX to Mainframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2  
Security Checking from Mainframe to UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3  
Setting Up Security for TMA TCP for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4  
Securing User Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4  
Securing Inbound Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4  
Securing Outbound Connections from CICS to UNIX . . . . . . . . . . . . . . . . . . . . . . . 3-5  
iv  
OracleTuxedo Mainframe Adapter for TCP CICS User Guide  
 
Securing Outbound Connections from CICS to CICS . . . . . . . . . . . . . . . . . . . . . . . . 3-5  
Securing Outbound Connections from CICS to IMS. . . . . . . . . . . . . . . . . . . . . . . . . 3-5  
Securing Outbound Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6  
Configuring and Administering Oracle TMA TCP for CICS  
Menu Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2  
The Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2  
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3  
The Connection Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6  
PF Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6  
Update Connection Screen (C2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7  
Inquire Connection Screen (C3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8  
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9  
Browse Connection Screen (C5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10  
The Requester Screens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11  
PF Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12  
Insert Requester Screen (R1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13  
Update Requester Screen (R2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16  
Inquire Requester Screen (R3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19  
Delete Requester Screen (R4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22  
Browse Requester Screen (R5). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24  
The Outbound Service Information Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25  
PF Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26  
OracleTuxedo Mainframe Adapter for TCP CICS User Guide  
v
 
Insert Outbound Service Information Screen (S1). . . . . . . . . . . . . . . . . . . . . . . . . . 4-26  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27  
Update Outbound Service Information Screen (S2) . . . . . . . . . . . . . . . . . . . . . . . . 4-28  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28  
Inquire Outbound Service Information Screen (S3) . . . . . . . . . . . . . . . . . . . . . . . . 4-29  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-30  
Delete Outbound Service Information Screen (S4) . . . . . . . . . . . . . . . . . . . . . . . . . 4-30  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31  
Browse Outbound Service Information Screen (S5) . . . . . . . . . . . . . . . . . . . . . . . . 4-32  
The User Connection ACCOUNT Screens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32  
PF Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33  
Insert User Connection ACCOUNT Screen (U1) . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34  
Update User Connection ACCOUNT Screen (U2) . . . . . . . . . . . . . . . . . . . . . . . . . 4-34  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35  
Inquire User Connection ACCOUNT Screen (U3) . . . . . . . . . . . . . . . . . . . . . . . . . 4-35  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36  
Delete User Connection ACCOUNT Screen (U4) . . . . . . . . . . . . . . . . . . . . . . . . . 4-36  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-37  
The Browse User Connection ACCOUNT Screen (U5) . . . . . . . . . . . . . . . . . . . . . 4-37  
The Inbound Service Information Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38  
PF Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39  
Insert Inbound Service Information Screen (I1) . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40  
Update Inbound Service Information Screen (I2) . . . . . . . . . . . . . . . . . . . . . . . . . . 4-41  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-42  
Inquire Inbound Service Information Screen (I3) . . . . . . . . . . . . . . . . . . . . . . . . . . 4-43  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-44  
vi  
OracleTuxedo Mainframe Adapter for TCP CICS User Guide  
 
Delete Inbound Service Information Screen (I4) . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-46  
The Browse Inbound Service Screen (I5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-47  
The Handler Configuration Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-48  
PF Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-48  
Update Handler Configuration Screen (H2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-49  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-50  
Inquire Handler Configuration Screen (H3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-50  
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-51  
Dynamically Configuring TMA TCP for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-52  
Modifying Outbound Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-52  
Modifying User Connection Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-52  
Modifying Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-53  
Deleting Requester LMIDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-53  
Administering the Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-53  
Programming Oracle Tuxedo Mainframe Adapter for TCP (CICS)  
Client Application Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1  
Buffer Layout Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1  
Making Calls from a CICS Client Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2  
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5  
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7  
Gateway Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7  
MVS or CICS Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7  
Application Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8  
Server Application Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8  
Programming Services with a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9  
Programming Services without a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9  
OracleTuxedo Mainframe Adapter for TCP CICS User Guide  
vii  
 
Modifying the Length of the Return Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9  
Modifying Return Message Lengths for C Programs. . . . . . . . . . . . . . . . . . . . . 5-9  
Modifying Return Message Lengths for COBOL Programs . . . . . . . . . . . . . . . 5-9  
Error and Informational Messages  
Messages Returned to the Remote Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1  
Messages Written to the TMA TCP for CICS Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3  
Codes Returned to a CICS Client Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7  
Informational Process Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10  
Data Field Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10  
System Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13  
viii  
OracleTuxedo Mainframe Adapter for TCP CICS User Guide  
 
C H A P T E R  
1
Introducing 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:  
z What You Need to Know  
z Oracle TMA TCP for CICS Architecture  
z Oracle TMA TCP Functionality  
z Oracle TMA TCP for CICS Components  
z Processing Scenarios  
z 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.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
1-1  
 
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:  
z TCP/IP networking  
z IBM CICS Sockets Interface  
z Defining new resources to CICS  
z 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:  
z Handler  
z Application Handler  
z Pre-requester  
z 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:  
z Requests that originate in a remote Oracle Tuxedo domain and request services offered by  
CICS  
z 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.  
1-2  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Oracle TMA TCP for CICS Components  
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 LMIDoption 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.  
z Handler  
z Application Handler  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
1-3  
 
z Pre-requester  
z Requester  
Two administrative tools are also available:  
z An online CICS administrative tool for configuring and maintaining the TMA TCP for  
CICS gateway  
z 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.  
1-4  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Oracle TMA TCP for CICS Components  
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 VSAMfile you must add the transaction BDWNto PLTSIfor CICS. This  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
1-5  
 
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.  
1-6  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Processing Scenarios  
Figure 1-1 Oracle Tuxedo to TMA TCP for CICS Routing  
Tuxedo  
TMA TCP Gateway  
TCP/IP  
Network  
TCP/IP for MVS  
CICS TCP/IP Listener  
TMA TCP for CICS  
TCP/CICS  
Handler  
TCP/CICS  
Application  
Handler  
TCP/CICS  
Application  
Handler  
User  
User  
User  
App3  
App1  
App2  
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  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
1-7  
 
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 LINKcommand to the Oracle TMA gateway. In  
the data passed with the EXEC CICS LINKcommand, the programmer supplies the name of the  
service and the data to be used as input to that service. When the EXEC CICS LINKcommand  
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.  
1-8  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Processing Scenarios  
Figure 1-2 Oracle TMA Client Gateway Configuration  
User Program  
EXEC CICS LINK  
User Program  
EXEC CICS LINK  
User Program  
EXEC CICS LINK  
BEA  
Control  
Table  
Pre-Requester  
Read CSA  
Pre-Requester  
Read CSA  
Pre-Requester  
Read CSA  
Read/Write TSQ  
Read/Write TSQ  
Read/Write TSQ  
BEA  
Control  
Table  
TS  
Q
TS  
Q
TS  
Q
TS  
Q
TS  
Q
BEA  
Common Storage  
Area  
Requester  
Requester  
(CSA)  
Read/Set CSA  
Read/Set CSA  
GW  
GW  
Tuxedo  
Tuxedo  
Figure 1-2 shows the configuration of the Oracle TMA client gateway. A client program (your  
CICS program) issues an EXEC CICS LINKcommand 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.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
1-9  
 
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.  
z Ensure that MVS TCP/IP is installed and configured.  
z Ensure that the Sockets for CICS interface and supplied listener are installed and  
configured. The listener product comes with the Sockets for CICS interface.  
z 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.  
z Find out on which ports TMA TCP gateway is listening. This information is necessary  
when you begin setting up services.  
z Follow the installation instructions for TMA TCP given in the Oracle TMA TCP  
Installation Guide.  
z 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.  
z Add an EXEC LINKstatement to one of your CICS programs and set up the data area as  
described in “Understanding How Oracle TMA TCP for CICS Works”.  
z 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.  
1-10  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
C H A P T E R  
2
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:  
z Starting the Listener Program  
z 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  
z 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.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
2-1  
 
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-2  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Running Oracle TMA TCP for CICS  
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 LINKcommand to execute the program specified in the TMA  
TCP protocol header. With the LINKcommand 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 TRANScall 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 TRANSIDcall 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/TPNOREPLYrequests, the remote program is invoked by a CICSSTART 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 BDWNto terminate active TMA TCP for CICS programs.  
Depending on the options specified, this causes all Handlers to shut down gracefully. The name  
of the BDWNtransaction may have been changed at your site during installation, so verify the  
name.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
2-3  
 
Using BDWN to Shut Down the Handler  
You can use the BDWNtransaction in a CICS region with the following parameters to shut down  
Handlers in various ways. The command line syntax for BDWNis illustrated in the following  
listing.  
Listing 2-1 BDWNCommand 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 BDWNtransaction 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 ALLalso frees any shared memory.  
This is the default for BDWN.  
CLEANUP  
Frees any shared memory of Handlers that have abended. CLEANUPdoes 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 BDWNtransaction. This  
parameter also frees any shared memory of Handlers that have abended. It does not  
shut down any Requesters.  
2-4  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Running Oracle TMA TCP for CICS  
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 RETURNcommand 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:  
z 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.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
2-5  
 
z Use the supplied shutdown transaction BDWN. This method causes ALL Requesters to shut  
down gracefully. The name of the BDWNtransaction 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 BDWNtransaction in a CICS region with the following parameters to shut down  
Requesters in various ways. The command line syntax for BDWNis illustrated in the following  
listing.  
Listing 2-2 BDWNCommand 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 BDWNtransaction 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 ALLalso 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 BDWNtransaction. It also  
frees memory associated with each LMID. This parameter does not shut down any  
Handlers.  
2-6  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Translating Data with TMA TCP gateway  
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.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
2-7  
 
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 CARRAYis 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 CARRAYis an  
exemplary buffer type for a graphics file.  
VIEW  
FML  
A VIEWbuffer 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(Fielded Manipulation Language)  
buffers are variable length, dynamic,  
self-describing buffers. Each field in the  
buffer has its own descriptive header. In  
Oracle Tuxedo, FMLbuffers can be tied  
closely to VIEWbuffers 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  
Translated from ASCII to EBCDIC (if needed)  
Translated to S9(4) COMP  
STRING and CHAR  
SHORT  
2-8  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Translating Data with TMA TCP gateway  
Table 2-2 Data Translation Rules  
Field Type  
LONG  
Translation Rules  
Translated to S9(9) COMP  
Translated to COMP-1  
Translated to COMP-2  
FLOAT  
DOUBLE  
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  
PIC X(n)  
PIC X  
Description  
View Field Type/Length  
Alpha-numeric Characters  
string / n  
Single Alpha-numeric Character char  
PIC X(n)  
PIC X  
Raw Bytes  
carray / n  
Single Numeric Byte  
16-bit Integer  
carray / 1  
short  
PIC S9(4) COMP  
PIC S9(9) COMP  
COMP-1  
32-bit Integer  
long  
Single-precision Floating Point  
float  
COMP-2  
Double-precision Floating Point double  
Packed Decimal dec_t / m,n  
PIC  
S9((m+(n+1))/2)V9  
(n)  
COMP-3  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
2-9  
 
Strings and Numeric Data: A Closer Look  
This subsection provides suggestions that help you develop VIEWdefinitions 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 VIEWdefinitions 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 CARRAYtype 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 VIEWelement.  
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 fieldswithin VIEWdefinitions.  
2-10  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
C H A P T E R  
3
Configuring the TMA TCP Security  
The TMA TCP product supports a security feature that allows a requester from Oracle Tuxedo  
services to pass a user ID through the CICS server interfaces for verification through a third-party  
security package. The following topics explain the how to set up security:  
z Service Request Processing with Security  
Security Checking from UNIX to Mainframe  
Security Checking from Mainframe to UNIX  
z Setting Up Security for TMA TCP for CICS  
Securing User Connections  
Securing Inbound Services  
Securing Outbound Connections from CICS to UNIX  
Securing Outbound Connections from CICS to CICS  
Securing Outbound Connections from CICS to IMS  
Securing Outbound Services  
Service Request Processing with Security  
The following sections describe the process flow for security verification of a service request.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
3-1  
 
Security Checking from UNIX to Mainframe  
Figure 3-1 depicts the process flow for security verifications from TMA TCP for CICS on UNIX  
to a mainframe.  
Figure 3-1 Security Checking for UNIX to Mainframe Transactions  
UNIX  
Mainframe  
3
4
2
Application  
Handler  
BEA TMA TCP  
Gateway  
Handler  
5
Remote  
Server  
Tuxedo  
Client  
1
1. When the TMA TCP gateway client program performs a tpinit(), the user’s Tuxedo  
identity is validated against the tpusrfile.  
2. When the client program issues a tpcall()or tpacall(), Tuxedo verifies (against the  
tpaclfile) the user is authorized to invoke the gateway service.  
3. When the gateway establishes the initial connection, connection security information  
(specified as RMTNAMEand PASSWORDin the GWICONFIGfile) is passed from the TMA TCP  
gateway to the remote gateway. If the RMTNAMEand PASSWORDvalues match the values  
configured on the remote gateway, the connection is established.  
With each request, the TMA TCP gateway passes the user’s Tuxedo identity to the remote  
TMA TCP for CICS gateway (to the Handler).  
Note: To pass authority checking, the user’s Tuxedo identity must match the mainframe  
user ID exactly.  
4. The remote TMA TCP for CICS gateway Handler initiates an Application Handler to act on  
behalf of the specified user ID.  
3-2  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Service Request Processing with Security  
5. The Application Handler calls the specified service using system security to check  
authorization.  
Note: You may need to update your surrogate security definitions to allow the successful  
invocation of the CICS application program (EXEC CICS START TRANSID). See your  
mainframe security administrator if your site has this requirement.  
Security Checking from Mainframe to UNIX  
Figure 3-2 depicts the process flow for security verifications from a mainframe to TMA TCP  
gateway on UNIX.  
Figure 3-2 Security Checking for Mainframe to UNIX Transactions  
UNIX  
Mainframe  
3
4
2
Remote  
Gateway  
BEA TMA TCP  
Gateway  
Tuxedo  
Server  
Client  
1
5
1. The user ID, established at mainframe log in, is checked by system security to verify that the  
user has permission to start a client transaction.  
2. The user ID is checked by system security to verify that the user has permission to send a  
request to the gateway.  
3. With each request, the gateway passes the user ID to the Tuxedo gateway.  
Note: To pass authority checking, the user’s Tuxedo identity must match the mainframe  
user ID exactly.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
3-3  
 
4. The TMA TCP gateway maps the mainframe user ID to a Tuxedo user ID and issues the  
service request on behalf of that user.  
5. The Tuxedo server performs access checks (based on the tpaclfile) to verify that the user  
has access to the requested service.  
Setting Up Security for TMA TCP for CICS  
The TMA TCP for CICS product supports enhanced security. This interface allows a requester  
from Oracle Tuxedo services to pass a User ID through the CICS server interface for  
authorization through your security package. For field definitions, refer to the “Configuring and  
Administering Oracle TMA TCP for CICS” section.  
Securing User Connections  
Complete the following tasks to enable the security feature for each connection.  
1. Specify SECURITY=Yin the Handler Configuration screen.  
2. Enter values for the ACCOUNTand PASSWORDfields in the User Connection Account screen.  
When SECURITY=Y, TMA TCP for CICS verifies the ACCOUNTand PASSWORDvalues from  
the User Connection Account match the RMTACCTand PASSWORDvalues in the TMA TCP  
gateway GWICONFIGfile *FOREIGNsection. If these values do not match and SECURITY=Y,  
a security error occurs.  
If SECURITY=N, the gateway allows a connection without any verification.  
Securing Inbound Services  
Complete the following tasks to enable the security feature for each inbound service.  
1. Set up transaction security through the mainframe with the security administrator.  
2. Specify SECURITY=Yin the Inbound Services screen for each service you want to secure.  
When SECURITY=Y, the gateway attempts to start user programs with the username that  
initiated the request as reported by the remote system.  
If SECURITY=N, the gateway starts user programs using the gateway’s user ID (as  
controlled by the socket listener).  
3-4  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Setting Up Security for TMA TCP for CICS  
Securing Outbound Connections from CICS to UNIX  
Complete the following tasks to enable the security feature for each outbound connection.  
1. Specify SECURITY=Yon the appropriate Requester screen.  
2. Enter ACCOUNTand PASSWORDvalues on the appropriate Requester screen.  
Verify that the parameter values for ACCOUNTand PASSWORDin the Requester screen match  
the RMTACCTand PASSWORDvalues in the *FOREIGNsection of the TMA TCP gateway  
GWICONFIGfile.  
When SECURITY=Y, the requester program sends the ACCOUNTand PASSWORDto the remote  
UNIX system on connection initiation. When SECURITY=N, the gateway attempts to make  
a connection without any verification.  
Securing Outbound Connections from CICS to CICS  
Complete the following tasks to enable the security feature for each outbound connection.  
1. Specify SECURITY=Yon the appropriate Requester screen.  
2. Enter ACCOUNTand PASSWORDvalues on the appropriate Requester screen.  
Verify that the parameter values for ACCOUNTand PASSWORDin the Requester screen match  
the ACCOUNTand PASSWORDvalues in the User Connection Account screen.  
When SECURITY=Y, the requester program sends the ACCOUNTand PASSWORDto the remote  
CICS system on connection initiation. When SECURITY=N, the gateway attempts to make  
a connection without any verification.  
Securing Outbound Connections from CICS to IMS  
Complete the following tasks to enable the security feature for each outbound connection.  
1. Specify SECURITY=Yon the appropriate Requester screen.  
2. Enter ACCOUNTand PASSWORDvalues on the appropriate Requester screen.  
Verify that the parameter values for ACCOUNTand PASSWORDin the Requester screen match  
the ACCOUNTand PASSWORDvalues in the GATEWAYTYPE=REMOTEstatement.  
When SECURITY=Y, the requester program sends the ACCOUNTand PASSWORDto the remote  
IMS system on connection initiation. When SECURITY=N, the gateway attempts to make a  
connection without any verification.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
3-5  
 
Securing Outbound Services  
Complete the following tasks to enable the security feature for each outbound service.  
1. Enable security for the corresponding outbound connection.  
2. Specify SECURITY=Yon the appropriate Outbound Service screen.  
3. Set up security for the appropriate users on the target system.  
3-6  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
C H A P T E R  
4
Configuring and Administering Oracle  
TMA TCP for CICS  
It is the responsibility of the Oracle Tuxedo administrator to set up the configuration file, but  
close coordination with the Oracle Tuxedo application developer and the CICS programmer is  
necessary.  
The following subsections describe the Oracle Tuxedo Mainframe Adapter for TCP (CICS)  
(hereafter referenced as TMA TCP for CICS) Maintenance System. The Oracle TMA TCP for  
CICS Maintenance System is an online CICS application for use in configuring, maintaining, and  
administering the TMA TCP for CICS gateway. The following topics explain the Maintenance  
System:  
z Menu Navigation  
z The Main Menu  
z The Connection Screens  
z The Requester Screens  
z The Outbound Service Information Screens  
z The User Connection ACCOUNT Screens  
z The Inbound Service Information Screens  
z The Handler Configuration Screens  
z Dynamically Configuring TMA TCP for CICS  
z Administering the Gateways  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-1  
 
To start the administration system, enter the transaction code as defined to CICS in the  
installation procedure. If the name was not changed during installation, the name of the  
transaction is BEAM.  
Menu Navigation  
You can access any of the following six groups of menus for maintaining connections, requesters,  
outbound services, the user connection account, inbound services, and Handler configuration.  
The following table describes how you can use each group of menus.  
Table 4-1 Menu Groups  
Menu Type  
Connection  
Requester  
Use  
To monitor and control configured and active connections  
To configure and maintain remote endpoints  
Outbound Service  
Information  
To configure each remote service and specify which  
Requester to use for each service  
User Connection Account  
To create and maintain user accounts  
Inbound Service Information To configure services residing locally that are accessed  
remotely  
Handler Configuration  
To configure and maintain the local endpoint  
Each of these topics is discussed in more detail in the following sections.  
The Main Menu  
The Main menu (BEAM) gives you access to all the maintenance screens.  
4-2  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Main Menu  
BEAPMNU  
BEA TMA 10.0 TCP FOR CICS  
SELECTION SCREEN  
BEAM M1  
TABLE  
OPERATION  
----------------  
-----------  
C - CONNECTION  
R - REQUESTER  
S - OUTBOUND SERVICE INFORMATION  
U - USER CONNECTION ACCOUNT  
I - INBOUND SERVICE INFORMATION  
H - HANDLER CONFIGURATION  
1 - INSERT  
2 - UPDATE  
3 - INQUIRE  
4 - DELETE  
5 - BROWSE  
SELECTION: __  
(e.g. R3)  
ENTER: PROCESS, PF3: EXIT  
Usage  
Use the Main menu to access the screens that make up the maintenance system. To move from  
the Main menu to a sub-menu, enter the appropriate two-character code. The first character in the  
code denotes the area in which you want to operate; the second character denotes the operation  
you want to perform on that area.  
The following table lists the codes for the areas of operation.  
Table 4-2 Main Menu (BEAM) Sub-menu Codes  
Code  
Area of Operation  
C
R
S
U
Connections  
Requesters  
Outbound Service Information  
User Connection Account  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-3  
 
Table 4-2 Main Menu (BEAM) Sub-menu Codes  
Code  
I
Area of Operation  
Inbound Service Information  
Handler Configuration  
H
The following table lists the codes for the allowable operations.  
Table 4-3 Main Menu (BEAM) Operation Codes  
Code  
Allowable Operation  
Insert  
1
2
3
4
5
Update  
Inquire  
Delete  
Browse  
Because some operations are not available in all three areas, the following table lists the valid  
combinations.  
.
Enter This Code  
To Access This Screen  
Update Connection  
Inquire Connection  
Browse Connection  
Insert Requester  
C2  
C3  
C5  
R1  
R2  
R3  
R4  
Update Requester  
Inquire Requester  
Delete Requester  
4-4  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Main Menu  
Enter This Code  
To Access This Screen  
R5  
S1  
S2  
S3  
S4  
S5  
U1  
U2  
U3  
U4  
U5  
I1  
I2  
I3  
I4  
I5  
H2  
H3  
Browse Requester  
Insert Outbound Service Information  
Update Outbound Service Information  
Inquire Outbound Service Information  
Delete Outbound Service Information  
Browse Outbound Service Information  
Insert User Connection Account  
Update User Connection Account  
Inquire User Connection Account  
Delete User Connection Account  
Browse User Connection Account  
Insert Inbound Service Information  
Update Inbound Service Information  
Inquire Inbound Service information  
Delete Inbound Service Information  
Browse Inbound Service Information  
Update Handler Configuration  
Inquire Handler Configuration  
You can use the maintenance system screens to view and alter a connection, but not to insert  
(create) or delete a connection. Connections are created and deleted by TMA TCP for CICS in  
its normal operation.  
The maintenance system checks the two-character selection code that you enter and displays the  
appropriate screen if the code is valid. If the code you enter is not valid, you receive an error  
message.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-5  
 
The Connection Screens  
The three screens available for maintaining connection instances are labeled Update, Inquiry, and  
Browse. The respective screens allow you to make an inquiry concerning a specific connection,  
to browse a list of all connections, or to disable/enable a connection.  
A connection instance is an established TCP/IP connection between a remote endpoint and a  
Requester or a Handler. For the purposes of TMA TCP for CICS, a remote endpoint is an TMA  
TCP gateway gateway executing within a remote Oracle Tuxedo domain.  
PF Keys  
The following function keys are available on various connection screens.  
Table 4-4 Function Keys  
Function Key  
ENTER  
PF3  
Definitions  
Process the selection code entered  
Transfer to Main Menu  
PF5  
Transfer to Connections Browse screen  
Display the previous page of records  
Display the next page of records  
PF7  
PF8  
Note: If you enter data and press PF3or PF5before pressing ENTER, the current operation  
process is aborted and the new screen is displayed.  
Update Connection Screen (C2)  
Use the UPDATE CONNECTIONscreen to update a record from the Connection file. When the  
screen initially displays, the LOGICAL MACHINE NAMEand TYPEfields are unprotected. Enter a  
valid LOGICAL MACHINE NAME(gateway ID) and TYPEand press ENTER. The screen re-displays  
showing the data from the record you specified and the STATUSfield is unprotected. The message  
RECORD READY FOR UPDATEdisplays. You can now make changes to the record.  
4-6  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Connection Screens  
BEAPCON  
BEA TMA 10.0 TCP FOR CICS  
UPDATE CONNECTION  
BEAM C2  
LOGICAL MACHINE NAME:  
________________  
TYPE:  
_
STATUS:  
MAX MSG SIZE:  
REQUESTER TASK NUMBER:  
NUMBER REQUESTS:  
NUMBER SUCCESS REQS:  
NUMBER RECONNECTS:  
NUMBER OPEN SOCKETS:  
NUMBER SESSIONS ACTIVE:  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
LOGICAL MACHINE  
NAME  
This field name is the gateway ID. Give it a unique name up to  
16 characters.Example: (bankmach1)  
For Requesters, this field name is the LMIDassociated with the  
service that the Requester is requesting.  
For a Handler, this field name is BEAHfollowed by the task  
number. The task number of the Handler is given in the  
BEALOG.  
TYPE  
The type of connection. Specify Ifor incoming connections or  
O for outgoing connections.  
STATUS  
The status of the connection. Specify Eto enable the connection.  
Specify Dfor normal shutdown which allows initiated tasks to  
complete prior to disconnecting. Specify Afor immediate  
shutdown which aborts all initiated tasks and disconnects.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-7  
 
Field Name  
Description  
MAX MSG SIZE  
The largest message allowed to be sent across this connection.  
The maximum is 32000. Example: (31000)  
REQUESTER TASK  
NUMBER  
The task number of the Requester that is currently associated  
with the LOGICAL MACHINE NAME. If there is not an active  
Requester, the task number is for the Requester most recently  
associated with that LMID.  
For a Handler, this field is blank; the task number is part of the  
LMID.  
NUMBER REQUESTS  
The number of service requests made during this connection.  
The number of successful communications.  
NUMBER SUCCESS  
REQS  
NUMBER RECONNECTS  
The number of successful connections.  
NUMBER OPEN  
SOCKETS  
The number of sockets that are currently opened by the  
Requester.  
NUMBER SESSIONS  
ACTIVE  
The number of active sessions on this connection.  
Inquire Connection Screen (C3)  
Use this screen to inquire about a record from the Connection file. When the screen is initially  
displayed, the LOGICAL MACHINE NAMEand TYPEfields are unprotected. Enter a valid LOGICAL  
MACHINE NAME(gateway ID) and TYPEand press ENTER. The screen is re-displayed with the data  
from the record you specified and the LOGICAL MACHINE NAMEand TYPEfields are unprotected.  
4-8  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Connection Screens  
BEAPCON  
BEA TMA 10.0 TCP FOR CICS  
INQUIRE CONNECTION  
BEAM C3  
LOGICAL MACHINE NAME:  
________________  
TYPE:  
_
STATUS:  
MAX MSG SIZE:  
REQUESTER TASK NUMBER:  
NUMBER REQUESTS:  
NUMBER SUCCESS REQS:  
NUMBER RECONNECTS:  
NUMBER OPEN SOCKETS:  
NUMBER SESSIONS ACTIVE:  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
LOGICAL MACHINE  
NAME  
This name is the gateway ID. Specify a unique name up to 16  
characters. Example: (bankmach1)  
For Requesters, this name is the LMIDassociated with the  
service that the Requester is requesting.  
For a Handler, this name is BEAHfollowed by the task number.  
The task number of the Handler is given in the BEALOG.  
TYPE  
The type of connection. Irepresents incoming connections or  
O represents outgoing connections.  
STATUS  
The status of the connection. Emeans the connection is  
enabled. Dmeans the connection is designated for a normal  
shutdown, which allows initiated tasks to complete prior to  
disconnecting. A means the connection shuts down  
immediately, aborts all initiated tasks, and disconnects.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-9  
 
Field Name  
Description  
MAX MSG SIZE  
The largest message allowed to be sent across this connection.  
The maximum is 32000. Example: (31000)  
REQUESTER TASK  
NUMBER  
The task number of the Requester that is currently associated  
with the LOGICAL MACHINE NAME. If there is not an active  
Requester, the task number is for the Requester most recently  
associated with that LMID.  
For a Handler, this field is blank; the task number is part of the  
LMID.  
NUMBER REQUESTS  
The number of service requests made during this connection.  
The number of successful communications.  
The number of successful connections.  
NUMBER SUCCESS REQS  
NUMBER RECONNECTS  
NUMBER OPEN SOCKETS  
The number of sockets that are currently opened by the  
Requester.  
NUMBER SESSIONS  
ACTIVE  
The number of active sessions on this connection.  
Browse Connection Screen (C5)  
Use this screen to browse records in the Connection file and to select individual records for  
further processing. If you access this screen from the Main menu, the first record on file is  
displayed at the top of the screen. If you access this screen from the Connection Update screen or  
the Inquire screen, the list starts with the key received from that screen.  
To select a record for processing enter a valid selection code in the SEL CDEfield. For example,  
to make an inquiry about a record, enter “3”. If you enter more than one selection code, the first  
one is used and all others are ignored. After the selection code is validated and processed, the  
screen for that process is displayed, and the record key appears in the LOGICAL MACHINE NAME  
field.  
4-10  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Requester Screens  
BEAPCON  
BEA TMA 10.0 TCP FOR CICS  
BROWSE CONNECTION  
BEAM C5  
SEL LOGICAL MACHINE STA MAXMSG NUMBER NUMBER NUMBER SOCK SESS ACT  
CDE NAME TUS SIZE REQS SUCREQ RECONS ETS IONS IVE TYPE  
--- ---------------- --- ------ ------ ------ ------ ---- ---- --- ----  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
_ ________________ _ _____ _____ _____ _____ __ __ _ _  
* SELCDE = (2: UPD, 3: INQ)  
ENTER: PROCESS, PF3: MENU, PF7: PREV, PF8: NEXT  
BEG/END OF FILE  
The Requester Screens  
A Requester is responsible for collecting request information to be sent to the remote Oracle  
Tuxedo domain. The Requester establishes network connectivity, transmits data to Oracle  
Tuxedo, and receives data from Oracle Tuxedo. Each Requester is responsible for one and only  
one remote endpoint (or one TCP/IP address/port combination). You can configure multiple  
Requesters to point to the same endpoint, but each Requester can have only one endpoint.  
On the following maintenance screens, each instance of the Requester is given a logical machine  
ID (LMID). You can give a Requester any unique LMIDthat is meaningful to you. Every service  
name is associated with one LMID. This method allows the Requester to know which remote  
machine is responsible for a particular service.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-11  
 
PF Keys  
The following table lists function keys available on various requester screens.  
Function Key  
ENTER  
PF3  
Function  
Process the selection code entered  
Transfer to Main menu  
PF5  
Transfer to Requester Browse screen  
Display the previous page of records  
Display the next page of records  
PF7  
PF8  
Note: If you enter data and press PF3or PF5before pressing ENTER, the operation process is  
aborted and the appropriate screen is displayed.  
Insert Requester Screen (R1)  
Use this screen to configure a new Requester by inserting a new record into the Requester file.  
When the screen is first displayed, all the fields are unprotected. Type the required data, then  
press ENTER. After the data is validated and processed, the screen is re-displayed and all the fields  
are unprotected.  
4-12  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Requester Screens  
BEAPREQ  
BEA TMA 10.0 TCP FOR CICS  
INSERT REQUESTER  
BEAM R1  
LMID:  
________________  
MULTIPLEX_CNT: __  
DNS: ________________________________________________________________  
HOST ADDRESS:  
PORT NUMBER:  
_______________  
_____  
MIN TIME (MILLISEC):  
MAX TIME (MILLISEC):  
_____  
_____  
SECURITY(Y/N): _  
ACCOUNT ID:  
PASSWORD:  
________  
DELTA TIME (MILLISEC): _____  
IDLE TIME (SECONDS): _____  
REQ IDLE TIME (SECONDS): _____  
LATENCY TIME (SECONDS): __  
MAX CONNS: __  
MAX QUEUE SIZE: _____  
MAX MSG SIZE:  
RETRY LIMIT:  
_____  
_____  
LMID TYPE:  
START TRAN-ID: ____  
CICS DATA: ___  
_
QUEUE NAME 1: ________  
QUEUE NAME 2: ________  
AUTO ENABLE LMID(E/D): _  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
LMID  
This name is the logical machine name or gateway ID.  
Give it a unique name up to 16 characters. Example:  
(bankmach1)  
DNS  
The host name that the domain name service recognizes.  
HOST ADDRESS  
PORT NUMBER  
The TCP/IP dot address. Example: (199.99.99.99)  
The TCP port. Check with the TCP/IP administrator for  
available ports. Example: (1234)  
SECURITY  
The status of connection-level security. Yspecifies that  
security is on and Ndenotes that security is off.  
Note: For additional security information, refer to the  
“Configuring the TMA TCP Security” section.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-13  
 
Field Name  
Description  
ACCOUNT ID  
An eight-character ID. This ID must be the same ID that is  
used on the Oracle Tuxedo-side configuration. Coordinate  
with the Oracle Tuxedo Administrator. Required if there is  
an entry in the PASSWORDfield. Example: (CICS001A)  
PASSWORD  
An eight-character password. This password must be the  
same as on the Oracle Tuxedo-side configuration.  
Coordinate with the Oracle Tuxedo Administrator.  
Required if there is an entry in the ACCOUNT IDfield.  
Example: (LETMEIN2)  
MAX QUEUE SIZE  
MAX MSG SIZE  
RETRY LIMIT  
Specifies the size of the local queue where requests are  
stored for servicing. A typical setting is 200.  
The largest message allowed to be sent across this  
connection. The maximum is 32000. Example: (4096)  
If the connection fails, this number determines how many  
attempts the system makes to reestablish the connection  
before marking the connection disabled. Example: (5).  
LMID TYPE  
The type of gateway the remote system is running (C for  
CICS, I for IMS, T for Tuxedo)  
START TRANID  
CICS DATA  
The ID of the transaction to be started if the remote system  
type is CICS.  
A string to be passed to the IBM TCP/IP Listener for use  
with the TMA TCP for CICS gateway. The default is " ".  
MULTIPLEX CNT  
MIN TIME  
The number of concurrent requests for each connection.  
The minimum length of time (in milliseconds) for a socket  
read to wait for data to be processed.  
MAX TIME  
The maximum length of time (in milliseconds) for a  
socket read to wait for data to be processed.  
DELTA TIME  
The time increase (in milliseconds) from MIN TIMEto  
MAX TIME.  
4-14  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Requester Screens  
Field Name  
Description  
IDLE TIME  
The amount of time in seconds that a connection is idle  
before it is closed. IDLE TIMEshould be a smaller  
amount of time than REQ IDLE TIME. A typical setting  
is 30 seconds.  
REQ IDLE TIME  
LATENCY TIME  
MAX CONNS  
The amount of time in seconds that a Requester is idle  
before it terminates. A typical setting is 120 seconds.  
Network time and system processing time added to give a  
true system wait time (in seconds).  
The maximum number of connections the Requester  
opens. The maximum value is 50for IBM TCP/IP.  
QUEUE NAME 1  
The unique name of a TS Q that is used for  
communications between the Pre-requester and the  
Requester.  
QUEUE NAME 2  
The unique name of a TS Q that is used for  
communications between the Pre-requester and the  
Requester.  
AUTO ENABLE LMID(E|D)  
This field is used for auto enabling of LMID. Enter E to  
automatically enable a disabled Requester LMID for  
TMA TCP for CICS gateway. Enter D to disable the  
automatic enabling of a disabled Requester LMID for  
TMA TCP for CICS gateway.  
Update Requester Screen (R2)  
Use this screen to update a record from the Requester file. The fields are the same as the ones on  
the Requester Insert screen, but on this screen you can change the values.  
When the screen is first displayed, the LMIDfield is unprotected. Enter a logical machine name  
and press ENTER. The screen is re-displayed showing the data from the requested record. The  
HOST ADDRESS, PORT NUMBER, ACCOUNT ID, PASSWORD, MAX MSG SIZE, and CONNECT RETRY  
LIMITfields are unprotected. The following message is displayed: RECORD READY FOR UPDATE.  
After the changes you entered are validated and processed, the screen is re-displayed and the  
LMIDfield is unprotected.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-15  
 
BEAPREQ  
BEA TMA 10.0 TCP FOR CICS  
UPDATE REQUESTER  
BEAM R2  
LMID:  
________________  
MULTIPLEX_CNT: __  
DNS: ________________________________________________________________  
HOST ADDRESS:  
PORT NUMBER:  
_______________  
_____  
MIN TIME (MILLISEC):  
MAX TIME (MILLISEC):  
_____  
_____  
SECURITY(Y/N): _  
ACCOUNT ID:  
PASSWORD:  
________  
DELTA TIME (MILLISEC): _____  
IDLE TIME (SECONDS): _____  
REQ IDLE TIME (SECONDS): _____  
LATENCY TIME (SECONDS): __  
MAX CONNS: __  
MAX QUEUE SIZE: _____  
MAX MSG SIZE:  
RETRY LIMIT:  
_____  
_____  
LMID TYPE:  
START TRAN-ID: ____  
CICS DATA: ___  
_
QUEUE NAME 1: ________  
QUEUE NAME 2: ________  
AUTO ENABLE LMID(E/D): _  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
LMID  
This name is the logical machine name or gateway ID. Give it a  
unique name up to 16 characters. Example: (bankmach1)  
DNS  
The host name that the Domain Name Service recognizes.  
HOST ADDRESS  
PORT NUMBER  
The TCP/IP dot address. Example: (199.99.99.99)  
The TCP port. Check with the TCP/IP administrator for available  
ports. Example: (1234)  
SECURITY  
The status of security. Yspecifies that security is on and Ndenotes  
that security is off.  
Note: For additional security information, refer to “Configuring  
the TMA TCP Security”.  
4-16  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Requester Screens  
Field Name  
Description  
ACCOUNT ID  
An eight-character ID for connection security. This ID must be the  
same ID that is used on the Oracle Tuxedo-side configuration.  
Coordinate with the Oracle Tuxedo Administrator. Required if  
there is an entry in the PASSWORDfield. Example: (CICS001A)  
PASSWORD  
An eight-character password for connection security. This  
password must be the same as on the Oracle Tuxedo-side  
configuration. Coordinate with the Oracle Tuxedo Administrator.  
Required if there is an entry in the ACCOUNT IDfield. Example:  
(LETMEIN1)  
MAX QUEUE SIZE  
MAX MSG SIZE  
RETRY LIMIT  
Specifies the size of the local queue where requests are stored for  
servicing. A typical setting is 200.  
The largest message allowed to be sent across this connection. The  
maximum is 32000. Example: (4096)  
If the connection fails, this number determines how many attempts  
the system makes to reestablish the connection before marking the  
connection disabled. Example: (5)  
LMID TYPE  
The type of gateway the remote system is running (C for CICS, I  
for IMS, T for Tuxedo)  
START TRANID  
CICS DATA  
The ID of the transaction to be started if the remote system type is  
CICS.  
A string to be passed to the IBM TCP/IP Listener for use with the  
TMA TCP for CICS gateway. The default is " ".  
MULTIPLEX CNT  
MIN TIME  
The number of concurrent requests for each connection.  
The minimum length of time (in milliseconds) for a socket read to  
wait for data to be processed.  
MAX TIME  
The maximum length of time (in milliseconds) for a socket read to  
wait for data to be processed.  
DELTA TIME  
IDLE TIME  
The time increase (in milliseconds) from MIN TIMEto MAX  
TIME.  
The amount of time in seconds that a connection is idle before it is  
closed. IDLE TIMEshould be a smaller amount of time than REQ  
IDLE TIME. A typical setting is 30 seconds.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-17  
 
Field Name  
Description  
REQ IDLE TIME  
The amount of time in seconds that a Requester is idle before it  
terminates. A typical setting is 120 seconds.  
LATENCY TIME  
MAX CONNS  
Network time and system processing time added to give a true  
system wait time (in seconds).  
The maximum number of connections the Requester opens. The  
maximum value is 50for IBM TCP/IP.  
QUEUE NAME 1  
QUEUE NAME 2  
The unique name of a TS Q that is used for communications  
between the Pre-requester and the Requester.  
The unique name of a TS Q that is used for communications  
between the Pre-requester and the Requester.  
AUTO ENABLE  
LMID(E|D)  
Enter E to automatically enable a disabled Requester LMID for  
TMA TCP for CICS gateway. Enter D to disable the automatic  
enabling of a disabled Requester LMID for TMA TCP for CICS  
gateway.  
Inquire Requester Screen (R3)  
Use this screen to make an inquiry about a record from the Requester file. The screen is initially  
displayed with the LOGICAL MACHINE NAMEfield unprotected. Enter the logical machine name  
and press ENTER. The screen is re-displayed with the data from the requested record and the  
LOGICAL MACHINE NAMEfield is unprotected.  
4-18  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Requester Screens  
BEAPREQ  
BEA TMA 10.0 TCP FOR CICS  
INQUIRE REQUESTER  
BEAM R3  
LMID:  
________________  
MULTIPLEX_CNT: __  
DNS: ________________________________________________________________  
HOST ADDRESS:  
PORT NUMBER:  
_______________  
_____  
MIN TIME (MILLISEC):  
MAX TIME (MILLISEC):  
_____  
_____  
SECURITY(Y/N): _  
ACCOUNT ID:  
PASSWORD:  
________  
DELTA TIME (MILLISEC): _____  
IDLE TIME (SECONDS): _____  
REQ IDLE TIME (SECONDS): _____  
LATENCY TIME (SECONDS): __  
MAX CONNS: __  
MAX QUEUE SIZE: _____  
MAX MSG SIZE:  
RETRY LIMIT:  
_____  
_____  
LMID TYPE:  
START TRAN-ID: ____  
CICS DATA: ___  
_
QUEUE NAME 1: ________  
QUEUE NAME 2: ________  
AUTO ENABLE LMID(E/D): _  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
LMID  
This name is the logical machine name or gateway ID. This name  
is a unique name up to 16 characters. Example: (bankmach1)  
DNS  
The host name that the domain Name Service recognizes.  
HOST ADDRESS  
PORT NUMBER  
The TCP/IP dot address. Example: (199.99.99.99)  
The TCP/IP port. Check with the TCP/IP administrator for  
available ports. Example: (1234)  
SECURITY  
The status of security. Yspecifies that security is on and Ndenotes  
that security is off.  
Note: For additional security information, refer to the  
“Configuring the TMA TCP Security” section.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-19  
 
Field Name  
Description  
ACCOUNT ID  
An eight-character ID. This ID must be the same ID that is used  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
PASSWORDfield. Example: (CICS001A)  
PASSWORD  
An eight-character password. This password must be the same as  
the password used on the Oracle Tuxedo-side configuration.  
Coordinate with the Oracle Tuxedo Administrator.  
Required if there is an entry in the ACCOUNT IDfield. Example:  
(LETMEIN1)  
MAX QUEUE SIZE  
MAX MSG SIZE  
RETRY LIMIT  
Specifies the size of the local queue where requests are stored for  
servicing. A typical setting is 200.  
The largest message allowed to be sent across this connection. The  
maximum is 32000. Example: (4096)  
If the connection fails, this number determines how many  
attempts the system makes to reestablish the connection before  
marking the connection disabled. Example: (5).  
LMID TYPE  
The type of gateway the remote system is running (C for CICS, I  
for IMS, T for Tuxedo)  
START TRANID  
CICS DATA  
The ID of the transaction to be started if the remote system type is  
CICS.  
A string to be passed to the IBM TCP/IP Listener for use with the  
TMA TCP for CICS gateway. The default is " ".  
MULTIPLEX CNT  
MIN TIME  
The number of concurrent requests for each connection.  
The minimum length of time (in milliseconds) for a socket read to  
wait for data to be processed.  
MAX TIME  
The maximum length of time (in milliseconds) for a socket read to  
wait for data to be processed.  
DELTA TIME  
IDLE TIME  
The time increase (in milliseconds) from MIN TIMEto MAX  
TIME.  
The amount of time in seconds that a connection is idle before it  
is closed. IDLE TIMEshould be a smaller amount of time than  
REQ IDLE TIME. A typical setting is 30 seconds.  
4-20  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Requester Screens  
Field Name  
Description  
REQ IDLE TIME  
The amount of time in seconds that a Requester is idle before it  
terminates. A typical setting is 120 seconds.  
LATENCY TIME  
MAX CONNS  
Network time and system processing time added to give a true  
system wait time (in seconds).  
The maximum number of connections the Requester opens. The  
maximum value is 50for IBM TCP/IP.  
QUEUE NAME 1  
QUEUE NAME 2  
The unique name of a TS Q that is used for communications  
between the Pre-requester and the Requester.  
The unique name of a TS Q that is used for communications  
between the Pre-requester and the Requester.  
AUTO ENABLE  
LMID(E|D)  
Enter E to automatically enable a disabled Requester LMID for  
TMA TCP for CICS gateway. Enter D to disable the automatic  
enabling of a disabled Requester LMID for TMA TCP for CICS  
gateway.  
Delete Requester Screen (R4)  
Use this screen to delete a record from the Requester file.  
WARNING: Deleting a Requester record can have serious ramifications. Think carefully  
before performing this operation. If there are any Service records that point to this  
GWID, any client calls to those services are rejected because Oracle TMA does not  
know to which remote machine the request should go.  
The screen is initially displayed with the LOGICAL MACHINE NAMEfield unprotected. Enter the  
logical machine name and press ENTER. The screen is then re-displayed with the data from the  
requested record and the LOGICAL MACHINE NAMEfield is protected. The following message is  
displayed: TO CONFIRM DELETE, PRESS ENTER AGAIN.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-21  
 
BEAPREQ  
BEA TMA 10.0 TCP FOR CICS  
DELETE REQUESTER  
BEAM R4  
LMID:  
________________  
MULTIPLEX_CNT: __  
DNS: ________________________________________________________________  
HOST ADDRESS:  
PORT NUMBER:  
_______________  
_____  
MIN TIME (MILLISEC):  
MAX TIME (MILLISEC):  
_____  
_____  
SECURITY(Y/N): _  
ACCOUNT ID:  
PASSWORD:  
________  
DELTA TIME (MILLISEC): _____  
IDLE TIME (SECONDS): _____  
REQ IDLE TIME (SECONDS): _____  
LATENCY TIME (SECONDS): __  
MAX CONNS: __  
MAX QUEUE SIZE: _____  
MAX MSG SIZE:  
RETRY LIMIT:  
_____  
_____  
LMID TYPE:  
START TRAN-ID: ____  
CICS DATA: ___  
_
QUEUE NAME 1: ________  
QUEUE NAME 2: ________  
AUTO ENABLE LMID(E/D): _  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
LMID  
This name is the logical machine name or gateway ID.  
This name is a unique name up to 16 characters. Example:  
(bankmach1)  
DNS  
The host name that the domain Name Service recognizes.  
HOST ADDRESS  
PORT NUMBER  
The TCP/IP dot address. Example: (199.99.99.99)  
The TCP/IP port. Check with the TCP/IP administrator  
for available ports. Example: (1234)  
SECURITY  
The status of security. Yspecifies that security is on and N  
denotes that security is off.  
Note: For additional security information, refer to the  
“Configuring the TMA TCP Security” section.  
4-22  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Requester Screens  
Field Name  
Description  
ACCOUNT ID  
An eight-character ID. This name must be the same ID  
that is used on the Oracle Tuxedo-side configuration.  
Coordinate with the Oracle Tuxedo Administrator.  
Required if there is an entry in the PASSWORDfield.  
Example: (CICS001A)  
PASSWORD  
An eight-character password. This password must be the  
same as on the Oracle Tuxedo-side configuration.  
Coordinate with the Oracle Tuxedo Administrator.  
Required if there is an entry in the ACCOUNT IDfield.  
Example: (LETMEIN1)  
MAX QUEUE SIZE  
MAX MSG SIZE  
RETRY LIMIT  
Specifies the size of the local queue where requests are  
stored for servicing. A typical setting is 200.  
The largest message allowed to be sent across this  
connection. The maximum is 32000. Example: (4096)  
If the connection fails, this number determines how many  
attempts the system makes to reestablish the connection  
before marking the connection disabled. Example: (5).  
LMID TYPE  
The type of gateway the remote system is running (C for  
CICS, I for IMS, T for Tuxedo)  
START TRANID  
CICS DATA  
The ID of the transaction to be started if the remote system  
type is CICS.  
A string to be passed to the IBM TCP/IP Listener for use  
with the TMA TCP for CICS gateway. The default is " ".  
MULTIPLEX CNT  
MIN TIME  
The number of concurrent requests for each connection.  
The minimum length of time (in milliseconds) for a socket  
read to wait for data to be processed.  
MAX TIME  
The maximum length of time (in milliseconds) for a  
socket read to wait for data to be processed.  
DELTA TIME  
The time increase (in milliseconds) from MIN TIMEto  
MAX TIME.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-23  
 
Field Name  
Description  
IDLE TIME  
The amount of time in seconds that a connection is idle  
before it is closed. IDLE TIMEshould be a smaller  
amount of time than REQ IDLE TIME. A typical setting  
is 30 seconds.  
REQ IDLE TIME  
LATENCY TIME  
MAX CONNS  
The amount of time in seconds that a Requester is idle  
before it terminates. A typical setting is 120 seconds.  
Network time and system processing time added to give a  
true system wait time (in seconds).  
The maximum number of connections the Requester  
opens. The maximum value is 50for IBM TCP/IP.  
QUEUE NAME 1  
The unique name of a TS Q that is used for  
communications between the Pre-requester and the  
Requester.  
QUEUE NAME 2  
The unique name of a TS Q that is used for  
communications between the Pre-requester and the  
Requester.  
AUTO ENABLE LMID(E|D)  
Enter E to automatically enable a disabled Requester  
LMID for TMA TCP for CICS gateway. Enter D to  
disable the automatic enabling of a disabled Requester  
LMID for TMA TCP for CICS gateway.  
Browse Requester Screen (R5)  
Use this screen to browse a list of the records in the Requester file. Additionally, you can select  
a record for further processing by entering a valid selection code in the first column of that  
record’s row.  
If you access this screen from the Main menu, the first record on file is displayed at the top of the  
screen. If you access this screen from the Insert, Update, Inquire, or Delete screens, the key  
received from that screen determines which records are displayed.  
To choose a record, enter a valid selection code in the SEL CDEfield next to that record. For  
example, to make an inquiry about a record, enter “3”. If you enter more than one selection code,  
the first one is used and the others are ignored.  
4-24  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Outbound Service Information Screens  
After the entry in the SEL CDEfield is validated and processed, the screen for that process is  
displayed and the record key appears in the LOGICAL MACHINE NAMEfield.  
BEAPREQ  
BEA TMA 10.0 TCP FOR CICS  
BROWSE REQUESTER  
BEAM R5  
SEL LOGICAL MACHINE  
HOST  
ADDRESS  
PORT MAXM CONN LMID START  
NUM SIZE R-LIM TYPE TRNID  
CDE  
NAME  
--- ---------------- --------------- ----- ----- ----- ---- -----  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
_ ________________ _______________ _____ _____ _____ _ ____  
* SELCDE = (1: INS, 2: UPD, 3: INQ, 4: DEL)  
ENTER: PROCESS, PF3: MENU, PF7: PREV, PF8: NEXT  
RECORD NOT FOUND  
The Outbound Service Information Screens  
A service is a name associated with some component of work. That component of work might be  
a banking transaction, an airline flight reservation, or an order for a dozen widgets. In Oracle  
Tuxedo, a client program that needs work done makes a service request.” A process called a  
server performs the work described in the service request on behalf of the client, then returns the  
results of its efforts back to the client. In MVS this process would be referred to as a call to a  
“black box.”  
In a CICS application that uses TMA TCP for CICS, a service name is passed in the data area in  
an EXEC CICS LINKcommand and the results are returned in that same area. The service screens  
use the terms “service name” and “remote service name.” The service name (such as,  
CIC01XXYYZZ) is what the service is known as to your CICS environment and the remote service  
name (such as, WITHDRAWL) is what the service is known as to Oracle Tuxedo. For simplicity, you  
can make both names the same, but if naming conventions differ, you can use different names.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-25  
 
PF Keys  
The following table lists function keys available on various outbound service screens.  
Table 4-5 Function Keys  
Function Key  
ENTER  
PF3  
Function  
Process the selection code entered  
Transfer to Main menu  
PF5  
Transfer to Browse screen  
Display the previous page of records  
Display the next page of records  
PF7  
PF8  
Note: If you enter data and press PF3or PF5before pressing ENTER, the operation process is  
aborted and the appropriate screen is displayed.  
Insert Outbound Service Information Screen (S1)  
Use this screen to insert a record into the service name file. The screen is first displayed with all  
fields unprotected. Enter the required data in the appropriate fields and press ENTER. After the  
data is validated and processed, the screen is re-displayed and all the fields are unprotected.  
4-26  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Outbound Service Information Screens  
BEAPSVC  
BEA TMA 10.0 TCP FOR CICS  
INSERT OUTBOUND SERVICE INFORMATION  
BEAM S1  
SERVICE NAME:  
________________  
LOGICAL MACHINE NAME: ________________  
REMOTE SERVICE NAME: ________________  
SERVICE TIMEOUT(SEC): _____  
SECURITY(Y/N):  
_
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
SERVICE NAME  
The service name as it is known to the CICS programmer.  
LOGICAL MACHINE  
NAME  
This name is a symbolic name as it was defined on the Requester  
Insert screen. It denotes the remote machine on which this  
service should be processed.  
REMOTE SERVICE  
NAME  
The name as it is known in the remote Oracle Tuxedo domain.  
SERVICE TIMEOUT  
SECURITY  
The number of seconds to wait for timing out this service request.  
The status of request-level security. Yspecifies that security is on  
and Ndenotes that security is off.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-27  
 
Update Outbound Service Information Screen (S2)  
Use this screen to update a record from the service name file. When the screen is first displayed,  
the SERVICE NAMEfield is unprotected. Enter the service name and press ENTER. The screen is  
then re-displayed with the data from the requested record and the LOGICAL MACHINE NAME,  
REMOTE SERVICE NAME, SERVICE TIMEOUT(SEC), and SECURITYfields are unprotected. The  
following message is displayed: RECORD READY FOR UPDATE.  
After the changes are validated and processed, the screen is re-displayed and the SERVICE NAME  
field is unprotected.  
BEAPSVC  
BEA TMA 10.0 TCP FOR CICS  
BEAM S2  
UPDATE OUTBOUND SERVICE INFORMATION  
SERVICE NAME:  
________________  
LOGICAL MACHINE NAME: ________________  
REMOTE SERVICE NAME: ________________  
SERVICE TIMEOUT(SEC): _____  
SECURITY(Y/N):  
_
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
SERVICE NAME  
The service name as it is known to the CICS programmer.  
LOGICAL MACHINE  
NAME  
This name is a symbolic name as it was defined on the Update  
Outbound Service Information screen. It denotes the remote  
machine on which this service should be processed.  
4-28  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Outbound Service Information Screens  
Field Name  
Description  
REMOTE SERVICE  
NAME  
The name as it is known in the remote Oracle Tuxedo domain.  
SERVICE TIMEOUT  
SECURITY  
The number of seconds to wait for timing out this service request.  
The status of security. Yspecifies that security is on and N  
denotes that security is off.  
Inquire Outbound Service Information Screen (S3)  
Use this screen to make an inquiry about a record from the SERVICE NAMEfile. The screen is  
initially displayed with the SERVICE NAMEfield unprotected. Enter the service name and press  
ENTER. The screen is re-displayed with the data from the requested record and the SERVICE NAME  
field is unprotected.  
BEAPSVC  
BEA TMA 10.0 TCP FOR CICS  
BEAM S3  
INQUIRE OUTBOUND SERVICE INFORMATION  
SERVICE NAME:  
________________  
LOGICAL MACHINE NAME: ________________  
REMOTE SERVICE NAME: ________________  
SERVICE TIMEOUT(SEC): _____  
SECURITY(Y/N):  
_
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-29  
 
Fields  
Field Name  
Description  
SERVICE NAME  
The service name as it is known to the CICS programmer.  
LOGICAL MACHINE  
NAME  
This name is a symbolic name as it was defined on the Inquire  
Outbound Service Information screen. It denotes the remote  
machine on which this service should be processed.  
REMOTE SERVICE  
NAME  
The name as it is known in the remote Oracle Tuxedo domain.  
SERVICE TIMEOUT  
SECURITY  
The number of seconds to wait for timing out this service request.  
The status of security. Yspecifies that security is on and Ndenotes  
that security is off.  
Delete Outbound Service Information Screen (S4)  
Use this screen to delete records from the service name file. The screen is initially displayed with  
the SERVICE NAMEfield unprotected. Type the service name and press ENTER. The screen is  
re-displayed with the data from the record requested and all the fields protected.  
The following message is displayed: TO CONFIRM DELETE, PRESS ENTER: AGAIN. After you  
press enter to confirm the deletion, the screen is re-displayed and the SERVICE NAMEfield is  
unprotected.  
4-30  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Outbound Service Information Screens  
BEAPSVC  
BEA TMA 10.0 TCP FOR CICS  
DELETE OUTBOUND SERVICE INFORMATION  
BEAM S4  
SERVICE NAME:  
________________  
LOGICAL MACHINE NAME: ________________  
REMOTE SERVICE NAME: ________________  
SERVICE TIMEOUT(SEC): _____  
SECURITY(Y/N):  
_
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
SERVICE NAME  
The service name as it is known to the CICS programmer.  
LOGICAL MACHINE  
NAME  
This name is a symbolic name as it was defined on the Delete  
Outbound Service Information screen. It denotes the remote  
machine on which this service should be processed.  
REMOTE SERVICE  
NAME  
The name as it is known in the remote Oracle Tuxedo domain.  
SERVICE TIMEOUT  
SECURITY  
The number of seconds to wait for timing out this service request.  
The status of security. Yspecifies that security is on and Ndenotes  
that security is off.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-31  
 
Browse Outbound Service Information Screen (S5)  
Use this screen to browse the records in the service name file. If you access this screen from the  
Main menu the first record on file is displayed at the top of the screen. If you access this screen  
from the Insert, Update, Inquire, or Delete screens, the list starts with the record key received  
from that screen.  
To select a record for processing, enter a valid selection code. For example, to make an inquiry  
about a record, enter “3”. If you enter more than one selection code, the first one is used, and the  
others are ignored. After the selection code is validated and processed, the screen for that process  
is displayed and the record key appears in the SERVICE NAMEfield.  
BEAPSVC  
BEA TMA 10.0 TCP FOR CICS  
BROWSE SERVICE NAME  
BEAM S5  
SEL  
CDE  
SERVICE  
NAME  
LOGICAL MACHINE  
NAME  
REMOTE SERVICE SERVICE  
NAME TIMEOUT  
SEC  
---  
--- ---------------- ---------------- ---------------- -------  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_ ________________ ________________ ________________  
_____  
_____  
_____  
_____  
_____  
_____  
_____  
_____  
_____  
_____  
_
_
_
_
_
_
_
_
_
_
* SELCDE = (1 -INS, 2 -UPD, 3 -INQ, 4 -DEL)  
ENTER: PROCESS, PF3: MENU, PF7: PREV, PF8: NEXT  
RECORD NOT FOUND  
The User Connection ACCOUNT Screens  
A Handler is responsible for receiving service requests from the remote Oracle Tuxedo domain.  
The User Connection ACCOUNTscreens allow for dynamic manipulation of accounts allowed to  
connect with a Handler when a Handler is configured with security enabled.  
4-32  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The User Connection ACCOUNT Screens  
PF Keys  
The following table lists function keys available on various user account screens.  
Table 4-6 Function Keys  
Function Key  
ENTER  
PF3  
Function  
Process the selection code entered  
Transfer to Main menu  
PF5  
Transfer to Browse screen  
Display the previous page of records  
Display the next page of records  
PF7  
PF8  
Note: If you enter data and press PF3or PF5before pressing ENTER, the operation process is  
aborted and the appropriate screen is displayed.  
Insert User Connection ACCOUNT Screen (U1)  
Use this screen to add a new Connection ACCOUNTby inserting a new record into the user file.  
When the screen is first displayed, all the fields are unprotected. Type the required data as  
described in the table below, then press ENTER. After the data is validated and processed, the  
screen is re-displayed and all the fields are unprotected.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-33  
 
BEAPUSR  
BEA TMA 10.0 TCP FOR CICS  
BEAM U1  
INSERT USER CONNECTION ACCOUNT  
ACCOUNT:  
________  
________  
PASSWORD:  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
ACCOUNT  
An eight-character ID. This name must be the same ID that is used  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
PASSWORDfield. Example: (CICS001A)  
PASSWORD  
An eight-character password. This password must be the same as  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
ACCOUNT IDfield. Example: (LETMEIN1)  
Update User Connection ACCOUNT Screen (U2)  
Use this screen to update a record on the account file. When the screen is first displayed, the  
ACCOUNTfield is unprotected. Enter the account ID, and press ENTER. The screen is then  
re-displayed with the data from the requested record and the PASSWORDfield is unprotected. The  
following message is displayed: RECORD READY FOR UPDATE.  
4-34  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The User Connection ACCOUNT Screens  
After the changes are validated and processed, the screen is re-displayed and the ACCOUNTfield  
is unprotected.  
BEAPUSR  
BEA TMA 10.0 TCP FOR CICS  
BEAM U2  
UPDATE USER CONNECTION ACCOUNT  
ACCOUNT:  
________  
________  
PASSWORD:  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
ACCOUNT  
An eight-character ID. This name must be the same ID that is used  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
PASSWORDfield. Example: (CICS001A)  
PASSWORD  
An eight-character password. This password must be the same as  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
ACCOUNT IDfield. Example: (LETMEIN1)  
Inquire User Connection ACCOUNT Screen (U3)  
Use this screen to make an inquiry about a record from the account file. The screen is initially  
displayed with the ACCOUNTfield unprotected. Enter the ACCOUNTand press ENTER. The screen  
is re-displayed with the data from the requested record and the ACCOUNTfield is unprotected.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-35  
 
BEAPUSR  
BEA TMA 10.0 TCP FOR CICS  
BEAM U3  
INQUIRE USER CONNECTION ACCOUNT  
ACCOUNT:  
________  
________  
PASSWORD:  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
ACCOUNT  
An eight-character ID. This name must be the same ID that is used  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
PASSWORDfield. Example: (CICS001A)  
PASSWORD  
An eight-character password. This password must be the same as  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
ACCOUNT IDfield. Example: (LETMEIN1)  
Delete User Connection ACCOUNT Screen (U4)  
Use this screen to delete a record from the account file. The screen is initially displayed with the  
ACCOUNTfield unprotected. Type the service name and press ENTER. The screen is re-displayed  
with the data from the record requested and all the fields protected.  
4-36  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The User Connection ACCOUNT Screens  
The following message is displayed: TO CONFIRM DELETE, PRESS ENTER: AGAIN. After you  
press enter to confirm the deletion, the screen is re-displayed and the ACCOUNTfield is  
unprotected.  
BEAPUSR  
BEA TMA 10.0 TCP FOR CICS  
BEAM U4  
DELETE USER CONNECTION ACCOUNT  
ACCOUNT:  
________  
________  
PASSWORD:  
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
ACCOUNT  
An eight-character ID. This name must be the same ID that is used  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
PASSWORDfield. Example: (CICS001A)  
PASSWORD  
An eight-character password. This password must be the same as  
on the Oracle Tuxedo-side configuration. Coordinate with the  
Oracle Tuxedo Administrator. Required if there is an entry in the  
ACCOUNT IDfield. Example: (LETMEIN1)  
The Browse User Connection ACCOUNT Screen (U5)  
Use this screen to browse the records in the account file. If you access this screen from the Main  
menu the first record on file is displayed at the top of the screen. If you access this screen from  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-37  
 
the Insert, Update, Inquire, or Delete screens, the list starts with the record key received from that  
screen.  
To select a record for processing, enter a valid selection code. For example, to make an inquiry  
about a record, enter “3”. If you enter more than one selection code, the first one is used, and the  
others are ignored.  
BEAPUSR  
BEA TMA 10.0 TCP FOR CICS  
BEAM U5  
BROWSE USER CONNECTION ACCOUNTS  
SEL  
CDE  
ACCOUNT  
-----  
----------  
_
_
_
_
_
_
_
_
_
_
________  
________  
________  
________  
________  
________  
________  
________  
________  
________  
* SELCDE = (1: INS, 2: UPD, 3: INQ, 4: DEL)  
ENTER: PROCESS, PF3: MENU, PF7: PREV, PF8: NEXT  
BEG/END OF FILE  
The Inbound Service Information Screens  
A service is a name associated with some component of work. That component of work can be a  
banking transaction, an airline flight reservation, or an order for a dozen widgets. In Oracle  
Tuxedo, a client program that needs work done makes a service request. A server performs the  
work described in the service request on behalf of the client, then returns the results of its efforts  
back to the client. In MVS this would be referred to as a call to a “black box.”  
The service screens use the terms LOCAL SERVICE NAMEand REMOTE SERVICE NAME. The  
LOCAL SERVICE NAME (such as, CIC01XXYYZZ) is what the service is known as to your CICS  
environment and the REMOTE SERVICE NAME(such as, WITHDRAWL) is what the service is known  
4-38  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Inbound Service Information Screens  
as to Oracle Tuxedo. For simplicity, you can make both names the same; however, different  
names can be used. Changes to the inbound service file are only picked up when the Handler is  
restarted.  
PF Keys  
The following table lists function keys available on various inbound service screens.  
Table 4-7 Function Keys  
Function Key  
ENTER  
PF3  
Function  
Process the data entered  
Transfer to Main menu  
Transfer to Browse screen  
Display the previous page of records  
Display the next page of records  
PF5  
PF7  
PF8  
Note: If you enter data and press PF3or PF5before pressing ENTER, the operation process is  
aborted and the appropriate screen is displayed.  
Insert Inbound Service Information Screen (I1)  
Use this screen to insert a record into the service name file. The screen is first displayed with all  
fields unprotected. Enter the required data in the following fields and press ENTER. After the data  
is validated and processed, the screen is re-displayed and all the fields are unprotected.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-39  
 
BEAPISN  
BEA TMA 10.0 TCP FOR CICS  
BEAM I1  
INSERT INBOUND SERVICE INFORMATION  
REMOTE SERVICE NAME: ________________  
LOCAL SERVICE NAME:  
TRANSACTION NAME:  
MAX MESSAGE SIZE:  
SECURITY (Y/N):  
________________  
____  
_____  
_
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
REMOTE SERVICE  
NAME  
The service name as it is known in the remote Oracle Tuxedo  
domain.  
LOCAL SERVICE  
NAME  
The service name as it is known to the CICS programmer.  
4-40  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Inbound Service Information Screens  
Field Name  
Description  
TRANSACTION NAME  
The name of the CICS transaction that is started to process this  
service request. This transaction is usually the transaction for the  
Application Handler program which is BEAAby default.  
For information about programming services without a reply, refer  
to the “Programming Oracle Tuxedo Mainframe Adapter for TCP  
(CICS)” section.  
Note: Services sending requests using a tpacallwith the  
TPNOREPLYflag set must have a unique TRANSACTION  
NAMEassociated with it. Do not use the TRANSACTION  
NAMEfor the Application Handler program or an error  
message results.  
MAX MESSAGE SIZE  
SECURITY  
The largest message allowed to be sent across this connection. The  
maximum is 32000. This size is the size of the actual data; TMA  
TCP manages additional message size through its internal headers.  
The status of security. Yenables security for the specified service  
and Ndisables security for the specified service.  
Update Inbound Service Information Screen (I2)  
Use this screen to update a record in the inbound service name file. The screen is first displayed  
with the REMOTE SERVICE NAMEfield unprotected. Enter the remote service name and press  
ENTER. The screen is re-displayed with the data from the requested record and the LOCAL  
SERVICE NAME, TRANSACTION NAME, MAX MESSAGE SIZE, and SECURITYfields unprotected.  
The following message displays: RECORD READY FOR UPDATE.  
After the changes are validated and processed, the screen is re-displayed and the REMOTE  
SERVICE NAMEfield is unprotected.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-41  
 
BEAPISN  
BEA TMA 10.0 TCP FOR CICS  
BEAM I2  
UPDATE INBOUND SERVICE INFORMATION  
REMOTE SERVICE NAME: ________________  
LOCAL SERVICE NAME:  
TRANSACTION NAME:  
MAX MESSAGE SIZE:  
SECURITY (Y/N):  
________________  
____  
_____  
_
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
REMOTE SERVICE  
NAME  
The service name as it is known in the remote Oracle Tuxedo  
domain.  
LOCAL SERVICE  
NAME  
The service name as it is known to the CICS programmer.  
4-42  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Inbound Service Information Screens  
Field Name  
Description  
TRANSACTION NAME  
The name of the CICS transaction that is started to process this  
service request. This transaction is usually the transaction for the  
Application Handler program which is BEAAby default.  
For information about programming services without a reply,  
refer to the “Programming Oracle Tuxedo Mainframe Adapter for  
TCP (CICS)” section.  
Note: Services sending requests using a tpacallwith the  
TPNOREPLYflag set must have a unique TRANSACTION  
NAMEassociated with it. Do not use the TRANSACTION  
NAMEfor the Application Handler program or an error  
message results.  
MAX MESSAGE SIZE  
SECURITY  
The largest message allowed to be sent across this connection. The  
maximum is 32000. This is the size of the actual data; TMA TCP  
manages additional message size through its internal headers.  
The status of security. Yenables security for the specified service  
and Ndisables security for the specified service.  
Inquire Inbound Service Information Screen (I3)  
Use this screen to inquire about a record in the inbound service name file. The screen is first  
displayed with the REMOTE SERVICE NAMEfield unprotected. Enter the remote service name and  
press ENTER. The screen is re-displayed with the data from the requested record and the REMOTE  
SERVICE NAMEfield unprotected.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-43  
 
BEAPISN  
BEA TMA 10.0 TCP FOR CICS  
BEAM I3  
INQUIRE INBOUND SERVICE INFORMATION  
REMOTE SERVICE NAME: ________________  
LOCAL SERVICE NAME:  
TRANSACTION NAME:  
MAX MESSAGE SIZE:  
SECURITY (Y/N):  
________________  
____  
_____  
_
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
REMOTE SERVICE  
NAME  
The service name as it is known in the remote Oracle Tuxedo  
domain.  
LOCAL SERVICE  
NAME  
The service name as it is known to the CICS programmer.  
4-44  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Inbound Service Information Screens  
Field Name  
Description  
TRANSACTION NAME  
The name of the CICS transaction that is started to process this  
service request. This transaction is usually the transaction for the  
Application Handler program which is BEAAby default.  
For information about programming services without a reply, refer  
to the “Programming Oracle Tuxedo Mainframe Adapter for TCP  
(CICS)” section.  
Note: Services sending requests using a tpacallwith the  
TPNOREPLYflag set must have a unique TRANSACTION  
NAMEassociated with it. Do not use the TRANSACTION  
NAMEfor the Application Handler program or an error  
message results.  
MAX MESSAGE SIZE  
SECURITY  
The largest message allowed to be sent across this connection. The  
maximum is 32000. This is the size of the actual data; TMA TCP  
manages additional message size through its internal headers.  
The status of security. Yspecifies that security is on and Ndenotes  
that security is off.  
Delete Inbound Service Information Screen (I4)  
Use this screen to delete a record in the inbound service name file. The screen is first displayed  
with the REMOTE SERVICE NAMEfield unprotected. Enter the remote service name and press  
ENTER. The screen is re-displayed with the data from the record requested and all fields protected.  
The following message displays: TO CONFIRM DELETE, PRESS ENTER AGAIN. After you press  
ENTERto confirm the deletion, the screen is re-displayed and the REMOTE SERVICE NAMEfield  
is unprotected.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-45  
 
BEAPISN  
BEA TMA 10.0 TCP FOR CICS  
BEAM I4  
DELETE INBOUND SERVICE INFORMATION  
REMOTE SERVICE NAME: ________________  
LOCAL SERVICE NAME:  
TRANSACTION NAME:  
MAX MESSAGE SIZE:  
SECURITY (Y/N):  
________________  
____  
_____  
_
ENTER: PROCESS, PF3: MENU, PF5: BROWSE  
Fields  
Field Name  
Description  
REMOTE SERVICE  
NAME  
The service name as it is known in the remote Oracle Tuxedo  
domain.  
LOCAL SERVICE  
NAME  
The service name as it is known to the CICS programmer.  
4-46  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Inbound Service Information Screens  
Field Name  
Description  
TRANSACTION NAME  
The name of the CICS transaction that is started to process this  
service request. This service request is usually the transaction for  
the Application Handler program. For information about  
programming services without a reply, refer to the “Programming  
Oracle Tuxedo Mainframe Adapter for TCP (CICS)” section.  
WARNING: Services sending requests using a tpacall  
with the TPNOREPLYflag set must have a  
unique TRANSACTION NAMEassociated with  
it. Do not use the TRANSACTION NAMEfor  
the Application Handler program or an error  
message results.  
MAX MESSAGE SIZE  
SECURITY  
The largest message allowed to be sent across this connection. The  
maximum is 32000. This is the size of the actual data; TMA TCP  
manages additional message size through its internal headers.  
The status of security. Yspecifies that security is on and Ndenotes  
that security is off.  
The Browse Inbound Service Screen (I5)  
Use this screen to browse the records in the inbound service name file. If you access this screen  
from the Main menu, the first record on file is displayed at the top of the screen. If you access this  
screen from the Insert, Update, Inquire, or Delete screens, the list starts with the record key  
received from that screen.  
To select a record for processing, enter a valid selection code. For example, to make an inquiry  
about a record, enter “3”. If you enter more than one selection code, the first one is used, and the  
others are ignored. After the selection code is validated and processed, the screen for that process  
is displayed and the record key appears in the REMOTE SERVICE NAMEfield.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-47  
 
BEAPISN  
BEA TMA 10.0 TCP FOR CICS  
BROWSE INBOUND SERVICE  
BEAM I5  
SEL REMOTE SERVICE  
LOCAL SERVICE  
NAME  
TRAN MAXM  
NAME SIZE SEC  
CDE  
NAME  
--- ---------------- ---------------- ---- ----- ---  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
_ ________________ ________________ ____ _____ _  
* SELCDE = (1 -INS, 2 -UPD, 3 -INQ, 4 -DEL)  
ENTER: PROCESS, PF3: MENU, PF7: PREV, PF8: NEXT  
RECORD NOT FOUND  
The Handler Configuration Screens  
A Handler is responsible for receiving service requests from the remote Oracle Tuxedo domain.  
The Handler Configuration screens allow for dynamic manipulation of the configuration used by  
all Handler programs in the system.  
Note: To apply changes that have been made to the Handler Configuration file, you must restart  
the Handler.  
PF Keys  
The following table lists the function keys available on various user account screens.  
4-48  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Handler Configuration Screens  
Table 4-8 Function Keys  
Function Key  
ENTER  
Function  
Process the data entered  
Transfer to Main menu  
PF3  
Note: If you enter data and press PF3before pressing ENTER, the operation process is aborted  
and the appropriate screen is displayed.  
Update Handler Configuration Screen (H2)  
Use this screen to update the configuration record on the user file. If a record does not exist, one  
is inserted into the user file. When the screen first displays, all fields are unprotected. After the  
changes are validated and processed, the screen is re-displayed.  
BEAPUSR  
BEA TMA 10.0 TCP FOR CICS  
BEAM H2  
UPDATE HANDLER CONFIGURATION  
SECURITY:  
Y
99  
20  
30  
5
MULTIPLEX COUNT:  
MIN TIME (MILLISECS):  
MAX TIME (MILLISECS):  
DELTA TIME (MILLISECS):  
IDLE TIME (SECONDS):  
0
ENTER: PROCESS, PF3: MENU  
UPDATE COMPLETED  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-49  
 
Fields  
Field Name  
Description  
SECURITY  
The status of gateway security. Ydenotes that security is activated  
and Ndenotes that security is not activated. If this field is set to N,  
the ACCOUNTand PASSWORDfields are not verified prior to  
establishing a connection.  
MULTIPLEX CNT  
MIN TIME  
The number of concurrent incoming service requests for each  
Handler.  
The minimum length of time (in milliseconds) for a socket read to  
wait for data to be processed.  
MAX TIME  
The maximum length of time (in milliseconds) for a socket read to  
wait for data to be processed.  
DELTA TIME  
IDLE TIME  
The time increase (in milliseconds) from MIN TIMEto MAX  
TIME.  
The amount of time in seconds a Handler is idle before it  
terminates.  
Inquire Handler Configuration Screen (H3)  
Use this screen to make an inquiry about the configuration record from the user file. The screen  
is displayed with the data from the requested record and all fields are protected.  
4-50  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
The Handler Configuration Screens  
BEAPUSR  
BEA TMA 10.0 TCP FOR CICS  
INQUIRE HANDLER CONFIGURATION  
BEAM H3  
SECURITY:  
Y
99  
20  
30  
5
MULTIPLEX COUNT:  
MIN TIME (MILLISECS):  
MAX TIME (MILLISECS):  
DELTA TIME (MILLISECS):  
IDLE TIME (SECONDS):  
0
ENTER: PROCESS, PF3: MENU  
Fields  
Field Name  
Description  
SECURITY  
The status of gateway security. Ydenotes that security is activated  
and Ndenotes that security is not activated. If this field is set to N,  
the ACCOUNTand PASSWORDfields are not verified prior to  
establishing a connection.  
MULTIPLEX CNT  
MIN TIME  
The number of concurrent incoming service requests for each  
Handler.  
The minimum length of time (in milliseconds) for a socket read to  
wait for data to be processed.  
MAX TIME  
The maximum length of time (in milliseconds) for a socket read to  
wait for data to be processed.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-51  
 
Field Name  
Description  
DELTA TIME  
The time increase (in milliseconds) from MIN TIME to MAX  
TIME.  
IDLE TIME  
The amount of time in seconds a program is idle before it  
terminates.  
Dynamically Configuring TMA TCP for CICS  
Dynamic configuration means that new configuration information affects currently running  
Handlers or Requesters without shutting them down. The new configuration information also  
affects Handlers and Requesters that are started after the information is entered. You can make  
the following changes to the TMA TCP for CICS gateway configuration dynamically:  
z Modifying Outbound Services  
z Modifying User Connection Accounts  
z Modifying Connections  
z Deleting Requester LMIDs  
All other configuration tasks are not dynamic, including Inbound Service Information and  
Handler Configuration. To process configuration information in these cases, the corresponding  
Requesters and Handlers must be shut down.  
Modifying Outbound Services  
You can dynamically configure outbound services by inserting a new record into the service  
name file, modifying an existing record in the service name file, or deleting a record in the service  
name file. Use the appropriate maintenance screens to accomplish the necessary task, S1 to insert,  
S2 to update, or S4 to delete. For field definitions, refer to the “The Outbound Service  
Information Screens” section.  
Modifying User Connection Accounts  
You can dynamically configure User Connection Accounts and enable accounts to connect to  
Handlers by inserting a new account into the user account file, modifying an existing user  
account, or deleting a user account. Use the appropriate maintenance screens to accomplish the  
4-52  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Administering the Gateways  
necessary task, U1 to insert, U2 to update, or U4 to delete. For field definitions, refer to the “The  
User Connection ACCOUNT Screens” section.  
Note: Changes to the User Connection Accounts do not affect Handlers that are currently  
connected, but only Handlers that connect after the change is made.  
Modifying Connections  
You can dynamically configure the status of a connection. Using the Update Connection screen  
(C2), you can enable, disable, or abort the connection for a given LMID. Dynamically configuring  
the status of a connection has an immediate effect on the corresponding Requesters. For field  
definitions, refer to the “The Connection Screens” section.  
Note: Because the data in the Update Connection screen is transient, setting the LMIDstatus to  
disable does not persist after the CICS region is shut down and then restarted. The  
Requester file, however, is persistent.  
Deleting Requester LMIDs  
Each instance of the Requester is given a logical machine name (LMID). You can give a Requester  
any unique LMIDthat is meaningful to you. Every service name is associated with one or more  
LMIDs. This method allows the Requester to identify which remote machine is responsible for a  
particular service. You can dynamically delete an LMIDusing the Update Requester screen (R2).  
This dynamic change only affect Pre-requesters immediately.  
Note: Requesters that are currently running do not read the information in the requester file and  
are not affected by this dynamic change.  
Administering the Gateways  
Oracle Tuxedo has a set of tmadminand dmadmincommands for the administration of the TMA  
TCP gateways. For detailed information about these commands, refer to the Oracle Tuxedo  
documentation.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
4-53  
 
4-54  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
C H A P T E R  
5
Programming Oracle Tuxedo  
Mainframe Adapter for TCP (CICS)  
The following subsections identify issues that CICS programmers should be aware of when they  
develop or modify application programs that operate with Oracle Tuxedo Mainframe Adapter for  
TCP (CICS) (hereafter referenced as TMA TCP for CICS):  
z Client Application Considerations  
z Server Application Considerations  
Client Application Considerations  
The following sections identify issues that CICS programers should be aware of when they  
develop or modify application programs that interoperate with TMA TCP for CICS as clients.  
To make requests to remote Oracle Tuxedo domains from CICS application programs, use the  
EXEC CICS LINKcommand. The exact layout of the request/response data area is discussed in a  
later section.  
Buffer Layout Issues  
The layout of the data buffer sent between CICS and Oracle Tuxedo should be agreed upon by  
the CICS applications programmer, the Oracle Tuxedo applications developer, and the Oracle  
Tuxedo administrator to ensure consistency and proper configuration. There are no limitations on  
the CICS programmer concerning native COBOL or C data types.  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
5-1  
 
Making Calls from a CICS Client Program  
To make a service call from a CICS program to a remote Oracle Tuxedo domain, make an EXEC  
CICS LINKcall to the Pre-requester. The service you want to access must be configured by the  
Oracle TMA Administrator, but from a programming point of view the LINKcall is all you need.  
The following COBOL record is in the COBOL copybook client.cbl.  
Listing 5-1 COBOL Record  
01 REQUEST-RECORD.  
05 REQUEST-HEADER.  
10 DATALEN  
PIC S9(08) COMP.  
PIC X(16).  
10 SVCNAME[16]  
10 REQUESTCD  
10 RETURNCD  
PIC S9(08) COMP.  
PIC S9(08) COMP.  
PIC S9(08) COMP.  
10 REQRETURNCD  
05 REQUEST-DATA.  
10 DATA-AREA  
PIC X(DATALEN).  
The layout of the structure in C that must be passed in the LINKcall is shown in Listing 5-2. The  
following C structures are in the clienth.hINCLUDEfile.  
Listing 5-2 C Structures  
typedef struct CLIENTHDR  
{
long DataLen;  
char SvcName[16];  
long RequestCd;  
long ReturnCd;  
long ReqReturnCd;  
} CLIENTHDR;  
/* THE LEN OF THE DATA FROM AND TO APPL */  
/* THE SERVICE NAME */  
/* THE REQUEST COMMAND FROM THE APPL */  
/* THE RETURN CODE TO THE APPL */  
/* THE RETURN CODE FROM THE PREQ AND REQ */  
typedef struct CMAREA  
{
5-2  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
 
Client Application Considerations  
CLIENTHDR CltHdr;  
/*HEADER */  
char Request_data[MAX_DATA_LENGTH]; /* REQUEST DATA */  
} CMAREA;  
The variables in the previous COBOL and C examples are defined as follows.  
DataLen  
The length of the data in the Request_datafield.  
SvcName  
The service request name (ask the administrator for the names).  
RequestCd  
A predefined numeric value that indicates the type of call this is.  
BEA_REQUEST_NORESPONSE- Value is 7. A No Reply Service Request. In this case the  
request is sent over to Oracle Tuxedo for the service to be performed, but no response data  
is sent back.  
BEA_REQUEST_RESPONSE- Value is 5. A Request/Response Request. A request is sent to  
Oracle Tuxedo and a response is expected back.  
Table 5-1 Request Codes  
Code  
Value  
+5.  
BEA-REQUEST-RESPONSE  
BEA-REQUEST-NORESPONSE  
+7.  
ReturnCd  
This code is the return code from the CICS Requester.  
All return codes are listed in the following table. Notify the administrator if any of the  
return codes indicate a processing or network problem.  
Note: For a complete description of these codes, refer to the “Codes Returned to a CICS  
Client Program” section in Appendix A.  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
5-3  
 
Table 5-2 Return Codes  
Code  
Value  
+0.  
BEA-NORMAL  
BEA-ERR-LENGTH  
+1.  
BEA-ERR-MISSING-SRV-NAME  
BEA-ERR-REQ-CODE  
BEA-ERR-SRC-NOT-FOUND  
BEA-ERR-READ-UMT  
BEA-ERR-SERVER  
+2.  
+3.  
+4.  
+5.  
+6.  
BEA-ERR-POST  
+7.  
BEA-ERR-CANCEL  
+8.  
BEA-ERR-WAIT  
+9.  
BEA-ERR-LMID-NOT-FOUND  
BEA-ERR-START-TRANSID  
BEA-ERR-DISABLE-ACQUIRING  
BEA-ERR-DISABLE-NOT-FND  
BEA-ERR-DISABLE-NOT-RESPOND  
BEA-ERR-DISABLE  
+10.  
+11.  
+12.  
+13.  
+14.  
+15.  
+16.  
+17.  
+18.  
+19.  
+20.  
+21.  
BEA-ERR-ALLOC  
BEA-ERR-TIMEOUT  
BEA-ERR-TSQ  
BEA-ERR-SOCKET-FAILURE  
BEA-ERR-PROTOCOL  
BEA-ERR-QUEUE-OVERFLOW  
5-4  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
 
Client Application Considerations  
ReqReturnCd  
This code is the return code from the Oracle Tuxedo Domain. See the Tuxedo  
documentation for a complete list of Tuxedo error codes  
Request_data  
This area is the area where request data gets placed and in which your returned data  
arrives. The length depends on how long this particular service is configured. Check with  
the administrator for each service. The maximum value is 32000.  
Examples  
The following sample is an example of a COBOL CICS client program.  
Listing 5-3 COBOL CICS Client Program Example  
IDENTIFICATION DIVISION.  
PROGRAM-ID. TESTCLN.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-3090.  
OBJECT-COMPUTER. IBM-3090.  
DATA DIVISION.  
WORKING-STORAGE SECTION.  
01 FILLER PIC X(32) VALUE 'SAMPLE COBOL CICS CLIENT PROGRAM'.  
01 MSG-AREA.  
05 M-DATA  
05 M-RCDE  
PIC X(42) VALUE SPACES.  
PIC Z(05) VALUE ZEROS.  
01 WS-COMMAREA.  
05 WC-DATALEN  
05 WC-SVCNAME  
PIC S9(9) COMP-4.  
PIC X(16).  
05 WC-REQUESTCD PIC S9(9) COMP-4.  
05 WC-RETURNCD PIC S9(9) COMP-4.  
05 WC-REQRETURNCD PIC S9(9) COMP-4.  
05 WC-REQDATA  
LINKAGE SECTION.  
01 DFHCOMMAREA  
PROCEDURE DIVISION.  
A100-ENTRY.  
PIC X(14).  
PIC X(14).  
MOVE +14  
TO WC-DATALEN.  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
5-5  
 
MOVE 'TOLOWER'  
MOVE +5  
TO WC-SVCNAME.  
TO WC-REQUESTCD.  
MOVE 'THIS IS A TEST' TO WC-REQDATA.  
EXEC CICS LINK PROGRAM('BEAPRERQ')  
COMMAREA(WS-COMMAREA)  
LENGTH(LENGTH OF WS-COMMAREA)  
END-EXEC.  
IF RETURNCD = 0  
MOVE 'SUCCESSFUL CALL, RETURN DATA IS IN WC-DATA'  
TO MSG-DATA  
ELSE  
MOVE 'PROCESS ERROR OCCURRED, RETURN CODE EQUAL '  
TO MSG-DATA  
MOVE RETURNCD TO M-RCDE  
END-IF.  
EXEC CICS SEND TEXT FROM(MSG-AREA) LENGTH(47)  
ERASE TERMINAL FREEKB CURSOR(0)  
END-EXEC.  
A200-EXIT.  
EXEC CICS RETURN END-EXEC.  
The following is an example of a C CICS client program.  
Listing 5-4 C CICS Client Program Example  
long resp, resp2;  
unsigned short int lmsg;  
struct CMAREA carea;  
carea.CltHdr.DataLen = strlen(sendbuf);  
memcpy(carea.CltHdr.SvcName, “ECHO”, 4);  
carea.CltHdr.RequestCd = BEA_REQUEST_RESPONSE;  
memcpy(carea.Request_data, “This is a test”, 14);  
lmsg=sizeof(carea);  
/* Use the name defined during installation */  
5-6  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
 
Client Application Considerations  
EXEC CICS LINK PROGRAM("PREREQ")  
COMMAREA(&carea)  
LENGTH(lmsg) RESP(resp) RESP2(resp2);  
if(carea.CltHdr.ReturnCd || carea.CltHdr.ReqReturnCd)  
process error;  
else  
successful call, returned data is in Request_data;  
Note: C Programmers, do not include the NULL terminator on any strings. In the previous  
example, the memxxxcalls were used instead of the strxxxcalls. This example is typical  
when using C and CICS together. For more information see your C for CICS  
documentation.  
Error Handling  
You may encounter the following three types of errors while using TMA TCP for CICS:  
z Gateway errors (communications problems)  
z MVS or CICS errors  
z Application errors  
The following subsections explain how TMA TCP handles these different kinds of errors.  
Gateway Errors  
When local or remote gateway errors occur they are logged in the Oracle Tuxedo ULOGfile on the  
remote Oracle Tuxedo node and in the BEALOGfile (a TD Queue defined during installation)  
within the CICS region. All associated service requests fail and if the TMA gateways are able to  
communicate with each other, error messages are communicated between them.  
MVS or CICS Errors  
For requests originating in the Oracle Tuxedo domain, if the remote target system does not make  
it possible for TMA TCP for CICS to detect particular types of failure, the TMA TCP gateway  
(the Oracle Tuxedo domain) blocking time-out parameter can be tuned to provide timely  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
5-7  
 
detection of problems. This configuration parameter is set in the remote TMA TCP gateway  
system; discuss any changes you want to make with the administrator of that system.  
Problems with requests that originate in the CICS region are also logged to the BEALOGfile.  
Additionally, time-out periods for these requests can be tuned using the TMA TCP for CICS  
administration tool.  
For more information about the blocking time-out parameter, refer to the Oracle TMA TCP  
gateway User Guide.  
Application Errors  
If an error occurs that makes the Handler unable to execute a certain program (such as, the  
program does not exist or is disabled) the Handler sends a message back to the TMA TCP  
gateway gateway. If any other type of error occurs within an application program and the Handler  
is not notified of the problem, a time-out message is sent from the Handler back to the remote  
gateway.  
For requests originating with CICS, Oracle Tuxedo returns information about specific problems,  
if possible. If there are network problems that prohibit the transmission of data, the request  
receives a timeout error.  
Server Application Considerations  
The following subsections identify issues that CICS programmers should be aware of when they  
develop or modify application programs that interoperate with TMA TCP for CICS as servers.  
A CICS application program that processes requests originating from a remote Oracle Tuxedo  
domain is written like a CICS application program that is invoked with the CICS LINKcommand.  
The CICS programs that work best for satisfying Oracle Tuxedo requests are the ones that  
perform a certain operation and return information to the caller. The CICS services requested by  
a Oracle Tuxedo client program must entail a single request/response scenario.  
CICS service programs that are called from Oracle Tuxedo clients must be careful if they give up  
control, as when performing an EXEC CICS XCTLoperation. To ensure that the response data is  
returned to the client, chaining programs must pass the original COMMAREAduring the XCTL so  
that it may be RETURNed to the TMA TCP for CICS Handler by the final program in the chain.  
5-8  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
 
Server Application Considerations  
Programming Services with a Response  
Service programs expected to send a response to the client use the EXEC CICS LINKcommand  
to execute. The COMMAREAoption contains a pointer to the raw data; therefore, no header is sent.  
As a result, the request data is available to the service programs in the COMMAREA.  
Programming Services without a Response  
Service programs that do not send replies back to the requester execute using transactions started  
by the EXEC CICS STARTcommand. The FROMoption of this command contains a pointer to the  
raw data; therefore, no header is sent. As a result, such service programs must use an EXEC CICS  
RETRIEVEcommand with the SEToption containing a pointer to the raw data.  
Note: Define a unique transaction for each service that does not send a reply and enter the name  
of that transaction in the TRANSACTION NAMEfield of the Inbound Service Information  
screen for the corresponding service.  
An example of a service sending no reply is one requested by a client using a tpacall with the  
TPNOREPLYflag set.  
Modifying the Length of the Return Message  
You can manage the actual size of the return message the system sends over the gateway on a per  
request basis. This is different than simply limiting the message size for a particular service using  
the MAX MESSAGEfield of the Inbound Service Information screen. To limit the size of the return  
message per request, the service program must ADDRESSthe TWA using the copybook or the  
include file delivered in the "YOURHLQ".BEATCPC.INCLUDEfile.  
Modifying Return Message Lengths for C Programs  
To modify the return message length on a per request basis, specify the message length in the  
rtnMsgSizefield in a TWA_CONNECTstructure defined in the TWAINCLfile.  
Modifying Return Message Lengths for COBOL Programs  
To modify the return message length on a per request basis, specify the message length in the  
RTN-MSG-SIZEfield in a TWA_CONNECTrecord layout in the copybook TWACOPY.  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
5-9  
 
5-10  
Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide  
 
A P P E N D I X A  
Error and Informational Messages  
The following topics describe TMA TCP for CICS messages:  
z Messages Returned to the Remote Gateway  
z Messages Written to the TMA TCP for CICS Log  
z Codes Returned to a CICS Client Program  
z Informational Process Messages  
z Data Field Error Messages  
z System Error Messages  
Messages Returned to the Remote Gateway  
Most of the messages produced from Oracle Tuxedo Mainframe for TCP (CICS) (hereafter  
referenced as TMA TCP for CICS) are sent back to the remote TMA TCP gateway and written  
to the ULOGon that system.  
Message  
Description  
BEA TMA TCP for CICS server  
The Handler process has been started.  
process initiated.  
Welcome to BEA TMA TCP for  
The connect process has completed successfully.  
MVS/CICS.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
A-1  
 
Error and Informational Messages  
Message  
Description  
Goodbye.  
The disconnect process has completed successfully.  
The requested service was not found in the inbound service name file.  
Service svcname not found.  
Client has already logged  
in.  
A client process has attempted to establish a connection when a  
connection already existed. (The connection request protocol was  
resent.)  
Client has not logged in.  
A client process has made a request to the TMA TCP for CICS  
gateway but has not yet established a login connection. (The  
connection request protocol was never sent.)  
BEA TMA TCP MVS/CICS server  
is active.  
This message is returned to the remote Tuxedo gateway when a PING  
request is sent to the TMA TCP for CICS gateway from the tmadmin  
administration tool.  
Invalid password.  
The password specified in the TMA TCP gateway configuration file  
does not match the password specified when the CICS supplied  
listener was configured.  
Invalid client account.  
The account code specified in the TMA TCP gateway configuration  
file does not match the account code specified when the CICS  
supplied listener was configured.  
Sorry-System Resource is  
protected by CICS.  
The mode command was executed through the tmadmin tool on  
Tuxedo and the administrative request specified is not available in the  
CICS region.  
Data too long, please check  
message header.  
A message received is larger than the maximum allowable message  
length.  
Data too short, please check  
message header.  
A message was received and was smaller than the smallest expected  
message.  
Message header is incorrect.  
An invalid protocol header was received. This can occur if there was  
a transmission error or if a message was sent to the gateway without  
having gone through the TMA TCP gateway gateway on the remote  
Tuxedo node.  
This transaction is not  
defined in CICS.  
A CICS transaction code was mapped to a service name in the TMA  
TCP gateway configuration file for a transaction code that is  
unknown to CICS.  
A-2  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Messages Written to the TMA TCP for CICS Log  
Message  
Description  
Application Handler  
abnormally terminated.  
The Application Handler terminated prior to completing the service  
request. This message usually occurs when a service has timed out.  
Verify that you are not expecting a reply from a service that does not  
send one.  
Requested Service timed out.  
The requested service did not complete within the time provided in  
the message header from the remote Tuxedo gateway.  
Unable to start another  
session.  
The Handler is already processing the maximum number of service  
requests configured as the multiplex count.  
Unable to start transaction.  
A CICS error occurred attempting to start the transaction.  
The Application Handler encountered a CICS error.  
Error occurred in  
Application Handler.  
Security error occurred in  
Application Handler.  
The Application Handler encountered a CICS security error.  
Messages Written to the TMA TCP for CICS Log  
Occasionally, messages are written directly to the CICS log configured specifically for TMA  
TCP for CICS. For more information about configuring the CICS log, refer to the “Configuring  
and Administering Oracle TMA TCP for CICS” section.  
Message  
Description  
Goodbye.  
The disconnect process has completed successfully.  
Service svcname not found.  
The requested service was not found in the inbound service name  
file.  
Client has already logged in.  
Client has not logged in.  
A client process has attempted to establish a connection when a  
connection already existed. (The connection request protocol was  
resent.)  
A client process has made a request to the TMA TCP for CICS  
gateway but has not yet established a login connection. (The  
connection request protocol was never sent.)  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
A-3  
 
Error and Informational Messages  
Message  
Description  
Invalid password.  
The password specified in the TMA TCP gateway configuration  
file does not match the password specified when the CICS supplied  
listener was configured.  
Invalid client account.  
The account code specified in the TMA TCP gateway  
configuration file does not match the account code specified when  
the CICS supplied listener was configured.  
Data too long, please check  
message header.  
A message received is larger than the maximum allowable  
message length.  
Application Handler  
abnormally terminated.  
The Application Handler terminated prior to completing the  
service request. This message usually occurs when a service has  
timed out. Verify that you are not expecting a reply from a service  
that does not send one.  
Requested Service timed out.  
The requested service did not complete within the time provided in  
the message header from the remote Tuxedo gateway.  
Unable to start another  
session.  
The Handler is already processing the maximum number of service  
requests configured as the multiplex count.  
Unable to start transaction.  
A CICS error occurred attempting to start the transaction.  
The Application Handler encountered a CICS error.  
Error occurred in Application  
Handler.  
Security error occurred in  
Application Handler.  
The Application Handler encountered a CICS security error.  
The DNS lookup function failed for the given host name.  
DNS Lookup Failed for  
HOST(host) ERRNO(errno)  
Dotted IP address (address)  
malformed.  
There was an erroneous IP address passed into the  
ConvertAddressfunction.  
Invalid data pointer  
(pointer).  
There was an invalid data buffer pointer passed into the  
BufferHeaderfunction.  
Socket CONNECT Failed.  
ERRNO=errno  
The Socket CONNECTfunction failed.  
fcntl(F_SETFL) Failed.  
The file control function with the F_SETFLoption failed in the  
ERRNO=errno FLAGS=hexcode  
connect socket function.  
A-4  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Messages Written to the TMA TCP for CICS Log  
Message  
Description  
fcntl (F_GETFL) Failed.  
ERRNO=errno  
The file control function with the F_GETFLoption failed in the  
connect socket function.  
Socket CREATE Failed.  
ERRNO=errno  
The Socket CREATEfunction failed.  
The Socket WRITEfunction failed.  
The Socket initialization function failed.  
WRITE on Socket Failed.  
ERRNO=errno  
initapi Failed. ERRNO=errno  
RETRIEVE Failed. RESP=hexcode  
RESP2=hexcode  
The CICS RETRIEVEcommand failed when it tried to access the  
buffer passed to the TMA TCP gateway Handler from the Sockets  
for CICS Listener.  
Load Control Failed.  
A CICS LOAD PROGRAMcommand failed. The Handler was  
RESP=hexcode RESP2=hexcode  
unable to load the control programs OTPCICS01or OTPCICS02.  
Start Task Failed.  
A CICS STARTcommand failed when the Handler tried to issue a  
RESP=hexcode RESP2=hexcode  
STARTon the specified user program.  
Link Program Failed.  
A CICS LINKcommand failed. The Handler was unable to LINK  
RESP=hexcode RESP2=hexcode  
to the specified user program.  
GETMAIN Failed. RESP=hexcode  
RESP2=hexcode  
The CICS GETMAINcommand failed.  
Take Socket Failed.  
ERRNO=errno  
The TMA TCP Handler was unable to take control of the TCP/IP  
socket.  
Error on Select. ERRNO=errno  
The Sockets SELECTfunction failed.  
Read on Socket Failed.  
ERRNO=errno  
An error was encountered while attempting to read from the active  
socket.  
Socket SEND Failed. RC=rc  
ERRNO=errno  
An error was encountered while issuing a send over the active  
socket.  
Handler connected  
successfully.  
The client request is allowed because the account and password  
codes are authorized to use the TMA TCP gateway.  
BEA TMA TCP Server CTOS is  
The TMA TCP gateway Handler is shutting down.  
shutting down.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
A-5  
 
Error and Informational Messages  
Message  
Description  
Verifying User Account.  
The Handler is verifying that the account and password codes  
supplied by TMA TCP gateway on the remote Tuxedo gateway are  
valid.  
Handler initialization  
complete.  
The TMA TCP Handler has successfully initialized.  
Normal shutdown requested, x  
requests pending.  
The TMA TCP Handler shuts down after the currently pending  
requests complete.  
Handler exceeded maximum idle  
time.  
The TMA TCPHandler has exceeded the configured IDLE TIME.  
BEA TMA TCP Handler is  
The TMA TCP Handler is shutting down.  
shutting down.  
Client disconnected.  
The client has been disconnected from the TMA TCP Handler.  
Read of file failed,  
resp(hexcode)  
A CICS READcommand failed.  
Freemain did not work,  
resp(hexcode)  
A CICS FREEMAINcommand failed.  
A CICS GETMAIN(SHARED)command failed.  
A CICS DELETEcommand failed.  
Getmain shared failed:  
resp(hexcode)  
Delete from file failed,  
resp(hexcode)  
Write to file failed,  
resp(hexcode)  
A CICS WRITEcommand failed.  
Rewrite of file failed,  
resp(hexcode)  
A CICS REWRITEcommand failed.  
A CICS READ(UPDATE)command failed.  
Read(update) of file failed,  
resp(hexcode)  
Unauthorized Client Rejected.  
The client request are not allowed because the account and/or  
password codes are not authorized.  
deleteq ts did not work,  
resp(hexcode)  
A CICS DELETEQ TScommand failed.  
A-6  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Codes Returned to a CICS Client Program  
Message  
Description  
Unable to start transaction  
A CICS error occurred attempting to start the transaction.  
Security Violation: Invalid  
user for this transaction  
The user ID sent with a request by the client does not match the  
user ID set in the mainframe security for this transaction.  
The Handler is designed to run  
in the background.  
A user has attempted to start the Handler from a terminal.  
The appHandler is designed to  
run in the background.  
A user, from a terminal, has attempted to start the transaction that  
initiates the Application Handler.  
App Handler received corrupted  
header, exiting.  
The Application Handler is terminating on initialization because  
there is a problem with the header it received. This would occur,  
for example, if the transaction for the Application Handler was  
given in the Inbound Service Information screen as the transaction  
to start a service with no reply.  
opcode is not CONNECT on  
connection.  
The Requester has received a reply that should be the  
acknowledgment of a connection request; however, the message  
does not contain the correct opcode.  
Trying connection, but already  
connected.  
The Requester has received a reply containing an opcode  
indicating a response to a connection request; however, the  
connection already exists.  
Read on sockets failed.  
Connection closed by other  
side.  
The Handler terminated because the socket status indicated that the  
client side had closed the connection.  
LMID is disabled. Auto  
enabling LMID ,LMID name>  
The pre-requester is dynamically enabling an LMID which is  
disabled. This message will be displayed only when the AUTO  
ENABLE option is set to E.  
Codes Returned to a CICS Client Program  
The following codes are returned to a CICS client program on return from a LINK to TMA TCP.  
For system level problems, please notify your CICS administrator.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
A-7  
 
Error and Informational Messages  
Message  
Description  
BEA_NORMAL  
Value 0  
Successful Return From Service Call.  
BEA_ERR_LENGTH  
Value 1  
There was an error regarding the length of the message sent or the  
length value specified.  
BEA_ERR_MISSING_SRV_NAME  
BEA_ERR_REQ_CODE  
Value 2  
A service request was made but no service name was provided.  
Value 3  
A service call was made with an invalid or missing request code.  
BEA_ERR_SRC_NOT_FOUND  
Value 4  
The service that was called cannot be found in the outbound service  
table.  
BEA_ERR_READ_UMT  
BEA_ERR_SERVER  
Value 5  
Check the FCT entry for the CONNECTIONSdataset.  
Value 6  
There was a problem accessing the Requester. Check that it is  
enabled.  
BEA_ERR_POST  
Value 7  
A CICS Post error occurred in TMA TCP.  
BEA_ERR_CANCEL  
Value 8  
A CICS Cancel error occurred in TMA TCP.  
BEA_ERR_WAIT  
Value 9  
A CICS Wait error occurred in TMA TCP.  
BEA_ERR_LMID_NOT_FOUND  
BEA_ERR_START_TRANSID  
BEA_ERR_DISABLE_ACQUIRING  
Value 10  
The service name provided specified a non-existent LMID.  
Value 11  
A CICS STARTerror occurred in TMA TCP.  
Value 12  
There was a problem getting an LMIDto use for this service request.  
A-8  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Codes Returned to a CICS Client Program  
Message  
Description  
BEA_ERR_DISABLE_NOT_FND  
Value 13  
The service name provided specifies an invalid LMIDor is missing  
the LMID.  
BEA_ERR_DISABLE_NOT_RESPOND  
BEA_ERR_DISABLE  
Value 14  
The Requester for handling this service name is not responding.  
Value 15  
The LMIDassociated with the requested service is not enabled.  
BEA_ERR_ALLOC  
Value 16  
The Pre-requester was unable to allocate the memory necessary to  
process a request.  
BEA_ERR_TIMEOUT  
Value 17  
The Pre-requester has timed out the request. This could occur either  
during processing by the Pre-requester, before the request is sent, or  
because the Pre-requester did not receive a response in time.  
BEA_ERR_TSQ  
Value 18  
The Pre-requester was unable to write the request to the appropriate  
TS queue.  
BEA_ERR_SOCKET_FAILURE  
Value 19  
The Requester closed a socket because the socket was in a state  
inconsistent with the requested operation.  
BEA_ERR_PROTOCOL  
Value 20  
The Requester closed a socket because the session data was corrupt.  
BEA_ERR_QUEUE_OVERFLOW  
Value 21  
The Requester has aborted a request because the pending request  
queue for the Requester is too full.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
A-9  
 
Error and Informational Messages  
Informational Process Messages  
Message  
Description  
Action  
"RECORD READY FOR  
UPDATE"  
The record selected is ready to  
be updated.  
Make the changes and press ENTERto  
process.  
"UPDATE COMPLETED"  
The changes made to the record Select another record to update, or press PF3  
selected for update have been  
processed.  
or PF5.  
"TO CONFIRM DELETE,  
PRESS ENTER:AGAIN"  
The record selected is ready to  
be deleted.  
Press ENTERto delete the selected record of  
press PF3or PF5to abort the delete.  
"DELETE COMPLETED"  
"INQUIRE COMPLETED"  
"INSERT COMPLETED"  
The record selected for delete  
has been deleted.  
Select another record to delete, or press PF3or  
PF5.  
The record selected for inquiry  
has been processed.  
Select another record to inquiry, or press PF3  
or PF5.  
The record entered has been  
inserted into the file.  
Enter another record, or press PF3or PF5.  
Data Field Error Messages  
Message  
Description  
Action  
"INVALID FUNCTION KEY,  
OPTIONS=(ENTER:,  
PF3:)"  
The PFKeypressed is not valid in Press a valid PFKey. See OPTIONS=.  
this operation.  
"INVALID FUNCTION KEY,  
OPTIONS=(ENTER:, PF3:,  
PF5:)"  
The PFKeypressed is not valid in Press a valid PFKey. See OPTIONS=.  
this operation.  
"INVALID FUNCTION KEY,  
OPTIONS=(ENTER:, PF3:,  
PF7:, PF8:)"  
The PFKeypressed is not valid in Press a valid PFKey. See OPTIONS=.  
this operation.  
A-10  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
Data Field Error Messages  
Message  
Description  
Action  
"INVALID LOGICAL  
MACHINE NAME"  
The LOGICAL MACHINE NAME  
entered is not valid.  
Enter a valid INVALID LOGICAL  
MACHINE NAME(i.e., LMIDNJ). Must  
not start with a space, null, or  
underscore.  
"INVALID HOST ADDRESS"  
The HOST ADDRESSentered is not Enter a valid HOST ADDRESS(i.e.,  
valid.  
1234.1234.99).Must not start with  
a space, null, or underscore.  
"HOST ADDRESS or DNS  
NAME REQUIRED"  
Neither the HOST ADDRESSnor  
the DNS NAMEhave been entered. DNS NAME.  
Enter either a valid HOST ADDRESSor  
"CANNOT HAVE BOTH HOST  
ADDRESS AND DNS NAME"  
Both HOST ADDRESSand DNS  
NAMEhave been entered.  
Enter either a valid HOST ADDRESSor  
DNS NAME.  
"INVALID MULTIPLEX  
COUNT OPTIONS=(1-99)"  
The MULTIPLEX COUNTentered Enter a valid number for MULTIPLEX  
is not valid. COUNT.  
"INVALID MAX  
CONNECTIONS  
The MAX CONNECTIONSentered Enter a valid number for MAX  
is not valid.  
CONNECTIONS.  
OPTIONS=(1-99)"  
"TRAN CODE INVALID FOR  
LMID TYPE (I IMS, T  
TCP)"  
A START TRAN CODEhas been  
entered and the LMID TYPEis not change the LMID TYPEto CICS.  
CICS.  
Remove the START TRAN CODEor  
"QUEUE NAME REQUIRED"  
The QUEUE NAMEhas not been  
Enter a valid QUEUE NAME.  
entered.  
"CICS DATA INVALID FOR  
LMID TYPE (I IMS, T  
TCP)"  
CICS DATAhas been entered and  
the LMID TYPEis not CICS.  
Remove the CICS DATAor change the  
LMID TYPEto CICS.  
"INVALID PORT NUMBER  
The PORT NUMBERentered is not Enter a valid PORT NUMBER(i.e.,  
OPTIONS=(1 -> 65,535)"  
valid.  
1234).Must not start with a space,  
null, or underscore and must be within  
the range (1 -> 65,535)  
"ACCOUNT ID REQUIRED"  
"PASSWORD REQUIRED"  
An ACCOUNT IDis required if you Enter an ACCOUNTor erase the  
entered a PASSWORD.  
PASSWORD.  
A PASSWORDis required if you  
Enter a PASWORDor erase the  
entered an ACCOUNT ID.  
ACCOUNT ID.  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
A-11  
 
Error and Informational Messages  
Message  
Description  
Action  
"INVALID MAX MSG SIZE  
OPTIONS=(1 -> 32000)"  
The MAX MSG SIZEentered is  
not valid.  
Enter a valid MAX MSG SIZE(i.e.,  
4096) Must not start with a space,  
null, or underscore and must be within  
the range (1 -> 32000)  
"INVALID CONNECT RETRY  
LIMIT"  
The CONNECT RETRY LIMIT  
entered is not valid.  
Enter a valid CONNECT RETRY  
LIMIT(i.e., 10) Must not start with a  
space, null, or underscore.  
"INVALID SELCDE,  
The SELCDEentered is not valid.  
Enter a valid SELCDE. See  
OPTIONS= (1: INS, 2:  
UPD, 3: INQ, 4: DEL)  
OPTIONS=.  
"INVALID SELCDE,  
OPTIONS= (2: UPD, 3:  
INQ)  
The SELCDEentered is not valid.  
Enter a valid SELCDE. See  
OPTIONS=.  
"INVALID SELECTION,  
OPTIONS=(C2-3, C5,  
R1-5, S1-5, U2-3,  
I1-5)"  
The SELECTIONentered is not  
valid.  
Enter a valid SELECTION. See the list  
of valid options in the message.  
"INVALID SERVICE NAME"  
The SERVICE NAMEentered is not Enter a valid SERVICE NAME. (i.e.,  
valid.  
EMPLSRV) Must not start with a space,  
null, or underscore.  
"INVALIDREMOTESERVICE  
NAME"  
The REMOTE SERVICE NAME  
entered is not valid.  
Enter a valid REMOTE SERVICE  
NAME(i.e., EMPLSRV) Must not start  
with a space, null, or underscore.  
"INVALID LMID TYPE  
OPTIONS= (C CICS, I  
IMS, T TCP)"  
The LMID TYPEentered is not  
valid.  
Enter a valid LMID TYPE. See Options  
"START TRAN CODE  
REQUIRED FOR LMID TYPE  
(C CICS)"  
No START TRAN CODEhas been Enter a valid START TRAN CODE.  
entered and the LMID TYPEis  
CICS.  
"INVALID TYPE (I  
The TYPEentered is not valid.  
Enter a valid TYPE.  
INCOMING, O OUTGOING)"  
"INVALID SECURITY FLAG  
(Y/N)"  
The SECURITY FLAGentered is  
not valid.  
Enter a valid SECURITY FLAG(Yor  
N).  
A-12  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 
System Error Messages  
Message  
Description  
Action  
"INVALID SERVICE  
TIMEOUT(SEC)"  
The SERVICETIMEOUT(SEC)  
entered is not valid.  
Enter a valid SERVICE  
TIMEOUT(SEC) (i.e. 30). Must not  
start with a space, null, or underscore.  
"INVALID STATUS  
The STATUSentered is not valid.  
Enter a valid STATUS. See  
OPTIONS=(E ENABLE, D  
DISABLE, A ABORT)"  
OPTIONS=.  
"INVALID OPTION=(E  
ENABLE, D DISABLE)"  
The AUTO ENABLE  
LMID (E|D)option entered is not  
valid or is empty.  
Enter a valid option (E or D).  
"NO CHANGE DONE STATUS  
ENTERED SAME AS ON  
RECORD"  
The STATUSon the record is 'E'  
and you entered an 'E'. The  
STATUSon the record is 'D' and  
you entered a 'D'. The STATUSon  
the record is 'A' and you entered a  
'A'.  
Enter the appropriate STATUS.  
"BEA_REQ_HDRRECORDNOT  
FOUND"  
An error occurred within the  
Connection CSA.  
Contact your system administrator.  
System Error Messages  
Message  
Description  
Action  
"BEG/END OF  
FILE"  
The end of file was detected  
during a browse.  
None  
"DUPLICATE  
RECORD"  
The record being inserted is  
already on the file.  
Use a different record key.  
"FILE NOT  
OPENED"  
The file is not available to  
CICS.  
Contact your system administrator. Check the file  
status via CEMT.  
"DSIDERR"  
Refer to the CICS Application Contact your system administrator.  
Reference Manual.  
"ILLOGIC"  
Refer to the CICS Application Contact your system administrator.  
Reference Manual  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
A-13  
 
Error and Informational Messages  
Message  
Description  
Action  
"INVREQ"  
Refer to the CICS Application Contact your system administrator.  
Reference Manual.  
"IOERR"  
Refer to the CICS Application Contact your system administrator.  
Reference Manual.  
"LENGERR"  
"MAPFAIL"  
"NOSPACE"  
"NOTAUTH"  
"PGMIDERR"  
Refer to the CICS Application Contact your system administrator.  
Reference Manual.  
Refer to the CICS Application Contact your system administrator. Check the Mapset  
Reference Manual.  
status via CEMT.  
Refer to the CICS Application Contact your system administrator.  
Reference Manual.  
Refer to the CICS Application Contact your system administrator.  
Reference Manual.  
Refer to the CICS Application Contact your system administrator. Check the Program  
Reference Manual.  
status via CEMT.  
"RECORD NOT  
FOUND"  
The record selected is not in the Verify the data you entered for the record key.  
file.  
"SYSIDERR"  
Refer to the CICS Application Contact your system administrator.  
Reference Manual.  
"UNKNOWN  
ERROR"  
Refer to the CICS Application Contact your system administrator.  
Reference Manual.  
A-14  
Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide  
 

NewAir Dehumidifier ADS 400 User Manual
Nike Video Gaming Accessories LE034 3940_UGqx 18 9 06 1314 Pgina 1 User Manual
Nikon Computer Keyboard HMSC7075 User Manual
Nortel Networks Telephone SL 100 User Manual
Omega Speaker Systems Indoor Furnishings Solid Birch Drawer User Manual
Omega Stud Sensor CDTX 90 User Manual
Oregon Film Camera ATCmini User Manual
Oregon Scientific Thermometer AW129BLRS User Manual
Palsonic Air Conditioner A22R220 User Manual
Panasonic Stereo Receiver AJ HD1400 User Manual