AIX CICS/6000 and Relational Database Management Systems

AIX CICS/6000 andRelational Database Management Systems Integration:

Experiences with the XA Interface

Document Number GG24-4214-00

July 1994

International Technical Support OrganizationSan Jose Center

Take Note!

Before using this information and the product it supports, be sure to read the general information under“Special Notices” on page xiii.

First Edition (July 1994)

This edition applies to IBM AIX CICS/6000 Version 1 Release 1 for use with the AIX Operating System Version 3Release 2.5.

Order publications through your IBM representative or the IBM branch office serving your locality. Publicationsare not stocked at the address given below.

An ITSO Technical Bulletin Evaluation Form for reader ′s feedback appears facing Chapter 1. If the form has beenremoved, comments may be addressed to:

IBM Corporation, International Technical Support OrganizationDept. 471, Building 70B5600 Cottle RoadSan Jose, California 95193-0001

When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 1994. All rights reserved.Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure issubject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Abstract

This document describes the integration of IBM AIX CICS/6000 Version 1 Release1 and the following relational databases running on AIX Version 3 Release 2.5:DATABASE 2 AIX/6000, Informix Version 5, Oracle7, and Sybase System 10.

The document is written to help you understand and implement the XA interfaceas defined in the X/Open Distributed Transaction Processing Model. A workingknowledge of IBM AIX CICS/6000 and relational database management systemsis assumed.

The document provides detailed information on how to implement the XAinterface in both a local and a remote configuration. It also provides guidelineson how to design an application in those configurations.

DS AX (154 pages)

Copyright IBM Corp. 1994 iii

iv CICS/6000 and RDBMSs

Contents

Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i i i

Special Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii i

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvHow This Document Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . xvRelated Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviInternational Technical Support Organization Publications . . . . . . . . . . . xviiAcknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Chapter 1. X/Open Distributed Transaction Processing Model . . . . . . . . . 11.1 Functional Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.1 Functional Components . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.1.2 Interfaces among Functional Components . . . . . . . . . . . . . . . . 21.1.3 Activity among Functional Components . . . . . . . . . . . . . . . . . . 3

1.2 Process Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 CICS/6000 and the X/Open DTP Model . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2. XA Integration Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 72.1 Relational Database Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.1.1 Shared Object or Library . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.2 XA Open String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.3 Resource Manager Switch . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1.4 Database Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.2 CICS/6000 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.2.1 XA Resource Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.2.2 CICS/6000 Region Environment Setup . . . . . . . . . . . . . . . . . . . 112.2.3 CICS/6000 Region Startup . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 3. Local Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.2 DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.2.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.2.2 DATABASE 2 AIX/6000 Configuration . . . . . . . . . . . . . . . . . . . 173.2.3 CICS/6000 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.3 Informix Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243.3.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243.3.2 Informix Version 5 Configuration . . . . . . . . . . . . . . . . . . . . . . 243.3.3 CICS/6000 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3.4 Oracle7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.4.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.4.2 Oracle7 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.4.3 CICS/6000 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3.5 Sybase System 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.5.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.5.2 Sybase System 10 Configuration . . . . . . . . . . . . . . . . . . . . . . 393.5.3 CICS/6000 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 4. Remote Implementation . . . . . . . . . . . . . . . . . . . . . . . . . 494.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494.2 DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Copyright IBM Corp. 1994 v

4.2.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.2.2 DATABASE 2 AIX/6000 Configuration . . . . . . . . . . . . . . . . . . . 524.2.3 CICS/6000 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

4.3 Oracle7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.3.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.3.2 Oracle7 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554.3.3 CICS/6000 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4.4 Sybase System 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574.4.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574.4.2 Sybase System 10 Configuration . . . . . . . . . . . . . . . . . . . . . . 594.4.3 CICS/6000 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 5. Resource Manager Initialization at Region Startup: ADiagrammatic View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

5.1 DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615.1.1 Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615.1.2 AIX Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

5.2 Informix Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635.2.1 Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645.2.2 AIX Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

5.3 Oracle7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655.3.1 Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655.3.2 AIX Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

5.4 Sybase System 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.4.1 Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685.4.2 AIX Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Chapter 6. Problem Determination . . . . . . . . . . . . . . . . . . . . . . . . . . 716.1 DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716.2 Informix Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736.3 Oracle7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746.4 Sybase System 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Chapter 7. Application Considerations . . . . . . . . . . . . . . . . . . . . . . . 797.1 CICS/6000 and a Local RDBMS . . . . . . . . . . . . . . . . . . . . . . . . . 80

7.1.1 CICS/6000 Transaction and DATABASE 2 AIX/6000 . . . . . . . . . . . 807.1.2 CICS/6000 Transaction and Local Informix Version 5 . . . . . . . . . . 837.1.3 CICS/6000 Transaction and Oracle7 . . . . . . . . . . . . . . . . . . . . 847.1.4 CICS/6000 Transaction and Sybase System 10 . . . . . . . . . . . . . . 857.1.5 CICS/6000 Transaction and Multiple Databases . . . . . . . . . . . . . 86

Appendix A. Appendix A. MicroFocus COBOL Run-Time Support . . . . . . 113A.1 CICS/6000 and DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . . . . . . 113A.2 CICS/6000 and Informix Version 5 . . . . . . . . . . . . . . . . . . . . . . . 114A.3 CICS/6000 and Oracle7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114A.4 CICS/6000 and Sybase System 10 . . . . . . . . . . . . . . . . . . . . . . . 114

Appendix B. Appendix B. Setting Up the UXA1 Demo . . . . . . . . . . . . . 117B.1 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117B.2 DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

B.2.1 Create Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117B.2.2 Run the Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118B.2.3 Configure Programs and Transactions for CICS/6000 Using SMIT for

DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

vi CICS/6000 and RDBMSs

B.2.4 Configure Programs and Transactions for CICS/6000 Using Scriptfor DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

B.3 Informix Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124B.3.1 Create Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124B.3.2 Run the Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126B.3.3 Configure Programs and Transactions for CICS/6000 Using SMIT for

Informix Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127B.3.4 Configure Programs and Transactions for CICS/6000 Using Script

for Informix Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130B.4 Oracle7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131


Oracle7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134B.4.4 Configure Programs and Transactions for CICS/6000 Using Script

for Oracle7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137B.5 Sybase System 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138


Sybase System 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141B.5.4 Configure Programs and Transactions for CICS/6000 Using Script

for Sybase System 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

List of Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Contents vii

viii CICS/6000 and RDBMSs

Figures

1. X/Open Distributed Transaction Processing Model: FunctionalComponents and Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2. X/Open Distributed Transaction Processing Model: Processes . . . . . . 4 3. CICS/6000 and the X/Open DTP Model: Architectural Positioning . . . . 5 4. CICS/6000 Region Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5. Source Code for DATABASE 2 AIX/6000 Switch Load File . . . . . . . . . 18 6. Source Code for DATABASE 2 AIX/6000 Switch Load File Makefile . . . 19 7. Check That User Is Member of the cics Group . . . . . . . . . . . . . . . 21 8. DB2 XA Definition for CICS/6000 . . . . . . . . . . . . . . . . . . . . . . . . 22 9. Cold Start the CICS/6000 Region . . . . . . . . . . . . . . . . . . . . . . . . 2310. Source Code for Informix Version 5 Switch Load File . . . . . . . . . . . 2711. Source Code for Informix Version 5 Switch Load File Makefile . . . . . . 2812. Informix Version 5 XA Definition for CICS/6000 . . . . . . . . . . . . . . . 3013. Source Code for Oracle7 Switch Load File . . . . . . . . . . . . . . . . . . 3414. Source Code for Oracle7 Switch Load File Makefile . . . . . . . . . . . . 3515. Oracle7 XA Definition for CICS/6000 . . . . . . . . . . . . . . . . . . . . . . 3716. Source Code for Sybase System 10 Switch Load File . . . . . . . . . . . 4317. Source Code for Sybase System 10 Switch Load File Makefile. . . . . . 4418. Sybase System 10 XA Definition for CICS/6000 . . . . . . . . . . . . . . . 4519. DATABASE 2 AIX/6000 Registration: Local and Remote (Client-Server) . 6220. Informix Version 5 Local Registration . . . . . . . . . . . . . . . . . . . . . 6421. Oracle7 Local Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . 6522. Oracle7 Remote Registration (Client-Server) . . . . . . . . . . . . . . . . 6623. Sybase System 10 Registration: Local and Remote (Client-Server) . . . 6824. Sample Syslog Entry for XA Error . . . . . . . . . . . . . . . . . . . . . . . 7225. CICS/6000 Console Message When Unable to Load a Switch Load File 7326. CICS/6000 Console Message: Unable to Open Informix Version 5

Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7327. CICS/6000 Console Message: TBCONFIG Not Correctly Set . . . . . . . . 7428. Oracle XA Trace File: Nonexistent User Put in Open String . . . . . . . . 7429. CICS/6000 Console Message: Nonexistent User . . . . . . . . . . . . . . . 7530. Sample Oracle XA Trace File: Server Configured Remotely . . . . . . . 7531. Oracle XA Trace Entry: SELECT Privilege Not Granted to V$XATRANS$

View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7632. Sybase XA Trace File: Wrong Password for User sa in Open String . . . 7733. CICS/6000 Console Messages: Wrong Password for User sa in Sybase

System 10 Open String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7734. Sybase XA Trace: Wrong LRM Name in Sybase System 10 Open String 7735. Sybase XA Trace: Wrong Server Name in Sybase System 10 xa_config

File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7836. Connect in SQL C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 8137. Sample Makefile to Compile a Program Using Two Different DATABASE

2 AIX/6000 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8338. Using Different Oracle7 Databases in One Application Server . . . . . . 8439. Using the SET CONNECTION Command . . . . . . . . . . . . . . . . . . . 8640. Sample Transaction Involving Different Databases . . . . . . . . . . . . . 8841. Sample Makefile for Compiling a Program That Uses Different

Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10942. Processes Related to DATABASE 2 AIX/6000 . . . . . . . . . . . . . . . 11843. Output of Makefile to Compile UXA1 Transaction: DATABASE 2

AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Copyright IBM Corp. 1994 ix

44. Defining the UXA1 Map Program to CICS/6000: DATABASE 2 AIX/6000 12145. Defining the DB2UXA1 Program to CICS/6000 . . . . . . . . . . . . . . . 12246. Defining the DB2U Transaction to CICS/6000 . . . . . . . . . . . . . . . 12347. Sample Shell Script to Configure CICS/6000 Resources: DATABASE 2

AIX/6000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12448. Processes Related to Informix . . . . . . . . . . . . . . . . . . . . . . . . 12549. Results of tbtape Command . . . . . . . . . . . . . . . . . . . . . . . . . . 12550. uxa1_inf5.mk Makefile after Editing . . . . . . . . . . . . . . . . . . . . . 12651. Output of uxa1_inf5.mk Makefile to Compile UXA1 Transaction: Informix

Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12752. Defining the UXA1 Map Program to CICS/6000: Informix Version 5 . . 12853. Defining the INFUXA1 Program to CICS/6000 . . . . . . . . . . . . . . . 12954. Defining the INFU Transaction to CICS/6000 . . . . . . . . . . . . . . . . 13055. Sample Shell Script to Configure CICS/6000 Resources: Informix

Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13156. Processes Related to Oracle . . . . . . . . . . . . . . . . . . . . . . . . . 13257. uxa1_ora7.mk Makefile after Editing . . . . . . . . . . . . . . . . . . . . . 13358. Output of uxa1_ora7.mk Makefile to Compile UXA1 Transaction . . . . 13359. Defining the UXA1 Map Program to CICS/6000: Oracle7 . . . . . . . . . 13560. Defining the ORAUXA1 Program to CICS/6000 . . . . . . . . . . . . . . . 13661. Defining the ORAU Transaction to CICS/6000 . . . . . . . . . . . . . . . 13762. Sample Shell Script to Configure CICS/6000 Resources: Oracle7 . . . 13863. Processes Releted to Sybase . . . . . . . . . . . . . . . . . . . . . . . . . 13864. uxa1_syb.mk Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13965. Output of uxa1_syb.mk Makefile to Compile UXA1 Transaction . . . . . 14066. Defining the UXA1 Map Program to CICS/6000: Sybase System 10 . . 14267. Defining the SYBUXA1 Program to CICS/6000 . . . . . . . . . . . . . . . 14368. Defining the SYBU Transaction to CICS/6000 . . . . . . . . . . . . . . . 14469. Sample Shell Script to Configure CICS/6000 Resources: Sybase

System 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

x CICS/6000 and RDBMSs

Tables

1. ax_ services in the XA Interface . . . . . . . . . . . . . . . . . . . . . . . . 8 2. xa_ services in the XA Interface . . . . . . . . . . . . . . . . . . . . . . . . 8

Copyright IBM Corp. 1994 xi

xii CICS/6000 and RDBMSs

Special Notices

This publication is intended to help personnel working with IBM AIX CICS/6000(5765-148). The information in this publication is not intended as thespecification of any programming interfaces that are provided by IBM AIXCICS/6000. See the PUBLICATIONS section of the IBM ProgrammingAnnouncement for IBM CICS for AIX on RISC System/6000 for more informationabout what publications are considered to be product documentation.

References in this publication to IBM products, programs or services do notimply that IBM intends to make these available in all countries in which IBMoperates. Any reference to an IBM product, program, or service is not intendedto state or imply that only IBM′s product, program, or service may be used. Anyfunctionally equivalent program that does not infringe any of IBM′s intellectualproperty rights may be used instead of the IBM product, program or service.

Information in this book was developed in conjunction with use of the equipmentspecified, and is limited in application to those specific hardware and softwareproducts and levels.

IBM may have patents or pending patent applications covering subject matter inthis document. The furnishing of this document does not give you any license tothese patents. You can send license inquiries, in writing, to the IBM Director ofCommercial Relations, IBM Corporation, Purchase, NY 10577.

The information contained in this document has not been submitted to anyformal IBM test and is distributed AS IS. The information about non-IBM(VENDOR) products in this manual has been supplied by the vendor and IBMassumes no responsibility for its accuracy or completeness. The use of thisinformation or the implementation of any of these techniques is a customerresponsibility and depends on the customer′s ability to evaluate and integratethem into the customer′s operational environment. While each item may havebeen reviewed by IBM for accuracy in a specific situation, there is no guaranteethat the same or similar results will be obtained elsewhere. Customersattempting to adapt these techniques to their own environments do so at theirown risk.

The following document contains examples of data and reports used in dailybusiness operations. To illustrate them as completely as possible, the examplescontain the names of individuals, companies, brands, and products. All of thesenames are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

The following terms, which are denoted by an asterisk (*) in this publication, aretrademarks of the International Business Machines Corporation in the UnitedStates and/or other countries:

The following terms, which are denoted by a double asterisk (**) in thispublication, are trademarks of other companies:

AIX AIX/6000AIXwindows CICSCICS/6000 DATABASE 2 AIX/6000RISC System/6000

Copyright IBM Corp. 1994 xiii

MicroFocus COBOL Micro Focus CompanyDCE, Distributed Computing Environment Open Software FoundationEncina, Transarc Transarc CorporationInformix Informix CorporationOracle, Oracle7 Oracle CorporationSybase Sybase, Inc.X/Open X/Open Company Limited

xiv CICS/6000 and RDBMSs

Preface

The X/Open Distributed Transaction Processing standard (X/Open DTP) definesthe concept of resource managers coordinated by a transaction manager.Relational databases like DATABASE 2 AIX/6000, Informix, Oracle, and Sybaseare typical resource managers. The transaction manager coordinates transactioninitiation and completion among these resource managers.

CICS/6000 transactions can access relational databases by including embeddedSQL calls inside an application program. Because CICS/6000 fulfills the role of atransaction manager in the X/Open DTP model, it can coordinate distributedtransactions to XA-enabled relational databases. XA is the so-called interfacebetween a transaction manager and resource managers in the X/Open DTPmodel.

This document describes the integration of IBM AIX CICS/6000 Version 1 Release1 and the following relational databases running on AIX Version 3 Release 2.5:DATABASE 2 AIX/6000, Informix Version 5, Oracle7, and Sybase System 10. Itprovides detailed information on how to implement the XA interface in both alocal and a remote configuration. It also provides guidelines on how to designan application in those configurations.

The document is written to help you understand and implement the XA interfaceas defined in the X/Open DTP model. A working knowledge of IBM AIXCICS/6000 and relational database management systems is assumed.

How This Document Is OrganizedThe document is organized as follows:

• Chapter 1, “X/Open Distributed Transaction Processing Model”

This chapter describes the functional and the process models as defined inthe X/Open DTP standard.

• Chapter 2, “XA Integration Concepts”

This chapter discusses the integration of CICS/6000 and XA-enabledrelational database management systems (RDBMSs).

• Chapter 3, “Local Implementation”

This chapter describes the implementation steps needed to integrateCICS/6000 with UNIX RDBMSs in the case where both CICS/6000 and theUNIX relational database reside on the same machine.

• Chapter 4, “Remote Implementation”

This chapter describes the implementation steps needed to integrateCICS/6000 with UNIX RDBMSs in the case where both CICS/6000 and theUNIX relational database reside on separate machines.

• Chapter 5, “ Resource Manager Initialization at Region Startup: ADiagrammatic View”

This chapter describes the steps involved in the startup of a CICS/6000region when connecting to an XA-compliant RDBMS.

Copyright IBM Corp. 1994 xv

• Chapter 6, “Problem Determination”

This chapter describes how to handle problem determination whenCICS/6000 is using XA support for UNIX relational database systems.

• Chapter 7, “Application Considerations”

This chapter describes some of our experiences configuring CICS/6000 indifferent application scenarios.

Related PublicationsThe publications listed in this section are considered particularly suitable for amore detailed discussion of the topics covered in this document.

• AIX CICS/6000 Application Programming Guide, SC33-0814

• AIX CICS/6000 Planning and Installation Guide, GC33-0816

• AIX CICS/6000 Message and Codes, SC33-0817

• AIX CICS/6000 Problem Determination, SC33-0818

• AIX CICS/6000 Application Programming Reference, SC33-0886

• AIX CICS/6000 Customization and Operation Guide, SC33-0931

• IBM DATABASE 2 AIX/6000 Installation Guide, GC09-1570

• IBM DATABASE 2 AIX/6000 Administration Guide, SC09-1571

• IBM DATABASE 2 AIX/6000 Programming Guide, SC09-1572

• IBM DATABASE 2 AIX/6000 Command Reference, SC09-1575

• IBM DATABASE 2 AIX/6000 Messages and Problem Determination Guide,SC09-1577

• Informix UNIX Products Installation Guide Version 5.0

• Informix OnLine Administrator′s Guide

• Informix TP/XA User Manual

• Informix Error Messages

• Oracle7 Server for IBM RISC/6000 Installation and Configuration Guide

• Oracle7 Server Administrator′s Guide

• Oracle7 Server for Unix - Administrator′s Guide

• Sybase SQL Server Installation Guide for AIX

• Sybase XA-Library Integration Guide for CICS/6000

• X/Open Distributed Transaction Processing Reference Model

• X/Open Distributed Transaction Processing: the XA Specification

• X/Open Distributed Transaction Processing: the TX (Transaction Demarcation)Specification

xvi CICS/6000 and RDBMSs

International Technical Support Organization PublicationsA complete list of International Technical Support Organization publications, witha brief description of each, may be found in:

Bibliography of International Technical Support Organization TechnicalBulletins, GG24-3070.

To get listings of ITSO technical bulletins (redbooks) online, VNET users maytype:

TOOLS SENDTO WTSCPOK TOOLS REDBOOKS GET REDBOOKS CATALOG

How to Order ITSO Technical Bulletins (Redbooks)

IBM employees in USA may order ITSO books and CD-ROMs usingPUBORDER. Customers in the USA may order by calling 1-800-879-2755 or byfaxing 1-800-284-4721. Visa and Master Cards are accepted. Outside theUSA, customers should their IBM branch office.

Customers may order hardcopy redbooks individually or in customized sets,called GBOFs, which relate to specific functions of interest. IBM employeesand customers may also order redbooks in online format on CD-ROMcollections, which contain the redbooks for multiple products.

AcknowledgmentsThis document is the result of a residency project conducted at the InternationalTechnical Support Organization, San Jose Center, during 1994.

The project was designed and managed by:

Guido De Simoni International Technical Support Organization, San Jose Center.

The document was written by:

Sebastiano Ardiri IBM Italy

Jasjit Vig IBM United Kingdom.

Thanks to the following people for the invaluable advice provided in theproduction of this document:

Peter Shum IBM Toronto Laboratories

Nancy Brown Informix

Alan Slutsky Informix

Deepak Puri Oracle

Kelly Pecoraro Sybase.

In addition I would like to thank those who took time to review this document:

Neil Kolban IBM Dallas System Center

Preface xvii

Everton Lewis IBM Hursley Laboratories

Dave Spencer IBM West Hursley.

Special thanks go to the following people:

Lorna Conas International Technical Support Organization, San Jose Center

Rolf Lie Informix

Dan Mori Oracle

Josh Bersin Sybase.

xviii CICS/6000 and RDBMSs

Chapter 1. X/Open Distributed Transaction Processing Model

In this chapter we describe the X/Open Distributed Transaction Processing (DTP)model, its software components and interfaces, and the flow of control. 1

1.1 Functional ModelFigure 1 is the basic X/Open DTP model of an application program environmentfor transaction processing.

The boxes are functional components; the connecting lines are interfaces amongthe components that X/Open has published or intends to publish. The arrowsindicate directions in which control may flow. Data may flow in both directionsacross each interface.

Figure 1. X/Open Distributed Transaction Processing Model: Functional Components andInterfaces

For a description of each functional component, see 1.1.1, “FunctionalComponents” on page 2. For a description of the three interfaces shown, see1.1.2, “Interfaces among Functional Components” on page 2.

The functional components are not necessarily separate processes, nor are theynecessarily totally within a single process. For a description of the processmodel, see 1.2, “Process Model” on page 4.

1 We extracted the information in section 1.1 of this chapter from pages 5-9 of X/Open Distributed Transaction ProcessingReference Model, document number G120, ISBN 1 872630 16 2. We extracted the information in section 1.2 of this chapter frompage 11 of the same book.

Copyright IBM Corp. 1994 1

1.1.1 Functional ComponentsThe three functional components of the X/Open DTP model are the applicationprogram, transaction manager, and resource manager.

1.1.1.1 Application ProgramThe application program (AP) implements the desired function of the end-userenterprise. Each AP specifies a sequence of operations that involves resourcessuch as databases. An AP defines the start and end of a global transaction,accesses resources within transaction boundaries, and usually decides whetherto commit or roll back each transaction.

1.1.1.2 Transaction ManagerThe transaction manager (TM) manages global transactions and coordinates thedecision to commit them or roll them back, thus ensuring atomic transactioncompletion. The TM also coordinates recovery activities of the resourcemanagers when necessary, such as after a component fails.

1.1.1.3 Resource ManagerThe resource manager (RM) manages a certain part of the computer ′s sharedresources. Many other software entities can request access to the resourcefrom time to time, using services that the RM provides. Examples of RMsinclude a database management system (DBMS), a file access method, such asX/Open indexed sequential access method (ISAM), or a print server. Some RMsmanage a communication resource.

In the X/Open DTP model, RMs structure any changes to the resources theymanage as recoverable and atomic transactions and let the TM coordinatecompletion of the transactions atomically with work done by other RMs.

1.1.2 Interfaces among Functional ComponentsThere are three interfaces among the functional components in the basic X/OpenDTP model:

• AP-RM. The AP-RM interfaces give the AP access to shared resources.Existing X/Open interfaces, such as structured query language (SQL) andISAM, provide AP portability. The X/Open DTP model imposes fewconstraints on the native RM application program interface (API). X/Openmay specify additional, specialized AP-RM communications interfaces forDTP, such as peer-to-peer and remote procedure call (RPC) interfaces.

• AP-TM. The AP-TM interface (the TX interface) lets the AP delimit globaltransactions. The TM provides routines that let the AP start and completeglobal transactions. The TM completes global transactions based upon arequest from the AP and coordinates with the participating RMs and otherinvolved TMs. When this coordination is completed, the TM returns thecompletion status of the AP. Details of the AP-TM interface are in X/OpenDistributed Transaction Processing: The TX (Transaction Demarcation)Specification.

• TM-RM. The TM-RM interface (the XA interface) lets the TM structure thework of RMs into global transactions and coordinate global transactioncompletion and recovery. In the XA specification, the routines that each RMprovides for the TM′s use are the xa_routines. The routines the TM providesfor the RMs to call form the ax_set.

2 CICS/6000 and RDBMSs

When an AP calls a TM through the TX interface, the TM typically implementseach TX call by contacting RMs through the XA interface. Because the XAinterface is invisible to the AP, the TM and RM may use other methods tointerconnect without affecting application portability.

A TM assigns a data structure called a transaction identifier (XID). The XID letsthe TM track and coordinate all of the work associated with a global transaction.Each RM maps the XID to the recoverable work it did for the transaction. Forglobal uniqueness, the XID should contain atomic action identifiers.

1.1.3 Activity among Functional ComponentsThe activity among the three functional components of the X/Open DTP model isrelated to different transaction operations.

1.1.3.1 Transaction InitiationWhen an AP instructs its TM to start a global transaction, the TM tells allappropriate RMs to associate the information about the global transaction withany work the AP may request from them.

Some RMs are configured so that the TM does not inform them when a globaltransaction starts. The RM contacts the TM to become associated with a globaltransaction only after the AP calls it to request actual work. This is calleddynamic registration. If static registration is requested, each new transaction inthe process generates a call to the RM that tells it that it has joined a newtransaction or resumed an old one.

1.1.3.2 Transaction CommitmentWhen an AP instructs its TM to commit a transaction, the TM and RMs usetwo-phase commit presumed rollback to ensure transaction atomicity.

In Phase 1, the TM asks all RMs to prepare to commit (or prepare ) their work. Italso asks whether the RM can guarantee its ability to commit the work it did onbehalf of a global transaction. If an RM can commit its work, it repliesaffirmatively. A negative reply reports failure.

In Phase 2, the TM directs all RMs either to commit or to roll back the work doneon behalf of a global transaction, as the case may be. All RMs commit or rollback changes to shared resources and then return status to the TM.

When an AP calls its TM to commit a global transaction, the TM reports onwhether commitment or rollback was the outcome. This report is based onreports the TM received (directly or through other TMs) from all involved RMs.

The XA specification contains two optimizations in the calling sequence betweenthe TM and RM. An RM can withdraw from further participation in a globaltransaction during Phase 1 if it was not asked to update shared resources (theread-only optimization). A TM can use one-phase commit if it is dealing withonly one RM that is making changes to shared resources.

The XA specification discusses requirements for stable recording of transactiondata, including specifying when the TM and RMs are free to discard theirknowledge of the global transaction.

Chapter 1. X/Open Distributed Transaction Processing Model 3

1.1.3.3 Transaction RollbackThe TM rolls back the global transaction if any RM responds negatively to thePhase 1 request, or if the AP directs the TM to roll back the global transaction.

The TM effects Phase 2 by telling RMs to roll back the transaction. The RMsmust not let any changes to shared resources become permanent.

1.1.3.4 Heuristic Transaction CompletionIn certain, unusual, cases, the RM could experience a long delay between Phase1 and 2 of the two-phase commit protocol. For example, the TM that issued theprepare-to-commit (Phase 1) request could block or fail later in the protocolsequence. In order to free resources, an RM may complete its work heuristically(independent of direction from its TM). The heuristic decision may be promptedby administrative action or by completion of a parametric timeout interval.

Heuristic decisions typically cannot depend on the knowledge of results at otherRMs that TMs normally coordinate. When any RM makes a heuristic decision,the global transaction may fail to maintain global atomicity; one RM may commitits work while another rolls back its work. Such mixed-heuristic completion mayleave shared resources in an inconsistent state. A TM may report amixed-heuristic condition to its AP.

1.1.3.5 Failures and RecoveryRecovery is a process of restoring shared resources to a consistent state aftervarious types of failure. The X/Open DTP model makes these assumptions:

• TMs and RMs have access to stable storage.

• TMs initiate and control transaction recovery.

• RMs provide for their own restart and recovery as directed by TMs.

1.2 Process ModelThis section describes the actual processes of the DTP model (see Figure 2).

Figure 2. X/Open Distributed Transaction Processing Model: Processes

An instance of the model is an operating-system process, implemented bycombining an AP with libraries for a TM and for one or more RMs. Throughthese libraries routines, the TM and RMs supply the AP with X/Open-compliant


APIs. The libraries also include interfaces between the TM and RMs with whichthe AP is not directly concerned.

The interface routines in an RM library include:

• The native interface routine that the AP calls

• The XA interface routines that the TM calls.

The interface routines in a TM library include:

• The TX interface routines that the AP calls

• The XA interface routines that some RMs may call.

Within a single instance of the model, an AP deals with exactly one TM, but theAP and TM may deal with multiple RMs.

1.3 CICS/6000 and the X/Open DTP ModelFigure 3 shows the architectural positioning of an IBM AIX CICS/6000 Version 1Release 1 (CICS/6000) system in the X/Open DTP model.

Figure 3. CICS/6000 and the X/Open DTP Model: Architectural Positioning

The CICS/6000 architecture hides the TX Interface.

Chapter 1. X/Open Distributed Transaction Processing Model 5


Chapter 2. XA Integration Concepts

In this chapter we discuss the integration of CICS/6000 and XA-enabled relationaldatabase management systems (RDBMSs). We divide the discussion into twoparts:

• Relational database concepts

• CICS/6000 concepts.

2.1 Relational Database ConceptsIn this section we introduce the concepts of:

• Shared object or library

• XA open string

• Resource manager switch

• Database privileges.

2.1.1 Shared Object or LibraryCICS/6000 has an advanced AIX load-based architecture under which transactioncode is dynamically loaded into long-running application server programs. Thisarchitecture allows new transactions to be added to a running CICS/6000 system.Because applications do not need to be relinked if there is an internal librarychange, application maintenance is easy.

To support the architecture, the vendors of XA-enabled RDBMSs supply sharedreentrant versions of their objects or libraries for use with CICS/6000. Theselibraries are discussed individually in Chapter 3, “Local Implementation” onpage 15 and Chapter 4, “Remote Implementation” on page 49.

2.1.2 XA Open StringA transaction manager calls xa_open() to initialize an RM and prepare it for usein a DTP environment.

Any information needed for the initialization of the RM (such as opening of files,identifying a resource domain) can be provided as parameters to xa_open(). Forexample, you need to provide DATABASE 2 AIX/6000 with a database name inorder to connect to it.

The XA open string is one of the arguments to xa_open() an d is specific to thedatabase. We discuss the XA open strings for the different databases inChapter 3, “Local Implementation” on page 15 and Chapter 4, “RemoteImplementation” on page 49.

If the resource manager supports multiple instances, the transaction managercan call xa_open() more than once for the same resource manager.


2.1.3 Resource Manager SwitchThe XA interface provides two types of services: ax_ services and xa_ services.

Table 1 shows the ax_ services, which:

• The TM provides

• Allow an RM to call a TM

• Allow an RM to dynamically control its participation in a transaction branch.

Table 1. ax_ services in the XA Interface

Name Description

ax_reg Register an RM with a TM.

ax_unreg Unregister an RM with a TM.

Table 2 shows the xa_ services, which:

• The RM provides

• Allow a TM to call an RM

• The TM calls in a particular sequence

• Allow a TM to inform an RM of transaction branch startup, commit, rollback,or coordinate failure recovery.

These are listed in Table 2

Table 2. xa_ services in the XA Interface

Name Description

xa_close Terminate the AP′s use of an RM.

xa_commit Tell the RM to commit a transaction branch.

xa_end Dissociate the thread from a transaction branch.

xa_forgetPermit the RM to discard its knowledge of a heuristically completed transactionbranch.

xa_open Initialize an RM for use by an AP.

xa_prepare Ask the RM to prepare to commit a transaction branch.

xa_recover Get a list of XIDs the RM has prepared or heuristically completed.

xa_rollback Tell the RM to roll back a transaction branch.

xa_startStart or resume a transaction branch; associate an XID with future work that thethread requests of the RM.

RMs must provide information that gives the TM access to the xa_ services.This information is provided through a switch, which is an external C variable oftype xa_switch_t . The switch returns values to the TM. The return fields are:

Field Description

name Resource manager name

flags Options specific to the database.


version value must be 0

others pointers to the xa_ routines of the RM

Let′s have a look at the flag options.

TMNOFLAGS This flag specifies that no flags have been set, that is, the RM doesnot support dynamic registration or asynchronous mode. It supportsassociation migration.

TMREGISTER This flag implies that the resource manager supports dynamicregistration.

Dynamic registration : Certain RMs, especially those involved inrelatively few global transactions, may ask the TM to assume thatthey are not involved in a transaction. For example, DATABASE 2AIX/6000 supports dynamic registration. Therefore, like all other RMs,DATABASE 2 AIX/6000 is initialized by CICS/6000 at region startup bythe xa_open() routine. However, CICS/6000 subsequently never callsDATABASE 2 AIX/6000 with the xa_start() routine.

Note

For all other RMs that do not support dynamic registrationCICS/6000 involves all associated RMs in a transaction branch.CICS/6000 issues the xa_start() routine for all transactions even ifone of those other RMs does not participate in the transaction.This operation could create an overhead if you have transactionsaccessing none or a few RMs.

When an AP requests works from a dynamically registered RM,before doing the work, the RM contacts the TM by calling the ax_reg()service. For more information refer to X/Open Distributed TransactionProcessing: The XA Specification.

TMNOMIGRATE This flag indicates that the resource manager does not supportassociation migration.

Association migration : Several threads may participate in a singletransaction branch, some more than once. The xa_start() andxa_end() routines pass an XID to an RM to associate or dissociate thecalling thread with a branch. Certain calls to xa_end() suspend thethread ′s association. The call may indicate that the association canmigrate, that is, that any thread may resume the association. In thiscase, the calling thread is no longer associated. For moreinformation refer to X/Open Distributed Transaction Processing: TheXA Specification.

TMUSEASYNC This flag indicates that the RM should use the asynchronousmode of operation for the xa_ services.

Aynchronous mode : The xa_ services typically operate synchronously,that is, control does not return to the caller until the operation iscomplete. Most xa_ services have a form by which the callerrequests asynchrony. Asynchronous calls should return immediately.The caller can subsequently call xa_complete() to test theaynchronous operation for completion. For more information refer toX/Open Distributed Transaction Processing: The XA Specification.

Chapter 2. XA Integration Concepts 9

2.1.4 Database PrivilegesRMs have different ways of implementing security. Somes RM require thatcertain database or table privileges be set before CICS/6000 can connect tothem. We discuss these privileges for each XA-enabled RM in Chapter 3, “LocalImplementation” on page 15 and Chapter 4, “Remote Implementation” onpage 49.

2.2 CICS/6000 ConceptsIn this section we introduce the concepts of:

• XA resource definitions

• CICS/6000 region environment setup

• CICS/6000 region startup.

2.2.1 XA Resource DefinitionsCICS/6000 uses the product definitions to hold information it needs to interface toother transactional products, using the X/Open XA protocol. Each XA definition(XAD) entry contains information for one product. These entries can be found ina file called XAD.stanza in the directory/var/cics_regions/ < r e g i o n _ n a m e > /database/XAD , where < r e g i o n _ n a m e > isthe name of the CICS/6000 region.

Each XAD entry consists of several attributes:

< K e y > Represents the name of the product and is the key for the XAD entry.Product names can be up to 12 characters long.

GroupName Group to which resource belongs. This 8-byte ASCII text attributeassigns a group name to which this resource description entrybelongs. The default value is ″″.

ActivateOnStartup If you set this attribute to yes, CICS/6000 always copies theresource definition from the permanent database to the run-timedatabase at cold start. The default is yes.

AmendCounter Number of updates (internal use only). Reserved for CICS/6000internal use.

Permanent Specifies whether or not CICS/6000 permits you to amend or deletethe permanent database entry. If you set the attribute to no, you canamend or delete the entry. The default value is no.

SwitchLoadFile Switch Load file path name. This ASCII text attribute is a pathname to an object file (linked using ld but not a main() program) thatcontains the xa_switch_t structure definition and xa supportsubroutines for this XA-compliant product. The default value is ″″.

XAOpen Resource manager initialization string, an ASCII character string. It isdescribed as the XA open string in 2.1.2, “XA Open String” onpage 7. It is specific to the RM. The default is ″″.

XAClose Resource manager termination string. This is an ASCII characterstring that is passed to the XA-compliant product′s xa_close_entry()function call. The layout of the string is specific to the XA productbeing defined. The default value is ″″.


XASerialize Resource manager serialization attribute. Indicates how CICS/6000should serialize access to an XA-compliant RM in a multithreadprocess. This attribute is used to indicate that an XA-compliantresource manager supports xa calls from multiple threads, and whichstyle of serialization the XA-compliant product requires. The defaultvalue is all_operations. The following values are accepted:

all_operations CICS/6000 serializes around each xa call made. This isthe default setting.

start_end CICS/6000 serializes around xa_start and xa_end calls.Serialization takes place around a transaction.

single_association or multiple_association Allows CICS/6000 toserialize based on whether the XA-compliant product isthread aware or not.

2.2.2 CICS/6000 Region Environment SetupThe file environment in the /var/c ics_regions/<region_name> directory, where< r e g i o n _ n a m e > is the name of the CICS/6000 region, contains a list ofenvironment variables that are set before the startup of the region. Thesevariables may be specific to the RM to which you are connecting.

2.2.3 CICS/6000 Region StartupBelow we present an overview of the steps involved in the startup of a CICS/6000Region when connecting to an XA-compliant RDBMS. We discuss the steps upto generic CICS/6000 initialization only. RM specific initialization is discussed inChapter 5, “ Resource Manager Initialization at Region Startup: A DiagrammaticView” on page 61.

Note

The RM must be running at CICS/6000 region startup. If the RM is notrunning, the region startup will fail on the xa_open() call.

Figure 4 on page 12 shows the flow of the CICS/6000 region startup.


Figure 4. CICS/6000 Region Startup

The steps in the process are discussed as follows:

1. Start up CICS/6000 region

Enter the following command:

$ smitty cics└─� Manage CICS/6000 Regions

└─� Cold Start a CICS/6000 Region

or use the fastpath command: smitty cicscoldstart.


In the first phase of the startup the cics process initializes the cicsld, cicsam,cicsrm, and cicsic processes. In the XA implementation we are interestedonly in the cicsam initialization.

2. Initialize application server (cicsam)

The application server registers its interfaces with cicsts.

3. Scan XAD definitions

As part of the XA interface registration the XA definitions are scanned toobtain the Switch Load File name and the XA Open String of the RMs.

4. Load Switch Load files

The Switch Load file as discussed in 2.2.1, “XA Resource Definitions” onpage 10 is an object file. It is loaded into a CICS application server usingthe AIX load() system call. The object file must be linked such that a functioncall is the entry point. This function entry returns the address of anxa_switch_t structure (see 2.1.3, “Resource Manager Switch” on page 8).

5. RM registration

CICS/6000 issues an xa_open() to the RM using the XA open string toprepare it for use in a distributed processing environment. Details of eachRM registration are discussed in Chapter 5, “ Resource ManagerInitialization at Region Startup: A Diagrammatic View” on page 61.



Chapter 3. Local Implementation

In this chapter we describe the implementation steps needed to integrateCICS/6000 with UNIX RDBMSs. We deal with the case where both CICS/6000 andthe UNIX RDBMSs reside on the same machine.

We explain the implementation of four UNIX RDBMSs:

• DATABASE 2 AIX/6000• Informix Version 5• Oracle7• Sybase System 10.

3.1 Before You StartCheck the following:

• AIX 3.2.5 is installed and running on your RISC System/6000.

• The following CICS/6000 Licensed Program Products (LPPs) are installed:

− cics6000base.base.obj 1.1.0.0

− cics6000.dev.obj 1.1.0.0

− cics6000.prod.obj 1.1.0.0

− cics6000clt.dev.obj 1.1.0.0

− cics6000clt.prod.obj 1.1.0.0

− cics6000mEn_US.msg 1.1.0.0.

• The following Encina LPPs are installed:

− encServ.obj 1.1.1.0

− encServmEn_US.msg 1.1.1.0

− encExec.obj 1.1.1.0

− encExecmEn_US.msg 1.1.1.0

− encSfs.obj 1.1.1.0

− encSfsmEn_US.msg 1.1.1.0.

• The following DCE LPPs are installed:

− dcebase.base.obj 1.2.0.0

− dcebase.En_US.msg 1.2.0.0

− dcebase.admin.obj 1.2.0.0

− dcebase.appdev.obj 1.2.0.0

− dcecds.obj 1.2.0.0

− dcecds.En_US.msg 1.2.0.0

− dcesec.obj 1.2.0.0

− dcesec.En_US.msg 1.2.0.0

− dcepthreads.obj 1.1.0.0

− dcepthreads.En_US.msg 1.1.0.0.


• The following PTFs have been applied:

− CICS/6000 December PTFs: U420315, U420263, U422258, U421442

− DCE base U419616

− DCE threads U422532.

• DCE is configured on your machine as either a client or a server.

• Encina Structured File Server and logserver are configured and running.

• A CICS/6000 region has been created.

Note

We ran the XA interface with CICS/6000 Version 1, Release 1, Level 0.Informix Version 5.02 and Sybase System 10 are officially supported withCICS/6000 Version 1, Release 1, Level 1.

For more information on configuration requirements refer to the AIX CICS/6000Planning and Installation Guide.

3.2 DATABASE 2 AIX/6000We divide our discussion of the DATABASE 2 AIX/6000 implementation into thefollowing parts:

• DATABASE 2 AIX/6000 configuration

• CICS/6000 configuration.

3.2.1 Before You StartMake sure that the following DATABASE 2 AIX/6000 products are installed onyour machine:

• IBM DATABASE 2 AIX/6000

• IBM AIX DATABASE 2 Client Application Enabler/6000

• IBM AIX DATABASE 2 Software Developer′s Kit.

Make sure that you have defined an instance for DATABASE 2 AIX/6000.

To create an instance:

1. Create an AIX userid. This is the instance owner ID.

2. Run the following command: /usr/lpp/db2_01_01_0000/instance/db2instanceinstance_name, where instance_name is the AIX user created in step 1.

3. Edit the .profile file of the instance owner and add the following line:.$HOME/sqllib/db2profile.

For more information on how to create an instance refer to the IBM DATABASE 2AIX/6000 Administration Guide.


3.2.2 DATABASE 2 AIX/6000 ConfigurationThe items that you need to consider in the implementation of DATABASE 2AIX/6000 are:

1. Shared object

2. XA open string

3. Resource manager switch

4. Database privileges.

We deal with each of these in the sections that follow.

3.2.2.1 Shared ObjectYou need to create a DATABASE 2 AIX/6000 shared object code. As its namesuggests, the shared code is loaded into memory once in the shared librarysegment and shared by all processes that reference it. The CICS/6000 COBOLrun-time environment, CICS/6000 C transactions, and the Switch Load file needto reference the DATABASE 2 AIX/6000 shared object at run time.

The DATABASE 2 AIX/6000 shared object db2.o must be used as input whenlinking CICS/6000 C programs to ensure that both the CICS/6000 system and theCICS/6000 C programs share the same copy of DATABASE 2 AIX/6000.

The steps to create the DATABASE 2 AIX/6000 shared object are:

1. AIX login as root

2. cd /usr/lpp/db2_01_01_0000/lib

3. ar -vx libdb2.a

4. mv shr.o db2.o.

Symbolic Links

If, after installing DATABASE 2 AIX/6000, you used the db2ln script to createsymbolic links from /usr to the DATABASE 2 AIX/6000 library and includefiles, you need to add another symbolic link from /usr to db2.o as follows:

ln -s /usr/lpp/db2_01_01_0000/lib/db2.o /usr/lib/db2.o.

These symbolic links allow your programs to be linked without any referenceto a specific release of DATABASE 2 AIX/6000. If you do not use thesesymbolic links, you will have to relink your programs when you migrate to anewer release of DATABASE 2 AIX/6000.

3.2.2.2 XA Open StringWe define the syntax of the XA open string in this section.

The XA open string must have the following syntax:

database_alias, < username,password> .

where the words in italics are values that you input.

Chapter 3. Local Implementation 17

The field values are:

database_alias Is the database name unless you have explicitly cataloged analias name after database creation.

username Indicates a valid AIX userid. This is optional. It is used to provideauthentication information to the database if the database is set upwith authenticat ion=server .

password This is the password for the above-mentioned userid.

Note

Because DATABASE 2 AIX/6000 uses a database name in the XA open string,you will need to:

• Create the database before region startup.

• Define an XA open string for each database that you use in a CICS/6000application.

3.2.2.3 Resource Manager SwitchFigure 5 shows the source code for the Switch Load file for DATABASE 2AIX/6000. You can find this file in the /usr/lpp/cics/v1.1/src/examples/xadirectory, db2xa.c.

#include < s t d i o . h >#include < t m x a / x a . h >

extern struct xa_switch_t db2xa_switch;extern struct xa_switch_t RegXA_xa_switch;extern struct xa_switch_t *cics_xa_switch;

struct xa_switch_t *CICS_XA_Init(void){

cics_xa_switch = &db2xa_switch;

cics_xa_init();

return(&RegXA_xa_switch);}

Figure 5. Source Code for DATABASE 2 AIX/6000 Switch Load File

Build the Switch Load file object, db2xa , by issuing the following command:

make -f db2xa.mk.

Figure 6 on page 19 shows the source code for the db2xa.mk makefile. You canalso find the code for this makefile in the /usr/lpp/cics/v1.1/src/examples/xadirectory, db2xa.mk.

This makefile assumes you have run db2ln (see the IBM DATABASE 2 AIX/6000Installation Guide for more details).


all: db2xa.cxlc_r -v -I/usr/lpp/encina/include \db2xa.c \-o db2xa \-eCICS_XA_Init \-L/usr/lpp/cics/v1.1/lib \-L/usr/lpp/encina/l ib \�-L/usr/lib�\�-lregxart -lsupprrt -linfdu -linftrrt -lsuperrt -ltasta -ltaslu \/usr/lpp/cics/v1.1/lib/regxa_swxa.o \/usr/l ib/db2.o

Figure 6. Source Code for DATABASE 2 AIX/6000 Switch Load File Makefi le

Note

In our installation, we added the highlighted line in Figure 6 to the db2xa.mkmakefile. Without this we got the following error at region startup:

� �ERZ5801E/0005 03/31/94 13:42:30 sanjose : Unsuccessful loadof program ′ / var/cics_regions/sanjose/bin/db2xa′ ; errno 8.ERZ5802E/0006 03/31/94 13:42:30 sanjose : Information onunsuccessful program load: ′3 getgrset /usr/lib/libs.a shr.o′ .ERZ1647E/0232 03/31/94 13:42:30 sanjose : Abnormal terminationA16D: Unable to load an External Resource Manager XA Support file.

� �

This has been fixed with the PTF U426881.

The make command creates a loadable file called db2xa. You must copy thisfile to the region directory.

Run the following command:

cp db2xa /var/cics_regions/<region_name>/bin/db2xa

where < r e g i o n _ n a m e > is the name of your region.

Below we describe the db2xa switch; it is for information only. No configurationis required.

Other than the pointers to the xa_ routines, the fields returned by the DATABASE2 AIX/6000 db2xa_switch are:

Field Description

name DB2/6000

flags TMREGISTER||TMNOMIGRATE

Explicitly state that the TM should not use association migration orasynchronous operation. Implicitly state that this RM is to usedynamic registration.



3.2.2.4 Database PrivilegesAt region startup the CICS application server makes an initial connection to theRM (in this case DATABASE 2 AIX/6000) using the XA open string. The AIXuserid used is cics. DATABASE 2 AIX/6000 uses AIX security; therefore the cicsuserid must have the privilege to connect to the database.

This privilege is given by the following commands:

db2 connect to cicstest

db2 grant connect on database to cics.

3.2.3 CICS/6000 ConfigurationThe steps required for the CICS/6000 setup are as follows:

1. Define XA resources.

2. Set up CICS/6000 region environment.

3. Start up CICS/6000 region.

3.2.3.1 XA Resource DefinitionsCICS/6000 resources are defined, created, changed, and removed using SMIT.Each resource type has definitions, and these are stored in AIX stanza files.

To access and modify resources in CICS/6000 your AIX userid must belong to thecics group. To check whether your userid belongs to this group, you can enterthe following command:

$ smitty└─� Security & Users

└─� Users └─� Change/Show Characteristics of a User

or use the fastpath command, smitty chuser, to get the Change User Attributespanel shown in Figure 7 on page 21.


� �Change User Attributes

Type or select values in entry fields.Press Enter AFTER making all desired changes.

[TOP] [Entry Fields]* User NAME jasjitUser ID [205] #ADMINISTRATIVE User? +LOGIN User? +PRIMARY Group [staff] +Group set [�staff,cics�] +ADMINISTRATIVE Groups [] +SU Groups [] +HOME Directory [/u/jasjit]Initial PROGRAM [/bin/ksh]User information []Another user CAN SU to user? +User CAN RLOGIN? +Trusted path? +

[MORE...12]

F1=Help F2=Refresh F3=Cancel F4=ListF5=Reset F6=Command F7=Edit F8=ImageF9=Shell F10=Exit Enter=Do

� �Figure 7. Check That User Is Member of the cics Group

User jasjit belongs to the group set containing the groups cics, staff, so jasjit hasthe authority to access and modify CICS/6000 resources.

Now, you need to define DATABASE 2 AIX/6000 as a resource manager toCICS/6000. .

Enter the following command to define a resource manager to the CICS/6000stanza database:


└─� Define Resources for a CICS/6000 Region └─� Manage Resource(s) └─� XA Definitions └─� Add New └─� Model XA Definition Identifier

or use the fastpath command, smitty cicsaddxad, to get the Add XA Definitionpanel shown in Figure 8 on page 22.


� �Add XA Definition


[Entry Fields]* XA Definition Identifier [�db2xad�]* Model XA Definition Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install Add +Group to which resource belongs []Activate resource at cold start? yes +Resource description [�DB2�XA�Product�Definit�>

* Number of updates 0Protect resource from modification? no +Switch Load File Path Name [�/var/cics_regions/sanj�>Resource Manager Initialization String [�cicstest�]Resource Manager Termination String []Resource Manager Serialization Attribute all_operations +


� �Figure 8. DB2 XA Definit ion for CICS/6000

The highlighted values are as follows:

• The XA Definition Identifier is unique for every XA definition.

• The Resource description is a comment line.

• The Switch Load File Path name is:

/var/c ics_regions/<region_name>/bin/db2xa,

where < r e g i o n _ n a m e > is the name of your region. This Switch Load file isthe file you created in 3.2.2.3, “Resource Manager Switch” on page 18.

• cicstest is the XA open string. No user name or password has beenprovided. This implies that the database was created withauthent icat ion=cl ient .

3.2.3.2 CICS/6000 Region Environment SetupIn the /var /c ics_regions/<region_name> region directory there is a file namedenvironment, which sets up the environment variables on region startup.

The environment variable for DATABASE 2 AIX/6000 is:

DB2INSTANCE Defines the instance for CICS/6000 to refer to.

The syntax for an entry in the environment file is:

DB2INSTANCE=db2 ,

where db2 is the instance name.


3.2.3.3 CICS/6000 Region StartupNow that you have configured all of the required components, it is time to bringup the CICS/6000 region.

Enter the following command to bring up the CICS/6000 region:



or use the fastpath command, smitty cicscoldstart, to get the Cold StartCICS/6000 Region panel shown in Figure 9.

� �

Cold Start CICS/6000 Region


[TOP] [Entry Fields]* Region identifier sanjoseResource description [Region Definition]Startup groups []Programs to execute at startup []Programs to execute at phase 1 of shutdown []Programs to execute at phase 2 of shutdown []Name of the default user identifier [CICSUSER]Type of RSL checking for Files external +Type of RSL checking for TDQs external +Type of RSL checking for TSQs external +Type of RSL checking for Journals external +Type of RSL checking for Programs external +Type of RSL checking for Transactions external +Do you want to use an External Security Manager? no +

[MORE...54]


� �Figure 9. Cold Start the CICS/6000 Region

Check the console.msg file in the /var/c ics_regions/<region_name> directoryfor the successful startup of the region. You should see a message similar tothis:

� �ERZ8006I/0806 03/31/94 17:50:43 sanjose : XA_OPEN succeeded:Application Server 7 connected to ′ DB2/6000′ using XA_OPEN string′ cicstest′ERZ1020I/0345 03/31/94 17:50:54 sanjose : *** CICS/6000 startupis complete ***

� �


3.3 Informix Version 5We divide our discussion of the Informix Version 5 implementation into thefollowing parts:

• Informix Version 5 configuration


3.3.1 Before You StartMake sure that the following Informix Version 5 products have been installed:

• Informix Online Version 5.01

• Informix TP/XA Version 5.01

• Informix ESQL/C Version 5.01

• Informix ESQL/COBOL Version 5.01.

For more information on the installation of Informix Version 5 products refer tothe Informix UNIX Products Installation Guide Version 5.0.

3.3.2 Informix Version 5 ConfigurationThe items that you need to consider in the implementation of Informix Version 5are:

• Shared objects

• XA open string

• Resource manager switch.


3.3.2.1 Shared ObjectsYou need to select an Informix Version 5 shared object code. As its namesuggests, this shared code is loaded into memory once in the shared librarysegment and shared by all processes that reference it. The CICS/6000 COBOLrun-time environment, CICS/6000 C transactions, and the Switch Load file needto reference the Informix Version 5 shared object at run time.

Two shared objects are defined for the Informix Version 5 TP/XA product.

libinf501cs.o In ESQL/COBOL, statement identifiers (created with a PREPAREstatement) and cursor names (created with a DECLARE statement)are not case sensitive, by default. If you want the ESQL/COBOLpreprocessor to be case sensitive with respect to statementidentifiers and cursor names, you should use this object.

libinf501ci.o If you are going to be using ESQL/C only or you do not require theESQL/COBOL preprocessor to be case sensitive with respect tostatement identifiers and cursor names, you should use this object.

These objects reside in the /usr/informix/lib/esql directory.


3.3.2.2 XA Open StringThe XA open string must have the following syntax:

{required_fields:...} [optional_fields].

The required_fields are:

• database_name

This is the name of a database that has been created on Informix Version 5.CICS/6000 connects to this database.

The optional_fields are:

• INFORMIXDIR=dirname

This is the full path name of the directory in which the Informix Version 5products are installed.

Note

Although the Informix TP/XA User Manual states that theINFORMIXDIR=dirname field is optional, our experience shows that it ismandatory.

• TBCONFIG= tbconfigname :

This is the name of the tbconfig file used for the Informix Version 5 OnlineRM. If not specified, the default value is tbconfig.

• SQLHOST= hostname :

This is the name of the computer on which the Informix Version 5 Online RMresides. If not specified, the default value is the local computer.

• SQLEXEC=execname

This is an alternative executable name for the Informix Version 5 Online RM.This is optional. If it is not specified, the default value is$INFORMIXDIR/lib/sqlturbo.

The words in italics are values that you input, and the words in capitals are to bewritten as is. The string should not contain any blanks or line feeds. Each fieldis separated by a colon (:).

A sample XA open string for Informix Version 5 is:

cicstest:INFORMIXDIR=/informix:TBCONFIG=tbconfig.INF.

Note

Informix Version 5 TP/XA does not allow more than one connection to thetransaction manager (in this case, CICS/6000). As the XA open string refersto an Informix Version 5 database, a CICS/6000 application can refer to onlyone database.


3.3.2.3 Resource Manager SwitchFigure 10 on page 27 shows the source code for the Switch Load file for InformixVersion 5. You can find this file in the /usr/lpp/cics/v1.1/src/examples/xadirectory, informxa.c.


#include < t m x a / x a 9 0 . h >

extern struct xa90_switch_t infx_xa_switch;extern struct xa90_switch_t *cics_xa90_switch;extern int (*cics_xa_sql_error)();

void cics_xa90_init();

struct sqlca_s{long sqlcode;char sqlerrm [72]char sqlerrp [8]long sqlerrd [6]struct sqlcaw_s

{char sqlwarn0;char sqlwarn1;char sqlwarn2;char sqlwarn3;char sqlwarn4;char sqlwarn5;char sqlwarn6;char sqlwarn7;} sqlwarn;

};extern struct sqlca_s sqlca;extern long SQLCODE;

extern long *cics_sqlca_code;extern char cics_sqlca_message [400]

int do_sql_error(void){

char errmsg [400]rgetmsg(sqlca.sqlcode, errmsg, sizeof(errmsg));cics_sqlca_code = &sqlca.sqlcode;strcpy(cics_sqlca_message,errmsg);

}


cics_xa_sql_error = &do_sql_error;cics_xa90_switch = &infx_xa_switch;cics_xa90_init();

return(&tmxa_xa90Switch);}

Figure 10. Source Code for Informix Version 5 Switch Load File


The Switch Load file defines an error handling routine, do_sql_error, that allowsthe display of error messages on the CICS console when set in the sqlca byInformix TP/XA.

To create the Switch Load file informxa object you must compile and link thecode given in Figure 10 on page 27. Figure 11 shows the source code for themakefile. You can also find the code for this makefile in the directory/usr/lpp/cics/v1.1/src/examples/xa directory, informxa.mk.

You must edit the informxa.mk file and replace the following:

• <Full pathname of Informix shared object> with the appropriate objectname. The two objects provided are described in 3.3.2.1, “Shared Objects”on page 24. Only one of these two objects can be used.

For example, if the object is libinf501cs.o, you must replace the path namewith /usr/informix/lib/esql/libinf501cs.o

• <Full pathname of Informix lib directory> with the path name of thedirectory containing the Informix shared object. For example, if the object isin the /usr/informix/lib/esql directory, the replaced line should be:

-L/usr/informix/l ib/esql.

To build the Switch Load file object, informxa, issue the following command:

make -f informxa.mk.

all: informxa.cxlc_r -v -I/usr/lpp/encina/include \informxa.c \-o informxa \-eCICS_XA_Init \-L�<Full�pathname�of�Informix�lib�directory>�\a�-L/usr/lpp/encina/l ib \-L/usr/lpp/cics/v1.1/lib \-lregxart \-lEncServer \�<Full�pathname�of�Informix�share�object>�

Figure 11. Source Code for Informix Version 5 Switch Load File Makefi le

The make command creates a loadable file called informxa. You must copy thisfile to the region directory.


cp informxa /var/cics_regions/<region_name>/bin/ informxa,


Below we describe the infx_xa switch; it is for information only. No configurationis required.


Other than the pointers to the xa_ routines, the fields returned by the InformixVersion 5 infx_xa_switch are:

Field Description

name INFORMIX

flags TMNOFLAGS

Explicitly state that the TM should not use association migration orasynchronous operation. Also implicitly state that this RM is not touse dynamic registration.

version value must be 0.


• Define XA resources.

• Set up CICS/6000 region environment.

• Start up CICS/6000 region.


To access and modify resources in CICS/6000 your AIX userid must belong to thecics group. To check whether your userid belongs to this group, refer toFigure 7 on page 21.

Now you need to define Informix Version 5 as a resource manager to CICS/6000.






� �

Add XA Definition


[Entry Fields]* XA Definition Identifier [�informxa�]* Model XA Definition Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install Add +Group to which resource belongs []Activate resource at cold start? yes +Resource description [�Informix�XA�Product�De�>

* Number of updates 4Protect resource from modification? no +Switch Load File Path Name [�/var/cics_regions/sanj>�Resource Manager Initialization String [�cicstest:INFORMIXDIR=/>�Resource Manager Termination String []Resource Manager Serialization Attribute all_operations +

F1=Help F2=Refresh F3=Cancel F4=ListF5=Reset F6=Command F7=Edit F8=ImageF9=Shell F10=Exit Enter=Do� �

Figure 12. Informix Version 5 XA Definit ion for CICS/6000


• The XA Definition Identifier is unique for every XA definition.

• The Resource description is a comment line.

• The Switch Load File Path Name is:

/var/c ics_regions/<region_name>/bin/ informxa,

where < r e g i o n _ n a m e > is the name of your region. This Switch Load file isthe file created in 3.3.2.3, “Resource Manager Switch” on page 26.

• cicstest:INFORMIXDIR=/informix:TBCONFIG=tbconfig.INF is the XA openstring.

3.3.3.2 CICS Region Environment SetupIn every region directory, namely, /var/c ics_regions/<region_name>, there is afile named environment which sets up the environment variables on regionstartup.

There are no required environment variables for Informix Version 5. Thevariables that can be specified are:

• INFORMIXDIR

• SQLEXEC.

The values of these are as specified in 3.3.2.2, “XA Open String” on page 25.


3.3.3.3 CICS/6000 Region StartupNow, that you have configured all of the required components, it is time to bringup the CICS/6000 Region.

Enter the following command to bring up the CICS/6000 region:



or use the fastpath command: smitty cicscoldstart, to get the Cold StartCICS/6000 Region panel shown in Figure 9 on page 23.


� �ERZ8006I/0806 03/31/94 17:50:44 sanjose : XA_OPEN succeeded:Application Server 7 connected to ′ INFORMIX-ONLINE′ using XA_OPENstring ′ cicstest:INFORMIXDIR=/home/informix:TBCONFIG=tbconfig.INF′ERZ1020I/0345 03/31/94 17:50:54 sanjose : *** CICS/6000 startupis complete ***

� �

3.4 Oracle7We divide our discussion of the Oracle7 implementation into the following parts:

• Oracle7 configuration


3.4.1 Before You StartMake sure that the following Oracle7 products have been installed:

• ORACLE7 Distributed Database option 7.0.16

• ORACLE7 Server (RDBMS) 7.0.16.4.0

• ORACLE7 XA Library 1.0.3.0.0

• Pro*C 1.5.10.1.0

• Pro*Cobol 1.5.10.1.0

• SQL*Plus 3.1.2.3.1

• SQL*Net V2 2.0.15.0.0

• TCP/IP Protocol Adapter (V2) 2.0.15.0.0.

For more information on the installation of the Oracle7 products refer to Oracle 7for IBM RISC/6000 Installation and Configuration Guide.


3.4.2 Oracle7 ConfigurationThe items that you need to consider in the implementation of Oracle7 are:

1. Shared library

2. XA open string


4. Table privileges.


3.4.2.1 Shared LibraryYou need to install an Oracle7 shared library for Oracle7 XA. As its namesuggests, the shared code is loaded into memory once in the shared librarysegment and shared by all processes that reference it. The CICS/6000 COBOLrun-time environment, CICS/6000 C transactions, and the Switch Load file needto reference the Oracle7 XA shared library at run time.

During the installation of the Oracle7 XA Library you will be prompted with:

Oracle XA installation

Some TP Monitors require a shared version of the ORACLE7 libraries. Doyou want to install a shared version of the libraries?

Make sure you select �Yes� to this prompt. The installation will create a sharedlibrary in the $ORACLE_HOME/lib directory. This library is calledlibsharesqlxa.a. Copy this library to the /usr/ l ib directory by running thecommand as the root AIX userid:

cp $ORACLE_HOME/lib/libsharesqlxa.a /usr/lib.

3.4.2.2 XA Open StringThe XA open string must have the following syntax:Oracle_XA{ + required_fields...} [ + optional_fields]

where the required_fields are:

• Acc=P { / / | /user/password }

Acc Specifies the user access information

P// Indicates that no explicit user or password information is providedand that the ops$login form will be used.

P/user/password: Indicates a valid ORACLE userid and the correspondingpassword.

• SesTm= session_time_limit

SesTm Specifies the maximum amount of time that a transaction can beinactive before the system automatically deletes it. The unit oftime is in seconds.

The optional_fields are:

• DB = dbname


DB Specifies the database name

dbname Indicates the name Oracle precompilers use to identify thedatabase. This field is required only when applications explicitlyspecify the database name (that is, use an AT clause in their SQLstatements).

• GPwd=P /group_password:

GPwd Specifies the server security password.

P/group_password Indicates the server security group password name.Server security groups provide an extra level of protection fordifferent applications running against the same ORACLE instance.The default is an ORACLE-defined server security group.

• LogDir = log_dir

LogDir Specifies the directory on a local machine where the Oracle XAlibrary error and tracing information can be logged.

log_dir Indicates the path name of the directory. The default is$ORACLE_HOME/rdbms/log if ORACLE_HOME is set; otherwise itis the current directory.

• MaxCur = maximum_#_of_open_cursors

MaxCur Specifies the number of cursors to be allocated when thedatabase is opened. It serves the same purpose as theprecompiler option, maxopencursors.

maximum_#_of_open_cursors: Indicates the number of open cursors to becached.

• SqlNet = connect_string

SqlNet Specifies the SQL*Net connect string

connect_string: Indicates the string to log on to the system. The connectstring can be either an SQL*Net V1 string, SQL*Net V2 string, orSQL*Net V2 alias. This field is required when you are setting upOracle on a machine separate from the TP Monitor.

The words in italics are values that you input, and the words in boldface are tobe written as is. The string should not contain any blanks or line feeds.

A sample of an XA open string for Oracle7 is:

Orac le_XA+Acc=P/sco t t / t i ge r+SesTm=35+LogDi r= / tmp/ log .o rac le.

3.4.2.3 Resource Manager SwitchFigure 13 on page 34 shows the source code for the Switch Load file forOracle7. You can find this file in the /usr/lpp/cics/v1.1/src/examples/xa directory,oraclexa.c.



extern struct xa_switch_t xaosw;extern struct xa_switch_t RegXA_xa_switch;extern struct xa_switch_t *cics_xa_switch;


cics_xa_switch = &xaosw;

cics_xa_init();


Figure 13. Source Code for Oracle7 Switch Load File

To create the Switch Load file oraclexa oracle you must compile and link thecode given in Figure 13. Figure 14 on page 35 shows the source code for themakefile. You can also find the code for this makefile in the/usr/lpp/cics/v1.1/src/examples/xa directory, oraclexa.mk.

You must edit this oraclexa.mk file and replace the following:

• <Full pathname of Oracle lib directory> with the path name of the directorycontaining the Oracle shared library.

• <Full pathname of Oracle shared library> with the appropriate library name.

We copied the shared library, libsharesqlxa.a, into the /usr/lib directory.Therefore, the replaced lines should be:

�-L/usr/lib�\�

�-lsharesqlxa�

Oracle Makefile

The oraclexa.mk makefile may have the home directory and the sharedlibrary names already added. Make sure that the home directory namematches the ORACLE_HOME environment variable and that the name of thelibrary is correct.

To build the Switch Load file object, oraclexa, issue the following command:

make -f oraclexa.mk.


all: oraclexa.cxlc_r -v -I/usr/lpp/encina/include oraclexa.c \-o oraclexa \-eCICS_XA_Init \-L�<Full�pathname�of�Oracle�lib�directory>� \-L/usr/lpp/cics/v1.1/lib \-L/usr/lpp/encina/l ib \-lregxart -lsuperrt -lsupprrt -linfdu -linftrrt -ltasta -ltaslu \-l�<Full�pathname�of�Oracle�shared�library>� \-lm \/usr/lpp/cics/v1.1/lib/regxa_swxa.o

Figure 14. Source Code for Oracle7 Switch Load File Makefi le

The make command creates a loadable file called oraclexa . You must copy thisfile to the region directory.


cp oraclexa /var/cics_regions/<region_name>/bin/oraclexa,


Below we describe the xaosw switch; it is for information only. No configurationis required.

Other than the pointers to the xa_ services, the fields returned by the Oracle7xaosw switch are:

Field Description

name ORACLE

flags TMNOREGISTER||TMMIGRATE

Explicitly state that the TM should not use association migration oraynchronous operation. Also implicitly state that this RM is not to usedynamic registration.

version value must be 0.

3.4.2.4 Table PrivilegesCICS/6000 connects to the RM with the Oracle userid defined in the XA openstring in 3.4.2.2, “XA Open String” on page 32. If the P// parameter is specifiedin the open string, the AIX userid must have the privileges to access thev$xatrans$ table. Otherwise, the Oracle userid specified in the open string musthave the privileges to access the v$xatrans$ table. This privilege is given by thefollowing command:

grant select on v$xatrans$ to public.






3.4.3.1 XA Resource DefinitionsCICS/6000 resources are defined, created, changed, and removed using SMIT.Each resource type has definitions, and these are stored in AIX files in the/var/cics_regions/<region_name>/database directory.


Now you need to define Oracle7 as a resource manager to CICS/6000.






� �

Add XA Definition


[Entry Fields]* XA Definition Identifier [�oraclexa�]* Model XA Definition Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install Add +Group to which resource belongs []Activate resource at cold start? yes +Resource description [�Oracle�XA�Product�De�>

* Number of updates 4Protect resource from modification? no +Switch Load File Path Name [�/var/cics_regions/sanj>�Resource Manager Initialization String [�Oracle_XA+Acc=P/scott/>�Resource Manager Termination String []Resource Manager Serialization Attribute all_operations +


Figure 15. Oracle7 XA Definit ion for CICS/6000


• The XA Definition Identifier is unique for every XA Definition.

• The Resource Description is a comment line.


/var/cics_regions/<region_name>/bin/oraclexa,


• Orac le_XA+Acc=P/sco t t / t i ge r+SesTm=35+LogDi r= / tmp/orac le . log is theXA open string.

3.4.3.2 CICS Region Environment SetupIn every region directory, namely, /var/c ics_regions/<region_name>, there is afile named environment, which sets up the environment variables on regionstartup.

Two environment variables are mandatory for Oracle7:

ORACLE_HOME Indicates the Oracle home directory

ORACLE_SID Indicates the Oracle SID used during the installation ofOracle7


3.4.3.3 CICS/6000 Region StartupNow that you have configured all of the requred components, it is time to bringup the CICS/6000 region.

Enter the following command to bring up the CICS/6000 region: .



or use the fastpath command, smitty cicscoldstart, to get the Cold StartCICS/6000 Region panel shown in Figure 9 on page 23.


� �ERZ8006I/0806 03/31/94 17:50:47 sanjose : XA_OPEN succeeded: ApplicationServer 6 connected to ′ Oracle_XA′ using XA_OPEN string ′ Oracle_XA+Acc=P/scott/tiger+SesTm=35+LogDir=/tmp′ERZ1020I/0345 03/31/94 17:50:54 sanjose : *** CICS/6000 startup iscomplete ***

� �

3.5 Sybase System 10We divide our discussion of the Sybase System 10 implementation the followingparts:

• Sybase System 10 configuration


3.5.1 Before You StartMake sure that the following Sybase System 10 products have been installed:

• Sybase SQL Server Version 10.0.1

• Sybase Embedded SQL/C

• Sybase Embedded SQL/COBOL

• Open Client/C

• Sybase XA-Library for CICS (we used beta release 10.0.1).


Note

The beta version of the XA-Library includes the following:

• XA-Library

• Open Client Client-Library

• CS-Library

• Embedded SQL/C

• Embedded SQL/COBOL.

Installing the beta version of the XA-Library installs all of these dependentproducts. Subsequent releases of XA-Library will contain only XA-Libraryfiles.

For more information on the installation of Sybase System 10 products refer toSybase SQL Server Installation Guide for AIX.

3.5.2 Sybase System 10 ConfigurationThe items that you need to consider in the implementation of Sybase System 10are:

1. Shared libraries

2. Stored procedures

3. XA configuration file

4. XA open string


6. Database privileges.


3.5.2.1 Shared LibrariesThe shared libraries required for the Sybase System 10 XA-Library are:

• CS-Library

• COMN-Library.

These can be found in the $SYBASE/lib directory. They are called libcomn.so.aand libcs.so.a, respectively. Also check for the existence of the shareablelibrary, libintl.so.a.

Note

The beta version of the Sybase System 10 XA-Library that we used did nothave the libintl.so.a library. We also had to create some links for thelibraries. In subsequent versions of the Sybase System 10 XA-Library youshould not need to do this. The patch for this is given below.


Beta version shared library patch

We had to run the following commands to create the shared libraries. (youprobably will not need to run them in subsequent releases):

Login as root

1. Create shared library libintl.so.a

• cd $SYBASE/lib

• mkdir tmp

• cp libintl.a tmp

• cd tmp

• touch libintl.shrlist

• echo ′!#/sybase/lib/libintl.so.a [libintl.so.o]′ > > l ibintl.shrlist

• ar w l ibint l .a >> l ibint l .shr l ist

• ar x libintl.a

• cc -bM:SRE -bE:libintl.shrlist -e_nostart -o libintl.so.o *.o

• ar vr libintl.so.a libintl.so.o

• cp libintl.so.a $SYBASE/lib

2. Create library links

• cd /

• mkdir remote

• mkdir /remote/pokey

• mkdir /remote/pokey/conn15

• mkdir /remote/pokey/conn15/csi

• mkdir /remote/pokey/conn15/csi/build

• mkdir /remote/pokey/conn15/csi/build/mass

• mkdir /remote/pokey/conn15/csi/build/mass/distrib

• mkdir /remote/pokey/conn15/csi/build/mass/distrib/rs6000

• mkdir /remote/pokey/conn15/csi/build/mass/distrib/rs6000/lib

• cd /remote/pokey/conn15/csi/build/mass/distrib/rs6000/lib

• ln -s $SYBASE/lib/libcomn.so.a .

• ln -s $SYBASE/lib/libintl.so.a .

3.5.2.2 Stored ProceduresTo function in a Sybase XA environment for CICS, your Sybase System 10 SQLServer requires additional stored procedures. These procedures are created asfollows:

1. Make sure that the server is running by running the following command:

ps -ef | grep sybase,

where sybase is the AIX userid used for the Sybase System 10 installation.You should see a response similar to that in the following screen:


� �sybase 14123 22058 0 09:07:19 pts/7 37:00 /sybase/bin/dataserver

-d/dev/rmasterlv -sSYBASE -e/sybase/install/errorlog -i/s sybase 22058 1 0 09:07:19 pts/7 0:00 sh ./RUN_SYBASE

� � 2. Log in as the AIX userid sybase.

3. cd $SYBASE

4. isql -Usa -P< s a _ p a s s w o r d > < ./scripts/xa_commit

5. isql -Usa -P< s a _ p a s s w o r d > < ./scripts/xa_sproc.

3.5.2.3 XA Configuration FileThe XA configuration file called xa_config is located in the $SYBASE directory.You must edit this file to reflect your configuration. Each entry in the xa_configfile has the following format:

[xa ]

lrm = lrm_connection

server = server_name

properties = prop_list

capabilities = cap_list,

where the words in italics are values that you input, and the words in boldfaceare to be written as is.


• lrm = lrm_connection

− The lrm_connection is unique to the Sybase System 10 XA environment.

− The lrm_connection or the logical resource manager (LRM) exist tosupport multiple connections to a single RM.

− Each LRM has its own user name and password.

This is required to control a particular connection′s access to SybaseSystem 10 SQL Server resources. The user name and password arespecified in the XA open string (refer to 3.5.2.4, “XA Open String” onpage 42) and as part of the CICS/6000 XA definition (refer to 3.5.3.1, “XAResource Definitions” on page 45).

• server = server_name

The server_name is the Sybase System 10 SQL Server to which the TM(CICS/6000 in this case) will connect.

• properties = prop_list

Each LRM has preconnection properties. The prop_list specifies thepreconnection properties to be set. This is an optional field.

• capabilities = cap_list

Each LRM has preconnection capabilities. The cap_list specifies thepreconnection capabilities to be set. This is an optional field.


3.5.2.4 XA Open StringThe XA open string must have the following syntax:

-Uusername -Ppassword -Nconnection_name -L log_dir

where the words in italics are values that you input, and the words in boldfaceare to be written as is.


• -Uusername

Specifies the user access information; username indicates a valid Sybaseuserid.

• -Ppassword

Indicates the password corresponding to the user.

• -Nconnection_name

Indicates a valid LRM name as specified in the xa_config file. For details oncreating LRMs refer to 3.5.2.3, “XA Configuration File” on page 41.

• -L log_dir

Indicates the path name of the directory where Sybase XA-Library errorinformation can be logged. This is an optional field. If this field is notspecified, error logging is turned off.

A sample of an XA open string for Sybase System 10 is:

-Usa -Psybase -Nconnection_1 -L/tmp/log.sybase.

3.5.2.5 Resource Manager SwitchFigure 16 on page 43 shows the source code for the Switch Load file for SybaseSystem 10. CICS/6000 Version 1 Release 1 does not include this file; subsequentreleases will include it. However, you can find this file in the Sybase System 10XA-Library installation. The directory is $SYBASE/sample/xalibrary/CICS/switch,and the file is called sybasexa.c.



extern struct xa_switch_t sybase_xa_switch;extern struct xa_switch_t RegXA_xa_switch;extern struct xa_switch_t *cics_xa_switch;

struct xa_switch_t *sybasexa(void){

cics_xa_switch = &sybase_xa_switch;

cics_xa_init();


Figure 16. Source Code for Sybase System 10 Switch Load File

To create the Switch Load file sybasexa object you must compile and link thecode given in Figure 16 Figure 17 on page 44 shows the source code for themakefile. You can also find the code for this makefile in the$SYBASE/sample/xalibrary/CICS/switch directory, sybasexa.mk.

You must make sure that the SYBASE environment variable has been set to theSybase System 10 installation directory. For example, if the installation directoryis /sybase, the export SYBASE=/sybase command sets the SYBASE environmentvariable.

To build the Switch Load file sybasexa object issue the following command:

make -f sybasexa.mk.

Note

With our configuration we found that we needed to add some more librariesto the makefile. If, after running the make command you get someunresolved symbols, add the highlighted libraries and object in Figure 17 onpage 44 to your code.


SHAROBJS = -lcs.so -lcomn.soSYB_LIBDIR = $(SYBASE)/libSYBLIBS = -lct -lintl -lm -ltcl -linsck -lxa

all: sybasexa.cxlc_r -v -I/usr/lpp/encina/include sybasexa.c \-o sybasexa \-esybasexa \-L/usr/lpp/cics/v1.1/lib \-L$(SYB_LIBDIR) \$(SHAROBJS) \$(SYBLIBS) \-lregxart \

�-lsupprt�-linfdu�-linftrrt�-lsuperrt�-ltasta�-ltaslu�\��-l/usr/lpp/cics/v1.1/lib/regxa_swxa.o�

Figure 17. Source Code for Sybase System 10 Switch Load File Makefile.

Below we describe the sybase_xa switch; it is for information only. Noconfiguration is required.

Other than the pointers to the xa_ routines the fields returned by the SybaseSystem 10 sybase_xa_switch are:

Field Description

name SYBASE_SQL_SERVER

flags TMNOFLAGS

Explicitly state that the TM should not use association migration orasynchronous operation. Also implicitly state that this RM is not touse dynamic registration.


3.5.2.6 Database PrivilegesThe Sybase System 10 XA open string described in 3.5.2.4, “XA Open String” onpage 42 does not explicitly connect to a database. Therefore no databaseprivileges need to be set for the CICS/6000 userid (the userid defined atCICS/6000 installation).








Now you need to define Sybase System 10 as a resource manager to CICS/6000.




or use the fastpath command, smitty cicsaddxad, to get the Add XA Definitionpanel shown in Figure 18.

� �

Add XA Definition


[Entry Fields]* XA Definition Identifier [�sybasexa�]* Model XA Definition Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install Add +Group to which resource belongs []Activate resource at cold start? yes +Resource description [�Sybase�XA�Product�De�>

* Number of updates 4Protect resource from modification? no +Switch Load File Path Name [�/var/cics_regions/sanj>�Resource Manager Initialization String [�″-Usa�-Psybase�-Nconnec>�Resource Manager Termination String []Resource Manager Serialization Attribute all_operations +


Figure 18. Sybase System 10 XA Definit ion for CICS/6000


Note

When typing the Resource Manager Initialization String make sure that youbegin and end the string with a double quote (″).


• The XA Definition Identifier is unique for every XA Definition.

• The Resource Description is a comment line.


/var/cics_regions/<region_name>/bin/sybasexa,


• -Usa -Psybase -Nconnection_1 -L/tmp/sybase.log is the XA open string.

3.5.3.2 CICS Region Environment SetupIn every region directory, namely, /var/c ics_regions/<region_name>, there is afile named environment, which sets up the environment variables on regionstartup.

You need to add a mandatory environment variable for Sybase System 10. Thesyntax is:

SYBASE= install_dir,

where

install_dir is the Sybase System 10 installation directory.

3.5.3.3 CICS/6000 Region StartupNow that you have configured all of the required components, it is time to bringup the CICS/6000 region.

Enter the following command to bring up the CICS/6000 region.:



or use the fastpath command, smitty cicscoldstart, to get the Cold StartCICS/6000 Region panel shown in Figure 9 on page 23.



� �ERZ8006I/0806 03/31/94 17:50:47 sanjose : XA_OPEN succeeded: ApplicationServer 7 connected to ′ SYBASE_SQL_SERVER′ using XA_OPEN string ′ -Usa -Psybase-Nconnection_2 -L/tmp/log.server′ERZ1020I/0345 03/31/94 17:50:54 sanjose : *** CICS/6000 startupis complete ***

� �



Chapter 4. Remote Implementation

In this chapter we describe the implementation steps needed to integrateCICS/6000 with UNIX RDBMSs. We deal with the case where the UNIX RDBMSand the CICS/6000 system reside on separate machines.

We explain the implementation of three UNIX RDBMSs:

• DATABASE 2 AIX/6000• Oracle7• Sybase System 10.

Note

We do not include Informix Version 5 in this list because it does not supportremote access to a CICS/6000 system.

4.1 Before You StartThis implementaion is spread over two RISC System/6000s. The UNIX RDBMSclient and CICS/6000 reside on one machine. For the purpose of this section wecall this the client machine. The UNIX RDBMS server resides on the secondmachine. We will call this the server machine.

Check the following on the client machine:


• The following CICS/6000 Licensed Program Products (LPPs) are installed:

− cics6000base.base.obj 1.1.0.0

− cics6000.dev.obj 1.1.0.0

− cics6000.prod.obj 1.1.0.0

− cics6000clt.dev.obj 1.1.0.0

− cics6000clt.prod.obj 1.1.0.0

− cics6000mEn_US.msg 1.1.0.0.

• The following Encina LPPs are installed:

− encServ.obj 1.1.1.0

− encServmEn_US.msg 1.1.1.0

− encExec.obj 1.1.1.0

− encExecmEn_US.msg 1.1.1.0

− encSfs.obj 1.1.1.0

− encSfsmEn_US.msg 1.1.1.0.

• The following DCE LPPs are installed:

− dcebase.base.obj 1.2.0.0

− dcebase.En_US.msg 1.2.0.0

− dcebase.admin.obj 1.2.0.0


− dcebase.appdev.obj 1.2.0.0

− dcecds.obj 1.2.0.0

− dcecds.En_US.msg 1.2.0.0

− dcesec.obj 1.2.0.0

− dcesec.En_US.msg 1.2.0.0

− dcepthreads.obj 1.1.0.0

− dcepthreads.En_US.msg 1.1.0.0.

• The following PTFs have been applied:

− CICS/6000 December PTFs: U420315, U420263, U422258, U421442

− DCE base U419616

− DCE threads U422532.

• DCE is configured on your machine as either a client or a server.

• Encina Structured File Server and logserver are configured and running.

• A CICS/6000 region has been created.

• UNIX RDBMS client.

Check the following on the server machine:


• UNIX RDBMS server.

Note

We ran the XA interface with CICS/6000 Version 1, Release 1, Level 0.Informix Version 5.02 and Sybase System 10 are officially supported withCICS/6000 Version 1, Release 1, Level 1.

For more information on configuration requirements refer to the AIX CICS/6000Planning and Installation Guide.

4.2 DATABASE 2 AIX/6000We divide our discussion of the DATABASE 2 AIX/6000 implementation into thefollowing parts:

• DATABASE 2 AIX/6000 configuration


4.2.1 Before You StartMake sure that the following DATABASE 2 AIX/6000 products are installed on theclient:

• IBM AIX DATABASE 2 Client Application Enabler/6000

• IBM AIX DATABASE2 Software Developer′s Kit.

Make sure that the following DATABASE 2 AIX/6000 products are installed on theserver:

• IBM DATABASE 2 AIX/6000


• IBM AIX DATABASE 2 Client Support/6000.

Make sure that you have defined an instance on both the DATABASE 2 AIX/6000client and server machines.

Creation of an instance is described in 3.2.1, “Before You Start” on page 16.

Make sure that you have created a DATABASE 2 AIX/6000 client-serverconfiguration. The DATABASE 2 AIX/6000 client will reside on the CICS/6000machine and the DATABASE 2 AIX/6000 server will reside on the remotemachine.

Use TCP/IP for the client-server configuration as follows:

1. As root add two new services to the /etc/services file on both machines. Ifthe service db21tcpip does not exist, use two available ports to add:

db21tcpip 2130/tcp

dontcare 2131/tcp

2. DATABASE 2 AIX/6000 server setup

• Log in as instance owner.

• Register the service name by entering:

db2 UPDATE DATABASE MANAGER CONFIGURATION USING SVCNAMEdb21tcpip.

• Create a database available to the client by entering:

db2 CREATE DATABASE cicsrem AUTHENTICATION CLIENT.

• Set the environment variable DB2COMM to TCPIP in the db2profile file.

• Start the database with db2start.

3. DATABASE 2 AIX/6000 client setup

• Log in as instance owner on the client machine.

• Catalog the node by entering:

db2 CATALOG TCPIP NODE baffin REMOTE baffin SERVER db21tcpip,

where baffin is the server name.

• Catalog the database by entering:

db2 CATALOG DATABASE cicsrem AS cicsloc AT NODE baffinAUTHENTICATION CLIENT,

where:

cicsrem is the database on the DATABASE 2 AIX/6000 server machine,and cicsloc is the database alias on the DATABASE 2 AIX/6000 clientmachine.

• Connect to the database on the server by entering:

db2 CONNECT TO cicsloc.

Chapter 4. Remote Implementation 51

4.2.2 DATABASE 2 AIX/6000 ConfigurationThe items that you need to consider in the implementation of DATABASE 2AIX/6000 are:

• Shared object

A shared object must be created on the DATABASE 2 AIX/6000 client. Referto 3.2.2.1, “Shared Object” on page 17 for details on how to create theDATABASE 2 AIX/6000 shared object.

• XA open string

Refer to 3.2.2.2, “XA Open String” on page 17 for details on the XA openstring for DATABASE 2 AIX/6000. The database name in the XA open stringmust correspond to the alias name that you cataloged on the client machine.For example, in the client setup in 4.2.1, “Before You Start” on page 50 thedatabase alias is cicsloc. The XA open string for this is:

cicsloc


A resource manager switch must be created on the DATABASE 2 AIX/6000client. Refer to 3.2.2.3, “Resource Manager Switch” on page 18 for detailson how to create the resource manager switch for DATABASE 2 AIX/6000.

• Database privileges

Database privileges must be established on the server machine. Refer to3.2.2.4, “Database Privileges” on page 20 for details on the databaseprivileges.


1. Defina XA resources

XA resources must be defined on the DATABASE 2 AIX/6000 client. Refer to3.2.3.1, “XA Resource Definitions” on page 20 for details of these definitions.

2. Set up CICS/6000 region environment

In every region directory, namely /var /c ics_regions/<region_name>, thereis a file named environment, which sets up the environment variables onregion startup.

The environment variable for DATABASE 2 AIX/6000 is:

DB2INSTANCE Defines the instance for CICS/6000 to refer to.

Multiple DATABASE 2 AIX/6000 Databases

If you use two or more DATABASE 2 AIX/6000 databases, whether theyare local or remote, you must be careful in setting up your configuration.The DB2INSTANCE environment variable can be set only once. Therefore,

• Locally: You can connect only to databases of the same instance perregion.

• Remotely: You must configure the same instance names on the localand remote machine.



CICS/6000 region startup must be done on the DATABASE 2 AIX/6000 client.Refer to 3.2.3.3, “CICS/6000 Region Startup” on page 23 for information onhow to start up the CICS/6000 region.

4.3 Oracle7We divide our discussion of the Oracle7 implementation into the following parts:

• Oracle7 configuration

• CICS/6000 configuration..

4.3.1 Before You StartMake sure that the following Oracle7 products have been installed on theOracle7 client machine:


• Pro*C 1.5.10.1.0

• Pro*COBOL 1.5.10.1.0

• SQL*Net V2 2.0.15.0.0


For more information on the installation of Oracle7 products on the clientmachine, refer to the Oracle 7 for IBM RISC/6000 Installation and ConfigurationGuide.

Make sure that the following Oracle7 products have been installed on theOracle7 server machine.

• ORACLE7 Distributed Database option 7.0.16

• ORACLE7 Server (RDBMS) 7.0.16.4.0


• SQL*Plus 3.1.2.3.1

• SQL*Net V2 2.0.15.0.0


For more information on the installation of Oracle7 products on the servermachine, refer to the Oracle 7 for IBM RISC/6000 Installation and ConfigurationGuide.

Make sure you have created an Oracle7 client-server configuration. The Oracle7client will reside on the CICS/6000 machine, and the Oracle7 server will resideon the remote machine.


1. Oracle7 server setup

• Check for an entry in the /etc/services file. There should be an entrysimilar to this:


� �listener 1522/tcp

� �where listener is the port that the Oracle7 server uses to listen for clientrequests.

• Create the listener.ora file in the /etc directory. Here is a samplelistener.ora file:

� �LISTENER =

(ADDRESS_LIST =(ADDRESS =

(PROTOCOL=IPC)(KEY=�cics�)

)(ADDRESS =

(PROTOCOL=IPC)(KEY=�B�)

)(ADDRESS =

(PROTOCOL=TCP)(HOST=�baffin�)(PORT=�1522�)

))

SID_LIST_LISTENER =(SID_LIST =

(SID_DESC=(SID_NAME=�B�)(ORACLE_HOME=�/oracle�)

))

� �where:

− cics is the service_name described in the tnsnames.ora file.

− B is the SID for the Oracle7 installation on the Oracle7 servermachine.

− baffin is the hostname of the Oracle7 server.

− 1522 is the port number for the listener in the /etc/services file on theOracle7 server machine.

− /oracle is the Oracle7 installation directory.

2. Oracle7 client setup

3. Create the .tnsnames.ora file in the home directory of the AIX cics user. Thisfile allows the client to connect to the Oracle7 server machine. Here is asample .tnsnames.ora file:


� ��CICS� =

(DESCRIPTION =(ADDRESS_LIST =

(ADDRESS =(COMMUNITY = SANJOSE.IBM.COM)(PROTOCOL = �TCP�)(HOST = �baffin�)(PORT = �1522�)

))(CONNECT_DATA =

(SID = �B�))

)

� �where:

• CICS is the service_name. This is a one word descriptor that the clientuses to connect to the Oracle7 server.

• TCP is the protocol used.

• baffin is the hostname of the Oracle7 server.

• 1522 is the port number for the listener in the /etc/services file on theOracle7 server machine.

• B is the SID for the Oracle7 installation on the Oracle7 server machine.

4. Check the client-server configuration from the Oracle7 client machine:

a. log in as the AIX user cics

b. export ORACLE_HOME=/oracle,

where /oracle is the Oracle7 installation directory.

c. export PATH=$PATH:$ORACLE_HOME/bin

d. sqlplus scott/tiger@cics,

where cics is the service_name as specified in the .tnsnames.ora file.

4.3.2 Oracle7 ConfigurationThe items that you have to consider in the implementation of Oracle7 are:

• Shared library

During the installation of the Oracle7 XA Library you will be prompted with:

Oracle XA Installation

Some TP monitors require a shared version of the ORACLE7 libraries.Do you want to install a shared version of the libraries?

Make sure you select �Yes� to this prompt. The installation will create ashared library in the $ORACLE_HOME/lib directory. This library is calledlibsharesqlxa.a. Copy this library to the /usr/ l ib directory by running thecommand as the root AIX userid:

cp $ORACLE_HOME/lib/libsharesqlxa.a /usr/lib

• XA open string

The syntax of the XA open string is described in 3.4.2.2, “XA Open String” onpage 32. You will need to add an extra field to the XA open string. This


field allows the CICS/6000 region to access data on the remote Oracle7server. The extra field is:

SqlNet = connect_string

SqlNet Specifies the SQL*Net connect string

connect_string: Indicates the string to log on to the system. The connectstring can be either an SQL*Net V1 string, SQL*Net V2 string, orSQL*Net V2 alias. This string is required when you are setting upOracle on a machine separate from the TP monitor.

For example, if you were to use the .tnsnames.ora and listener.ora files listedin 4.3.1, “Before You Start” on page 53, the XA open string would be:

Orac le_XA+Acc=P/sco t t / t i ge r+SesTm=35+LogD i r= / tmp /xa . l og+Sq lNe t=c i cs

where cics is the service_name as specified in the .tnsnames.ora file.


You need to create the resource manager switch on the Oracle7 clientmachine. Refer to 3.4.2.3, “Resource Manager Switch” on page 33 for detailson how to create the resource manager switch.

• Table privileges

Table privileges must be established on the Oracle7 server machine. Fordetails refer to 3.4.2.4, “Table Privileges” on page 35.


1. Define XA resources

XA resources must be defined on the Oracle7 client machine. For detailsrefer to 3.4.3.1, “XA Resource Definitions” on page 36.


In every region directory, namely /var/c ics_regions/<region_name>, thereis a file named environment, which sets up the environment variables onregion startup.

There are no mandatory environment variables for Oracle7 in theclient-server setup. However, there is an optional variable:

TNS_ADMIN Indicates the directory where the tnsnames.ora file canbe located. If this variable is not set, the .tnsnames.orafile must exist in the AIX cics userid.

Note

There is a dot ( . ) prefix on the tnsnames.ora file when the TNS_ADMINvariable is not set.


CICS/6000 region startup must be done on the Oracle7 client machine. Fordetails refer to 3.4.3.3, “CICS/6000 Region Startup” on page 38.


4.4 Sybase System 10We divide our discussion of the Sybase System 10 implementation into thefollowing parts:

• Sybase System 10 configuration


4.4.1 Before You StartMake sure that the following Sybase System 10 products have been installed onthe same machine as CICS/6000, that is, the Sybase System 10 client machine:

• Sybase Embedded SQL/C

• Sybase Embedded SQL/COBOL

• Open Client/C

• Sybase XA-Library for CICS (we used beta release 10.0.1).

For more information on the installation of Sybase System 10 products refer tothe Sybase SQL Server Installation Guide for AIX.

Make sure that the following Sybase System 10 products have been installed onthe server machine:

• Sybase SQL Server Version 10.0.1

• Sybase XA-Library for CICS (we used beta release 10.0.1)

Note

The beta version of the XA-Library includes the following:

• XA-Library

• Open Client Client-Library

• CS-Library

• Embedded SQL/C

• Embedded SQL/COBOL.

Installing the beta version of the XA-Library installs all of these dependentproducts. Subsequent releases of XA-Library will contain only XA-Libraryfiles.

Make sure you have created a Sybase System 10 client-server configuration.The Sybase System 10 client will reside on the CICS/6000 machine, and theSybase System 10 server will reside on the remote machine.


1. Sybase System 10 server setup

• Check for an entry in the /etc/services file. There should be an entrysimilar to this:

� �SYBASE query 2025/tcp

� �


where SYBASE is the Sybase System 10 SQL Server on the remotemachine.

• The server requires the interfaces file in the $SYBASE directory to listenfor clients.

• Use sybinit to create the interfaces file entry. For details refer to SybaseSQL Server Installation Guide for AIX. This entry should match the entryin the /etc/services file. For example, the interfaces file entrycorresponding to the /etc/services above is:

� �SYBASE

query tcp ether bengal 2025master tcp ether bengal 2025

� �where bengal is the hostname of the Sybase System 10 SQL Server.

• Set the environment variable DSLISTEN to the Sybase System 10 SQLServer name. To do this run the following command:

export DSLISTEN= server_name,

where server_name is the name of the Sybase System 10 SQL Serverspecified at installation time. If DSLISTEN is not set, the default value isSYBASE.

2. Sybase System 10 client setup

• Set the server name

The environment variable for this is DSQUERY. To set this variable runthe following command:

export DSQUERY= server_name,

where server_name is the name of the Sybase System 10 SQL Server onthe remote machine.

• Create an entry in the interfaces file

Use sybinit to create an entry. This entry should be the same as theentry in the interfaces file for the remote Sybase System 10 SQL Server.For example, the entry should be similar to this:

� �SYBASE

query tcp ether bengal 2025master tcp ether bengal 2025

� �where SYBASE is the Sybase System 10 SQL Server name on the remoteserver machine.

3. Check the client-server configuration from the Sybase System 10 clientmachine.

a. log in as the AIX user cics.

b. export SYBASE=/sybase,

where /sybase is the Sybase System 10 installation directory.

c. export PATH=$PATH:$SYBASE/bin

d. export DSQUERY=SYBASE,


where SYBASE is the Sybase System 10 SQL Server name.

e. isql -Usa -Psybase,

where sybase is the password for the user sa.

4.4.2 Sybase System 10 ConfigurationThe items you need to consider in the implementation of Sybase System 10 are:

• Shared libraries

You must create the shared libraries on the Sybase System 10 clientmachine. Refer to 3.5.2.1, “Shared Libraries” on page 39 for details on howto create the shared libraries.

• Stored procedures

You must run the stored procedures on the Sybase System 10 servermachine. To function in a Sybase XA environment for CICS, your SQL serverrequires additional stored procedures. Refer to 3.5.2.2, “Stored Procedures”on page 40 for details on how to create the stored procedures.

• XA configuration file

You must create an XA configuration file on the Sybase System 10 clientmachine. The XA configuration file called xa_config is located in the$SYBASE directory. Refer to 3.5.2.3, “XA Configuration File” on page 41 fordetails on how to add an entry to this file.

• XA open string

For details on the XA open string for Sybase System 10 refer to 3.5.2.4, “XAOpen String” on page 42.


You must create the resource manager switch on the Sybase System 10client machine. For details on the creation of the resource manager switchrefer to 3.5.2.5, “Resource Manager Switch” on page 42.

• Database privileges

The Sybase System 10 XA open string described in 3.5.2.4, “XA Open String”on page 42 does not explicitly connect to a database. Therefore nodatabase privileges need to be set for the CICS/6000 userid (the useriddefined when the CICS/6000 was installed).


1. Define XA resources

XA resources must be defined on the Sybase System 10 client machine. Fordetails refer to 3.5.3.1, “XA Resource Definitions” on page 45.


In every region directory, namely /var/c ics_regions/<region_name>, thereis a file named environment, which sets up the environment variables onregion startup.

You need to add the following environment variable for the Sybase System10 client-server configuration:

SYBASE= sybase_dir,


where sybase_dir is the Sybase System 10 installation directory.

Note

If you set the environment variable DSQUERY in the region environmentfile, it has no effect on the Sybase System 10 SQL Server to which theCICS/6000 region will connect. This is unlike the Sybase System 10client-server configuration without a TP monitor, where setting theDSQUERY variable defines the Sybase System 10 SQL Server. In aCICS/6000 environment the LRM connection name is used to check thecorresponding Sybase System 10 SQL Server name from the xa_configfile.


CICS/6000 region startup must be done on the Sybase System 10 clientmachine. For details refer to 3.5.3.3, “CICS/6000 Region Startup” onpage 46.


Chapter 5. Resource Manager Initialization at Region Startup: ADiagrammatic View

In this chapter we review the steps required to start up a CICS/6000 region whenconnecting to an XA-compliant RDBMS. We also show the various AIXprocesses created for each RDBMS whenever a CICS/6000 region is started up.We discuss the following four databases:

• DATABASE 2 AIX/6000

• Informix Version 5

• Oracle7

• Sybase System 10.

5.1 DATABASE 2 AIX/6000In this section we describe the process flow at DATABASE 2 AIX/6000registration and the AIX processes generated.

5.1.1 RegistrationFigure 19 on page 62 depicts the DATABASE 2 AIX/6000 local and remoteregistration process.


Figure 19. DATABASE 2 AIX/6000 Registration: Local and Remote (Client-Server)

The database alias is obtained from the XA open string. The region environmentfile is checked to obtain the DB2INSTANCE value. Then the database directoryof the DB2INSTANCE is checked for a match in the database alias name. If theimplementation is local, a connection is established to the DATABASE 2 AIX/6000server. If the implementation is remote, the node name is obtained from thedatabase directory and is checked against the node name in the node directory.Once a match is found, the port number and the hostname are obtained andchecked against the /etc/services file of the hostname for a port number match.If those port numbers match, a connection is established to the DATABASE 2AIX/6000 server on the hostname system.

5.1.2 AIX ProcessesWhen you have started the region successfully, issue the following command tosee the AIX processes for DATABASE 2 AIX/6000:

ps -ef | grep db2

For the local DATABASE 2 AIX/6000 implementation you will see:


� �db2 5858 23066 0 17:25:41 - 0:00 �db2agent�db2 9451 10779 0 17:25:57 - 0:00 db2dlockdb2 10779 23066 0 Mar 25 - 0:00 db2dlockroot 12527 17188 5 17:27:52 pts/9 0:00 grep db2db2 13276 23066 0 17:25:38 - 0:00 �db2agent�db2 14566 23066 0 17:25:43 - 0:00 �db2agent�root 18713 1 0 Mar 25 - 0:00 db2wdogdb2 23066 18713 0 Mar 25 - 1:36 db2syscdb2 25030 10368 0 Mar 23 pts/6 0:01 -kshroot 28312 1 0 17:22:09 - 0:00 db2licddb2 28700 23066 0 Mar 25 - 0:00 [db2loggr]db2 32234 28700 0 17:25:57 - 0:00 [db2loggr]� �

The highlighted processes service the CICS/6000 application servers. There isone db2agent process for each CICS/6000 application server.

For the remote DATABASE 2 AIX/6000 implementation you will see:

� �db2 4864 22783 0 10:52:08 - 0:00 db2dlockdb2 18434 22783 0 10:52:09 - 0:00 �db2tcpcm�root 20478 1 0 10:52:08 - 0:00 db2wdogdb2 22105 28417 0 11:14:51 - 0:00 [db2loggr]db2 22783 20478 0 10:52:08 - 0:00 db2syscdb2 26458 18434 0 11:14:51 - 0:00 �db2agent�db2 27749 29684 13 11:15:51 pts/7 0:00 ps -efdb2 28417 22783 0 10:52:08 - 0:00 [db2loggr]db2 29684 31475 0 10:51:36 pts/7 0:00 -kshdb2 29788 4864 0 11:14:52 - 0:00 db2dlockdb2 29955 22783 0 10:52:10 - 0:00 �db2tcpim�db2 30299 18434 0 11:14:52 - 0:00 �db2agent�db2 30822 29684 1 11:15:51 pts/7 0:00 grep db2root 32016 1 0 10:57:49 - 0:00 db2licddb2 32344 18434 0 11:14:51 - 0:00 �db2agent��

The db2agent processes service the CICS/6000 application servers. In addition,the db2tcpim and db2tcpcm processes are required for the client-serverconfiguration. There is one db2agent process for each CICS/6000 applicationserver.

Note

When we ran two DATABASE 2 AIX/6000 servers—one on the local machineand one on the server machine—there were three db2agent processes on thelocal machine but none on the remote machine.

5.2 Informix Version 5In this section we describe the process flow at Informix Version 5 registrationand the AIX processes generated.

Chapter 5. Resource Manager Initialization at Region Startup: A Diagrammatic View 63

5.2.1 RegistrationFigure 20 depicts the Informix Version 5 local registration process.

Figure 20. Informix Version 5 Local Registration

The database_name, INFORMIXDIR, and TBCONFIG are obtained from the XAopen string, and, with these values, a connection is established to the InformixVersion 5 server.

5.2.2 AIX ProcessesWhen you have started the region successfully, issue the following commands tosee the AIX processes for Informix Version 5:

ps -ef | grep informix

and

ps -ef | grep sqlturbo

For the Informix Version 5 implementation you will see:

� �informix 11555 28472 0 Mar 29 - 0:00 tbundo

root 12529 17188 7 17:28:14 pts/9 0:00 grep informixinformix 25473 21786 0 Mar 23 pts/6 0:01 -kshinformix 28472 1 0 Mar 25 - 10:33 tbinitinformix 31545 28472 0 Mar 25 - 0:15 tbpgcl

root 12536 17188 5 17:29:04 pts/9 0:00 grep sqlturbocics 21479 23515 0 17:25:43 - 0:00 �sqlturbo�cics�5.01.U��RDS#N000000�-x�cicstest�cics 26339 12249 0 17:25:41 - 0:00 �sqlturbo�cics�5.01.U��RDS#N000000�-x�cicstest�cics 33247 13786 0 17:25:40 - 0:00 �sqlturbo�cics�5.01.U��RDS#N000000�-x�cicstest��


The highlighted processes service the CICS/6000 application servers. There isone sqlturbo process for each CICS/6000 application server.

5.3 Oracle7In this section we describe the process flow at Oracle7 registration and the AIXprocesses generated.

5.3.1 RegistrationFigure 21 depicts the Oracle7 local registration process.

Figure 21. Oracle7 Local Registration

The user and password are obtained from the XA open string. The Oracle7environment variable values, ORACLE_SID and ORACLE_HOME, are obtainedfrom the region environment file. With these values a connection is establishedto the Oracle7 server.

Figure 22 on page 66 depicts the Oracle7 remote registration process.


Figure 22. Oracle7 Remote Registration (Client-Server)

The SQL*Net V2.0 alias name is obtained from the XA open string. A match forthis is to be found in the .tnsnames.ora file. Subsequently the Oracle7 SID value,port number, and hostname are obtained from this file. The listener.ora file onthe hostname is checked for a match in the port number and Oracle7 SID value.On the success of this match a connection on the hostname machine isestablished to the Oracle7 server.

5.3.2 AIX ProcessesWhen you have started the region successfully, issue the following command tosee the AIX processes for Oracle7:

ps -ef | grep oracle

For a local Oracle7 implementation you will see:


� �cics 8677 1 0 17:25:42 - 0:00 �oracleA�(DESCRIPTION=��(LOCAL=YES)(ADDRESS=(PROTOCOL=beq)))�

oracle 10642 1 0 Mar 29 - 0:02 ora_reco_Aroot 12540 17188 3 17:29:22 pts/9 0:00 grep oraclecics 13033 1 0 17:25:44 - 0:00 �oracleA�(DESCRIPTION=��(LOCAL=YES)(ADDRESS=(PROTOCOL=beq)))�

oracle 19557 27763 0 Apr 03 pts/2 0:00 -kshoracle 20110 1 0 Mar 29 - 2:32 ora_pmon_Aoracle 20879 1 0 Mar 29 - 5:16 ora_dbwr_Aoracle 21136 1 0 Mar 29 - 2:38 ora_lgwr_Aoracle 24747 1 0 Mar 29 pts/0 0:00 /oracle/bin/tnslsnrLISTENER -inherit

oracle 31377 1 0 Mar 29 - 1:34 ora_smon_Acics 33505 1 0 17:25:40 - 0:00 �oracleA�(DESCRIPTION=��(LOCAL=YES)(ADDRESS=(PROTOCOL=beq)))��

The highlighted processes service the CICS/6000 application servers. There isone oracleA process for each CICS/6000 application server.

For a remote Oracle7 implementation you will see:

� �root 6924 29948 3 17:31:44 pts/1 0:00 grep oracle

oracle 18831 1 0 Mar 29 - 1:00 ora_smon_Boracle 19597 1 0 Mar 29 - 4:07 ora_dbwr_Boracle 21491 1 0 17:25:45 - 0:00 �oracleB (LOCAL=NO)�oracle 23182 1 0 Mar 29 - 2:06 ora_lgwr_Boracle 23440 1 0 Mar 29 - 0:02 ora_reco_Boracle 23948 1 0 Mar 29 - 1:54 ora_pmon_Boracle 25316 1 0 14:32:06 - 0:00 /oracle/bin/tnslsnrLISTENER -inherit

oracle 30449 1 0 17:25:45 - 0:00 �oracleB (LOCAL=NO)�oracle 30959 1 0 17:25:43 - 0:00 �oracleB (LOCAL=NO)��

The highlighted processes service the CICS/6000 application servers. There isone oracleB process for each CICS/6000 application server.

Note

We used the dedicated server configuration for Oracle7 where a serverhandles requests for a single-user process. In an Oracle7 multithreadedserver configuration, many user processes share a small number of serverprocesses. Using the multithreaded server reduces the number of Oracle7AIX processes.

5.4 Sybase System 10In this section we describe the process flow at Sybase System 10 registrationand the AIX processes generated.


5.4.1 RegistrationFigure 23 depicts the Sybase System 10 local and remote registration process.

Figure 23. Sybase System 10 Registration: Local and Remote (Client-Server)

The LRM connection name is obtained from the XA open string. A match for thisname is obtained from the xa_config file, and the Sybase System 10 SQL servername corresponding to the LRM name is obtained. After this. The interfaces fileis then checked for a match in the Sybase System 10 SQL server entry. Thecorresponding port number and hostname are obtained from the interfaces file.The /etc/services file on the hostname is checked for a port number match. Onthe success of this match a connection is established to the Sybase System 10SQL server.


5.4.2 AIX ProcessesWhen you have started the region successfully, issue the following command tosee the AIX processes for Sybase System 10:

ps -ef | grep sybase

For a local Sybase System 10 implementation you will see:

� �root 8704 17188 7 17:29:42 pts/9 0:00 grep sybase

sybase 10368 25473 0 Mar 23 pts/6 0:00 -kshsybase 18118 1 0 Mar 29 pts/0 0:00 sh ./RUN_SYBASEsybase 20423 18118 0 Mar 29 pts/0 439:55 /sybase/bin/dataserver-d/dev/rmasterlv -sSYBASE -e/sybase/install/errorlog -i/s� �

For a remote Sybase System 10 implementation you will see:

� �root 6928 29948 5 17:32:05 pts/1 0:00 grep sybase

sybase 20156 1 0 Mar 29 - 0:00 sh ./RUN_SYB_SERVERsybase 24253 20156 2 Mar 29 - 179:34 /sybase/bin/dataserver-d/dev/rmasterlv -sSYB_SERVER -e/sybase/install/errorlogsybase 27674 17939 0 Apr 03 pts/3 0:00 -ksh� �

Note

Sybase System 10 uses a multithreaded server. Therefore, you do not seeany AIX processes corresponding to the CICS/6000 application servers. TheAIX dataserver process services all requests from CICS/6000. It uses a singlethread for each CICS/6000 application server.



Chapter 6. Problem Determination

In this chapter we briefly describe how to handle problem determination whenCICS/6000 is using XA support for DATABASE 2 AIX/6000, Informix Version 5,Oracle7, and Sybase System 10

For more details, refer to the specific database documentation.

6.1 DATABASE 2 AIX/6000When an error is detected during an XA request from the CICS/6000, the userprogram (the client application and/or server application) might not be able toget the error code from the TM. If your program abends or gets a cryptic returncode from the CICS/6000, check the message log file to get more information.The message log file for CICS/6000 is/var/cics_regions/<region_name>/console.msg. In addition, DATABASE 2AIX/6000 writes out additional information to the AIX system log if that log isenabled.

To enable the system log for DATABASE 2 AIX/6000 carry out the following steps:

1. Log in as user root.

2. Modify the /etc/syslog.conf file to include the following line:

user.warn < f i l e _ n a m e >

where < f i l e _ n a m e > is the explicit path of an existing file where the entrieswill be made (the file must exist before the step 2 is performed). You cancreate the empty file using the following AIX command:

touch < f i le_name>

3. Determine the pid of the system log daemon and send a kill -1 signal to thispid to enable syslogd: ps -ef | grep syslogd

k i l l - 1 <p id>

DATABASE 2 AIX/6000 writes all XA-specific errors to the system log as anSQLCA with SQLCODE -998 (transaction or heuristic errors) with the appropriatereason code and subcodes as message tokens. If a connection fails, theconnection error or communication error will also have its SQLCA written to thesystem log.

Some of the common problems we encountered are the following:

• XA open string contains invalid syntax.

• The connection to the database specified in the open string fails because thedatabase has not been cataloged, DATABASE 2 AIX/6000 has not beenstarted, or the server application′s user name or password is not authorizedto connect to the database.

• Communication error in client-server configuration

• Cannot read or load the Switch Load file.


Figure 24 is a sample syslog entry for an XA error. The entry is related to an XAopen string where instead of using cicsloc we made a typing error (cicslox).

� �Mar 31 11:44:42 bengal DB2[32056]:DB2 (db2) XA DTP Support sqlxa_make_connection reports:probe id 103 with error 2048 and alert num 0Mar 31 11:44:42 bengal DB2[32056]:extra symptom string provided: XA - error connecting to databaseMar 31 11:44:42 bengal DB2[32056]:data: 53514c43 41202020 00000088 fffffc0b SQLCA .....|.Mar 31 11:44:42 bengal DB2[32056]:data: 00084349 43534c4f 58ff0000 00000000 ..CICSLOX.......Mar 31 11:44:42 bengal DB2[32056]:data: 00000000 00000000 00000000 00000000 ................Mar 31 11:44:42 bengal last message repeated 2 timesMar 31 11:44:42 bengal DB2[32056]:data: 00000000 00000000 53514c45 524c4e4b ........SQLERLNKMar 31 11:44:42 bengal DB2[32056]:data: 00000000 00000000 00000000 00000000 ................Mar 31 11:44:42 bengal DB2[32056]:data: 00000000 00000001 20202020 20202020 ........Mar 31 11:44:42 bengal DB2[32056]:data: 20202035 32303035 52005Mar 31 11:44:42 bengal DB2[32056]:DB2 (db2) XA DTP Support sqlxa_open reports:� �

Figure 24. Sample Syslog Entry for XA Error

You will notice that:

• Each line is prefixed with the time stamp, the product name (DB2), the hostname (in this case, bengal) and the pid that reports the problem.

• The line DB2 (db2) XA DTP Support

displays some internal information about where this error was caught. Thename in parentheses (db2) is the DB2INSTANCE name.

• The line extra symptom string provided: XA - error connecting to database

informs you that the error occurred in XA connecting a database.

• Text displayed on the right-hand side indicates that this is an SQLCA call soyou can find the sqlcode description in the IBM DATABASE 2 AIX/6000Messages and Problem Determination Guide. The sqlcode is hexadecimalfffffc0b (where ffff is negative SQLCODE) and the decimal value is(fc0b-ffff)+1=-1013.

SQL13N

The database alias name or database name < n a m e > could not be found.

sqlcode=-1013

You can use the Command Line Processor to retreive the message and anexplanation of an sqlcode by using the following command:

db2 ? sql1013


Figure 25 on page 73 is the /var/cics_regions/<region_name>/console.msgentry when CICS/6000 is unable to load the Switch Load file, db2xa.

� �ERZ10144I/0375 03/31/94 13:42:24 sanjose : Application server 8 startedERZ5801E/0005 03/31/94 13:42:30 sanjose :Unsuccessful load of program ′ / var/cics_regions/sanjose/bin/db2xa′ ; errno 8.ERZ5802E/0006 03/31/94 13:42:30 sanjose :Information on unsuccessful program load: ′3 getgrset /usr/lib/libs.a shr.o′ .ERZ1647E/0232 03/31/94 13:42:30 sanjose :Abnormal termination A16D:Unable to load an External Resource Manager XA Support file.ERZ1040I/0055 03/31/94 13:42:31 sanjose :CICS/6000 control process ′ cicsas′ completed with exit code 0ERZ5801E/0005 03/31/94 13:42:32 sanjose :Unsuccessful load of program ′ / var/cics_regions/sanjose/bin/db2xa′ ; errno 8.ERZ5802E/0006 03/31/94 13:42:32 sanjose :Information on unsuccessful program load: ′3 getgrset /usr/lib/libs.a shr.o′ .

� �Figure 25. CICS/6000 Console Message When Unable to Load a Switch Load File

6.2 Informix Version 5Informix Version 5 passes all XA errors to CICS/6000 through the do_sql_errorroutine, and these are entries written intothe/var/cics_regions/<region_name>/console.msg file.

Some of the common problems we encountered are the following:


• XA open string parameter definition wrong or incomplete.

• Switch Load file not found or available.

Figure 26 is the /var/cics_regions/<region_name>/console.msg entry whenCICS/6000 tries to connect to a nonexistent database using an incorrect openstring.

� �ERZ10144I/0375 03/31/94 15:06:50 sanjose :Application server 8 startedERZ8032E/0807 03/31/94 15:07:07 sanjose :Abnormal termination U8032. XA_OPEN was unsuccessful when opening′ INFORMIX-ONLINE′ because XA_OPEN string′ cicstesx:INFORMIXDIR=/home/informix:TBCONFIG=tbconfig.INF′ is invalid.ERZ1003I/0094 03/31/94 15:07:07 sanjose :CICS/6000 is performing region abnormal termination in process ′ cicsas′ERZ5204I/0602 03/31/94 15:07:07 sanjose : Dump to ′ SYSA0001.dmp′ started.

� �Figure 26. CICS/6000 Console Message: Unable to Open Informix Version 5 Database

We had a problem with the optional field parameter, TBCONFIG. This field mustbe set if your Informix Version 5 OnLine is using a tbconfig file different from the

Chapter 6. Problem Determination 73

default file. In our installation we used the tbconfig.INF file. If you do not putthat file in the open string, every time you start two CICS/6000 transactions at thesame time, the region will dump with the error as shown in Figure 27 onpage 74. If you run one transaction at time, however, you will be able to workwith the CICS/6000 region.

� �

ERZ8030E/8012 03/31/94 16:22:54 sanjose BA00:Abnormal termination U8030. XA Interface internal error in ′ XA_PRECOM′by ′ INFORMIX-ONLINE′ for XID′528c0000 0006010c 73616e6a 6f736500 00000006 73616e6a 6f736500 00000006′(Transaction=′ INFU′ , TermId=′ BA00′ , UserId=′ gdscics′ ) . ′ ′ . ′SQLCODE 0, Unknown error message 0.ERZ1003I/0094 03/31/94 16:22:54 sanjose BA00: CICS/6000 is performingregion abnormal termination in process ′ cicsas′ERZ5204I/0602 03/31/94 16:22:54 sanjose BA00: Dump to ′ SYSA0001.dmp′ started.

� �Figure 27. CICS/6000 Console Message: TBCONFIG Not Correctly Set

It is possible to track the status of global transactions using the Informix Version5 utility tbstat with the -u option. This utility is fully documented in the InformixOnLine Administrator′s Guide.

6.3 Oracle7The Oracle XA library logs any error and tracing information to its trace file.This information is useful in supplementing the XA error code.

The name of the trace file is:

xa_db_namedate.trc,

where db_name is the database name you specified in the open string fieldDB=db_name, and date is the date when the information was logged to thetrace file. If you do not specify DB=db_name in the open string, it automaticallydefaults to the name NULL.

Note that multiple Oracle XA library RMs with the same DB field and LogDir fieldin their open strings log all trace information that occurs on the same day to thesame trace file.

Figure 28 shows an Oracle trace file when a nonexistent user was put in theopen string:

� �174221.24447.2:ORACLE XA: Version 1.0.3.0.0 - Production. RM name = ′ Oracle_XA′ .

174221.24447.2:xaolgn: XAER_INVAL; logon denied.

� �Figure 28. Oracle XA Trace File: Nonexistent User Put in Open String


The entry in the trace file contains the following information:

• 174221 - time when the information was logged

• 24447 - process ID

• 2 - RM ID

• xaolgn - the module

• logon denied - error information returned.

Figure 29 shows the CICS/6000 console message for the previous error.

� �

ERZ8032E/0807 03/31/94 17:42:21 sanjose :Abnormal termination U8032. XA_OPEN was unsuccessful when opening ′ Oracle_XA′because XA_OPEN string ′ Oracle_XA+Acc=P/scoot/tiger+SesTm=35+LogDir=/tmp′is invalid.ERZ8032E/0807 03/31/94 17:42:21 sanjose :Abnormal termination U8032. XA_OPEN was unsuccessful when opening ′ Oracle_XA′because XA_OPEN string ′ Oracle_XA+Acc=P/scoot/tiger+SesTm=35+LogDir=/tmp′is invalid.ERZ1003I/0094 03/31/94 17:42:21 sanjose :CICS/6000 is performing region abnormal termination in process ′ cicsas′ERZ5204I/0602 03/31/94 17:42:21 sanjose : Dump to ′ SYSA0001.dmp′ started.

� �Figure 29. CICS/6000 Console Message: Nonexistent User

Figure 30 shows the error we received when we tried to configure Oracle7remotely and we not properly set up the tnsnames.ora file.


135210.29851.0:xaolgn: XAER_RMERR; upiahs failed. ORA-12203.

135211.29851.0:ORA-12203: TNS:unable to connect to destination

� �Figure 30. Sample Oracle XA Trace File: Server Configured Remotely

Figure 31 on page 76 shows the entry in the Oracle7 XA trace file if you failed togrant the SELECT privilege to the V$XATRANS$ view for all Oracle accounts thatOracle7 XA Library applications will use.



175237.24241.1:xaofetch: XAER_RMERR; upipse rtn ORA-942; sql_stmt=SELECT k2gtifmt,k2gtitid_ext, k2gtibid FROM sys.v$xatrans$

175237.24241.1:ORA-00942: table or view does not exist

175237.24241.1:xaorecover: xaofetch rtn -3.

� �Figure 31. Oracle XA Trace Entry: SELECT Privi lege Not Granted to V$XATRANS$ View

For more details, refer to the Oracle7 Server for Unix - Administrator′s Reference.

6.4 Sybase System 10Sybase System 10 XA-Library writes tracing information in the fully qualified filename specified in the open string. If you do not specify the -L option and alogfile parameter, logging is disabled.

Some of the common problem we encountered are the following:


• The connection to the database specified in the open string fails because theserver is not correctly set in the XA configuration file as the LRM.

• Sybase System 10 has not been started.

• User name or password not authorized to connect to the server

• Communication error in client-server configuration

• Cannot read or load Switch Load file.

Figure 32 on page 77 shows a Sybase System 10 trace file if you used the wrongpassword for user sa in the open string.


� �9853:xa__log_init: pid 9853 started at Fri Apr 1 11:22:35 1994

9853: XA_ENTRY: xa_open: info: -Usa -Psybasi -Nconnection_1-L/tmp/sybase.log rmid: 0x0, flags 0x0

9853: xa__list_open: failed to get XCL name9853: lrm_lookup: connection_19853: lrm_lookup: using config file /sybase/xa_config9853: lrm_lookup: connection_19853: lrm_lookup: using config file /sybase/xa_config9853: xc__open: Connecting to serv: SYBASE, user: sa, passwd: sybasi.9853: XA_EXIT: xa_open: ret_stat: -327518:xa__log_init: pid 27518 started at Fri Apr 1 11:22:53 1994

� �Figure 32. Sybase XA Trace File: Wrong Password for User sa in Open String

Figure 33 shows the CICS/6000 console message file.

� �ERZ8005E/0805 04/01/94 11:22:37 sanjose :Abnormal termination U8005. XA_OPEN returned a Resource Manager error whenopening ′ SYBASE_SQL_SERVER′ using XA_OPEN string ′ -Usa -Psybasi -Nconnection_1-L/tmp/sybase.log′ . ′ ′ERZ1003I/0094 04/01/94 11:22:37 sanjose :CICS/6000 is performing region abnormal termination in process ′ cicsas′ERZ5204I/0602 04/01/94 11:22:37 sanjose : Dump to ′ SYSA0001.dmp′ started.

� �Figure 33. CICS/6000 Console Messages: Wrong Password for User sa in Sybase System10 Open String

If you put in your open string an lrm_name that is not an entry in the SybaseSystem 10 xa_config file, you will get an entry in the CICS/6000 console messagefile as shown in Figure 33 and an XA logging trace similar to that shown inFigure 34.

� �25128:xa__log_init: pid 25128 started at Fri Apr 1 11:45:16 1994

25128: XA_ENTRY: xa_open: info: -Usa -Psybase -Nconnection_3-L/tmp/log.server rmid: 0x0, flags 0x025128: xa__list_open: failed to get XCL name25128: lrm_lookup: connection_325128: lrm_lookup: using config file /sybase/xa_config25128: lrm_lookup: lrm name not found25128: xa_list_open: failed to init connection25128: XA_EXIT: xa_open: ret_stat: -331883:

� �Figure 34. Sybase XA Trace: Wrong LRM Name in Sybase System 10 Open String

Figure 35 on page 78 shows you the XA trace logging when the server namedefined in the xa_config entry does not exist.


� �xa__log_init: pid 31883 started at Fri Apr 1 13:49:14 1994

31883: XA_ENTRY: xa_open: info: -Usa -Psybase -Nconnection_2-L/tmp/log.server rmid: 0x0, flags 0x031883: xa__list_open: failed to get XCL name31883: lrm_lookup: connection_231883: lrm_lookup: using config file /sybase/xa_config31883: lrm_lookup: connection_231883: lrm_lookup: using config file /sybase/xa_config31883: xc__open: Connecting to serv: SYS_SERVER, user: sa, passwd: sybase.31883: XA_EXIT: xa_open: ret_stat: -3

� �Figure 35. Sybase XA Trace: Wrong Server Name in Sybase System 10 xa_config File


Chapter 7. Application Considerations

In this chapter we describe some of our experiences in configuring CICS/6000 indifferent scenarios.

Before we actually discuss each scenario, we want you to think about thefollowing points:

• In a DTP environment, server applications are reused by many usertransactions, but there is no mechanism for the TM to provide the RM with:

− The actual user ID that invokes the transaction (all transactions areperformed under the server application ID)

− Information about when a program begins and ends. The RM knows onlytransactions, and it must treat each transaction as unrelated to theprevious transaction.

• The XA Interface allows CICS/6000 to run against different RDBMSs (local orremote) depending on the capabilities of each RDBMS. Some RDBMSs canhandle different threads in the same process, but, when used in conjunctionwith CICS/6000, this feature does not have any advantage. CICS/6000serializes all operations. For more details you can refer to 2.2.1, “XAResource Definitions” on page 10. CICS/6000 provides options to serializethe threads so that one thread will execute to a syncpoint before another onebegins.

• There is typically a noticeable overhead for crossing between a CICS/6000transaction program and an SQL database; so the number of crossingsshould be minimized, for performance reasons. This is a good reason forcoding dynamic SQL or calls to SQL stored procedures.

• All updates made through EXEC SQL calls in a CICS/6000 transaction canshare a common syncpoint with all other updates made elsewhere in thenetwork, under the control of EXEC CICS SYNCPOINT.

• CICS/6000 can arrange to drive syncpoint in the database only when thedatabase is actually updated for a given transaction, and only if the databasehas support for dynamic registration as specified in the X/Open DTP model(2.1.3, “Resource Manager Switch” on page 8). This can reduce the cost ofsyncpoint when you are running in an environment with multiple XAdatabases, where transactions usually update only data managed by some ofthe applications.

• All updates made everywhere by the transaction using EXEC CICSSYNCPOINT are committed or rolled back as a unit, no matter how or whennetworks or components may fail and restart. With a database that supportsXA dynamic registration, EXEC CICS SYNCPOINT is as efficient as EXEC SQLCOMMIT, in those cases where it would be safe to use EXEC SQL COMMIT.

• Typically, SQL operations that declare cursors or prepare dynamic SQL arerelatively expansive, compared with SQL operations that access data; so youshould arrange to do the expansive operations no more than once pertransaction program.

• Good programming within CICS means keeping your transactions as shortlived as possible, utilizing such CICS methods as pseudo conversationalprogramming to present the illusion of a long-running task.


• In CICS/6000 a single application server (cicsas) process is bound to aparticular task for the duration of the task. If the task suspends itself orperforms I/O or a similar operation that may allow it to be context switched,it remains loaded in the application server. The application server wasdesigned to minimize process creation and initialization time.

7.1 CICS/6000 and a Local RDBMSThis scenario is probably the easiest but the worst from the point of view ofresource distribution. The database machine would be a dedicated machine inorder to obtain distribution of tasks on specialized hardware.

Each single RDBMS would be allowed to define a different database on a singleinstance; below we analyze the capabilities of each RDBMS to handle thisfeature using the XA Interface.

7.1.1 CICS/6000 Transaction and DATABASE 2 AIX/6000DATABASE 2 AIX/6000 allows you to create several databases running on oneinstance of the database manager. Creating a database sets up all systemcatalog tables that the database needs and allocates the database recovery log.

For each database used, CICS/6000 requires an entry into the XA Definitionstanza as shown in Figure 8 on page 22, using the name of the database as theconnection string. You can imagine writing an application that can switch fromone database to another using explicitly the SQL CONNECT statement as in thefragment of the uxa1.sqc sample program shown in Figure 36 on page 81.


� �#define DATABASE1 ″cicsloc″#define DATABASE2 ″cicsrem″

EXEC SQL BEGIN DECLARE SECTION;

char dbase[15];

EXEC SQL END DECLARE SECTION;

main(){

strcpy(dbase,DATABASE1);EXEC SQL CONNECT TO :dbase;

.

.

.EXEC SQL UPDATE cheeseset order_quantity = :order_quantitywhere name = :name;

.

.

.

EXEC CICS SYNCPOINT RESP(rcode);if (rcode != DFHRESP(NORMAL))

EXEC CICS ABEND ABCODE(″X011″ ) ;

strcpy(dbase,DATABASE2);EXEC SQL CONNECT TO :dbase;

.

.

.EXEC SQL UPDATE cheeseset order_quantity = :order_quantitywhere name = :name;

.

.

.}

� �Figure 36. Connect in SQL C Program

Note

DATABASE 2 AIX/6000 requires an explicit disconnect before you can connectto a different database. In a CICS/6000 application using the XA library younever do an EXEC SQL DISCONNECT (it will force immediate shutdown of theCICS/6000 region), but you must execute an EXEC CICS SYNCPOINTotherwise the new connection does not take effect.

If you do not explicitly connect to a database in your application, CICS/6000assumes the last succesful connection. If you try to run against a database anapplication that does not belong to it, you will get a time-stamp conflict error:

SQL0818N A timestamp conflict occurred. SQLSTATE=51003 sqlcode=-818.

Your application must be precompiled and bound on both databases (remote andlocal).

Chapter 7. Application Considerations 81

Upon any successful SQL CONNECT (including a CONNECT with no options,which only queries the current connection) a number will be returned in theSQLERR[5] field in the SQLCA structure. The possible values are:

• -0-No information (value returned only by DB2/2 1.0 and earlier releases -included here for reference).

• -1- The connection does not allow syncpoint flow but allows updates (non-XAtransaction).

• -2- The connection does not allow syncpoint flow or updates (globaltransaction connecting to a DRDA database).

• -3- The connection allows syncpoint flow (global transaction connecting toDATABASE 2 AIX/6000).

• -4- Reserved.

The database manager allows the use of the SQL CONNECT with theUSER/USING clause to explicitly establish an SQL access ID different from theaccess ID of the server application.

The following restrictions apply:

• SQL COMMIT and ROLLBACK statements not allowed

The error could be SQLSTATE 56021, 56028, 56029, depending on whether itwas a static or dynamic commit or rollback statement.

• Handling database-initiated rollback

If the RM initiated a rollback, all subsequent SQL requests will be rejectedwith SQLSTATE 51021 to inform you that you must roll back the globaltransaction with the TM′s syncpoint services - CICS/6000 CICS SYNCPOINTROLLBACK.

• No cursors declared with the WITH HOLD option

DATABASE 2 AIX/6000 rejects any attempt to open a WITH HOLD cursor inthe CICS/6000 environment with SQLSTATE 56026.

• No updates allowed to a DRDA database

• API restrictions

APIs are not supported in a DTP environment because they would internallyissue a commit in the database and bypass the two-phase commit process(SQLSTATE 56026):

Precompile Bind Backup Restore Restart Roll Forward Migrate Import ExportReorganize Table

For more details see the IBM DATABASE 2 AIX/6000 Programming Guide and theAIX CICS/6000 Application Programming Guide.

In Figure 37 on page 83 you can see how we modified the original makefile forthe UXA1 transaction in order to update the same row in the same table into twodifferent DATABASE 2 AIX/6000 databases.


� �all: uxa1m.map db2_lr

uxa1m.map: uxa1.bmscicsmap uxa1.bms

db2_lr: db2_lr.ccsCCFLAGS=″ / usr/lib/db2.o″ ; \export CCFLAGS; \cicstcl -e -d -lC db2_lr.ccs

db2_lr.ccs: db2_lr.sqcdb2 connect to cicsloc; \db2 prep db2_lr.sqc bindfile package using db2_lr; \db2 bind db2_lr.bnd ;\db2 grant execute on package db2_lr to publicdb2 connect to cicsrem; \db2 bind db2_lr.bnd ;\db2 grant execute on package db2_lr to publicmv db2_lr.c db2_lr.ccs

� �Figure 37. Sample Makefi le to Compile a Program Using Two Different DATABASE 2AIX/6000 Databases

7.1.2 CICS/6000 Transaction and Local Informix Version 5The only configuration actually supported by Informix Version 5 is the localconfiguration. It is not possible to configure more than one database running onthe same instance of Informix Version 5 in CICS/6000 XAD stanza. If you try toconfigure more than one, the CICS/6000 region is terminated during cold start,and Informix Version 5 reports an internal error inside the/var/cics_regions/<region name>/console.msg file. After this error you have tostop Informix Version 5 and start again in order to bring up the CICS/6000 region.

The following SQL statements behave differently in an X/Open DTP environment:

• CLOSE DATABASE

• CREATE DATABASE

• DATABASE

• LOCK TABLE

• SET ISOLATION

• SET EXPLAIN

• SET LOCK MODE

• SET LOG

• UNLOCK TABLE

• BEGIN WORK

• COMMIT WORK

• ROLLBACK WORK.

For more details refer to the Informix TP/XA User Manual.


We tried using the DATABASE statement inside the code to switch to anotherdatabase and we got the following SQL error message:

-701 Statement is invalid within the XA environment

as documented in the Informix Error Messages manual.

7.1.3 CICS/6000 Transaction and Oracle7Oracle7 could support both local and remote databases and it is also possible towrite applications in a CICS/6000 environment that can access different Oracle7databases. An application may include the default database, as well as one ormore named databases respecting the following rules:

• Each database must have an open string configured to CICS/6000.

• The default database open string must be without the DB optional field.

• The other database open string must specify DB=db_name.

• The application server program must contain the SQL DECLARE DATABASEstatement for each nondefault database.

Figure 38 shows how you can access three Oracle7 databases in one applicationserver (one default, Oracle1, and Oracle2).

� �EXEC SQL DECLARE Oracle1 DATABASE;EXEC SQL DECLARE Oracle2 DATABASE;

EXEC SQL BEGIN DECLARE SECTION;db_name1 CHARACTER(10);db_name2 CHARACTER(10);

EXEC SQL END DECLARE SECTION;...

set db_name1 = ′ Oracle1′ ;set db_name2 = ′ Oracle2′ ;

.

.

. EXEC SQL UPDATE cheese set order_quantity = :order_quantity where name = :name;

EXEC SQL AT :db_name1 UPDATE cheese set order_quantity = :order_quantity where name = :name;

EXEC SQL AT :db_name1 UPDATE cheese set order_quantity = :order_quantity where name = :name;

� �Figure 38. Using Different Oracle7 Databases in One Application Server

Note

The names specified in each open string DB optional field must be the sameas those used in the SQL DECLARE DATABASE statement (in this example,Oracle1 and Oracle2).


Applications using XA do not create Oracle database connections of their own.Any work that they perform would be outside the global transaction and mayconfuse the connection information used by the Oracle7 XA library.

Oracle XA applications can access other Oracle7 databases through a databaselink, with the following restrictions:

• The other database accessed should be another Oracle7.

• Access to the other database must use SQL*NET V2.

• The following SQL statements must never be used:

− EXEC SQL ROLLBACK WORK

− EXEC SQL COMMIT WORK

− DDL SQL statement like CREATE TABLE

− EXEC SQL SAVEPOINT

− SET TRANSACTION READ ONLY

− EXEC SQL WORK RELEASE

− EXEC SQL ROLLBACK WORK RELEASE.

Cursors, when used in Oracle XA applications, are valid only for the duration ofthe transaction. Explicit cursors should be opened after the transaction beginsand closed before the commit or rollback. Also, you must use therelease_cursor=yes option when compiling your precompiler application.

You can use precompilers with the default database or with named databases asshown in Figure 38 on page 84. Only one default connection is allowed perprocess.

Note

The Oracle7 libsharesqlxa.a must be linked to your application. Verify thatyou are using the libsharesqlxa.a that you copied in the /usr/ l ib directory asdocumented in 3.4.2.1, “Shared Library” on page 32.

7.1.4 CICS/6000 Transaction and Sybase System 10Sybase System 10 supports both local and remote databases. Embedded SQLapplications running in a CICS/6000 region must conform to the followingconstraints in order to function within the Sybase System 10 XA environment:

• Transaction management

The CICS/6000 region is responsible for transaction management, soapplications operating in this environment cannot issue SQL statements thatmanage begin, commit, and rollback transactions.

• Connection management

In the CICS/6000 region, applications rely on the Sybase System 10 XAenvironment for management of client-server connections. Connectionmanagement occurs transparently to the application, so it cannot invokeCONNECT and DISCONNECT.


• Current connection

The notion of default connection does not exist in the Sybase System 10 XAenvironment, so applications must always explicitly specify a currentconnection. There are two ways to specify the current connection: throughthe SET CONNECTION command or the AT CONNECTION name clause.

A current connection does not span transactions; an application must resetthe current connection after each EXEC CICS SYNCPOINT command.

Figure 39 shows how you can use the set connection command.

� �..

EXEC SQL WHENEVER NOT FOUND GOTO :errexit;

EXEC SQL SET CONNECTION connection_1;

EXEC SQL SELECT name, supplier, supplier_address, order_quantityinto

:name, :supplier, :supplier_address, :order_quantityFROM cheeseWHERE name = :name;

.

.

� �Figure 39. Using the SET CONNECTION Command

You can find more information in the Sybase System 10 XA-Library IntegrationGuide for CICS/6000.

7.1.5 CICS/6000 Transaction and Multiple DatabasesWe modified the UXA1 transaction to update the same row in the same table ofDATABASE 2 AIX/6000, Informix Version 5, Oracle7, and Sybase System 10. Thethree different updates belong to the same logical unit of work (LUW).

Note

We tried the program shown in Figure 40 on page 88 with Informix OnLineVersion 5.01, but we always got an SQL return code indicating an error notdocumented (unrecognized sqlca.sqlcode).

Moving to Informix Online Version 5.02 we managed to solve the problempartially. The program worked fine as long as it accessed an Informixdatabase with the SQL SELECT statement first; otherwise we still got an SQLunknown return code. The problem did not occur with SQL UPDATEstatement.

The implementation steps discussed in 3.3.2, “Informix Version 5Configuration” on page 24 were tested with Informix OnLine Version 5.01,although there are no differences for this implementation between Version5.01 and Version 5.02.

Each database uses its own precompiler, so the SQL statements are in differentprograms. Figure 40 on page 88 shows the main file (alldb1.ccs) and the select


and/or update routines for each database. This sample is not the bestprogramming style, but our aim was to:

• Determine whether we could use multiple databases in a single CICS/6000transaction.

• Give an example of a method to compile and link a program that requiresmultiple database preprocessors.


� �File alldb1.ccs

#include <stdio.h>#include <cics_packon.h>#include ″mxa1.h″#include <cics_packoff.h>

#define UPDATECHEESE ″The cheese tables were successfully updated″

int rcode;int retcode;

char name[16];char supplier[30];char supplier_address[30];int order_quantity;

extern syb_select();extern syb_update();extern db2_select();extern db2_update();extern inf_select();extern inf_update();extern ora_select();extern ora_update();

main(){

char errmsg[400];char qmsg[400];

short mlen;

/* Get addresability for EIB */

EXEC CICS ADDRESS EIB(dfheiptr);

/* Write record to CICS temporary storage queue */

sprintf(qmsg, ″%s″ , ″Running Transaction MXA1″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)

LENGTH(mlen) RESP(rcode);if (rcode != DFHRESP(NORMAL))


/* Send the first map */

EXEC CICS SEND MAP(″PANEL1″) MAPSET(″MXA1″ )FREEKB ERASE RESP(rcode);

if (rcode != DFHRESP(NORMAL))EXEC CICS ABEND ABCODE(″X001″ ) ;

� �Figure 40 (Part 1 of 21). Sample Transaction Involving Different Databases


� �/* Receive the response */

EXEC CICS RECEIVE MAP(″PANEL1″) MAPSET(″MXA1″) RESP(rcode);if (rcode != DFHRESP(NORMAL))


/* Select a record from the table based on user input */

sprintf(name, ″%s″ , panel1.panel1i.newnamei);

fprintf(stderr,″%d: cheese name is %s\n″ , getpid(),name);

retcode = inf_select(name);if (retcode == 0){

sprintf(qmsg, ″%s,%s″ , ″INFORMIX: cheese present: ″ , name);mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)



}

retcode = syb_select(name);if (retcode == 0){

sprintf(qmsg, ″%s,%s″ , ″SYBASE: cheese present: ″ , name);mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)



}

retcode = db2_select(name);if (retcode == 0){

sprintf(qmsg, ″%s,%s″ , ″DB2/6000: cheese present: ″ , name);mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)



}

retcode = ora_select(name);if (retcode == 0){

sprintf(qmsg, ″%s,%s″ , ″ORACLE: cheese present: ″ , name);mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)

LENGTH(mlen) RESP(rcode);



� �if (rcode != DFHRESP(NORMAL))


}

/* Fill in and send the second map */



/* Receive the response */



fprintf(stderr,″reply was %x\n″ , panel2.panel2i.questi);if (panel2.panel2i.questi == ′ y′ ){

/* Send the third map */EXEC CICS SEND MAP(″PANEL3″) MAPSET(″MXA1″ )

FREEKB ERASE RESP(rcode);


/* Receive the response */



/* Update the Database */

order_quantity = atoi(panel3.panel3i.newordi);

retcode = syb_update(name,order_quantity);if (retcode == 0){

sprintf(qmsg, ″%s″ , ″SYBASE: cheese table updated ″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)



}



� �retcode = db2_update(name,order_quantity);if (retcode == 0){

sprintf(qmsg, ″%s″ , ″DB2/6000: cheese table updated″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)



}

retcode = inf_update(name,order_quantity);if (retcode == 0){

sprintf(qmsg, ″%s″ , ″INFORMIX: cheese table updated″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)



}

retcode = ora_update(name,order_quantity);if (retcode == 0){

sprintf(qmsg, ″%s″ , ″ORACLE: cheese table updated″ ) ;mlen = strlen(qmsg);

EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)LENGTH(mlen) RESP(rcode);


}

/* Write a record to the temporary queue */

sprintf(qmsg, ″%s″ , ″The cheese tables were updated″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg)



}else{

/* The user does not wish to update so free the keyb′ d & return */fprintf(stderr,″not a y, a %c\n″ , panel2.panel2i.questi);



� �EXEC CICS SEND CONTROL ERASE FREEKB;EXEC CICS RETURN;

}

/* Commit the update */

EXEC CICS SYNCPOINT RESP(rcode);if (rcode != DFHRESP(NORMAL))


/* Send the fourth map confirming successful update */

sprintf(panel4.panel4o.messageo, UPDATECHEESE);EXEC CICS SEND MAP(″PANEL4″) MAPSET(″MXA1″ )

FREEKB ERASE RESP(rcode);if (rcode != DFHRESP(NORMAL))


/* free the keyb′ d & return */

EXEC CICS SEND CONTROL FREEKB;EXEC CICS RETURN;

}



� �File inf_sel.ec


#define NOCHEESE ″There is no such cheese in the table″#define SQLNOTFOUND 100

extern int inf_select();EXEC SQL INCLUDE sqlca;

int inf_select(db_cheese)char db_cheese[15];{


int rcode;int mlen;


int order_quantity;varchar name[15];char supplier[30];char supplier_address[30];


EXEC SQL WHENEVER SQLERROR GOTO :errexit;EXEC SQL WHENEVER NOT FOUND GOTO :errexit;

strcpy(name,db_cheese);

EXEC SQL SELECT order_quantityinto

:order_quantityFROM cheeseWHERE name = :name;

sprintf(panel2.panel2o.order3o, ″%d″ , order_quantity);return(0);

errexit:

EXEC SQL WHENEVER SQLERROR CONTINUE;

/* Handle ″no rows returned″ from SELECT */if (sqlca.sqlcode == SQLNOTFOUND){

sprintf(panel4.panel4o.messageo, ″%s″ , NOCHEESE);



� �EXEC CICS SEND MAP(″PANEL4″) MAPSET(″MXA1″ )




}

rgetmsg((short)sqlca.sqlcode, errmsg, sizeof(errmsg));strncpy(panel4.panel4o.messageo, errmsg, 60);

sprintf(panel4.panel4o.codeo, ″%d″ , sqlca.sqlcode);

/* Send the fourth map with appropriate message */




}



� �File syb_sel.cpre

#include <stdio.h>#include <sybtesql.h>#include <cics_packon.h>#include ″mxa1.h″#include <cics_packoff.h>

#define SQLNOTFOUND 100#define NOCHEESE ″There is no such cheese in the table″

extern int syb_select();

EXEC SQL INCLUDE sqlca;

int syb_select(db_cheese)char db_cheese[16];{

int rcode;char errmsg[400];


char name[16];char supplier[30];char supplier_address[30];int order_quantity;

EXEC SQL END DECLARE SECTION;EXEC SQL WHENEVER SQLERROR GOTO :errexit;EXEC SQL WHENEVER NOT FOUND GOTO :errexit;EXEC SQL SET CONNECTION connection_1;


EXEC SQL SELECT name, supplier, supplier_address, order_quantityinto

:name, :supplier, :supplier_address, :order_quantityFROM cheeseWHERE name = :name;

sprintf(panel2.panel2o.nameo, ″%s″ , name);sprintf(panel2.panel2o.supplo, ″%s″ , supplier);sprintf(panel2.panel2o.addresso, ″%s″ , supplier_address);sprintf(panel2.panel2o.order1o, ″%d″ , order_quantity);

return(0);



� �errexit:


sprintf(panel4.panel4o.messageo, ″%s″ , NOCHEESE);EXEC CICS SEND MAP(″PANEL4″) MAPSET(″MXA1″ )


EXEC CICS ABEND ABCODE(″X009″ ) ;EXEC CICS SEND CONTROL FREEKB;EXEC CICS RETURN;

}

sprintf(errmsg, ″%.60s\n″ , sqlca.sqlerrm.sqlerrmc);strncpy(panel4.panel4o.messageo, errmsg, 60);






}



� �File db2_sel.sqc

#include <sql.h>#include <stdio.h>#include <cics_packon.h>#include ″mxa1.h″#include <cics_packoff.h>


extern int db2_select();EXEC SQL INCLUDE sqlca;

int db2_select(db_cheese)char db_cheese[15];{

char errmsg[400];int rcode;


long int order_quantity;char name[16];char supplier[30];char supplier_address[30];





:order_quantityFROM cheeseWHERE name = :name;

sprintf(panel2.panel2o.order2o, ″%d″ , order_quantity);return(0);

errexit:







� �EXEC CICS SEND CONTROL FREEKB;EXEC CICS RETURN;

}

sqlaintp (errmsg, sizeof(errmsg), 0, &sqlca);strncpy(panel4.panel4o.messageo, errmsg, 60);



EXEC CICS SEND MAP(″PANEL4″) MAPSET(″MXA1″) FREEKB ERASE RESP(rcode);if (rcode != DFHRESP(NORMAL))



}



� �File ora_sel.pc



extern int ora_select();


int ora_select(db_cheese)char db_cheese[16];{

char errmsg[400];int rcode;


varchar name[16];int order_quantity;char supplier[30];char supplier_address[30];



strcpy(name.arr,db_cheese);name.len = strlen(name.arr);


:order_quantityFROM cheeseWHERE NAME = :name;

sprintf(panel2.panel2o.order4o, ″%d″ , order_quantity);

return(0);

errexit:/* Handle ″no rows returned″ from SELECT */if (sqlca.sqlcode == SQLNOTFOUND){




EXEC CICS SEND CONTROL FREEKB;



� �EXEC CICS RETURN;

}

sprintf(errmsg, ″%.60s\n″ , sqlca.sqlerrm.sqlerrmc);strncpy(panel4.panel4o.messageo, errmsg, 60);





/* Rollback the transaction */

EXEC CICS SYNCPOINT ROLLBACK;EXEC CICS SEND CONTROL FREEKB;

EXEC CICS RETURN;}



� �File syb_up.cpre

#include <stdio.h>#include <sybtesql.h>#include <cics_packon.h>#include ″mxa1.h″#include <cics_packoff.h>

#define NOCHEESE ″There is no such cheese in the table″

extern int syb_update();


int syb_update(db_name,db_order_quantity)char db_name[16];int db_order_quantity;{


short mlen;int rcode;int retcode;


char name[16];int order_quantity;


EXEC SQL WHENEVER SQLERROR GOTO :errexit;

strcpy(name,db_name);order_quantity = db_order_quantity;


EXEC SQL UPDATE cheeseset order_quantity = :order_quantitywhere name = :name;

sprintf(qmsg, ″%s″ , ″UPDATE SYBASE″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg) LENGTH(mlen) RESP(rcode);


return(0);

errexit:

sprintf(errmsg, ″%.60s\n″ , sqlca.sqlerrm.sqlerrmc);



� �strncpy(panel4.panel4o.messageo, errmsg, 60);







EXEC CICS RETURN;}



� �File db2_up.sqc

#include <sql.h>#include <stdio.h>#include <cics_packon.h>#include ″mxa1.h″#include <cics_packoff.h>


extern int db2_update();EXEC SQL INCLUDE sqlca;

int db2_update(db_name,db_order_quantity)char db_name[15];int db_order_quantity;{




char name[15];long int order_quantity;






sprintf(qmsg, ″%s″ , ″UPDATE DB2/6000 ″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg) LENGTH(mlen) RESP(rcode);


return(0);

errexit:



� �sqlaintp(errmsg, sizeof(errmsg), 0, &sqlca);

strncpy(panel4.panel4o.messageo, errmsg, 60);sprintf(panel4.panel4o.codeo, ″%d″ , sqlca.sqlcode);






EXEC CICS RETURN;}



� �File inf_up.ec



extern int inf_update();


int inf_update(db_name,db_order_quantity)char db_name[15];int db_order_quantity;{




varchar name[15];int order_quantity;






sprintf(qmsg, ″%s″ , ″UPDATE INFORMIX″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg) LENGTH(mlen) RESP(rcode);


return(0);



� �errexit:

EXEC SQL WHENEVER SQLERROR CONTINUE;

rgetmsg(sqlca.sqlcode, errmsg, sizeof(errmsg));







EXEC CICS RETURN;}



� �File ora_up.pc



extern int ora_update();


int ora_update(db_name,db_order_quantity)char db_name[16];int db_order_quantity;{




varchar name[16];int order_quantity;



strcpy(name.arr,db_name);name.len = strlen(name.arr);

order_quantity = db_order_quantity;



sprintf(qmsg, ″%s″ , ″UPDATE ORACLE″ ) ;mlen = strlen(qmsg);EXEC CICS WRITEQ TS QUEUE(″TEMPXAQ1″) FROM(qmsg) LENGTH(mlen) RESP(rcode);



� �if (rcode != DFHRESP(NORMAL))EXEC CICS ABEND ABCODE(″X007″ ) ;

return(0);

errexit:sprintf(errmsg, ″%.60s\n″ , sqlca.sqlerrm.sqlerrmc);







EXEC CICS RETURN;}


Figure 41 on page 109 shows the makefile for compiling and linking our sampleprogram.


� �## Makefile to build the MXA1 example program using Sybase Oracle# Informix e DB2/6000#

SHAROBJS = -lcs.so -lcomn.so

SYB_SHAR_LIBDIR = $(SYBASE)/lib

LIBDIR = $(SYBASE)/lib

SYBLIBS = -lct -lintl -ltcl -lm -linsckCFLAGS = -c -g

all: mxa1m.map all1

mxa1m.map: mxa1.bmscicsmap mxa1.bms

all1:syb_sel.o syb_up.o db2_sel.o db2_up.o inf_sel.o inf_up.o ora_sel.oora_up.o alldb.c

xlc_r -v -emain alldb&dotc -o all1 syb_sel.o syb_up.o db2_sel.o \db2_up.o inf_sel.o inf_up.o ora_sel.o ora_up.o \-I/usr/lpp/cics/v1.1/include \-L/usr/lib \-L $(SYB_SHAR_LIBDIR)\-L/usr/lpp/cics/v1.1/lib \-L $(LIBDIR) \-L/home/oracle/lib \$(SHAROBJS) \$(SYBLIBS) \/usr/lpp/cics/v1.1/lib/libcics_api.a \/usr/lib/db2.o \/usr/lib/libinf501cs.o \-lsharesqlxa -lm -lld

inf_sel.o:inf_sel.ccscicstran -e -d -lC inf_sel.ccsxlc_r -v -c inf_sel.c \-I/usr/lpp/cics/v1.1/include -I$(INFORMIXDIR)/incl/esql

inf_up.o:inf_up.ccscicstran -e -d -lC inf_up.ccsxlc_r -v -c inf_up.c \-I/usr/lpp/cics/v1.1/include -I$(INFORMIXDIR)/incl/esql

syb_sel.o:syb_sel.ccscicstran -e -d -lC syb_sel.ccsxlc_r -v -c syb_sel.c \-I/usr/lpp/cics/v1.1/include -I$(SYBASE)/include

� �Figure 41 (Part 1 of 3). Sample Makefi le for Compil ing a Program That Uses DifferentDatabases


� �syb_up.o:syb_up.ccs

cicstran -e -d -lC syb_up.ccsxlc_r -v -c syb_up.c \-I/usr/lpp/cics/v1.1/include -I$(SYBASE)/include

ora_sel.o:ora_sel.ccscicstran -e -d -lC ora_sel.ccsxlc_r -v -c ora_sel.c \-I/usr/lpp/cics/v1.1/include -I$(ORACLE_HOME)/include

ora_up.o:ora_up.ccscicstran -e -d -lC ora_up.ccsxlc_r -v -c ora_up.c \-I/usr/lpp/cics/v1.1/include -I$(ORACLE_HOME)/include

db2_sel.o: db2_sel.ccscicstran -e -d -lC db2_sel.ccsxlc_r -v -c db2_sel.c \-I/usr/lpp/cics/v1.1/include

db2_up.o: db2_up.ccscicstran -e -d -lC db2_up.ccsxlc_r -v -c db2_up.c \-I/usr/lpp/cics/v1.1/include

db2_sel.ccs:db2_sel.sqcdb2 connect to cicsloc; \db2 prep db2_sel.sqc; \db2 grant execute on package db2_sel to publicmv db2_sel.c db2_sel.ccs

db2_up.ccs:db2_up.sqcdb2 connect to cicsloc; \db2 prep db2_up.sqc; \db2 grant execute on package db2_up to publicmv db2_up.c db2_up.ccs

inf_sel.ccs:inf_sel.ec$(INFORMIXDIR)/bin/esql -e inf_sel.ecmv inf_sel.c inf_sel.ccs

inf_up.ccs:inf_up.ec$(INFORMIXDIR)/bin/esql -e inf_up.ecmv inf_up.c inf_up.ccs

syb_sel.ccs:syb_sel.cpre$(SYBASE)/bin/cpre syb_sel.cpremv syb_sel.c syb_sel.ccs

syb_up.ccs:syb_up.cpre$(SYBASE)/bin/cpre syb_up.cpremv syb_up.c syb_up.ccs



� �ora_sel.ccs:ora_sel.pc

$(ORACLE_HOME)/bin/proc release_cursor=yes \sqlcheck=none ireclen=512 iname=ora_sel.pc

mv ora_sel.c ora_sel.ccs

ora_up.ccs:ora_up.pc$(ORACLE_HOME)/bin/proc release_cursor=yes \

sqlcheck=none ireclen=512 iname=ora_up.pcmv ora_up.c ora_up.ccs

alldb.c:alldb.ccscicstran -e -d -lC alldb.ccs




Appendix A. Appendix A. MicroFocus COBOL Run-Time Support

In this appendix we briefly describe how to create a MicroFocus COBOL run timefor CICS/6000 and RDBMSs.

To run a COBOL program you must first create in /usr/lpp/cics/v1.1/bin a filecalled cicsprCOBOL, which contains the COBOL support routines and run-timeinformation.

To create the COBOL run-time support for CICS/6000 you have to carry out thefollowing steps:


2. Install Micro Focus COBOL for UNIX (Release 3.1 or later).

3. Set the COBDIR environment variable to the directory where MicroFocusCOBOL is installed (on our machine, /usr/ l ib/cobol)

4. Add $COBDIR/bin and /usr/lpp/cics/v1.1/bin to the PATH environmentvariable.

5. Change to the proper directory by entering:

cd /usr/lpp/cics/v1.1/bin.

6. Run the command cicsmkcobol [-o OutPutFile ] [-L Library Pathname]...][ObjectFiles] [Libraries ]

where:

-o OutPutFile specifies the name of the generated file (if the -o parameter is notpresent , the cicsprCOBOL file is placed in the current directory).

-L Library Pathname specifies a directory you want to add to the LIBPATH incicsprCOBOL.

ObjectFiles is the name of the object file you want to use (for example, db2.o).

Libraries is the name of the libraries you want to use.

For more detailed information refer to the AIX CICS/6000 Planning andInstallation Guide and the AIX CICS/6000 Customization and Operation Guide.

A.1 CICS/6000 and DATABASE 2 AIX/6000To build the MicroFocus COBOL run-time support for CICS/6000 and DATABASE2 AIX/6000 1.0 you have to run the cicsmkcobol with the following options:

cicsmkcobol -L /usr/lpp/db2_01_01_0000/lib /usr/lpp/db2_01_01_0000/lib/db2.o

Refer to 3.2.2.1, “Shared Object” on page 17 to learn how to create the db2.oobject file.


A.2 CICS/6000 and Informix Version 5Informix Version 5 provides a pair of shared objects, libinf501cs.o andlibinf501ci.o. If you need the ESQL/COBOL preprocessor to be case sensitivewith respect to statement identifiers (created with a PREPARE statement) andcursor names (created with a DECLARE statement), you have to use thelibinf501cs.o shared object file when you run the cicsmkcobol script.

Otherwise you should use the libinf501ci.o shared object file. When you installthe Informix Version 5 TP/XA product, both libraries are copied in the /usr/ l ibdirectory. The use of the shared object file must be consistent when you createthe Switch Load file as documented in 3.3.2.3, “Resource Manager Switch” onpage 26.

To build the MicroFocus COBOL run-time support for CICS/6000 and InformixVersion 5 you have to run the cicsmkcobol script with the following options:

cicsmkcobol -L /usr/lib /usr/lib/libinf501cs.o.

A.3 CICS/6000 and Oracle7To build the MicroFocus COBOL run-time support for CICS/6000 and Oracle7 youhave to run the cicsmkcobol script with the following options:

cicsmkcobol -L $ORACLE_HOME/lib $ORACLE_HOME/procob/lib/cobsqlintf.o$ORACLE_HOME/lib/libsharesqlxa.a,

where ORACLE_HOME is the installation path of Oracle7 (on our machine,/oracle).

A.4 CICS/6000 and Sybase System 10To build the MicroFocus COBOL run-time support for CICS/6000 and SybaseSystem 10 you have to carry out the following steps:


2. Set the COBDIR environment variable to the directory path for the MicroFocus COBOL installation.

3. Set the PATH environment variable to include the Micro Focus COBOL bindirectory.

4. Change to the proper directory by entering:

cd $SYBASE/sample/xalibrary/CICS.

5. Run xa_make_cobol_runtime,

where SYBASE is the installation path of Sybase System 10 (on our machine,/sybase).

Note

The xa_make_cobol_runtime script runs the cicsmkcobol, which is in the/usr/lpp/cics/v1.1/bin directory. If cicsmkcobol is located somewhere else,you must edit the script to reflect the change in location.


The xa_make_cobol_runtime script builds a Micro Focus COBOL run-timeenvironment with CICS/6000 and Sybase System 10 XA support. It allowsCICS/6000 transactions written in COBOL to reference XA-Library and OpenClient functions at run time.

Appendix A. Appendix A. MicroFocus COBOL Run-Time Support 115


Appendix B. Appendix B. Setting Up the UXA1 Demo

In this chapter we describe the steps required to set up the UXA1 demo to workwith CICS/6000 and RDBMSs using the XA interface.

We tell you how to create a database demo and table, populate the table,configure the makefile, compile the application, and configure CICS/6000resources to run the demo with the following relational databases:

• DATABASE 2 AIX/6000

• Informix Version 5

• Oracle7

• Sybase System 10.

B.1 Before You StartWe assume that your RISC System/6000 is already running DATABASE 2AIX/6000, Informix Version 5, Oracle7, or Sybase System 10.

AIX 3.2.5 is the minimum operating level required for the CICS/6000 DecemberPTF.

B.2 DATABASE 2 AIX/6000The samples are included in the CICS/6000 LPPs. You can find in the/usr/lpp/cics/v1.1/src/samples/xa directory the files you need to build and runthe UXA1 transaction. The following files are supplied:

• uxa1.README instructions to build a CICS/6000 C or COBOL transaction

• uxa1.db2 SQL script to create and populate tables

• uxa1.bms CICS/6000 basic mapping support (BMS) source for panels

• uxa1.sqc C source file for DATABASE 2 AIX/6000

• uxa1_db2.mk C makefile for DATABASE 2 AIX/6000.

B.2.1 Create DatabaseLog in as a user that owns a DB2/6000 instance and verify that the database isrunning by issuing the command:

$ ps -ef | grep db2

Figure 42 on page 118 shows the output on our machine.


� � root 12565 1 0 Feb 23 - 0:01 db2licd

db2 15017 16296 0 15:31:47 - 0:00 db2syscdb2 15531 15017 0 15:31:47 - 0:00 Ydb2loggr″root 16296 1 0 15:31:47 - 0:00 db2wdogdb2 16554 15017 0 15:31:47 - 0:00 db2dlockdb2 24603 1 0 Feb 24 - 0:08 /u/db2/sqllib/bin/db2bp 24db2 24875 1 0 Feb 24 - 0:00 /u/db2/sqllib/bin/db2bp 24seb 25791 23993 4 16:06:16 pts/0 0:00 grep db2

� �Figure 42. Processes Related to DATABASE 2 AIX/6000

If DATABASE 2 AIX/6000 is not running, you can bring it up by entering thiscommand:

$ db2start.

Now you are ready to execute the SQL script, uxa1.db2, using the db2 -CommandLine Processor. The command can be used to execute SQL statements, directlyfrom the operating system command prompt:

$ db2 -f uxa1.db2.

The -f option tells the command line processor to read the command input froma file instead of from standard input.

Uxa1.db2 creates a cicstest database and a table, cheese, within the database,populates the table, and grants any user the right to work against the table andconnect to the cicstest database.

B.2.2 Run the MakefileBefore running the makefile you must check that the PATH environment variableincludes the /usr/lpp/cics/v1.1/bin path. To do this run the command:

$ echo $PATH

You also have to check that DB2INSTANCE is set in order to identify the instanceas required by the DATABASE 2 AIX/6000 configuration (on our machine, db2loc).You can do this by running:

$ echo $DB2INSTANCE

Now you can enter from the command line:

$ make -f uxa1_db2.mk.



� �cicsmap uxa1.bms

ERZ0511I/0106: Basic Mapping Support (BMS) map translation ended.0 errors, 0 warnings.ERZ0513I/0702: Physical map generated to ′ uxa1m.map′ .ERZ0514I/0601: Logical map generated to ′ uxa1.h′ .

;db2 connect to cicstest; \;;db2 prep uxa1.sqc; \;;db2 grant execute on package uxa1 to public

Database Connection Information

Database product = DB2/6000 1.1.0SQL authorization ID = DB2

Local database alias = CICSTEST

LINE MESSAGES FOR uxa1.sqc------ -----------------------------------------------------------------

SQL0060W The ″C″ precompiler is in progress.SQL0091W Precompilation or binding was ended with ″0″

errors and ″0″ warnings.DB20000I The SQL command completed successfully. mv uxa1.c uxa1.ccs CCFLAGS=″ / usr/lib/db2.o″ ; \export CCFLAGS; \cicstcl -e -d -lC uxa1.ccs

ERZ0447I/5002: Running the translation step: ′ cicstran -e -d -lCuxa1.ccs′ERZ0460I/5015: cicstran translation ended: 0 error(s), 0 warning(s).ERZ0449I/5003: Running the compile and link step:′ xlc_r /usr/lpp/cics/v1.1/lib/libcics_api.a -e main-I/usr/lpp/cics/v1.1/lib/libcics_api.a -e main-I/usr/lpp/cics/v1.1./include /usr/lib/db2.o -o uxa1 uxa1.c′

� �Figure 43. Output of Makefi le to Compile UXA1 Transaction: DATABASE 2 AIX/6000

The uxa1_db2.mk makefile provided with the XA samples assumes that you haverun the db2ln command to create links for libraries in:

/usr/lpp/db2_vv_rr_mmmm/lib to /usr/ l ib

and for include files in:

/usr/lpp/db2_vv_mmmm/include to /usr/include.

Refer to the DATABASE 2 AIX/6000 Installation Guide for a complete descriptionof the use of the db2ln command.

The makefile creates the uxa1m.map map running the cicsmap translator,connects to the database, and executes the prep command to precompile anapplication program source file containing embedded SQL statements.

The makefile also creates a package in the database to which a connection hasbeen established, and it grants all users the privilege to execute the packageuxa1.

Appendix B. Appendix B. Setting Up the UXA1 Demo 119

As the last step the makefile starts the cicstcl translator, which performs thetranslation, compiles the translated program, and links all resulting objects usingthe AIX xlc_r command to produce the uxa1 executable program.

Refer to the AIX CICS/6000 Application Programming Guide for a completedescription of the use of the cicsmap and cicstcl commands. Refer toDATABASE 2 AIX/6000 Command Reference for a complete description of the useof the prep and grant commands.

Note

If you drop the database after the compilation, you have to rerun the prepcommand to create the package. The easiest way to do that is to update theuxa1.sqc file by entering:

$ touch uxa1.sqc

and then rerunning:

$ make -f uxa1_db2.mk

B.2.3 Configure Programs and Transactions for CICS/6000 Using SMIT forDATABASE 2 AIX/6000

The makefile, as described in B.2.2, “Run the Makefile” on page 118, produces auxa1m.map file and a uxa1 file that you can move under your CICS/6000 regionby entering:

$ cp uxa1m.map /var/cics_regions/<region>/maps/prime/uxa1m.map

$ cp uxa1 /var/cics_regions/<region>/bin/DB2UXA1.

Your AIX user identifier must belong to the AIX cics group to move both files.Renaming the uxa1 program enables you to distinguish it from the name used ina different database.

Now you must define the CICS/6000 resources by using SMIT or writing a shellscript that adds all of the entries you need as shown in B.2.4, “ConfigurePrograms and Transactions for CICS/6000 Using Script for DATABASE 2AIX/6000” on page 123.

Resource definitions are held in the stanza files, which make up the permanentdatabase that CICS/6000 uses to cold start the system, and in the run-timedatabase, which CICS/6000 uses to hold information about its resources when itis running.

Enter the following command to define a program to the CICS/6000 stanzadatabase:


└─� Define Resources for a CICS/6000 Region └─� Manage Resource(s) └─� Programs └─� Add New └─� Model Program Identifier


or use the fastpath command, smitty cicsaddpd.

When prompted for a model program identifier, choose the model �″″�. You willget a panel similar to that shown in Figure 44.

� �Add Program


[TOP] [Entry Fields]* Program Identifier [�UXA1�]* Model Program Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Resource description [UXA1 Map Program Defini>

* Number of updates 0Protect resource from modifications? no +Program enable status enabled +Remote system on which to run program []Name to use for program on remote system []Resource Level Security Key [private]Program path name <�e/maps/prime/uxa1m.map�]

[MORE...2]


� �Figure 44. Defining the UXA1 Map Program to CICS/6000: DATABASE 2 AIX/6000

The full program path name as shown in Figure 44 is:/var/cics_regions/<region_name>/maps/prime/uxa1m.map.

Note

You must call the UXA1 program identifier; otherwise CICS/6000 returns anAPCT error because the application defines a mapset UXA1.

You now have to install the DB2UXA1 program by running the fastpathcommand, smitty cicsaddpd. You will get the panel shown in Figure 45 onpage 122.


� �Add Program


[TOP] [Entry Fields]* Program Identifier [�DB2UXA1�]* Model Program Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Resource description [DB2UXA1 Program Defini>

* Number of updates 0Protect resource from modifications? no +Program enable status enabled +Remote system on which to run program []Name to use for program on remote system []Resource Level Security Key [private]Program path name <�ns/sanjose/bin/DB2UXA1�]

[MORE...2]


� �Figure 45. Defining the DB2UXA1 Program to CICS/6000

The full program path name as shown in Figure 45 is:/var/cics_regions/<region_name>/bin/DB2UXA1.

At this point you have to define the DB2U transaction to CICS/6000 by enteringthe following command:


└─� Define Resources for a CICS/6000 Region └─� Manage Resource(s) └─� Transactions └─� Add New └─� Model Transaction identifier

or by using the fastpath command, smitty cicsaddtd.

When prompted for a model transaction identifier, choose the model �″″�. Youwill get a panel similar to that shown in Figure 46 on page 123.


� �Add Transaction


[TOP] [Entry Fields]* Transaction Identifier [�DB2U�]* Model Transaction Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Group to which resource belongs []Activate the resource at cold start? yes +Resource description [�DB2�Demo�Cheese�XA�App�>

* Number of updates 0Protect resource from modification? no +Transaction enable status enabled +Remote System Identifier []Remote Transaction Identifier []Resource Level Security Key [private]Transaction Level Security Key [1]Type of RSL Checks none +Type of TSL Checks internal +Should transaction be dumped on an abend? no +First program name [�DB2UXA1�]

[MORE...14]


� �Figure 46. Defining the DB2U Transaction to CICS/6000

B.2.4 Configure Programs and Transactions for CICS/6000 Using Script forDATABASE 2 AIX/6000

If you prefer, you can configure programs and transactions by writing a shellscript as shown in Figure 47 on page 124.


� �#!/bin/kshecho $CICSREGIONBINDIR=/var/cics_regions/$CICSREGION/binMAPDIR=/var/cics_regions/$CICSREGION/maps/prime

cp uxa1 $BINDIR/DB2UXA1cp uxa1m.map $MAPDIR

cicsadd -c td -r $CICSREGION \ResourceDescription=″DB2 Demo Cheese XA Application″ \ProgName=″DB2UXA1″ \DB2U

cicsadd -c pd -r $CICSREGION -P ″DB2UXA1″ \ResourceDescription=″DB2UXA1 Program Definition″ \PathName=″$BINDIR/DB2UXA1″

cicsadd -c pd -r $CICSREGION -P ″UXA1″ \ResourceDescription=″UXA1 Map Definitions″ \PathName=″$MAPDIR/uxa1m.map″ \ProgType=map

� �Figure 47. Sample Shell Script to Configure CICS/6000 Resources: DATABASE 2AIX/6000

These configurations take effect only after a cold start of CICS/6000 because wehave defined resources only to database stanza files.

B.3 Informix Version 5The samples are included in CICS/6000 LPPs, and you can find in the/usr/lpp/cics/v1.1/src/samples/xa directory the files you need to build and runthe UXA1 transaction. The following files are supplied:


• uxa1.sql SQL script to create and populate tables

• uxa1.bms CICS/6000 BMS source for panels

• uxa1.ec C source file for Informix

• uxa1_inf5.mk C Makefile for Informix.

Note

The /usr/lpp/cics/v1.1/doc directory explains how to configure InformixVersion 5 with CICS/6000. Please read informix501.README file.

B.3.1 Create DatabaseLogin as user Informix and verify that the database is running by using thecommand:

$ ps -ef | grep informix.



� �informix 8130 1 0 Feb 28 hft/0 2:41 tbinit -isyinformix 19139 8130 0 Feb 28 hft/0 0:03 tbpgclinformix 22879 8130 0 17:22:08 hft/0 0:00 tbundo

seb 23832 26899 6 11:14:22 pts/0 0:00 grep informix

� �Figure 48. Processes Related to Informix

If Informix is not running, you can bring it up by entering the command:

$ tbinit.

Use the ps command to check that the tbinit and tbpgcl daemons are running.We created a cicstest database with the DB-Access utility by using the command:

$ dbaccess -dc cicstest,

and we changed the logging from buffered to unbuffered, so, in the event of afailure, only the single alteration in progress at the time of the failure is lost. Youcan do that by running this command:

$ tbtape -s -U cicstest.

CICS/6000 expects to work with unbuffered logging.

You will be asked to perform an archive. Type 0 and you will get the messagesshown in Figure 49.

� �Please enter the level of archive to be performed (0, 1, or 2)

Please label this tape as number 1 in the archive sequence.

Level 0 archive is 100 percent completed.

date: Fri Mar 4 09:45:38 1994

Tapes required to restore the system to the stateat the beginning of this archive:

Archive level: 0 Archive date: Fri Mar 4 09:45:38 1994

Logical log unique id at the beginning of the archive: 1

Database(s) logging status successfully updated.

Program over.

� �Figure 49. Results of tbtape Command

Now you must grant to public the cicstest database; we suggest that you add thisline to the uxa1.sql file:

grant resource to public;


Furthermore the uxa1.sql file contains some lines that begin with a pound sign(#) that dbaccess cannot understand, so you have to add the right delimiters forcomments { } or delete those lines.

Now you are ready to execute the SQL uxa1.sql script by typing:

$ dbaccess cicstest uxa1.

Uxa1.sql creates a table, cheese, within the cicstest database, populates thetable, and grants any user the right to work against the table and connect to thecicstest database.

B.3.2 Run the MakefileBefore running the makefile you must edit it to reflect your Informix Version 5customization. The makefile assumes that INFORMIXDIR is set to /usr/informix;we modified the uxa1_inf5.mk as shown in Figure 50.

� �INFORMIXDIR=/home/informix

all: uxa1m.map uxa1


uxa1: uxa1.ec$(INFORMIXDIR)/bin/esql -e uxa1.ecmv uxa1.c uxa1.ccsCCFLAGS=″-I$(INFORMIXDIR)/incl/esql \

-L/home/informix/lib/esql \/home/informix/lib/esql/libinf501cs.o″ ; \

export CCFLAGS; \cicstcl -e -d -lC uxa1.ccs

� �Figure 50. uxa1_inf5.mk Makefi le after Editing


$ make -f uxa1_inf5.mk.




ERZ0511I/0106: Basic Mapping Support (BMS) map translation ended.0 errors, 0 warnings.ERZ0513I/0702: Physical map generated to ′ uxa1m.map′ .ERZ0514I/0601: Logical map generated to ′ uxa1.h′ .

/home/informix/bin/esql -e uxa1.ecmv uxa1.c uxa1.ccsCCFLAGS=″-I/home/informix/incl/esql \ -L/home/informix/lib/esql \ /home/informix/lib/esql/libinf501cs.o″ ; \


ERZ0447I/5002: Running the translation step: ′ cicstran -e -d -lC uxa1.ccs′ERZ0460I/5015: cicstran translation ended: 0 error(s), 0 warning(s).ERZ0449I/5003: Running the compile and link step:′ xlc_r /usr/lpp/cics/v1.1/lib/libcics_api.a -e main-I/usr/lpp/cics/v1.1/include -I/home/informix/incl/esql-L/home/informix/lib/esql /home/informix/lib/esql/libinf501cs.o -o uxa1 uxa1.c′

� �Figure 51. Output of uxa1_inf5.mk Makefi le to Compile UXA1 Transaction: InformixVersion 5

Refer to the Informix - OnLine Administrator ′s Guide for more details about howto use Informix utilities.

B.3.3 Configure Programs and Transactions for CICS/6000 Using SMIT forInformix Version 5



$ cp uxa1 /var/cics_regions/<region>/bin/INFUXA1.


Now you must define the CICS/6000 resources by using SMIT or writing a shellscript that adds all of the entries you need as shown in B.3.4, “ConfigurePrograms and Transactions for CICS/6000 Using Script for Informix Version 5” onpage 130.







When prompted for a model program identifier, choose the model �″″�. You willget a panel similar to that shown in Figure 52

� �Add Program




[MORE...2]


� �Figure 52. Defining the UXA1 Map Program to CICS/6000: Informix Version 5


Note


You now have to install the INFUXA1 program by running the fastpath command,smitty cicsaddpd. You will get the panel shown in Figure 53 on page 129.


� �Add Program


[TOP] [Entry Fields]* Program Identifier [�INFUXA1�]* Model Program Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Resource description [INFUXA1 Program Defini>

* Number of updates 0Protect resource from modifications? no +Program enable status enabled +Remote system on which to run program []Name to use for program on remote system []Resource Level Security Key [private]Program path name <�ns/sanjose/bin/INFUXA1�]

[MORE...2]


� �Figure 53. Defining the INFUXA1 Program to CICS/6000

The full program path name as shown in Figure 45 on page 122 is:/var/cics_regions/<region_name>/bin/INFUXA1.

At this point you have to define the INFU transaction to CICS/6000 by enteringthe following command:



or by using the fastpath command: smitty cicsaddtd.





[TOP] [Entry Fields]* Transaction Identifier [�INFU�]* Model Transaction Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Group to which resource belongs []Activate the resource at cold start? yes +Resource description [�INF�Demo�Cheese�XA�App�>

* Number of updates 0Protect resource from modification? no +Transaction enable status enabled +Remote System Identifier []Remote Transaction Identifier []Resource Level Security Key [private]Transaction Level Security Key [1]Type of RSL Checks none +Type of TSL Checks internal +Should transaction be dumped on an abend? no +First program name [�INFUXA1�]

[MORE...14]


� �Figure 54. Defining the INFU Transaction to CICS/6000

B.3.4 Configure Programs and Transactions for CICS/6000 Using Script forInformix Version 5

You can configure programs and transaction by writing a shell script as shown inFigure 55 on page 131.



cp uxa1 $BINDIR/INFUXA1cp uxa1m.map $MAPDIR

cicsadd -c td -r $CICSREGION \ResourceDescription=″INF Demo Cheese XA Application″ \ProgName=″INFUXA1″ \INFU

cicsadd -c pd -r $CICSREGION -P ″INFUXA1″ \ResourceDescription=″INFUXA1 Program Definition″ \PathName=″$BINDIR/INFUXA1″


� �Figure 55. Sample Shell Script to Configure CICS/6000 Resources: Informix Version 5


B.4 Oracle7The samples are included in CICS/6000 LPPs, and you can find in the/usr/lpp/cics/v1.1/src/samples/xa directory the files you need to build and runthe UXA1 transaction. The following files are supplied:



• uxa1.bms CICS/6000 BMS source for panels

• uxa1.ec C source file for Informix

• uxa1_inf5.mk C Makefile for Informix.

Note

The /usr/lpp/cics/v1.1/doc directory explains how to configure InformixVersion 5 with CICS/6000. Please read the oracle713.README file.

B.4.1 Create DatabaseLog in as user Oracle and verify that the database is running by using thecommand:

$ ps -ef | grep oracle.



� �seb 8846 20353 5 11:38:10 pts/7 0:00 grep oracle

oracle 12359 1 0 10:54:27 - 0:01 ora_dbwr_ora7 oracle 13640 1 0 10:54:29 - 0:00 ora_lgwr_ora7 oracle 18758 1 0 10:54:25 - 0:00 ora_pmon_ora7 oracle 19275 1 0 10:54:35 - 0:00 ora_d000_ora7 oracle 21321 1 0 10:54:31 - 0:01 ora_smon_ora7 oracle 21578 1 0 10:54:33 - 0:00 ora_s000_ora7

� �Figure 56. Processes Related to Oracle

If Oracle is not running, you can bring it up by entering the command:

$ sqldba lmode=yes.

You will be prompted with:

S Q L D B A > .

Type:

SQLDBA> connect internal

SQLDBA> startup

SQLDBA> exi t .

Use the ps command to check that the Oracle processes are running.

The uxa1.sql file contains some lines that begin with a pound sign (#) thatOracle ′s utility SQLPLUS cannot understand. You can either add the rightdelimiters for comments { } or delete those lines.

Now you are ready to execute the SQL uxa1.sql script by typing:

$ sqlplus scott/tiger @uxa1.sql.

Note

The user scott/t iger is available if you install the database demo duringOracle installation; otherwise you have to create an Oracle user.

Uxa1.sql creates a table, cheese, populates the table, and grants any user theright to work against the table.

B.4.2 Run the MakefileBefore running the makefile you must edit it to reflect your Oracle7customization. The makefile assumes that ORACLE_HOME is set to /usr/oracle;we modified the uxa1_ora7.mk as shown in Figure 57 on page 133.


� �ORACLE_HOME=/home/oracle

all: uxa1m.map uxa1


uxa1: uxa1.pc$(ORACLE_HOME)/bin/proc release_cursor=yes sqlcheck=none \

ireclen=512 iname=uxa1.pcmv uxa1.c uxa1.ccsCCFLAGS=″-L/home/oracle/lib \

-lsharesqlxa -lm -lld″ ; \export CCFLAGS; \cicstcl -e -d -lC uxa1.ccsrm -f uxa1.c

� �Figure 57. uxa1_ora7.mk Makefi le after Editing


$ make -f uxa1_ora7.mk.

Figure 58 shows the output on our machine.


ERZ0511I/0106: Basic Mapping Support (BMS) map translation ended.0 errors, 0 warnings.

ERZ0513I/0702: Physical map generated to ′ uxa1m.map′ .ERZ0514I/0601: Logical map generated to ′ uxa1.h′ .

/home/oracle/bin/proc release_cursor=yes sqlcheck=noneireclen=512 iname=uxa1.pc

Pro*C: Release 1.5.9.0.1 - Production on Tue Mar 8 16:54:01 1994

Copyright (c) Oracle Corporation 1979, 1992. All rights reserved.

Precompiling uxa1.pcmv uxa1.c uxa1.ccsCCFLAGS=″-L/home/oracle/lib \ -lsharesqlxa -lm -lld″ ; \


ERZ0447I/5002: Running the translation step: ′ cicstran -e -d -lC uxa1.ccs′ERZ0460I/5015: cicstran translation ended: 0 error(s), 0 warning(s).ERZ0449I/5003: Running the compile and link step:′ xlc_r /usr/lpp/cics/v1.1/lib/libcics_api.a -e main -I/usr/lpp/cics/v1.1/include-L/home/oracle/lib -lsharesqlxa -lm -lld -o uxa1 uxa1.c′″uxa1.c″ , line 345.22: 1506-193 (E) Function call argument cannot be assignedto corresponding parameter.

rm -f uxa1.c

� �Figure 58. Output of uxa1_ora7.mk Makefi le to Compile UXA1 Transaction


Note

We received error 1506-193 (see Figure 59 on page 135) because of theincorrect use of the sprintf function library:

sprintf(name.arr, ″ % s″, panel1.panel1i.newnamei);

A possible workaround is this:

sprintf(temp_name, ″ % s″, panel1.panel1i.newnamei);

strcpy(name.arr,temp_name);

where temp_name is defined as:

char temp_name [16];

Refer to the Oracle7 Server Administrator′s Guide for more details about how touse Oracle utilities.

B.4.3 Configure Programs and Transactions for CICS/6000 Using SMIT forOracle7



$ cp uxa1 /var/cics_regions/<region>/bin/ORAUXA1


Now you must define the CICS/6000 resources by using SMIT or writing a shellscript that adds all of the entries you need as shown in B.4.4, “ConfigurePrograms and Transactions for CICS/6000 Using Script for Oracle7” on page 137.







When prompted for a model program identifier, choose the model �″″�. You willget a panel similar to that shown in Figure 59

� �Add Program




[MORE...2]


� �Figure 59. Defining the UXA1 Map Program to CICS/6000: Oracle7


Note


You now have to install the ORAUXA1 program by running the fastpathcommand, smitty cicsaddpd. You will get the panel shown in Figure 60 onpage 136.


� �Add Program


[TOP] [Entry Fields]* Program Identifier [�ORAUXA1�]* Model Program Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Resource description [ORAUXA1 Program Defini>

* Number of updates 0Protect resource from modifications? no +Program enable status enabled +Remote system on which to run program []Name to use for program on remote system []Resource Level Security Key [private]Program path name <�ns/sanjose/bin/ORAUXA1�]

[MORE...2]


� �Figure 60. Defining the ORAUXA1 Program to CICS/6000

The full program path name as shown in Figure 45 on page 122 is:/var/cics_regions/<region_name>/bin/ORAUXA1.

At this point you have to define the ORAU transaction to CICS/6000 by enteringthe following command:








[TOP] [Entry Fields]* Transaction Identifier [�ORAU�]* Model Transaction Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Group to which resource belongs []Activate the resource at cold start? yes +Resource description [�ORA�Demo�Cheese�XA�App�>

* Number of updates 0Protect resource from modification? no +Transaction enable status enabled +Remote System Identifier []Remote Transaction Identifier []Resource Level Security Key [private]Transaction Level Security Key [1]Type of RSL Checks none +Type of TSL Checks internal +Should transaction be dumped on an abend? no +First program name [�ORAUXA1�]

[MORE...14]


� �Figure 61. Defining the ORAU Transaction to CICS/6000

B.4.4 Configure Programs and Transactions for CICS/6000 Using Script forOracle7




cp uxa1 $BINDIR/ORAUXA1cp uxa1m.map $MAPDIR

cicsadd -c td -r $CICSREGION \ResourceDescription=″ORA Demo Cheese XA Application″ \ProgName=″ORAUXA1″ \ORAU

cicsadd -c pd -r $CICSREGION -P ″ORAUXA1″ \ResourceDescription=″ORAUXA1 Program Definition″ \PathName=″$BINDIR/ORAUXA1″


� �Figure 62. Sample Shell Script to Configure CICS/6000 Resources: Oracle7


B.5 Sybase System 10We had the demo, Cheese, with the beta code of the Sybase XA-Library forCICS/6000. The following files are supplied:


• uxa1.cpre C source file for Sybase

• uxa1_syb.mk makefile for Sybase.

B.5.1 Create DatabaseLog in as user Sybase and verify that the database is running by using thecommand:

$ ps -ef | grep syabse.

Figure 63 shows the output on our machine.

� � sybase 9544 11847 10 10:36:15 hft/2 0:44 /sybase/bin/dataserver

-d/dev/rmasterlv -sSYBASE -e/sybase/install/errorlog -i/s sybase 11847 1 0 10:36:15 hft/2 0:00 sh ./RUN_SYBASE

seb 14949 14689 3 10:54:21 pts/0 0:00 grep sybase

� �Figure 63. Processes Releted to Sybase

If Sybase is not running, you can bring it up by entering the command:


$ startserver,

which you can find in the $SYBASE/install directory; use the ps command tocheck that the Sybase processes are running.

Execute the SQL script uxa1.sql by typing:

$ isql -Usa -P<Server password> -i uxa1.sql.

Note

The user, sa, is available after the Sybase System 10 Server installation, butwith a null password. You are required to set a password for the SystemAdministrator account by using the sp_password system procedure asdocumented in the Sybase SQL Server Installation Guide for IBM RISCSystem/6000. The installation process adds a pseudo-user, ″probe″, for useby the two-phase commit program only.

Uxa1.sql creates a table, cheese, populates the table, and grants any user theright to work against the table.

B.5.2 Run the MakefileThe makefile requires that you modify your SYBASE environment variable toreflect your Sybase System 10 installation (see Figure 64).

� �SHAROBJS = -lcs.so -lcomn.so

SYB_SHAR_LIBDIR = $(SYBASE)/lib

LIBDIR = $(SYBASE)/lib

SYBLIBS = -lct -lintl -ltcl -lm -linsckCFLAGS = -c -gall: uxa1m.map uxa1


uxa1: uxa1.cpre$(SYBASE)/bin/cpre uxa1.cpremv uxa1.c uxa1.ccsCCFLAGS=″-I $(CICSPATH)/v1.1/include -I $(SYBASE)/include \-L $(SYB_SHAR_LIBDIR)\-L $(LIBDIR) \$(SHAROBJS) \$(SYBLIBS)″ ; \export CCFLAGS; \cicstcl -e -d -lC uxa1.ccs

� �Figure 64. uxa1_syb.mk Makefi le

To compile the demo enter from the command line:

$ make -f uxa1_syb.mk




ERZ0511I/0106: Basic Mapping Support (BMS) map translation ended.0 errors, 0 warnings.

ERZ0513I/0702: Physical map generated to ′ uxa1m.map′ .ERZ0514I/0601: Logical map generated to ′ uxa1.h′ .

/sybase/bin/cpre uxa1.cpreM_WHEN_WARN,Unable to find the SQL statement ′ WHENEVER WARNING′ .M_WHEN_NF,Unable to find the SQL statement ′ WHENEVER NOT FOUND′ .0 Error(s) and 2 Warning(s) found.Statistical Report:

Program name: cpreOptions specified:Input file name: uxa1.cpreListing file name:Target file name: uxa1.cISQL file name:Tag ID specified:Compiler used: ANSI_COpen Client version: CS_VERSION_100Number of information messages: 11Number of warning messages: 2Number of error messages: 0Number of SQL statements parsed: 6Number of host variables declared: 5Number of SQL cursors declared: 0Number of dynamic SQL statements: 0Number of stored Procedures generated: 0Connection(s) information:

User id:Server:Database:

mv uxa1.c uxa1.ccsCCFLAGS=″-I /v1.1/include -I /sybase/include \

-L /sybase/lib\-L /sybase/lib \-lcs.so -lcomn.so \-lct -lintl -ltcl -lm -linsck″ ; \export CCFLAGS; \cicstcl -e -d -lC uxa1.ccs

ERZ0447I/5002: Running the translation step: ′ cicstran -e -d -lC uxa1.ccs′ERZ0460I/5015: cicstran translation ended: 0 error(s), 0 warning(s).ERZ0449I/5003: Running the compile and link step:′ xlc_r /usr/lpp/cics/v1.1/lib/libcics_api.a -e main -I/usr/lpp/cics/v1.1/include-I /v1.1/include -I /sybase/include -L /sybase/lib -L /sybase/lib -lcs.so-lcomn.so -lct -lintl -ltcl -lm -linsck -o uxa1 uxa1.c′

� �Figure 65. Output of uxa1_syb.mk Makefi le to Compile UXA1 Transaction

Note

In the uxa1.cpre we added an SQL statement to connect to the server definedin the $SYBASE/xa_config file; otherwise the application cannot manage anydata. The statement is:

EXEC SQL SET CONNECTION connection_1;


B.5.3 Configure Programs and Transactions for CICS/6000 Using SMIT forSybase System 10



$ cp uxa1 /var/cics_regions/<region>/bin/SYBUXA1.


Now you must define the CICS/6000 resources by using SMIT or writing a shellscript that adds all of the entries you need as shown in B.5.4, “ConfigurePrograms and Transactions for CICS/6000 Using Script for Sybase System 10” onpage 144.






When prompted for a model program identifier, choose the model �″″�. You willget a panel similar to that shown in Figure 66 on page 142.


� �Add Program




[MORE...2]


� �Figure 66. Defining the UXA1 Map Program to CICS/6000: Sybase System 10


Note


You now have to install the SYBUXA1 program by running the fastpathcommand, smitty cicsaddpd. You will get the panel shown in Figure 67 onpage 143.


� �Add Program


[TOP] [Entry Fields]* Program Identifier [�SYBUXA1�]* Model Program Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Resource description [SYBUXA1 Program Defini>

* Number of updates 0Protect resource from modifications? no +Program enable status enabled +Remote system on which to run program []Name to use for program on remote system []Resource Level Security Key [private]Program path name <�ns/sanjose/bin/SYBUXA1�]

[MORE...2]


� �Figure 67. Defining the SYBUXA1 Program to CICS/6000

The full program path name as shown in Figure 45 on page 122 is:/var/cics_regions/<region_name>/bin/SYBUXA1.

At this point you have to define the SYBU transaction to CICS/6000 by enteringthe following command:








[TOP] [Entry Fields]* Transaction Identifier [�SYBU�]* Model Transaction Identifier ″″* Region name [sanjose] +Add to database only OR Add and Install �Add�AND�Install� +Group to which resource belongs []Activate the resource at cold start? yes +Resource description [�ORA�Demo�Cheese�XA�App�>

* Number of updates 0Protect resource from modification? no +Transaction enable status enabled +Remote System Identifier []Remote Transaction Identifier []Resource Level Security Key [private]Transaction Level Security Key [1]Type of RSL Checks none +Type of TSL Checks internal +Should transaction be dumped on an abend? no +First program name [�SYBUXA1�]

[MORE...14]


� �Figure 68. Defining the SYBU Transaction to CICS/6000

B.5.4 Configure Programs and Transactions for CICS/6000 Using Script forSybase System 10




cp uxa1 $BINDIR/SYBUXA1cp uxa1m.map $MAPDIR

cicsadd -c td -r $CICSREGION \ResourceDescription=″SYB Demo Cheese XA Application″ \ProgName=″SYBUXA1″ \SYBU

cicsadd -c pd -r $CICSREGION -P ″SYBUXA1″ \ResourceDescription=″SYBUXA1 Program Definition″ \PathName=″$BINDIR/SYBUXA1″


� �Figure 69. Sample Shell Script to Configure CICS/6000 Resources: Sybase System 10




Glossary

AAPI . Application programming interface. A set ofcalling conventions defining how a service is invokedthrough a software package.

APPC . Advanced Program-to-ProgramCommunication. An implementation of SNA′s LU 6.2protocol that allows interconnected systems tocommunicate and share the processing of programs.

archive . The maintenance and use of backup copiesof files or full disk images to be used in the case ofloss or damage of data due to unforeseencircumstances. Archived copies are also used tomaintain historical copies of information.

asynchronous . Without regular time relationship;unexpected or unpredictable with respect to theexecution of program instruction. See synchronous.

Bbusiness process . An entity-handling activity that isof limited duration, defined in scope, and set bybusiness goals and policies, not by organization orimplementation.

Cclient . As in client-server computing, the applicationthat makes requests to the server and, often, dealswith the interaction necessary with the user.

client-server computing . A form of distributedprocessing, in which the task required to beprocessed is accomplished by a client portion thatrequests services and a server portion that fullfi l lsthose requests. The client and server remaintransparent to each other in terms of location andplatform. See distributed processing, client, andserver.

communications models . The ways of implementingcommunications between the distributed elements ofan application. Examples are conversational, remoteprocedure call, and messaging.

conversational . Communication model where twodistributed applications exchange information by wayof a conversation; typically one application starts (orallocates) the conversation, sends some data, andallows the other application to send some data. Bothapplications continue in turn until one decides tofinish (or deallocate). The conversational model is asynchronous form of communication.

cooperative processing . The process by which asingle application is divided between two or morehardware platforms. Very often the term is used toreflect a tightly coupled relationship between theparts of the application.

CPI-C. Common Programming Interface forCommunication, providing a common interface for theimplementation of the conversational communicationmodel.

Ddatabase . (1) A collection of interrelated data storedtogether with controlled redundancy according to ascheme to serve one or more applications. (2) Alldata files stored in the system. (3) A set of datastored together and managed by a databasemanagement system.

DCE. Distributed Computing Environment. Adoptedby the industry as a de facto standard for distributedcomputing. DCE allows computers from a variety ofvendors to communicate transparently and sharesuch resources as computing power, files, printers,and other objects in the network.

design . The process of composing a softwareblueprint, showing how to build from the requirementsspecification document. Design often includes moduledecompositions, data structure definitions, fi le formatdefinitions, and important algorithm descriptions.

directory . A repository of information about objects,functions, or services and a set of services tomanipulate the repository. In this document the termdirectory is used to describe a function to identify andprovide information about resources in a network,such as servers, files, applications.

distributed processing . Distributed processing is anapplication and/or systems model in which functionand data may be distributed across multiplecomputing resources connected on a LAN or WAN.See client-server computing and peer-to-peerprocessing.

EENCINA . Enterprise computing in a new age. A set ofDCE-based products from Transarc Corporation thatare available on the RISC System/6000. Encina is afamily of online transaction processing products andincludes:

• Encina Toolkit Executive

• Encina Server


• Encina Structured File Server (SFS)

• Encina Peer-to-Peer Communication Executive(PPC).

environment . The collective hardware and softwareconfiguration of a system.

event driven . Term used to describe an applicationenvironment where the sequence of processing isdetermined primarily by the application ′s response toexternal events, which may be initiated by the user,the operating system, or other applications.

Ffile server . A centrally located computer that acts asa storehouse of data and applications for numeroususers of a local area network.

GGUI. Graphical user interface. A style of userinterface that replaces the character-based screenwith an all-points-addressable, high resolutiongraphics screen that uses windows to display multipleapplications at the same time while allowing userinput by means of a keyboard or a pointing devicesuch as a mouse, a pen, or a trackball.

Hheterogeneous network . A local or wide areanetwork comprising hardware and software fromdifferent vendors, usually implementing multipleprotocols, operating systems, and applications.

hook . (1) In programming, an area of program codethat makes connections with other program codes. (2)A mechanism by which procedures are called whencertain events occur in the system. (3) A documentedprogramming interface in a component of system orapplication software that provides a means ofextending or modifying the function of that componentthrough the attachment of user-supplied code.

host . (1) In a computer network, a computerproviding services such as computation, databaseaccess, and network control functions. (2) Theprimary or controll ing computer in a multiplecomputer installation.

Iinstance . An individual application object thatbelongs to a particular object class. An instance of aclass is an actual object displaying the properties ofthat class.

instantiate . To represent a class abstraction with a

concrete instance of the class by providing values forthe attributes of the class.

interactive processing . A type of processing in whicha program or system alternately accepts input andresponds. An interactive system is conversational,that is, a continuous dialog exists between the userand the system.

interoperability . The ability to interconnect systemsfrom different manufacturers and have them worktogether to satisfy a business requirement. Someexamples of requirements are message interchangebetween systems, and sharing of resources, such asdata, between applications running on differenthardware and software platforms.

LLUW . Logical unit of work. An update that durablytransforms a resource from one consistent state toanother consistent state.

Mmessaging . A communications model whereby thedistributed applications communicate by sendingmessages to each other. A message is typically ashort packet of information that does not necessarilyrequire a reply. Messaging implements asynchronouscommunications.

middleware . Middleware is a set of services thatallows distributed applications to interoperate on aLAN or WAN. It shields the developer or end-userfrom the system complexity and enables delivery ofservice requests or responses transparently acrosscomputing resources.

Oobject . A program or a group of data that canbehave like a thing in the real world.

OLTP . Online transaction processing. A style ofcomputing that supports interactive applications inwhich requests submitted by terminal users areprocessed as soon as they are received. Results arereturned to the requester in a relatively short periodof time. A online transaction processing systemsupervises the sharing of resources for processingmultiple transactions at the same time, minimizescompute time and duration of locks and, separatesuser thinking-time from the use of storage and otherresources.


Ppeer-to-peer processing . A form of distributedprocessing where the distributed parts of anapplication can both make and serve requests,typically in a conversational structure, as opposed toone side making the requests and the other sidefill ing them, as in client-server computing.

portability . The ability to move application softwarecomponents from one system for use on anothersystem. Perfect portability would permit suchmovement without modification of those components.

process . (1) A unique, finite course of events definedby its purpose or by its effect, achieved under definedconditions. (2) Any operation or combination ofoperations on data. (3) A function being performed orwaiting to be performed. (4) A program in operation,for example, a daemon.

protocol . (1) A formal set of conventions governingthe format and control of data. (2) A set of proceduresor rules for establishing and controlling transmissionsfrom a source device or process to a target device orprocess.

Rrecovery . The use of archived copies to reconstructfiles, databases, or complete disk images after theyare lost or destroyed.

RPC. Remote procedure call. A communicationmodel where requests are made by function calls todistributed procedures elsewhere. The location of theprocedures is transparent to the calling application.

resource manager . A software program thatmaintains the state of resources and provides accessand control to them through APIs. A resource can bea device as well as a program or object, althoughnormally it is referred to as a device.

Sserver . Any computing resource dedicated toresponding to client requests. Servers may be linkedto clients through LANs or WANs to perform services,such as printing, database access, fax, and imageprocessing, on behalf of multiple clients at the sametime.

SQL . Structured query language. SQL started asIBM ′s query language for DB2. SQL became sopopular with users and vendors outside IBM that ANSIadopted a version of SQL as a U.S. standard in 1986.A year later ISC gave SQL formal internationalstandard status.

stored procedures . Facility for storing proceduralcode associated with relational database managementsystems (RDBMSs) that enforces its use during anydatabase operation.

synchronous . (1) Pertaining to two or moreprocesses that depend on the occurrences of aspecific event such as a common timing signal. (2)Occurring with a regular or predictable timerelationship.

Ttest . Testing involves checking each individualmodule built during the implementation phase, thenintegrating the modules into a single programstructure. The program as a whole is then tested toensure that it performs as designed.

thread of control . Inside the X/Open DTP model, theconcept that associates RM work with the globaltransaction. Routines in the XA interface that managethe association among a thread of control andtransactions must be called from the same thread.

transaction . A unit of processing (consisting of oneor more application programs) initiated by a singlerequest. A transaction may require the initiation ofone or more tasks for its execution.

transaction branch . A part of the work in support of aglobal transaction for which the TM and the RMengage in a commitment protocol coordinated with,but separate from, that for other branches.

transaction manager . Provides the function to begin,end, commit, and rollback transactions.

transaction monitor . Provides a total environment fortransactional applications. In addition to transactionmanager functions, provides services to aiddevelopment, execution, and operation of transactionapplications.

transaction processing . A style of computing thatsupports interactive applications in which requestsubmitted by users are processed as soon as they arereceived. Results are returned to the requester in arelatively short period of time. A transactionprocessing system supervises the sharing ofresources for processing multiple transactions at thesame time.

transparency . The state where certain elements ofthe system are hidden so that other parts of thesystem need not depend on the specificimplementation of those elements. For instance, aservers ′s location is transparent to its client; thus,when the server ′s location changes, the clients neednot be changed.

Glossary 149

two-phase commit . For a database, a protocol that isused to ensure uniform transaction commit or abort ina distributed data environment between two or moreparticipants. The protocol consists of two phases: thefirst to reach a common decision, and the second toimplement the decision.

TX. Within the DTP model adopted by X/Open, theinterface among the application or transactionmonitor and the transaction manager.

Wworkflow . The automation of work among userswhere the system is intelligent enough to act basedon the definition of work types, tasks, and therecognition of dynamic processing conditions.

workstation . A configuration of input/output

equipment at which an operator works. A terminal ormicrocomputer, usually one that is connected to amainframe or a network, at which a user can performapplications.

XXA . Within the DTP model adopted by X/Open, theinterface between the transaction manager andresource managers.


List of Abbreviations

API application programminginterface

ATI automatic task initiation

CRA crash recovery archive

EI EXEC interface

FD fi le definition

IBM International BusinessMachines Corporation

ISC intersystem communication

ITSO International TechnicalSupport Organization

LAN local area network

LPP l icenced program product

LUW logical unit of work

OLTP online transaction processing

PPC peer-to-peer communication

PID process identifier

RD region definition

RDBMS relational databasemanagement system

SFS Structured File Server

SMIT System ManagementInterface Tool

SRC system resource controller

transid transaction identification code

UD user definition

WAN wide area network



Index

Aall_operation 11API 147application program 2ax_ services 8

Bbusiness process 147

CCICS/6000 processes 12CICS/6000 XA Definition 10client 147client-server computing 147COBOL configuration 113

Ddatabase 147DATABASE 2 AIX/6000

configuration 17database privileges 20dynamic registration 19local implementation 16problem determination 71registration: local and remote 62remote implementation

client setup 51server setup 51

Switch Load file definition 18XA resource definitions 20

DB2INSTANCE 22, 52directory 147distributed processing 147dynamic registration 79

Eenvironment 148

Fflag options

TMMIGRATE 35TMNOFLAGS 9TMNOMIGRATE 9, 19TMNOREGISTER 35TMREGISTER 9, 19TMUSEASYNC 9

Hhook 148

IInformix Version 5

configuration 24implementat ion 23problem determination 73registrat ion 63Switch Load file 28

initi l ization string 10instance 148

LLRM 41

Oobject 148Oracle7

local implementation 31problem determination 74registrat ion 65remote implementation


Switch Load file 34table privi leges 35

Pprocess 149protocol 149

Rrecovery 4, 149resource manager 2resource manager registration 13resource manager switch 7, 8, 9, 17, 18, 24, 26, 32,

33, 42, 52rollback 4

Sserver 149shared l ibrary 7, 32, 39shared object 7, 17, 24, 52SQL 149Switch Load file 10, 13, 18, 22Sybase System 10

configuration 39database privileges 44


Sybase System 10 (continued)local implementation 38lrm_connection 41problem determination 76registrat ion 67remote implementation


stored procedures 40Switch Load file 43

SYNCPOINT 79, 81, 86

Tthread of control 149transaction 149transaction branch 8transaction identif ier 3transaction manager 2two-phase commit 3, 150TX interface 2

XX/Open DTP model

activity among functional components 3CICS/6000 and 5functional components 2functional model 1interfaces among functional components 2process model 4

XA definition 10, 29XA interface 2, 7, 8, 10, 79, 150XA open string 7, 10, 13, 17, 24, 25, 32, 42, 52xa_ services 8


ITSO Technical Bulletin Evaluation RED000

AIX CICS/6000 andRelational Database Management Systems Integration:Experiences with the XA Interface

Publication No. GG24-4214-00

Your feedback is very important to help us maintain the quality of ITSO Bulletins. Please fill out thisquestionnaire and return it using one of the following methods:

• Mail it to the address on the back (postage paid in U.S. only)• Give it to an IBM marketing representative for mailing• Fax it to: Your International Access Code + 1 914 432 8246• Send a note to [email protected]

Please rate on a scale of 1 to 5 the subjects below.(1 = very good, 2 = good, 3 = average, 4 = poor, 5 = very poor)

Overall Satisfaction ____

Organization of the bookAccuracy of the informationRelevance of the informationCompleteness of the informationValue of illustrations

____________________

Grammar/punctuation/spell ingEase of reading and understandingEase of finding informationLevel of technical detailPrint quality

____________________

Please answer the following questions:

a) If you are an employee of IBM or its subsidiaries:

Do you provide billable services for 20% or more of your time? Yes____ No____

Are you in a Services Organization? Yes____ No____

b) Are you working in the USA? Yes____ No____

c) Was the Bulletin published in time for your needs? Yes____ No____

d) Did this Bulletin meet your needs? Yes____ No____

If no, please explain:

What other topics would you like to see in this Bulletin?

What other Technical Bulletins would you like to see published?

Comments/Suggestions: ( THANK YOU FOR YOUR FEEDBACK! )

Name Address

Company or Organizat ion

Phone No.

Cut or FoldAlong Line

Cut or FoldAlong Line

ITSO Technical Bulletin Evaluation RED000GG24-4214-00 IBML

Fold and Tape Please do not staple Fold and Tape

NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES

BUSINESS REPLY MAILFIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

IBM International Technical Support OrganizationDepartment 471, Building 070B5600 COTTLE ROADSAN JOSE CAUSA 95193-0001

Fold and Tape Please do not staple Fold and Tape

GG24-4214-00

IBML

Printed in U.S.A.

GG24-4214-00

Documents

AIX CICS/6000 and Relational Database Management Systems