Tib Ad Cics Users Guide

8/19/2019 Tib Ad Cics Users Guide

1/179

TIBCO Adapter™ for CICS

User’s Guide

Software Release 5.3 May 2008


2/179

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDEDOR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITEDADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLEDSOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FORANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF ALICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSEAGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USERLICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THESOFTWARE (AND WHICH IS DUPLICATED IN TIBCO ADAPTER FOR CICS USER’S GUIDE) OR IF THEREIS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT,THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT ISSUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTEACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws andtreaties. No part of this document may be reproduced in any form without the written authorization of TIBCOSoftware Inc.

TIB, TIBCO, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO Adapter, TIBCOHawk, TIBCO Designer, TIBCO Rendezvous, TIBCO Enterprise Message Service, TIBCO Runtime Agent, TIBCOAdministrator, TIBCO ActiveEnterprise and TIBCO Repository are either registered trademarks or trademarks

of TIBCO Software Inc. in the United States and/or other countries.EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems, Inc. in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALLOPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAMETIME. SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON ASPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BEINCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKEIMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED INTHIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING

BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 1999-2008 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information


3/179

TIBCO Adapter for CICS User’s Guide

| iii

Contents

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

TIBCO Adapter for CICS Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Third-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

How to Contact TIBCO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Adapter Components and Data Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Adapter Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Enterprise Server Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Preparing your Environment for Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Operating System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Pre-Installation Worksheet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Adapter Machine Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Installer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Upgrading the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Uninstalling the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Installation Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Installation History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Adapter Components and Compatible Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Adapter Run-Time Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Required and Optional TIBCO Products. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Installing on Microsoft Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Installing on Windows 2000 and 2003 Terminal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25


4/179


iv | Contents

Installing the Adapter on Microsoft Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Combining Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3 Configuring the CICS Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Storage Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

General CICS Adapter and Operating System Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

z/OS Enterprise COBOL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Distribution and Software Contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Complete Replacement Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Component Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Installation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

TIBCO CICS Adapter MVS Installation Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Uploading the Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Initial Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Receiving the Initial Installation File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

TIBCO CICS Adapter MVS Installation Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Optional CICS Adapter Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Enabling the IBM CICS TCP/IP Socket Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Using SXNR versus SXND Transaction ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Verifying Connectivity to TIBCO Relay Server with CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Security Considerations for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

CICS Security using TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Sanity Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43TIBCO Adapter Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

TIBQ Error/Trace Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapter 4 Configuring the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Create a New Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

TIBCO Designer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Create an Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Specify the CICS Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Add a Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Configure the RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Save and Deploy the Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

List of Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69


5/179


Contents |v

Chapter 5 Deploying the Adapter Using TIBCO Administrator Enterprise Edition . . . . . . . . . 71

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Create an EAR File in TIBCO Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Deploy the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Monitor the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Chapter 6 Deploying the Adapter Using TIBCO Administrator . . . . . . . . . . . . . . . . . . . . . . . . . 76

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Export the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Create a Properties File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Set Properties in Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Assign Security Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Start the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Stop the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Monitor the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Adapter Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Properties File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Predefined Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Encrypting a Password in the Properties File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Server Repository URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

TIBCO Rendezvous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

HTTP and HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Defining a urlFile to be Accessed via HTTPS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Local Project URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Install the Adapter as a Service on Microsoft Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Chapter 7 Conversion Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

General Conversion Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Mappings from COBOL PIC clause to TIBCO scalars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Chapter 8 Monitoring the Adapter Using TIBCO Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Starting TIBCO Hawk Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Starting TIBCO Hawk Software on Unix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Starting TIBCO Hawk Software on Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

The Auto-Discovery Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108


6/179


vi | Contents

Invoking Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Standard Microagents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Custom Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Appendix A Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Appendix B Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Appendix C Troubleshooting Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

General Problem Diagnosis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Connection failures to CICS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Cannot Properly Connect to CICS Server: Additional Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Login from the Adapter to CICS Server Fails. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

CICS Program Execution Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Incorrect CICS Program Input or Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

RPC Operation call is rejected with a "Config Error" Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Problem Diagnosis Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Appendix D Pre-Configured Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Running the Pre-Configured Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Before Starting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Converting Dat Files to Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Updating the Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Running the Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163


7/179


|vii

Tables

Table 1 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Table 2 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Table 3 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Table 4 Adapter Machine Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Table 5 TIBCO Adapter components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Table 6 Required and Optional TIBCO Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Table 7 Supported platforms, package names, service packs and disk space for Microsoft Windows . . . 24

Table 8 Installed Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Table 9 Adapter Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Table 10 TIBCO Administrator Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Table 11 Adapter Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Table 12 Predefined Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Table 13 Optional properties for server-based URL (TIBCO Rendezvous) . . . . . . . . . . . . . . . . . . . . . . . . . 91

Table 14 Optional properties for server-based URL (HTTP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Table 15 Properties Required for HTTPS urlFiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Table 16 Optional parameters for local project URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Table 17 COBOL to TIBCO ActiveEnterprise Conversion Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Table 18 Standard Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Table 19 Custom Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Table 20 Points of Failure in a Client/Server Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148


8/179


viii | Tables


9/179

TIBCO Adapter for CICS User's Guide

| ix

Preface

This manual explains how to install, operate and monitor the TIBCO Adapter™for CICS. It is intended for application administrators and developers who areresponsible for integration tasks. This manual assumes you are familiar with bothTIBCO Rendezvous™ and the z/OS CICS environment.

Topics

• Related Documentation, page x

• Typographical Conventions, page xii

• How to Contact TIBCO Support, page xiv


10/179


x | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Adapter for CICS Documentation

The following documents form the TIBCO Adapter for CICS documentation set:

• TIBCO Adapter Concepts Read this manual to gain an understanding ofadapters in general that you can apply to the various tasks you mayundertake.

• TIBCO Adapter for CICS User’s Guide Read this manual for instructions onhow to install, configure, deploy and run the product.

• TIBCO Adapter for CICS Release Notes Read the release notes for a list of newand changed features. This document also contains lists of known issues and

closed issues for this release.

Other TIBCO Product Documentation

You may find it useful to read the documentation for the following TIBCOproducts:

• TIBCO Rendezvous software: This is TIBCO’s real-time transport layer that is

used by TIBCO Adapter for CICS software.

• TIBCO Adapter SDK software, including TIBCO Designer™ and TIBCORepository™: These related products are used to configure and manageTIBCO ActiveEnterprise™ data and metadata.

• TIBCO Hawk® software: This application provides network monitoring.TIBCO Adapter for CICS software integrates with TIBCO Hawk software.

Third-Party Documentation

You can find many of the IBM documents in these CD-ROM sets:

• Online Library Omnibus Edition MVS Collection


11/179


Preface |xi

• Online Library Omnibus Edition z/OS Collection

Table 1 Related Documents

Publication Title Form Number

IBM RACF User’s Guide SC23-3728

IBM RACF Messages SC23-3730

IBM RACF System Programmer’s Guide SC23-3725

IBM TCP/IP for MVS: Messages and Codes SC31-7132

IBM TCP/IP for MVS: Customization and AdministrationGuide

SC31-7134

IBM TCP/IP for MVS: User’s Guide SC31-7136

IBM TCP/IP Performance Tuning Guide SC31-7188

IBM TCP/IP for MVS: Planning and Migration Guide SC31-7189

IBM ISPF Dialog Developers Guide and Reference SC34-4486

IBM TSO/E CLISTS SC28-1876

IBM REXX/370 User’s Guide SH19-8160

IBM Online Library Omnibus Edition z/OS Collection SK2T-6700


12/179


xii | Typographical Conventions

Typographical Conventions

The following typographical conventions are used in this manual.

Table 2 General Typographical Conventions

Convention Use

code font Code font identifies commands, code examples, filenames, pathnames, andoutput displayed in a command window. For example:

UseMyCommand

to start the foo process.bold code

font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin.

• In large code samples, to indicate the parts of the sample that are ofparticular interest.

• In command syntax, to indicate the default parameter for a command. For

example, if no parameter is specified, MyCommand is enabled:MyCommand [enable | disable]

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO BusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain severalportlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace.For example: MyCommand pathname

Keycombinations

Key name separated by a plus sign indicate keys pressed simultaneously. Forexample: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after theother. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, forexample, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to applythe information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example,

data loss or corruption if certain steps are taken or not taken.


13/179


Preface |xiii

Table 3 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical ’OR’ that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:MyCommand para1 | param2 | param3

{ } A logical group of items in a command. Other syntax notations may appearwithin each logical group.

For example, the following command requires two parameters, which can beeither the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parametercan be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters.The first parameter must be param1. You can optionally include param2 as thesecond parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}


14/179


xiv | How to Contact TIBCO Support

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, pleasecontact TIBCO Support as follows.

• For an overview of TIBCO Support, and information about getting startedwith TIBCO Support, visit this site:

http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a username, you can request one.

|1

http://www.tibco.com/services/supporthttps://support.tibco.com/https://support.tibco.com/http://www.tibco.com/services/support


15/179


|1

Chapter 1 Introduction

This chapter provides an overview of the TIBCO Adapter for CICS product,discusses its main features and describes how the various components aredesigned.

Topics

• Overview, page 2

• Features, page 5

• Adapter Components and Data Flow, page 7

• Enterprise Server Components, page 11

2 | Chapter 1 Introduction


16/179



Overview

TIBCO Adapter for CICS is part of the TIBCO ActiveEnterprise suite of products,that provides a modular, event-driven approach to the distribution andintegration of information across multiple platforms and applicationenvironments. The Adapter allows ActiveEnterprise applications to request datafrom CICS applications that are running on the z/OS Enterprise Server systems.Upon receiving a request from an ActiveEnterprise application, the Adapterperforms any necessary data mapping and then initiates the appropriateoperation with the z/OS region on the z/OS system. Upon receiving a response

back from the CICS application, the Adapter performs the data mapping and thenroutes the results back to the calling application.

The Adapter is designed with the TIBCO Adapter SDK and uses the standardTIBCO Designer and TIBCO Repository facilities for performing configurationand administrative chores. The Adapter supports the sequential execution ofmultiple operations thus allowing complex requests to be processed via TIBCOIntegrationManager™ or TIBCO BusinessWorks™. Support is also provided for

TIBCO Hawk so that the appropriate sinks can be defined that assist in thetracking and resolution of error conditions.

TIBCO Adapter for CICS functions as a TIBCO Rendezvous synchronousRequest-Response server (RPC server) where applications invoke operations andget return values via messages that are routed using subject-based addressing.Multiple adapter instances can run concurrently on the same network and eachinstance can maintain multiple TIBCO Rendezvous sessions. The followingdiagram shows the interaction between the Adapter, the CICS region and

application software environments:

Overview |3


17/179


Overview |3

Figure 1 TIBCO Adapter for CICS Architecture

The TIBCO Adapter for CICS provides two-way communication between TIBCOActiveEnterprise applications and the CICS region using a request/reply model.The Adapter sends and receives messages in ActiveEnterprise wire format thatincludes control information in header fields. The TIBCO ActiveEnterpriseoperation is essentially translated into a Distributed Program Link (DPL/ECI) callto the target CICS system. The Adapter executes this call on the correspondingCICS ECI programs and awaits the results. Upon receipt, the results are set in theassociated return value for the invoked operation and the resulting data is thenmade available to the calling application.

The Adapter exchanges data with the CICS via a memory buffer structurereferred to as a COMMAREA. Message data generated by ActiveEnterpriseapplications is translated into the fixed format that is required by CICS and isthen assigned a COMMAREA where it can be retrieved by the CICS application.

The results that are generated by the CICS system are then returned to theAdapter via the COMMAREA.

Schema files that are set up during the configuration process determine thestructure of inbound and outbound data. These schemas provide data format anddata description information used by the Adapter to transform data beforepassing it between the TIBCO ActiveEnterprise application and the CICS system.The metadata is defined in the TIBCO Repository where every CICS ECI programabstraction has two corresponding schemas that define the operations that aresupported by the object and the data structures used as parameters for calling

Application Application

Publish/Subscribe

Network

TIBCO Hawk

TIBCO Adapter

for CICS

TIBCORepository

CICS

TIBCO Rendezvous



18/179



operations on the object. To assist in the process of creating the necessary schemasfor your site, a special utility is provided with the Adapter that automatically setsup the mappings based on the data in the COBOL copybook that is used by the

CICS application on the z/OS system.

Features |5


19/179


|

Features

TIBCO Adapter for CICS offers the following main features:• Transparently passes message requests from ActiveEnterprise applications to

the CICS system and returns the results.

• Provides multi-threaded execution for fast and efficient message processing.

• Built-in message conversions based on the data mappings that are stored inthe repository.

• Provides a standard means of configuring, operating and monitoring theAdapter based on the ActiveEnterprise suite of products.

• Supports TIBCO Rendezvous Reliable message delivery.

• Includes comprehensive CICS Distributed Program Link support.

• Provides integration with TIBCO Hawk for monitoring and error resolution.

• Provides logging facilities for tracking transactions and fine tuning data

processing operations.

TIBCO ActiveEnterprise Compliant

The Adapter is designed with the TIBCO Adapter SDK and uses the standardTIBCO Designer and TIBCO Repository facilities for performing configurationand administrative chores. The Adapter supports the sequential execution ofmultiple operations thus allowing complex requests to be processed via TIBCO

IntegrationManager or TIBCO BusinessWorks. Support is also provided forTIBCO Hawk, which is useful in the tracking and resolution of error conditions.

Multi-threaded Performance

TIBCO Adapter for CICS maintains a pool of threads for performing tasks so itcan respond to and process multiple events in a simultaneous manner. Forexample, after event processing begins, status messages are exchanged between

the Adapter and the CICS software. Multithreading enables the Adapter to trackand communicate event status without affecting other processing.

CICS Distributed Program Link Support

The CICS Distributed Program Link (DPL) support or External Call Interface(ECI) as it is sometimes called, allows the Adapter to call a CICS program runningon a Enterprise Server, as a subroutine. The Adapter communicates with the

server CICS program using a data area called a COMMAREA, which serves as a



20/179


|

buffer where data can be exchanged. The COMMAREA is passed to the CICSserver on the call, and the CICS program typically populates it with data accessedfrom files or databases, which is then returned to the client for manipulation or

display.

ImportCopyBook Utility

The ImportCopyBook utility converts COBOL copybooks into the AE Schemas inthe TIBCO Designer. These COBOL copybooks represent the COMMAREAdefinitions in a CICS program.

The ImportCopyBook utility creates all of the necessary schemas needed to

convert data types between ActiveEnterprise applications and the CICS system.

Exception Handling

During event processing, the Adapter provides ongoing and comprehensivestatus notification including status messages and errors. The Adapter transcribesthese notifications in the same manner as CICS ECI invocations and sends them

back to the initiating system as an RPC Exception. The high level of status and

error visibility gives both applications and CICS logs full access to errorinformation. This feature helps synchronize applications and CICS software withregard to the status of operations and the state of data in the database.

Logging

TIBCO Adapter for CICS logging capabilities are provided by the TIBCO AdapterSDK. Using a standard set of tracing features, information can be routed to anapplication, a TIBCO Hawk agent or a standard file channel. You can control theamount of information sent and its destination by modifying the appropriatesettings in the adapter configuration file. TIBCO Hawk methods also provideaccess to trace settings.

Adapter Components and Data Flow |7


21/179


|

Adapter Components and Data Flow

TIBCO Adapter for CICS software is composed of set of components that performvarious functions as follow:

Figure 2 TIBCO Adapter for CICS Components

Adapter Components

CICS Custom Adapter Event Handler

The Event Handler component processes events that are posted to it by the TIBCO

Adapter SDK. Most of the events will be for incoming messages directed todesignated RPC operations, which have been defined to be routed to CICS. Whena designated message arrives, the event handler receives the associated MTree(AE message) and invokes the Message Mapper and XDR Data Conversionmodules, based upon configuration and Metadata information defined for thatRPC operation.

T I B C O A d a p t e r fo r C I C S

R u n T i m e

C I C S

E v e n t

H and le rs

A c ti veEn te rp r i se

M essa ges

M essa ge

M appe r

LA N T C P

I/O D rive r

IB M

T C P / I P

EC I D a ta

C ICS TC P

T r a n S t a r t

E C I D ata C

S

K

L

TIB C O

R e lay

X a c t i o n

U s e r

E C I

A p p

T r a n S t a r t S e c u r i ty

M od ule

R e p o s i t o r y

M s g M a p s

C O M M

A re a



22/179


Message Mapper Module

The Message Mapper Module converts incoming TIBCO ActiveEnterprisemessage fields (MTrees) into a designated Input COMMAREA for the CICS

transaction associated with that RPC operation. It also converts the replyCOMMAREA from the CICS transaction into an outgoing TIBCO Adapter MTree(RV or AE) reply message. Message mapping is driven by the TIBCO Adaptermessage map Metadata information, supplied from the Repository.

LAN TCP I/O Driver

The LAN TCP I/O Driver performs all TCP I/O between the Windows system

and CICS. It issues the CICS Transaction Start messages to start a transaction onCICS and sends the associated COMMAREA. It also receives the reply messagefrom the CICS transaction, including any reply COMMAREA. It passes anyreplies to the Message Mapper Module for processing. All data (program name,COMMAREA data, lengths, return codes) that are sent to and received from theEnterprise Server are in S/370 (EBCDIC, big endian) format.

Threads SupportThe TIBCO Adapter SDK automatically provides multi-threaded support. TheAdapter uses one thread per connection to CICS. Each TIBCO ActiveEnterpriseclient is associated with a specific thread and connection to CICS. Configurationparameters set the maximum limit of concurrent connections that can be active forthe Adapter.

Admin SupportThe TIBCO Adapter SDK obtains configuration information from the Repositoryand supplies it to the Adapter. It also provides Listener support for TIBCO Hawkadministrator events.

Tracing and Event Logging

Standard TIBCO Adapter tracing facilities are provided for tracking all TCP I/Oto CICS, TIBCO ActiveEnterprise messages that are sent or received, and all majorcalls.

Repository Message Maps

The Adapter uses a set of Message Maps to perform conversions between theCICS COMMAREA and TIBCO ActiveEnterprise messages. These Message Mapsare stored in the TIBCO Repository.

Adapter Components and Data Flow |9


23/179


Request-Response Service

The Adapter request-response service (RPC Server) subscribes to messages basedon the subject that is defined in its configuration. It listens for operation requests

and passes them onto the in-memory objects. The definition for an RPC server can be made to serve one or more class operations. For every operation served by theserver, there is a corresponding in-memory object that executes the CICSDPL/ECI call. The RPC Server uses the services of the connection manager andthe API library manages errors for the sub system and forwards error indicationsto the error module.

The steps involved in the execution of the CICS DPL/ECI call are as follows:

1. Get a connection.

2. Begin the transaction based on the connection.

3. Covert the incoming data to CICS format.

4. Call the CICS library API to execute the operation.

5. Convert the returned data to the TIBCO message format.

6. Execute a Commit or Rollback based on the success of the transaction.7. Release the connection.

Note: Every request has a predefined parameter called "server-id" in therepository. Based on the server-id, the RPC server queries the connectionmanager to get the CICS server identity.

Error Logging Module

The Error Logging Module is a standard feature of the TIBCO Adapter SDK and isimplemented through the Application Manager. The TIBCO Hawk Implant is alsoa standard feature provided by the Application Manager. For more informationabout TIBCO Adapter SDK, see TIBCO Adapter SDK Concepts. For moreinformation about TIBCO Hawk, see the TIBCO Hawk Administrator's Guide.

TIBCO CICS Error Log

Errors detected by the SXNCRLAY program are written to the "TIBQ" TD Queueunder CICS.

Data Flow

The Adapter processes data between ActiveEnterprise applications and the CICS

system according to the following series of steps:



24/179


1. Upon receipt of a message, via the TIBCO Adapter SDK run-time componenton the LAN, the Adapter converts the Rendezvous message into aself-describing (in-memory), MTree structure.

2. The Adapter passes the request to the Event handler module, that locates theMetadata information that was defined for the RPC operation and transaction,and forwards the Metadata information and the MTree (TIBCOActiveEnterprise message fields) to the Message Mapper module.

3. The Message Mapper module maps the incoming MTree into a COMMAREAstructure that has been defined for the CICS transaction associated with themessage.

4. The Message Mapper module passes the COMMAREA, and associatedtransaction id, userid, and password to the LAN TCP I/O module.

5. The LAN TCP I/O module issues a CICS TCP Transaction Start header toinvoke the CICS based TIBCO "relay module". It also passes in the name of thetarget user CICS program that is to be invoked and the associatedCOMMAREA ("ECI Data").

6. The TIBCO relay transaction is invoked on the CICS system, which then readsthe CICS user program name and the COMMAREA from the LAN. The relaytransaction then invokes the designated user CICS application via an EXECCICS LINK and passes it the COMMAREA. The CICS based TIBCO relaymodule passes the COMMAREA but does not perform any data conversionsor manipulation of the buffer.

7. The CICS application performs its function and then returns the results. TheTIBCO relay transaction sends the contents of the modified COMMAREA

back to the LAN TCP I/O module.

8. The LAN TCP I/O module passes the reply COMMAREA back to theMessage Mapper module.

9. The Message Mapper module maps the reply COMMAREA into a TIBCOActiveEnterprise ReplySubject message (MTree) based upon Metadatainformation supplied from the Repository's message maps.

10. The Adapter run-time support passes the message for delivery to therequesting TIBCO ActiveEnterprise application.

Enterprise Server Components |11


25/179


Enterprise Server Components

The Adapter works in conjunction with a CICS interface component that operateson the z/OS system. Following are descriptions for these Enterprise Servercomponents.

CICS TCP Listener (CSKL)

CSKL is the standard CICS Listener component supplied by IBM. It accepts TCPTran Start headers and invokes the designated CICS transaction program.

Tran Start Security Module

The Tran Start Security Module is a TIBCO supplied assembler module that doesan EXEC CICS VERIFY for any User Id and Password that is received on a TCPTran Start request. It is automatically called by CSKL when a Tran Start requestarrives. This module uses the UserId/Password that is passed via the LAN by theAdapter but does not do any form of user id or password mapping on the

Enterprise Server side.

TIBCO Relay Transaction

The TIBCO Relay Transaction reads and processes the data message sent by theLAN TCP I/O component. The message contains the name of the user program toinvoke, connection flags, the length of the input COMMAREA and the actualcontents of the input COMMAREA itself.

The Relay Transaction issues an EXEC CICS LINK to the user program, passing itthe received COMMAREA. When the user program returns, the Relay transactioncreates a return message containing a return code (ok or failed), the length of thereply COMMAREA, and the actual contents of the output reply COMMAREA.

It then sends this reply message back to the LAN TCP I/O component. If the userprogram Abends or does not exist, an error return code and an (EBCDIC) errortext message is sent back to the LAN TCP I/O component.

Based upon the connection flags that were received on the input message, theRelay transaction either terminates (and closes the TCP connection), or remainsactive and waits for another program name and input COMMAREA message.

User ECI Application

The Adapter supports communications with any user written CICS application

(COBOL, PL/1, Assembler, C/370) that uses a COMMAREA for its input andoutput, and is designed to be called via EXEC CICS LINK invocation.



26/179


|13


27/179


Chapter 2 Installation

This chapter explains how to install TIBCO Adapter for CICS. Chapter 3,Configuring the CICS Component explains how to configure the MVS CICScomponents that are required by the Adapter to begin processing data for TIBCORendezvous applications.

Topics

• Preparing your Environment for Installation, page 14

• Pre-Installation Worksheet, page 16

• Installer Overview, page 17

• Installation Registry, page 19

• Adapter Components and Compatible Software, page 20

• Installing on Microsoft Windows, page 24

This software may be available on multiple operating systems. However, notall operating system platforms for a specific software version are released at thesame time. Please see the readme.txt file for the availability of this softwareversion on a specific operating system platform.

14 | Chapter 2 Installation


28/179


Preparing your Environment for Installation

The most time-consuming part of an adapter installation is the collection ofenvironment information and parameters. This section helps you complete thisprocess. It provides a check list of parameters you should obtain from varioussystem administrators within your organization before installing the adapter.

Operating System Requirements

Obtain the following information from the administrator of the machine on whichyou plan to install the adapter:

Username and password to access the system and run the adapter:

Do you have the required credentials to run the installer?

• On Microsoft Windows, administrator privileges are required to install.

• Note that the TIBCO Runtime Agent (TRA) must be installed prior toinstalling the adapter and the adapter installation always places files underthe TIBCO root directory that was set when the TRA was installed.

Is there enough space on that disk or partition to install the adapter? The adapterneeds space in your temp area and the directory where it is installed.

• See Installation Registry on page 19 for details about temp folder space

requirements on Microsoft Windows.• See Table 7 on page 24 for Microsoft Windows installations.

You must have write permissions to these directories to install the adapter.

• To run the adapter you must have permissions to access the project whereadapter configuration is stored.

• Depending on whether TIBCO Administrator is used to set access

permissions, you may need an account identified by Administrator. See theTIBCO Administrator User’s Guide for details.

System name:

System IP address:

Username:

Password:

Preparing your Environment for Installation |15


29/179


Determine how the adapter installation files are to be transferred to this system.The installation files can be downloaded from download.tibco.com (if you havean account setup to download). Do you plan to use FTP, NFS, HTTP, or installfrom a CD?



30/179


Pre-Installation Worksheet

Use this form to capture the information you will need to collect before startinginstalling the adapter.

Adapter Machine Information

Table 4 Adapter Machine Information

Field Name Field Description Field ValueHostname

(Example:adapter1.tibco.com)

Name of the machine on which theadapter is being installed.

IP address

(Example: 192.168.12.12)

IP address of the machine on whichthe adapter is being installed.

User account

(Example: administrator)

User account to be used for theinstallation.

User domain (if Windows)

(Example: ENGR2)

Network domain to which the user belongs.

User password

Disk and path on which toinstall adapter

(Example: /opt/tibco)

How will machine beaccessed

[ ] directly [ ] terminal server [ ] xterm [ ] telnet

[ ] other: ………………………

How will installation files betransferred to machine

[ ] CD-drive [ ] internet download [ ] FTP to machine

[ ] network disk mounting

Installer Overview |17


31/179


Installer Overview

The installer allows you to run it in different modes. Each mode is supported onall platforms.

• GUI mode

• Console mode

• Silent mode

GUI ModeIn GUI mode, the installer presents panels that allow you to make choices aboutproduct selection, product location, and so on. When you invoke the installer bydouble-clicking on the icon, GUI mode is used.

Console Mode

Console mode allows you to run the installer from the command prompt or

terminal window. This is useful if your machine does not have a Windowsenvironment.

Silent Mode

Silent mode either installs using default settings or uses a response file that wassaved during an earlier installation. Silent mode installs without prompting youfor information.

• If no response file has been recorded earlier and you invoke the installer withthe -silent argument, the default installation parameters are used.

• If a response file exists, and the installer is started with -options as an argument, the installer uses the values specified by theuser when the response file was generated.

Upgrading the Adapter

Software from TIBCO uses three numbers to indicate whether the release is major,minor or a patch. For example, 5.0.0 indicates a major release, 5.1.0 indicates aminor release and 5.1.1 indicates a patch release. The installer for a patch releaseperforms an automatic upgrade. For example, the installer automaticallyupgrades a 5.0.0 release to 5.0.1 by overwriting the contents of the 5.0 directory.



32/179


For a major and minor release, the installer prompts whether you wish toupgrade, and informs you if incompatible products are on your system. If youproceed, major or minor releases are installed under a new directory that isnamed using the major or minor release numbers.

For example, if you have installed the 5.0.0 release and are upgrading to a 5.1.0minor release, it will be installed under the 5.1 directory. This allows both the 5.0and 5.1 releases to coexist on the same machine.

If you are upgrading the adapter, or reinstalling a clean version of the software,you may uninstall the product first or allow the installer to perform the upgradeor reinstall.

Note that, if you are reinstalling over the same adapter version:• You are not prompted to supply the installation location. The software is

automatically reinstalled where the previous version was installed.

• If any files are currently locked (that is, in use), the installer marks the file fordeletion in the install location. After installation, the installer prompts you toreboot your system. You must reboot before using the software.

Uninstalling the Adapter

The TIBCO Installation Manager (TIM) allows you to:

• Display installed products

• Display product components

• Display product dependencies and references

• Uninstall products and all references

To start the program on Microsoft Windows:

Click Start>TIBCO>TIBCO Installation Manager

The TIBCO Installation Manager displays all TIBCO software installed on yourmachine. Details about the selected TIBCO product are displayed in the rightrows. Click the Uninstall button to remove the selected product. Note that some

products cannot be installed from the utility. Instructions about uninstalling theseproducts are listed in the uninstall window (after clicking the Uninstall button).

Click the TIBCO Installation Manager help button for information about using theprogram.

Installation Registry |19


33/179


Installation Registry

The installer maintains an installation registry. The registry location depends onthe platform. This section explains where the registry files are located. The fileshave vpd as a prefix, which stands for Vital Product Database. Note that theinstaller does not recognize TIBCO ActiveEnterprise 4.x products.

Microsoft Windows Platforms

ActiveEnterprise products maintain the installation registry in the %SystemRoot% folder. The following files represent the installation registry:

%SystemRoot% \vpd.properties%SystemRoot% \vpd.properties.tibco.systemName

Installer Disk Space Requirements in Temporary Area

The entire package is extracted into a temp folder, typically SystemDrive:\Tempor SystemDrive:\Documents and Settings\\LocalSettings\Temp.

The installer requires 9.23 MB of free space in the temp directory.

Installation History

The installer and uninstaller creates a file calledTIBCOInstallationHistory.xml in the same location where the installationregistry is created (i.e., the %SystemRoot% folder). Each time an installation anduninstallation is performed, entries are appended to the file.

The file TIBCOInstallationHistory.xml therefore contains the record of allinstallation and uninstallation activities of all products, features and components.

Do not edit, modify, rename, move, or remove any of the registry vpd files.

Do not edit, modify, rename, move, or remove theTIBCOInstallationHistory.xml file.



34/179


Adapter Components and Compatible Software

The TIBCO Adapter SDK provides the run-time environment for the Adapter. Itprovides access to Repository configuration and Metadata information,automatically packs and unpacks TIBCO Rendezvous messages into MTrees,provides multi-threading support, provides tracing facilities, and includes TIBCOHawk administrative hooks.

Installing Adapter Components

You can install different adapter components on different machines. For example,you can install the run-time adapter on one machine and install the design-timecomponents on another machine. This allows you to configure an adapter on onemachine and run it on another.

You can install adapters as part of a TIBCO administration domain. Forinformation about administration domain, see your TIBCO BusinessWorks Administrator’s Guide. Adapters can also be installed standalone, independent ofBusinessWorks.

Adapter Run-Time Components

Table 5 describes the adapter components on the adapter installation package.

Table 5 TIBCO Adapter components

Component

Run-time adapter Provides the runtime service for executing adapter configuration instancescreated with TIBCO Designer. Parameters of data exchanges are stored inprojects created using the adapter palette and the design-time adapter (see

below).

Adapter palette Adapter-specific GUI that is loaded in TIBCO Designer (see next section fordetails) at configuration time.

Adapter Components and Compatible Software |21

R i d d O ti l TIBCO P d t


35/179


Required and Optional TIBCO Products

Depending on the tasks you wish to perform, you must install one or more otherTIBCO products. The next table describes required and optional products and

their purpose.

Table 6 Required and Optional TIBCO Products

Component Purpose

TIBCO Runtime Agent(TRA)

Required. TIBCO Runtime Agent supplies a number of TIBCO andthird-party libraries used by the adapter and other TIBCO products bothat design-time and runtime. This includes, for example, TIBCO

Rendezvous software.You must install TIBCO Runtime Agent on each machine that hosts anadapter. TIBCO Runtime Agent must be installed before you install theadapter.

In a TIBCO BusinessWorks installation, TRA communicates with theTIBCO Administration Server. In a standalone installation, TRA providesconnectivity to other applications configured for the TIBCO

environment.

TIBCO Designer Required. TIBCO Designer is an easy to use graphical user interface fordesign-time configuration of TIBCO adapters.

TIBCO Designer is installed as part of the TIBCO Runtime Agentinstallation.

Using TIBCO Designer, developers create a project, add components to it

with a simple drag-and-drop interface, and specify the configurationinformation for each component.

When a new TIBCO product is installed, TIBCO Designer palettes areinstalled if TIBCO Designer is already installed on the machine. The nexttime TIBCO Designer is launched, the palettes become automaticallyavailable.


T bl 6 R i d d O ti l TIBCO P d t


36/179


TIBCO Administrator Required. TIBCO Administrator is available in two editions, RepositoryEdition and Enterprise Edition. You must install either edition. TheRepository Edition does not include the Application Managementmodule. Enterprise Edition is required if you are using the adapter withTIBCO BusinessWorks. Administrator includes the following modules:

• User Management. Management of authentication, roles and users,that is, connecting roles (groups) and users to access control lists(ACLs). This includes security for server-based projects at

design-time and for deployed applications at runtime.

• Resource Management. Monitoring of machines and of all runningapplications in a TIBCO administration domain. Alerts can becreated, for example, to notify an administrator if the number ofprocesses or disk usage exceed a certain number.

• Application Management. Uploading of Enterprise Archive (EAR)files, creation, configuration, deployment, and monitoring of

applications. This console is also used to start and stop applications.

TIBCO Administrator is available as a separate installation and can beinstalled after installing the adapter.

TIBCO BusinessWorks Optional. TIBCO BusinessWorks is a scalable, extensible, and easy-to-useintegration platform that allows you to develop integration projects.TIBCO Adapters are typically part of integration projects created usingTIBCO BusinessWorks.

TIBCO BusinessWorks is available as a separate installation and can beinstalled after installing the adapter.

TIBCO EMS Optional. TIBCO EMS allows you to use the Java Messaging Services(JMS) as the message transport for your adapter.

TIBCO EMS is available as a separate installation and can be installedafter the adapter is installed.


Component Purpose

Adapter Components and Compatible Software |23



37/179


TIBCO Hawk Optional. TIBCO Hawk is available as a separate installation and can beinstalled after the adapter is installed.

TIBCO Adapter for CICS contains a TIBCO Hawk microagent that allowsthe Adapter to be monitored remotely using TIBCO Hawk Display.Because the Adapter software is built on top of the TIBCO Adapter SDK,a basic set of methods that is part of the SDK is also available.

• Adapter-specific methods include the ability to set the debug leveland polling interval for the adapter, turning the verbose flag on or offand getting specific configuration information for an adapter.

• Adapter SDK methods include getting general status information,such as the number of TIBCO ActiveEnterprise messages receivedand published, the number of errors since the last call, the PID of theapplication, and so on.

TIBCO Hawk software also allows you to build rules that trigger an

action when certain conditions occur. For example, a rule canautomatically restart the adapter if it has not responded for 30 seconds.See the TIBCO Hawk Administrator's Guide for information about buildingrules.


Component Purpose


Installing on Microsoft Windows


38/179


Installing on Microsoft Windows

Before starting the installation procedure, review the topics in this section todetermine that your system meets the basic requirements and that you have theprerequisite software installed.

During the installation you will be asked to identify whether the adapter should be installed in the TIBCO BusinessWorks environment or as a standaloneapplication.

The following is a list of prerequisites for installing the adapter on Microsoft

Windows systems. See Installer Disk Space Requirements in Temporary Area onpage 19 for additional disk space requirements.

Prerequisites

The following system requirements are recommended. The actual requirementsdepend on your application environment.

• 700 MHz or greater processor

• 256 MB or more memory

CICS Software Requirements

In addition to the software required by the Adapter on the Windows systemwhere the Adapter is operating, you also need to have the appropriate CICSsoftware loaded and properly configured on the z/OS system where thetransaction processing will take place.

• E CommServer for z/OS with CICS IP Socket Support.

Table 7 Supported platforms, package names, service packs and disk space for Microsoft Windows

Platform Package Names Service Pack Disk Space(MB)

Microsoft Windows XP TIB_adcics-simple_5.3.0_w32.exe Service Pack 1 17

Microsoft Windows2003 Server

TIB_adcics-simple_5.3.0_w32.exe 78

Microsoft Windows2000 (Professional,Server or AdvancedServer)

TIB_adcics-simple_5.3.0_w32.exe Service Pack 4 orhigher

78

Installing on Microsoft Windows |25

If the adapter is installed in a TIBCO BusinessWorks environment, TIBCO


39/179


t e adapte s sta ed a CO us ess o ks e o e t, COBusinessWorks software must be installed prior to the adapter installation.

TIBCO Runtime Agent Must be Installed Before the AdapterBefore you can install the adapter, you must install the TRA. If you use the Typicalinstallation, the installer places all libraries and other products required by theadapter into the TIBCO HOME directory.

During installation, the adapter installer checks for the availability of alldependent products in the target system. If any of the dependencies are notavailable, the installer will immediately exit. Otherwise installation will proceed.

Installer Account

You must have administrator privileges for the machine on which the adapter isinstalled. If you do not have administrator privileges, the installer will exit. Youmust then log out of the system and log in as a user with the required privileges,or request your system administrator to assign the privileges to your account.

Installing from Network Drive

If you intend to install the product on a network drive, you must ensure that theaccount used for installation has permission to access the network drive.

Sample Programs

The installation media includes sample COBOL programs called SXNCIVP1 and

SXNCIQA1.

Installing on Windows 2000 and 2003 Terminal Server

There are two modes in Windows Terminal Server: Execute and Install. Users arelogged on by default in Execute mode, which allows them to run applications. Toinstall an adapter so that everyone can use it, log on as administrator in Install

mode. When the adapter is installed in the Install mode, the installation registry ismaintained in the %SystemRoot% folder.

Windows Terminal Server must be running in remote admin mode, notapplication sharing mode. The adapter is not supported if installed on a machinethat is using Windows Terminal Server in application sharing mode.


The best way to install the adapter on Windows Terminal Server is to use the


40/179


y pAdd/Remove Programs control panel applet. This automatically sets your modeto Install during the installation and then back to Execute afterwards.Alternatively, you can manually change your mode to Install before starting the

installation by typing the following at a command prompt:

C:\> change user /install

Change back to Execute mode after installation is complete by typing:

C:\> change user /execute

To check your current mode, type the following:

C:\> change user /query

Installing the Adapter on Microsoft Windows

You can either download the adapter package or install the package from a CD.The installer prompts you to accept the license agreement, then to choose toperform a typical install or custom install.

• A typical install has minimal prompts and installs standard components in

default locations.

• A custom install prompts you to choose which components of the productsuite to install and installs only those components.

The installer checks your system for the installation home directory that wasestablished when TIBCO Runtime Agent was installed. The adapter is installedunder the installation home directory.

Use one of the following modes to install the software.

Install Using GUI Mode

GUI mode allows you input values in panels. Type the following at the commandprompt:

TIB_adcics-simple_5.3.0_w32.exe

Install Using Console Mode

Console mode allows you to install the software in a non-Windows environment.The installer will prompt you for values. Type the following at the commandprompt:

TIB_adcics-simple_5.3.0_w32.exe -is:javaconsole -console

When running in console mode you can move through the installation process as

described next:

Installing on Microsoft Windows |27

Enter Key = Moves forward in the installer2 G b k t i


41/179


2 = Goes back to previous screen3 = Cancels the Wizard and exits the installation or uninstallation4 = Redisplays the current screen

Install Using Silent Mode

Silent mode allows you to install the software without prompts. Type thefollowing at the command prompt:

TIB_adcics-simple_5.3.0_w32.exe -silent

Install and Generate a Response File

You can generate a response file during installation which you can later use toinvoke the installer with the selected values as default values (GUI mode) or asselected values (silent mode).

To install and generate a response file, type the following at the commandprompt:

TIB_adcics-simple_5.3.0_w32.exe -options-recordC:\directory\

Install Using a Response File

You can use a previously generated response file for installation. For non-silent

modes, the response file determines the defaults that are presented. For silentmode, the response file determines what will be installed.

To install using a response file, type the following at the command prompt:

TIB_adcics-simple_5.3.0_w32.exe -optionsC:\directory\

Combining Options

You can combine the different available options. For example, to install in silentmode using a response file, use:

TIB_adcics-simple_5.3.0_w32.exe -silent -options

To install using Console mode and generate a response file, use:

.exe -is:javaconsole -console-options-record

The response file does not record selections at the component level. It does recordall other selections, for example, which products you wished to install.



42/179


|29

Chapter 3 Configuring the CICS Component


43/179


p g g p

This chapter describes how to install and configure the MVS CICS componentsfor the TIBCO CICS Adapter.

Topics

• Installation Requirements, page 30

• Distribution and Software Contents, page 32

• TIBCO CICS Adapter MVS Installation Overview, page 33

• Uploading the Software, page 35

• TIBCO CICS Adapter MVS Installation Procedure, page 37

• Enabling the IBM CICS TCP/IP Socket Interface, page 39

• Using SXNR versus SXND Transaction ID, page 40

• Security Considerations for CICS, page 41

• Sanity Checks, page 43

• TIBCO Adapter Tracing, page 45

• TIBQ Error/Trace Log, page 46

30 | Chapter 3 Configuring the CICS Component

Installation Requirements


44/179


To install and use the CICS Adapter, you must install TCP/IP 3.4 or above withassociated CICS sockets support. You also need to have the appropriate z/OSsoftware loaded and configured before you activate the CICS Adapter.

Storage Requirements

The CICS Adapter MVS software requires approximately 15 cylinders ofDirect-Access Storage Device (DASD) space. The table below lists file information

and requirements.

General CICS Adapter and Operating System Requirements

The CICS Adapter MVS component is installed in the z/OS MVS environment.Below are the prerequisites for operating the CICS Adapter:

• Verify that the CICS Adapter software is the correct package for youroperating system. Currently the CICS Adapter mainframe component issupported on z/OS version 1.4 and above. The CICS supported versions arefor Transaction Server, TS 2.x and 3.x..

• The

.LOAD

library installed as part of the CICS Adapter must beconcatenated in the DFHRPL DDName of your CICS startup procedure(s).

• The new group list members TIBLIST and TCPLIST must included in theGRPLIST of CICS System Initialization Parameter.

• The CICS Resource definitions required by the CICS Adapter are includedwith the product and must be added to the CICS CSD during the installation.

Table 8 Installed Data Sets

Data SetSpace(1st / 2nd)

DSORG RECFM LRECL BLK SIZE

.COPY CYL (1/1) PO FB 80 27920

.INSTALL CYL (6/1) PO FB 80 27920

.LOAD CYL (1/10) PO U 0 27920

.SRC CYL (1/1) PO FB 80 27920

Installation Requirements |31

• The IBM CICS TCP V 3.4 Socket Resource definitions required by the CICSAdapter are included with the product and must be added to the CICS TCP


45/179


Adapter are included with the product and must be added to the CICS TCPCSD during the installation process.

• The EZA configuration file definition for EZAO transaction is included withthe product and must be created during the installation process

z/OS Enterprise COBOL Requirements

When using the IBM z/OS Enterprise COBOL compiler, you must set theTRUNC(BIN) parameter in the parameter list used by the compiler. This must bedone for any newly-compiled user program that is to be used with the CICS

adapter. Failure to set this parameter will cause any COMMAREA length greaterthan 9999 bytes to be truncated, including the EIBCALEN field. This is arestriction in the z/OS Enterprise COBOL compiler.

Previous versions of the IBM COBOL compiler defaulted to NOTRUNC, whichavoided this issue. The new z/OS Enterprise COBOL compiler does not providethis default.


Distribution and Software Contents


46/179


The CICS Adapter MVS software is available from the adapter home in the

mainframe directory. The CICS Adapter MVS software is distributed in IBM XMITformat. If your site does not have DFSMSdss, you need to make a special requestfor a CD to perform the installation.

Complete Replacement Package

By default, the CICS Adapter MVS software is delivered as a non SMP/E

stand-alone, base function package. CICS Adapter modifications and updates aresupplied as modules that can be installed independently as necessary.

Component Code

CICS Adapter modules are divided into different components. Each componentcan be identified by a 3-character code that has been registered with the IBM

product codes division. The CICS Adapter component code for installation isSXN.

Installation Files

The installation files listed below are in the C:\tibco\adapter\5.3\mainframe directory.

TIBCO CICS Adapter MVS product:

TIB_adcics_5.3.0_zos.sxn.xmit.inst

TIB_adcics_5.3.0_zos.sxn.xmit.main

TIBCO CICS Adapter MVS Installation Overview |33

TIBCO CICS Adapter MVS Installation Overview


47/179


Before installing, read the installation requirements and identify the files

necessary for your installation.

CICS Adapter installation provides default values for system and dataconfiguration parameters. For a first installation of the product, using thesedefaults provides for easier startup, connectivity and message flow testing.

In addition, the variables or required items in the following table should beobtained before performing the installation. They are in the correspondingmember(s); all members reside in the .INSTALL dataset.

Installation Steps

The steps for installation are listed below; additional details are described insubsequent sections of this chapter.

1. Upload/unload the CICS Adapter XMIT files to your host.

2. RECEIVE the installation XMIT file containing installation JCL and parameters.

3. Customize the installation JCL.

4. RECEIVE, RESTORE and populate the CICS Adapter MVS product libraries.

5. Customize and execute the define JCL of CICS Resource Definitions.

6. Customize and execute the define JCL of IBM TCP V 3.4 Socket Resource

Definitions.

Required Item Member

If you are transferring the CICS Adapter MVSinstallation files from a server, obtain the IP address orserver name for the FTP process.

SXNAFTP

Obtain the dataset and/or member name where your

site TCPDATA information resides.

SXNAFTP

Obtain the generic CICS Application Identifier. SXNEZADF

Obtain the High Level Qualifier for your CICS systemload library. The suffix is for libraries SDFHLOAD.

SXNCSDDFSXNCSDTC

Obtain the High Level Qualifier for your CICS region

CSD dataset.

SXNCSDDF

SXNCSDTC


7. Execute the define and populate the CICS TCP/IP socket configuration file JCL.


48/179


8. Start the IBM CICS TCP/IP sockets interface.

When you have completed these steps, CICS Adapter MVS components should be customized and ready for use.

Conclude the installation by running the Installation Verification Program (IVP)tests relevant for your environment. This ensures that the connectivity, datatransformation, message flow and system operations are correctly installed andfunctional. Refer to Appendix D, Pre-Configured Examples, for instructions onrunning the IVP programs.

Uploading the Software |35

Uploading the Software


49/179


If you have acquired the TIBCO CICS Adapter software by downloading it from

the TIBCO web site, you will need to upload the software to the z/OS MVS hostsystem using the FTP file transfer utility. The sample JCL below illustrates thestatements needed to perform this file transfer.

Initial Installation

Sample JCL to Upload Using IBM’s FTP

This sample JCL copies CICS Adapter installation file(s) from a LAN server or PCto the z/OS MVS host:

//#JOBNAME JOB (&SYSUID),'CICS Adapter FTP', CLASS=A//*// SET FTPADDR=10.10.2.99 < IP Address or Host Name//*

//FTP EXEC PGM=FTP,REGION=0M,PARM='&FTPADDR (TIMEOUT 20'//SYSPRINT DD SYSOUT=*//OUTPUT DD SYSOUT=*//SYSTCPD DD DISP=SHR,DSN=TCPIP.PROFILE(FTPDATA) < Host Member//INPUT DD *

cd /binaryLOCSITE RECFM=FB LRECL=80 BLKSIZE=27920 TR PRI=60 SEC=15

get .sxn.xmit.inst' #USERHLQ.XMIT.INST' (REPLACEquit/*//

Receiving the Initial Installation File

The .XMIT.INST file contains the JCL that is required to receiveother files and to create the appropriate libraries for the CICS Adapter. Tocomplete this process, you must substitute the appropriate site-specific uservalues for the TIBCO supplied variables.

Follow these steps:

This step always needs to be performed during a TIBCO CICS Adapter initialinstallation on the MVS Host.


1. From the ISPF Command Shell Panel, type the following command to receivea file containing the JCL required to begin a first time installation:


50/179


e co g e JC eq e o eg s e s oreceive inda('.XMIT.INST')

TSO will prompt with the following:INMR906A Enter restore parameters or 'DELETE' or 'END' +

2. Supply the following:DA('.INSTALL')

After a successful receive, the following message is displayed:INMR001I Restore successful to dataset '.INSTALL'

The data set name supplied in Step 2 is output and populated with the members

that are required in order for you to continue with the installation.

TIBCO CICS Adapter MVS Installation Procedure |37

TIBCO CICS Adapter MVS Installation Procedure


51/179


Perform the following steps to install the MVS components for the CICS Adapter.

Edit the selected members listed in the steps below. Substitute the variables,follow any instructions that are contained in the member and then submit the JCLfor execution. All members reside within the .INSTALL dataset.

STEP 1: Upload the files via FTP to your z/OS host

Member: SXNAFTP

STEP 2: Populate TIBCO CICS Adapter product libraries

This member will receive and restore then populate the CICSAdapter MVS product libraries.

Member: SXNARECV

STEP 3: Update CICS