Oracle Audio Technologies Oracle Tuxedo User Manual

Oracle® Tuxedo® Mainframe Adapter for TCP

CICS User Guide

Release 10.0

June 2008

Tuxedo® Mainframe Adapter for TCP CICS User Guide, Release 10.0 Copyright © 2007, 2008, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure

and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on content, products and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

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

CHAPTER

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 do wn 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 option is set to E (Enable), the Pre-Requester automatically enables the LMID and starts the Requester and processes the request.

AUTO ENABLE LMID option is provided in the Requester configuration. When the

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 gatew ay 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

VSAM file you must add the transaction BDWN to PLTSI for 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

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

Processing Scenarios

TMA TCP for CICS

TCP/CICS Handler

TCP/CICS Application Handler

User App1

User App2

TCP/CICS Application Handler

User App3

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 the data passed with the service and the data to be used as input to that service. When the 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.

EXEC CICS LINK command, the programmer supplies the name of the

EXEC CICS LINK command to the Oracle TMA gateway. In

EXEC CICS LINK command

1-8 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Figure 1-2 Oracle TMA Client Gateway Configuration

Processing Scenarios

User Program

EXEC CICS LINK

Pre-Requester Read CSA Read/Write TSQ

TS Q

Requester Read/Set CSA

User Program

EXEC CICS LINK

Pre-Requester Read CSA Read/Write TSQ

TS Q

User Program

EXEC CICS LINK

Pre-Requester Read CSA Read/Write TSQ

TS Q

Requester Read/Set CSA

TS Q

BEA Control Table

BEA Common Storage

Area (CSA)

Tuxedo

Figure 1-2 shows the configuration of the Oracle TMA client gateway. A client program (your

CICS program) issues an

EXEC CICS LINK command to the Pre-requester. The Pre-requester

verifies that the service name is valid and identifies the Requester to which it should it should pass the request. The Pre-requester starts a different Requester for each configured remote endpoint. The Requester then sends the request to the remote Oracle Tuxedo domain and waits for a response. Once the response is returned, the Requester notifies the Pre-requester and hands the response to the Pre-requester, which then returns the response to the client program.

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 LINK statement to one of your CICS programs and set up the data area as

described in “Understanding How Oracle TMA TCP for CICS Works”.

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

CHAPTER

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

3. Handler issues a

4. Listener resumes listening for new connection requests

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

givesocket() function call takesocket() function call

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

TCP protocol header. With th e

LINK command to execute the program specified in the TMA

LINK command it also passes along any request data

provided by the client application that made the original Oracle Tuxedo service request.

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

CICS program. c. The Handler transmits the response to the remote TMA TCP gateway gateway. d. The Handler stays connected to the remote gateway awaiting another service request.

3. If the multiplex count is greater than 1 or security is enabled, then the following tasks occur. a. The Handler issues an

EXEC CICS START TRANS call with the transaction specified in the

Inbound Service File for the service specified in the TMA TCP protocol header. The transaction should be the same as the Application Handler program.

Note: If security is enabled, the

EXEC CICS START TRANSID call uses the user ID specified

in the TMA TCP protocol header.

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

Application Handler. c. The Handler transmits the response to the remote TMA TCP gateway gateway. d. The connection between the Handler and the gateway remains and the Handler waits for

another service request.

For

tpacall/TPNOREPLY requests, the remote program is invoked by a CICS START TRANSID

command and no data is returned to the original caller. In this case, a unique transaction must be defined for the service. Use the Inbound Service Information screen to enter this unique transaction name rather than using the transaction name that starts the Application Handler.

Shutting Down the Handler

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

Use the supplied shutdown transaction Depending on the options specified, this causes all Handlers to shut down gracefully. The name of the

BDWN transaction may have been changed at your site during installation, so verify the

name.

BDWN to terminate active TMA TCP for CICS programs.

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 2-3

Using BDWN to Shut Down the Handler

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

Listing 2-1 BDWN Command Line Syntax for Handlers

BDWN [ALL | CLEANUP | HANDLER I | HANDLER]

BDWN

Shuts down all Handlers or all Requesters or both. It also frees shared memory that was allocated by a Handler that has abended without freeing the shared memory that it allocated. You can specify optional parameters with the 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 transaction. Specifying

ALL also frees any shared memory.

BDWN is illustrated in the following

BDWN transaction to shut down

BDWN

This is the default for

CLEANUP

BDWN.

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

HANDLER I

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

HANDLER

Shuts down all Handlers gracefully allowing them to complete all processing off all requests that were received before the execution of the 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

BDWN transaction. This

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 program). The client receives its response in the

EXEC CICS RETURN command to the client program (your

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

BDWN transaction may have been changed at your site

during installation. Check with the person who installed TMA TCP for CICS at your site.

Using BDWN to Shut Down the Requester

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

Listing 2-2 BDWN Command Line Syntax for Requesters

BDWN [ALL | REQUESTER I | REQUESTER]

BDWN

Shuts down all Handlers or all Requesters or both. It also frees shared memory used by the Requesters associated with each logical machine ID ( parameters with the

BDWN transaction to shut down Handlers or Requesters immediately

or after processing of all requests has completed. The default is

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 transaction. Specifying

ALL also frees any shared memory.

BDWN is illustrated in the following

LMID). You can specify optional

ALL.

BDWN

This is the default for

REQUESTER I

BDWN.

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 frees memory associated with each Handlers.

2-6 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

BDWN transaction. It also

LMID. This parameter does not shut down any

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 CIC S 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

CARRAY

VIEW

FML

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.

A CARRAY is a buffer of raw data that contains no terminating character and that undergoes no conversion or translation; the data is sent from one system to another without modification. A exemplary buffer type for a graphics file.

A VIEW buffer is a collection of field definitions that can be treated as a single entity. It is comparable to a record layout in COBOL or a structure in C.

(Fielded Manipulation Language)

FML

buffers are variable length, dynamic, self-describing buffers. Each field in the buffer has its own descriptive header. In Oracle Tuxedo, closely to from one to the other is direct.

FML buffers can be tied

VIEW buffers so that conversion

CARRAY is an

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

STRING and CHAR Translated from ASCII to EBCDIC (if needed)

SHORT

2-8 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Passed untranslated as sequences of bytes

Translated to S9(4) COMP

Table 2-2 Data Translation Rules

Field Type Translation Rules

Translating Data with TMA TCP gateway

LONG

FLOAT

DOUBLE

Translated to S9(9) COMP Translated to COMP-1 Translated to COMP-2

Note: Oracle Tuxedo provides a field type named dec_t that supports decimal values within

VIEWs. The TMA TCP gateway product translates these fields into machine independent

representations of packed decimals. For example,

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.

dec_t(m,n) becomes

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

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

Remote Data Type Description View Field Type/Length

PIC X(n)

PIC X

PIC X(n)

PIC X

PIC S9(4) COMP

Alpha-numeric Characters string / n Single Alpha-numeric Character char Raw Bytes carray / n Single Numeric Byte carray / 1 16-bit Integer short

PIC S9(9) COMP

COMP-1

COMP-2

PIC S9((m+(n+1))/2)V9

(n) COMP-3

32-bit Integer long Single-precision Floating Point float Double-precision Floating Point double Packed Decimal dec_t / m,n

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 VIEW definitions for input and output buffers and records. It also explains how string data and numeric data are treated in the TMA TCP gateway environment.

Including NULL Characters in String Length Calculations

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

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

Note: Although TMA TCP gateway does not require strings to be NULL-terminated, it respects

NULL termination. Therefore, when TMA TCP gateway detects a NULL (zero) character within a string, it does not process any subsequent characters. To pass full 8-bit data that contains embedded NULL values, use a

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.

CARRAY type field or buffer.

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

In addition, you can convert numeric values into strings (and the reverse). For example, while FML buffers do not directly support the fields and map these to

2-10 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

dec_t fields within VIEW definitions.

dec_t type VIEW element.

dec_t type, you can place decimal values in string

CHAPTER

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

BEA TMA TCP

Gateway

Tuxedo

Client

1. When the TMA TCP gateway client program performs a identity is validated against the

2. When the client program issues a

tpacl file) the user is authorized to invoke the gateway service.

tpusr file.

tpcall() or tpacall(), Tuxedo verifies (against the

Handler

Mainframe

Application

Handler

tpinit(), the user’s Tuxedo

Remote

Server

3. When the gateway establishes the initial connection, connection security information (specified as gateway to the remote gateway. If the

RMTNAME and PASSWORD in the GWICONFIG file) is passed from the TMA TCP

RMTNAME and PASSWORD values 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

Tuxedo

Server

UNIX

BEA TMA TCP

Gateway

Mainframe

Remote

Gateway

Client

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 has access to the requested service.

tpacl file) to verify that the user

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

2. Enter values for the When

the User Connection Account match the gateway a security error occurs.

SECURITY=Y in the Handler Configuration screen.

ACCOUNT and PASSWORD fields in the User Connection Account screen.

SECURITY=Y, TMA TCP for CICS verifies the ACCOUNT and PASSWORD values from

RMTACCT and PASSWORD values in the TMA TCP

GWICONFIG file *FOREIGN section. If these values do not match and SECURITY=Y,

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 When initiated the request as reported by the remote system.

If controlled by the socket listener).

3-4 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

SECURITY=Y in the Inbound Services screen for each service you want to secure.

SECURITY=Y, the gateway attempts to start user programs with the username that

SECURITY=N, the gateway starts user programs using the gateway’s user ID (as

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

2. Enter Verify that the parameter values for

the

GWICONFIG file.

When UNIX system on connection initiation. When

SECURITY=Y on the appropriate Requester screen.

ACCOUNT and PASSWORD values on the appropriate Requester screen.

ACCOUNT and PASSWORD in the Requester screen match

RMTACCT and PASSWORD values in the *FOREIGN section of the TMA TCP gateway

SECURITY=Y, the requester program sends the ACCOUNT and PASSWORD to the remote

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

2. Enter Verify that the parameter values for

the When

CICS system on connection initiation. When a connection without any verification.

SECURITY=Y on the appropriate Requester screen.

ACCOUNT and PASSWORD values on the appropriate Requester screen.

ACCOUNT and PASSWORD in the Requester screen match

ACCOUNT and PASSWORD values in the User Connection Account screen.

SECURITY=Y, the requester program sends the ACCOUNT and PASSWORD to the remote

SECURITY=N, the gateway attempts to make

Securing Outbound Connections from CICS to IMS

Complete the following tasks to enable the security feature for each outbound connection.

1. Specify

2. Enter Verify that the parameter values for

the When

IMS system on connection initiation. When connection without any verification.

SECURITY=Y on the appropriate Requester screen.

ACCOUNT and PASSWORD values on the appropriate Requester screen.

ACCOUNT and PASSWORD in the Requester screen match

ACCOUNT and PASSWORD values in the GATEWAY TYPE=REMOTE statement.

SECURITY=Y, the requester program sends the ACCOUNT and PASSWORD to the remote

SECURITY=N, the gateway attempts to make a

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

3. Set up security for the appropriate users on the target system.

SECURITY=Y on the appropriate Outbound Service screen.

3-6 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

CHAPTER

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 Use

Connection To monitor and control configured and active connections Requester To configure and maintain remote endpoints Outbound Service

Information User Connection Account To create and maintain user accounts Inbound Service Information To configure services residing locally that are accessed

Handler Configuration To configure and maintain the local endpoint

Each of these topics is discussed in more detail in the following sections.

To configure each remote service and specify which Requester to use for each service

remotely

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 BEAM M1

SELECTION SCREEN

TABLE OPERATION

---------------- -----------

C - CONNECTION 1 - INSERT R - REQUESTER 2 - UPDATE S - OUTBOUND SERVICE INFORMATION 3 - INQUIRE U - USER CONNECTION ACCOUNT 4 - DELETE I - INBOUND SERVICE INFORMATION 5 - BROWSE H - HANDLER CONFIGURATION

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

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 Area of Operation

Inbound Service Information Handler Configuration

The following table lists the codes for the allowable operations.

Table 4-3 Main Menu (BEAM) Operation Codes

Code Allowable Operation

Insert 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 Update Requester Inquire Requester Delete Requester

4-4 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Enter This Code To Access This Screen

The Main Menu

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 Definitions

ENTER

PF3

PF5

PF7

PF8

Note: If you enter data and press

process is aborted and the new screen is displayed.

Process the selection code entered Transfer to Main Menu Transfer to Connections Browse screen Display the previous page of records Display the next page of records

PF3 or PF5 before pressing ENTER, the current operation

Update Connection Screen (C2)

Use the UPDATE CONNECTION screen to update a record from the Connection file. When the screen initially displays, the valid

LOGICAL MACHINE NAME (gateway ID) and TYPE and press ENTER. The screen re-displays

showing the data from the record you specified and the

RECORD READY FOR UPDATE displays. You can now make changes to the record.

LOGICAL MACHINE NAME and TYPE fields are unprotected. Enter a

STATUS field is unprotected. The message

4-6 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

The Connection Screens

BEAPCON BEA TMA 10.0 TCP FOR CICS BEAM C2

UPDATE CONNECTION

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

TYPE

STATUS

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 service that the Requester is requesting.

For a Handler, this field name is number. The task number of the Handler is given in the

BEALOG.

The type of connection. Specify I for incoming connections or O for outgoing connections.

The status of the connection. Specify E to enable the connection. Specify complete prior to disconnecting. Specify A for immediate shutdown which aborts all initiated tasks and disconnects.

LMID associated with the

BEAH followed by the task

D for normal shutdown which allows initiated tasks to

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-7

Field Name Description

MAX MSG SIZE

REQUESTER TASK NUMBER

NUMBER REQUESTS

NUMBER SUCCESS REQS

NUMBER RECONNECTS

NUMBER OPEN SOCKETS

NUMBER SESSIONS ACTIVE

The largest message allowed to be sent across this connection. The maximum is 32000. Example: (31000)

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

For a Handler, this field is blank; the task number is part of the

LMID.

The number of service requests made during this connection. The number of successful communications.

The number of successful connections. The number of sockets that are currently opened by the

Requester. The number of active sessions on this connection.

LMID.

Inquire Connection Screen (C3)

Use this screen to inquire about a record from the Connection file. When the screen is initially displayed, the

MACHINE NAME

from the record you specified and the

LOGICAL MACHINE NAME and TYPE fields are unprotected. Enter a valid LOGICAL

(gateway ID) and TYPE and press ENTER. The screen is re-displayed with the data

LOGICAL MACHINE NAME and TYPE fields are unprotected.

4-8 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

The Connection Screens

BEAPCON BEA TMA 10.0 TCP FOR CICS BEAM C3

INQUIRE CONNECTION

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

TYPE

STATUS

This name is the gateway ID. Specify a unique name up to 16 characters. Example: (bankmach1)

For Requesters, this name is the service that the Requester is requesting.

For a Handler, this name is The task number of the Handler is given in the

The type of connection. I represents incoming connections or O represents outgoing connections.

The status of the connection. E means the connection is enabled. shutdown, which allows initiated tasks to complete prior to disconnecting. A means the connection shuts down immediately, aborts all initiated tasks, and disconnects.

LMID associated with the

BEAH followed by the task number.

BEALOG.

D means the connection is designated for a normal

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-9

Field Name Description

MAX MSG SIZE

REQUESTER TASK NUMBER

NUMBER REQUESTS

NUMBER SUCCESS REQS

NUMBER RECONNECTS

NUMBER OPEN SOCKETS

NUMBER SESSIONS ACTIVE

The largest message allowed to be sent across this connection. The maximum is 32000. Example: (31000)

For a Handler, this field is blank; the task number is part of the

LMID.

The number of service requests made during this connection. The number of successful communications. The number of successful connections. The number of sockets that are currently opened by the

Requester. The number of active sessions on this connection.

LMID.

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 to make an inquiry about a record, enter “

3”. If you enter more than one selection code, the first

SEL CDE field. For example,

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 BEAM C5

BROWSE CONNECTION

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, transmit s data to Oracl e 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 confi gure 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 LMID that is meaningful to you. Every service

name is associated with one machine is responsible for a particular service.

LMID. This method allows the Requester to know which remote

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 Function

ENTER

PF3

PF5

PF7

PF8

Note: If you enter data and press

aborted and the appropriate screen is displayed.

Process the selection code entered Transfer to Main menu Transfer to Requester Browse screen Display the previous page of records Display the next page of records

PF3 or PF5 before pressing ENTER, the operation process is

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 BEAM R1

INSERT REQUESTER

LMID: ________________ MULTIPLEX_CNT: __ DNS: ________________________________________________________________ HOST ADDRESS: _______________ PORT NUMBER: _____ MIN TIME (MILLISEC): _____ SECURITY(Y/N): _ MAX TIME (MILLISEC): _____ ACCOUNT ID: ________ DELTA TIME (MILLISEC): _____ PASSWORD: IDLE TIME (SECONDS): _____ REQ IDLE TIME (SECONDS): _____ MAX QUEUE SIZE: _____ LATENCY TIME (SECONDS): __ MAX MSG SIZE: _____ MAX CONNS: __ RETRY LIMIT: _____

LMID TYPE: _ QUEUE NAME 1: ________ START TRAN-ID: ____ QUEUE NAME 2: ________

CICS DATA: ___ AUTO ENABLE LMID(E/D): _

ENTER: PROCESS, PF3: MENU, PF5: BROWSE

Fields

Field Name Description

LMID

DNS

HOST ADDRESS

PORT NUMBER

SECURITY

This name is the logical machine name or gateway ID. Give it a unique name up to 16 characters. Example: (bankmach1)

The host name that the domain name service recognizes. The TCP/IP dot address. Example: (199.99.99.99) The TCP port. Check with the TCP/IP administrator for

available ports. Example: The status of connection-level security . Y specifies that

security is on and N denotes that security is off. Note: For additional security information, refer to the

(1234)

“Configuring the TMA TCP Security” section.

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-13

Field Name Description

ACCOUNT ID

PASSWORD

MAX QUEUE SIZE

MAX MSG SIZE

RETRY LIMIT

LMID TYPE

START TRANID

CICS DATA

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

PASSWORD field. Example: (CICS001A)

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 ID field.

Example: (LETMEIN2) 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).

The type of gateway the remote system is running (C for CICS, I for IMS, T for Tuxedo)

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 TIME to

MAX TIME.

4-14 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Field Name Description

The Requester Screens

IDLE TIME

REQ IDLE TIME

LATENCY TIME

MAX CONNS

QUEUE NAME 1

QUEUE NAME 2

AUTO ENABLE LMID(E|D)

The amount of time in seconds that a connection is idle before it is closed. IDLE TIME should be a smaller amount of time than REQ IDLE TIME. A typical setting is 30 seconds.

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

The unique name of a TS Q that is used for communications between the Pre-requester and the Requester.

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.

50 for IBM TCP/IP.

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 and press

HOST ADDRESS, PORT NUMBER, ACCOUNT ID, PASSWORD, MAX MSG SIZE, and CONNECT RETRY LIMIT

ENTER. The screen is re-displayed showing the data from the requested record. The

fields 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

LMID field is unprotected.

LMID field is unprotected. Enter a logical machine name

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-15

BEAPREQ BEA TMA 10.0 TCP FOR CICS BEAM R2

UPDATE REQUESTER

LMID TYPE: _ QUEUE NAME 1: ________ START TRAN-ID: ____ QUEUE NAME 2: ________

CICS DATA: ___ 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:

DNS

HOST ADDRESS

PORT NUMBER

The host name that the Domain Name Service recognizes. The TCP/IP dot address. Example: (199.99.99.99) The TCP port. Check with the TCP/IP administrator for availa ble

ports. Example: (1234)

SECURITY

The status of security. Y specifies that security is on and N denotes 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

(bankmach1)

Field Name Description

The Requester Screens

ACCOUNT ID

PASSWORD

MAX QUEUE SIZE

MAX MSG SIZE

RETRY LIMIT

LMID TYPE

START TRANID

CICS DATA

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

PASSWORD field. Example: (CICS001A)

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

(LETMEIN1)

ACCOUNT ID field. Example:

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)

The type of gateway the remote system is running (C for CICS, I for IMS, T for Tuxedo)

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

MAX TIME

DELTA TIME

IDLE 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. The maximum length of time (in millisecon ds) for a socket read to

wait for data to be processed. The time increase (in milliseconds) from MIN TIME to MAX

TIME

The amount of time in seconds that a connection is idle before it is closed. IDLE TIME should 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

LATENCY TIME

MAX CONNS

QUEUE NAME 1 The unique name of a TS Q that is used for communications

QUEUE NAME 2 The unique name of a TS Q that is used for communications

AUTO ENABLE LMID(E|D)

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

between the Pre-requester and the Requester.

between the Pre-requester and the Requester. 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.

50 for IBM TCP/IP.

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 and press

LOGICAL MACHINE NAME field is unprotected.

ENTER. The screen is re-displayed with the data from the requested record and the

LOGICAL MACHINE NAME field unprotected. Enter the logical machine name

4-18 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

The Requester Screens

BEAPREQ BEA TMA 10.0 TCP FOR CICS BEAM R3

INQUIRE REQUESTER

LMID TYPE: _ QUEUE NAME 1: ________ START TRAN-ID: ____ QUEUE NAME 2: ________

CICS DATA: ___ AUTO ENABLE LMID(E/D): _

ENTER: PROCESS, PF3: MENU, PF5: BROWSE

Fields

Field Name Description

LMID

DNS

HOST ADDRESS

PORT NUMBER

SECURITY

This name is the logical machine name or gateway ID. This name is a unique name up to 16 characters. Example:

The host name that the domain Name Service recognizes. 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) The status of security. Y specifies that secu rity is on and N denotes

that security is off. Note: For additional security information, refer to the

(bankmach1)

“Configuring the TMA TCP Security” section.

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-19

Field Name Description

ACCOUNT ID

PASSWORD

MAX QUEUE SIZE

MAX MSG SIZE

RETRY LIMIT

LMID TYPE

START TRANID

CICS DATA

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

PASSWORD field. Example: (CICS001A)

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

(LETMEIN1)

ACCOUNT ID field. Example:

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

The type of gateway the remote system is running (C for CICS, I for IMS, T for Tuxedo)

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 TIME to MAX

TIME

The amount of time in seconds that a connection is idle before it is closed.

REQ IDLE TIME. A typical setting is 30 seconds.

IDLE TIME should be a smaller amount of time than

4-20 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Field Name Description

The Requester Screens

REQ IDLE TIME

LATENCY TIME

MAX CONNS

QUEUE NAME 1

QUEUE NAME 2

AUTO ENABLE LMID(E|D)

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

The unique name of a TS Q that is used for communications between the Pre-requester and the Requester.

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.

50 for IBM TCP/IP.

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 name and press requested record and the displayed:

TO CONFIRM DELETE, PRESS ENTER AGAIN.

ENTER. The screen is then re-displayed with the data from the

LOGICAL MACHINE NAME field is protected. The following message is

LOGICAL MACHINE NAME field unprotected. Enter the

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-21

BEAPREQ BEA TMA 10.0 TCP FOR CICS BEAM R4

DELETE REQUESTER

LMID TYPE: _ QUEUE NAME 1: ________ START TRAN-ID: ____ QUEUE NAME 2: ________

CICS DATA: ___ 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

HOST ADDRESS

PORT NUMBER

The host name that the domain Name Serv ice re cogniz es. The TCP/IP dot address. Example: (199.99.99.99) The TCP/IP port. Check with the TCP/IP administrator

for available ports. Example:

SECURITY

The status of security. Y specifies 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

(1234)

Field Name Description

The Requester Screens

ACCOUNT ID

PASSWORD

MAX QUEUE SIZE

MAX MSG SIZE

RETRY LIMIT

LMID TYPE

START TRANID

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

PASSWORD field.

Example: (CICS001A) 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 ID field.

Example: (LETMEIN1) 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).

The type of gateway the remote system is running (C for CICS, I for IMS, T for Tuxedo)

The ID of the transaction to be started if the remote system type is CICS.

CICS DATA

MULTIPLEX CNT

MIN TIME

MAX TIME

DELTA TIME

A string to be passed to the IBM TCP/IP Listener for use with the TMA TCP for CICS gateway. The default is " ".

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. The maximum length of time (in milliseconds) for a

socket read to wait for data to be processed. The time increase (in milliseconds) from MIN TIME to

MAX TIME.

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-23

Field Name Description

IDLE TIME

REQ IDLE TIME

LATENCY TIME

MAX CONNS

QUEUE NAME 1

QUEUE NAME 2

AUTO ENABLE LMID(E|D)

The amount of time in seconds that a connection is idle before it is closed. IDLE TIME should be a smaller amount of time than REQ IDLE TIME. A typical setting is 30 seconds.

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

The unique name of a TS Q that is used for communications between the Pre-requester and the Requester.

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.

50 for IBM TCP/IP.

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 S example, to make an inquiry about a record, enter “ the first one is used and the others are ignored.

4-24 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

EL CDE field next to that record. For

3”. If you enter more than one selection code,

The Outbound Service Information Screens

After the entry in the SEL CDE field is validated and processed, the screen for that process is displayed and the record key appears in the

BEAPREQ BEA TMA 10.0 TCP FOR CICS BEAM R5

BROWSE REQUESTER

SEL LOGICAL MACHINE HOST PORT MAXM CONN LMID START CDE NAME ADDRESS NUM SIZE R-LIM TYPE TRNID

--- ---------------- --------------- ----- ----- ----- ---- -----

_ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____ _ ________________ _______________ _____ _____ _____ _ ____

* SELCDE = (1: INS, 2: UPD, 3: INQ, 4: DEL) ENTER: PROCESS, PF3: MENU, PF7: PREV, PF8: NEXT RECORD NOT FOUND

LOGICAL MACHINE NAME field.

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 LINK command 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 se rvice

name (such as, can make both names the same, but if naming conventions differ, you can use different names.

WITHDRAWL) is what the service is known as to Oracle Tuxedo. For simplicity, you

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 Function

ENTER

PF3

PF5

PF7

PF8

Note: If you enter data and press

aborted and the appropriate screen is displayed.

Process the selection code entered Transfer to Main menu Transfer to Browse screen Display the previous page of records Display the next page of records

PF3 or PF5 before pressing ENTER, the operation process is

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 data is validated and processed, the screen is re-displayed and all the fields are unprotected.

ENTER. After the

4-26 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

The Outbound Service Information Screens

BEAPSVC BEA TMA 10.0 TCP FOR CICS BEAM S1

INSERT 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

LOGICAL MACHINE NAME

REMOTE SERVICE NAME

SERVICE TIMEOUT

SECURITY

The service name as it is known to the CICS programmer. 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.

The name as it is known in the remote Oracle Tuxedo domain.

The number of seconds to wait for timing out this service request. The status of request-level security. Y specifies that security is on

and N denotes 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 NAME field is unprotected. Enter the service name and press ENTER. The screen is

then re-displayed with the data from the requested record and the

REMOTE SERVICE NAME, SERVICE TIMEOUT(SEC), and SECURITY fields are unprotected. The

following message is displayed:

RECORD READY FOR UPDATE.

LOGICAL MACHINE NAME,

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

LOGICAL MACHINE NAME

4-28 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

The service name as it is known to the CICS programmer. 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.

Field Name Description

The Outbound Service Information Screens

REMOTE SERVICE NAME

SERVICE TIMEOUT

SECURITY

The name as it is known in the remote Oracle Tuxedo domain.

The number of seconds to wait for timing out this service request. The status of security. Y specifies 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 NAME file. The screen is initially displayed with the

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

SERVICE NAME field unprotected. Enter the service name and press

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-29

Fields

Field Name Description

SERVICE NAME

LOGICAL MACHINE NAME

REMOTE SERVICE NAME

SERVICE TIMEOUT

SECURITY

The service name as it is known to the CICS programmer. 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.

The name as it is known in the remote Oracle Tuxedo domain.

The number of seconds to wait for timing out this service request. The status of security. Y specifies that security is on and N denotes

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 NAME field 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:

press enter to confirm the deletion, the screen is re-displayed and the unprotected.

TO CONFIRM DELETE, PRESS ENTER: AGAIN. After you

SERVICE NAME field is

4-30 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

The Outbound Service Information Screens

BEAPSVC BEA TMA 10.0 TCP FOR CICS BEAM S4

DELETE 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

LOGICAL MACHINE NAME

REMOTE SERVICE NAME

SERVICE TIMEOUT

SECURITY

The service name as it is known to the CICS programmer. 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.

The name as it is known in the remote Oracle Tuxedo domain.

The number of seconds to wait for timing out this service request. The status of security. Y specifies that security is on and N denotes

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 “ 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

BEAPSVC BEA TMA 10.0 TCP FOR CICS BEAM S5

BROWSE SERVICE NAME

SEL SERVICE LOGICAL MACHINE REMOTE SERVICE SERVICE CDE NAME NAME NAME TIMEOUT SEC

--- ---------------- ---------------- ---------------- ------- ---

_ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _ _ ________________ ________________ ________________ _____ _

* SELCDE = (1 -INS, 2 -UPD, 3 -INQ, 4 -DEL) ENTER: PROCESS, PF3: MENU, PF7: PREV, PF8: NEXT RECORD NOT FOUND

3”. If you enter more than one selection code, the first one is used, and the

SERVICE NAME field.

The User Connection ACCOUNT Screens

A Handler is responsible for receiving service requests from the remote Oracle Tuxedo domain. The User Connection connect with a Handler when a Handler is configured with security enabled.

4-32 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

ACCOUNT screens allow for dynamic manipulation of accounts allowed to

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 Function

ENTER

PF3

PF5

PF7

PF8

Note: If you enter data and press

aborted and the appropriate screen is displayed.

Process the selection code entered Transfer to Main menu Transfer to Browse screen Display the previous page of records Display the next page of records

PF3 or PF5 before pressing ENTER, the operation process is

Insert User Connection ACCOUNT Screen (U1)

Use this screen to add a new Connection ACCOUNT by 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 screen is re-displayed and all the fields are unprotected.

ENTER. After the data is validated and processed, the

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

PASSWORD

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

PASSWORD field. Example: (CICS001A)

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 ID field. 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

ACCOUNT field is unprotected. Enter the account ID, and press ENTER. The screen is then

re-displayed with the data from the requested record and the following message is displayed:

4-34 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

RECORD READY FOR UPDATE.

PASSWORD field is unprotected. The

The User Connection ACCOUNT Screens

After the changes are validated and processed, the screen is re-displayed and the ACCOUNT field 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

PASSWORD

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

PASSWORD field. Example: (CICS001A)

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 ID field. 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 is re-displayed with the data from the requested record and the

ACCOUNT field unprotected. Enter the ACCOUNT and press ENTER. The screen

ACCOUNT field 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

PASSWORD

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

PASSWORD field. Example: (CICS001A)

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 ID field. 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

ACCOUNT field 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

ACCOUNT field 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

PASSWORD

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

PASSWORD field. Example: (CICS001A)

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 ID field. 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 NAME (such as, CIC01XXYYZZ) is what the service is known as to your CICS

environment and the

4-38 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

REMOTE SERVICE NAME (such as, WITHDRAWL) is what the service is known

LOCAL SERVICE NAME and REMOTE SERVICE NAME. The

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 Function

ENTER

PF3

PF5

PF7

PF8

Note: If you enter data and press

aborted and the appropriate screen is displayed.

Process the data entered Transfer to Main menu Transfer to Browse screen Display the previous page of records Display the next page of records

PF3 or PF5 before pressing ENTER, the operation process is

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 is validated and processed, the screen is re-displayed and all the fields are unprotected.

ENTER. After the data

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

LOCAL SERVICE NAME

The service name as it is known in the remote Oracle Tuxedo domain.

The service name as it is known to the CICS programmer.

4-40 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Field Name Description

The Inbound Service Information Screens

TRANSACTION NAME

MAX MESSAGE SIZE

SECURITY

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 BEAA by 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

TPNOREPLY flag set must have a unique TRANSACTION

associated with it. Do not use the TRANSACTION

NAME NAME

for the Application Handler program or an error

message results.

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. Y enables security for the specified service and N disables security for the specified service.

tpacall with the

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

ENTER. The screen is re-displayed with the data from the requested record and the LOCAL SERVICE NAME, TRANSACTION NAME, MAX MESSAGE SIZE, and SECURITY fields unprotected.

The following message displays:

REMOTE SERVICE NAME field unprotected. Enter the remote service name and press

RECORD READY FOR UPDATE.

After the changes are validated and processed, the screen is re-displayed and the

SERVICE NAME

field is unprotected.

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-41

REMOTE

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

LOCAL SERVICE NAME

The service name as it is known in the remote Oracle Tuxedo domain.

The service name as it is known to the CICS programmer.

4-42 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Field Name Description

The Inbound Service Information Screens

TRANSACTION NAME

MAX MESSAGE SIZE

SECURITY

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 BEAA by 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

TPNOREPLY flag set must have a unique TRANSACTION

associated with it. Do not use the TRANSACTION

NAME NAME

for the Application Handler program or an error

message results.

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. Y enables security for the specified service and N disables security for the specified service.

tpacall with the

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 press

ENTER. The screen is re-displayed with the data from the requested record and the REMOTE

SERVICE NAME field unprotected.

REMOTE SERVICE NAME field unprotected. Enter the remote service name and

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

LOCAL SERVICE NAME

The service name as it is known in the remote Oracle Tuxedo domain.

The service name as it is known to the CICS programmer.

4-44 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Field Name Description

The Inbound Service Information Screens

TRANSACTION NAME

MAX MESSAGE SIZE

SECURITY

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 BEAA by 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

TPNOREPLY flag set must have a unique TRANSACTION

associated with it. Do not use the TRANSACTION

NAME NAME

for the Application Handler program or an error

message results.

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. Y specifies that security is on and N denotes that security is off.

tpacall with the

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

ENTER. The screen is re-displayed with the data from the record requested and all fields protected.

The following message displays:

ENTER to confirm the deletion, the screen is re-displayed and the REMOTE SERVICE NAME field

is unprotected.

REMOTE SERVICE NAME field unprotected. Enter the remote service name and press

TO CONFIRM DELETE, PRESS ENTER AGAIN. After you press

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

LOCAL SERVICE NAME

The service name as it is known in the remote Oracle Tuxedo domain.

The service name as it is known to the CICS programmer.

4-46 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide

Field Name Description

The Inbound Service Information Screens

TRANSACTION NAME

The name of the CICS transaction that is started to process this service request. This service request is usually the transac tion 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 unique it. Do not use the

TPNOREPLY flag set must have a

TRANSACTION NAME associated with

TRANSACTION NAME for

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. Y specifies that security is on and N denotes 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 NAME field.

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4-47

BEAPISN BEA TMA 10.0 TCP FOR CICS BEAM I5

BROWSE INBOUND SERVICE

SEL REMOTE SERVICE LOCAL SERVICE TRAN MAXM CDE NAME NAME NAME SIZE SEC

--- ---------------- ---------------- ---- ----- ---

_ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _ _ ________________ ________________ ____ _____ _

* 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

Table 4-8 Function Keys

Function Key Function

The Handler Configuration Screens

ENTER

PF3

Process the data entered Transfer to Main menu

Note: If you enter data and press PF3 before 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

MULTIPLEX COUNT: 99

MIN TIME (MILLISECS): 20

MAX TIME (MILLISECS): 30

DELTA TIME (MILLISECS): 5

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

MULTIPLEX CNT

MIN TIME

MAX TIME

DELTA TIME

IDLE TIME

The status of gateway security. Y denotes that security is activated and N denotes that security is not activ ated. If th is field is set t o N,

ACCOUNT and PASSWORD fields are not verified prior to

the establishing a connection.

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.

The maximum length of time (in milliseconds) for a socket read to wait for data to be processed.

The time increase (in milliseconds) from MIN TIME to 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 BEAM H3

INQUIRE HANDLER CONFIGURATION

SECURITY: Y

MULTIPLEX COUNT: 99

MIN TIME (MILLISECS): 20

MAX TIME (MILLISECS): 30

DELTA TIME (MILLISECS): 5

IDLE TIME (SECONDS): 0

ENTER: PROCESS, PF3: MENU

Fields

Field Name Description

SECURITY

MULTIPLEX CNT

MIN TIME

MAX TIME

The status of gateway security. Y denotes that security is acti vated and

N denotes that security is not activated. If this fi eld is se t to N,

ACCOUNT and PASSWORD fields are not verified prior to

the establishing a connection.

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.

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

IDLE TIME

The time increase (in milliseconds) from MIN TIME to MAX 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 the status of a connection has an immediate effect on the corresponding Requesters. For field definitions, refer to the “The Connection Screens” section.

LMID. Dynamically configuring

Note: Because the data in the Update Connection screen is transient, setting the

disable does not persist after the CICS region is shut down and then restarted. The Requester file, however, is persistent.

LMID status to

Deleting Requester LMIDs

Each instance of the Requester is given a logical machine name (LMID). You can give a Requester any unique

LMIDs. This method allows the Requester to identify which remote machine is responsible for a

particular service. You can dynamically delete an This dynamic change only affect Pre-requesters immediately.

Note: Requesters that are currently running do not read the information in the requester file and

LMID that is meaningful to you. Every service name is associated with one or more

LMID using the Update Requester screen (R2).

are not affected by this dynamic change.

Administering the Gateways

Oracle Tuxedo has a set of tmadmin and dmadmin commands 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

CHAPTER

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 LINK command. 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 LINK

Oracle TMA Administrator, but from a programming point of view the The following COBOL record is in the COBOL copybook

Listing 5-1 COBOL Record

01 REQUEST-RECORD. 05 REQUEST-HEADER. 10 DATALEN PIC S9(08) COMP. 10 SVCNAME[16] PIC X(16). 10 REQUESTCD PIC S9(08) COMP. 10 RETURNCD PIC S9(08) COMP. 10 REQRETURNCD PIC S9(08) COMP. 05 REQUEST-DATA. 10 DATA-AREA PIC X(DATALEN).

The layout of the structure in C that must be passed in the LINK call is shown in Listing 5-2. The following C structures are in the

call to the Pre-requester. The service you want to access must be configured by the

LINK call is all you need.

client.cbl.

clienth.h INCLUDE file.

Listing 5-2 C Structures

typedef struct CLIENTHDR { long DataLen; /* THE LEN OF THE DATA FROM AND TO APPL */ char SvcName[16]; /* THE SERVICE NAME */ long RequestCd; /* THE REQUEST COMMAND FROM THE APPL */ long ReturnCd; /* THE RETURN CODE TO THE APPL */ long ReqReturnCd; /* THE RETURN CODE FROM THE PREQ AND REQ */ } CLIENTHDR;

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_data field.

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 res ponse 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

BEA-REQUEST-RESPONSE

BEA-REQUEST-NORESPONSE

ReturnCd

+5. +7.

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

BEA-NORMAL

BEA-ERR-LENGTH

BEA-ERR-MISSING-SRV-NAME

BEA-ERR-REQ-CODE

BEA-ERR-SRC-NOT-FOUND

BEA-ERR-READ-UMT

BEA-ERR-SERVER

BEA-ERR-POST

BEA-ERR-CANCEL

BEA-ERR-WAIT

BEA-ERR-LMID-NOT-FOUND

BEA-ERR-START-TRANSID

BEA-ERR-DISABLE-ACQUIRING

BEA-ERR-DISABLE-NOT-FND

BEA-ERR-DISABLE-NOT-RESPOND

+0. +1. +2. +3. +4. +5. +6. +7. +8. +9. +10. +11. +12. +13. +14.

BEA-ERR-DISABLE

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

+15. +16. +17. +18. +19. +20. +21.

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 PIC X(42) VALUE SPACES. 05 M-RCDE PIC Z(05) VALUE ZEROS. 01 WS-COMMAREA. 05 WC-DATALEN PIC S9(9) COMP-4. 05 WC-SVCNAME 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 PIC X(14). LINKAGE SECTION. 01 DFHCOMMAREA PIC X(14). PROCEDURE DIVISION. A100-ENTRY. MOVE +14 TO WC-DATALEN.

Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide 5-5

MOVE 'TOLOWER' TO WC-SVCNAME. MOVE +5 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

memxxx calls were used instead of the strxxx calls. 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 ULOG file on the remote Oracle Tuxedo node and in the

BEALOG file (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 param eter 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 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.

BEALOG file.

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 LINK command.

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 returned to the client, chaining programs must pass the original that it may be

5-8 Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide

RETURNed to the TMA TCP for CICS Handler by the final program in the chain.

EXEC CICS XCTL operation. To ensure that the response data is

COMMAREA during the XCTL so

Server Application Considerations

Programming Services with a Response

Service programs expected to send a response to the client use the EXEC CICS LINK command to execute. The As a result, the request data is available to the service programs in the

COMMAREA option contains a pointer to the raw data; therefore, no header is sent.

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 START command. The FROM option of this command contains a pointer to the

raw data; therefore, no header is sent. As a result, such service programs must use an

RETRIEVE

Note: Define a unique transaction for each service that does not send a reply and enter the name

An example of a service sending no reply is one requested by a client using a tpacall with the

TPNOREPLY flag set.

command with the SET option containing a pointer to the raw data.

of that transaction in the screen for the corresponding service.

TRANSACTION NAME field of the Inbound Service Information

EXEC CICS

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 MESSAGE field of the Inbound Service Information screen. To limit the size of the return

message per request, the service program must include file delivered in the

"YOURHLQ".BEATCPC.INCLUDE file.

Modifying Return Message Lengths for C Programs

To modify the return message length on a per request basis, specify the message length in the

rtnMsgSize field in a TWA_CONNECT structure defined in the TWAINCL file.

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-SIZE field in a TWA_CONNECT record layout in the copybook TWACOPY.

Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide 5-9

ADDRESS the TWA using the copybook or the

5-10 Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide

APPENDIX

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

ULOG on that system.

Message Description

BEA TMA TCP for CICS server process initiated.

Welcome to BEA TMA TCP for MVS/CICS.

The Handler process has been started.

The connect process has completed success fully.

Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide A-1

Error and Informational Messages

Message Description

Goodbye.

Service svcname not found. The requested service was not found in the inbound service name file.

Client has already logged in.

The disconnect process has completed successfully.

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.

Data too short, please check message header.

Message header is incorrect.

A message received is larger than the maximum allowable message length.

A message was received and was smaller than the smallest expected message.

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

Oracle Audio Technologies Oracle Tuxedo User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual