Adaptive Server Enterprise

Transcription

1 XA Interface Integration Guide for CICS, Encina, and TUXEDO Adaptive Server Enterprise 15.0

2 DOCUMENT ID: DC LAST REVISED: Aug Copyright by Sybase, Inc. All rights reserved. This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement. To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) , fax (617) Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc. Sybase, the Sybase logo, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server, Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication, Adaptive Server Everywhere, Adaptive Warehouse, Afaria, Answers Anywhere, Anywhere Studio, Application Manager, AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-Translator, APT-Library, AvantGo Mobile Delivery, AvantGo Mobile Inspection, AvantGo Mobile Marketing Channel, AvantGo Mobile Pharma, AvantGo Mobile Sales, AvantGo Pylon, AvantGo Pylon Application Server, AvantGo Pylon Conduit, AvantGo Pylon PIM Server, AvantGo Pylon Pro, Backup Server, BizTracker, ClearConnect, Client-Library, Client Services, Convoy/DM, Copernicus, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer, DataWindow, DataWindow.NET, DB-Library, dbqueue, Developers Workbench, DirectConnect, DirectConnect Anywhere, Distribution Director, e-adk, E-Anywhere, e-biz Impact, e-biz Integrator, E-Whatever, EC Gateway, ECMAP, ECRTP, efulfillment Accelerator, Embedded SQL, EMS, Enterprise Application Studio, Enterprise Client/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer, Enterprise Work Modeler, eprocurement Accelerator, EWA, Financial Fusion, Financial Fusion Server, Gateway Manager, GlobalFIX, ianywhere, ianywhere Solutions, ImpactNow, Industry Warehouse Studio, InfoMaker, Information Anywhere, Information Everywhere, InformationConnect, InternetBuilder, iscript, Jaguar CTS, jconnect for JDBC, M2M Anywhere, Mach Desktop, Mail Anywhere Studio, Mainframe Connect, Maintenance Express, Manage Anywhere Studio, M-Business Channel, M-Business Network, M-Business Server, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, mfolio, Mirror Activator, MySupport, Net- Gateway, Net-Library, New Era of Networks, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Biz, Open Client, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, PocketBuilder, Pocket PowerBuilder, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerScript, PowerSite, PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst, QAnywhere, Rapport, RemoteWare, RepConnector, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, Replication Toolkit, Report- Execute, Report Workbench, Resource Manager, RFID Anywhere, RW-DisplayLib, RW-Library, S-Designor, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script, SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQL Server SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, S.W.I.F.T. Message Format Libraries, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server, Sybase Gateways, Sybase IQ, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User Workbench, SybaseWare, Syber Financial, SyberAssist, SybFlex, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, TradeForce, Transact-SQL, Translation Toolkit, UltraLite, UltraLite.NET, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, VisualWriter, VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server, XcelleNet, and XP Server are trademarks of Sybase, Inc. 02/05 Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. All other company and product names used herein may be trademarks or registered trademarks of their respective companies. Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS for the DOD and as set forth in FAR (a)-(d) for civilian agencies. Sybase, Inc., One Sybase Drive, Dublin, CA

3 Contents About This Book... vii CHAPTER 1 Introduction... 1 Overview... 1 Requirements... 2 CHAPTER 2 The Sybase XA Environment... 5 Definitions... 5 Overview of the X/Open DTP model... 6 Components of the model... 7 How the components communicate... 8 How the components interact... 8 Recovery The Sybase XA environment Components of the Sybase XA environment Connections in the Sybase XA environment Identifying connections via LRMs Establishing connections Distributing work across LRMs CHAPTER 3 Configuring the XA Environment Configuring Adaptive Server Open string parameters for DTM XA Interface Open string parameters dtm_tm_role required for username Log file and trace flag parameters xa_open() function behavior XA configuration file for DTM XA Interface Environment variable for specifying configuration file [all] section for defining common LRM parameters Editing the XA configuration file Additional capabilities, properties, and options Using the DTM XA Interface with CICS XA Interface Integration Guide for CICS, Encina, and TUXEDO iii

4 Contents Building the switch-load file Adding a Sybase stanza to the CICS region XAD definition Using the DTM XA Interface with Encina Assigning an open string with monadmin create rm Initializing LRMs with mon_registerrmi Linking applications with DTM XA Interface libraries Establishing connections Using the DTM XA Interface with TUXEDO Linking Setting up the UBBCONFIG file Creating the TUXEDO configuration file Building the TMS Build COBOL runtime environment CHAPTER 4 Application Programming Guidelines X/Open DTP versus traditional Sybase transaction processing Transaction and connection management Transaction management Connection management The current connection Nontransactional connections Deallocate cursor function with Client-Library Dynamic SQL Getting a Client-Library connection handle Multiple-thread environment issues Caveats of thread use Embedded SQL thread-safe code Tightly coupled transactions Linking with CT Library Sample embedded SQL COBOL fragment Sample embedded SQL C fragment Index iv Adaptive Server Enterprise

5 Contents XA Interface Integration Guide for CICS, Encina, and TUXEDO v

6 Contents vi Adaptive Server Enterprise

7 About This Book Audience How to use this book This guide serves as a reference manual for: System administrators setting up a distributed transaction processing (DTP) environment that includes one or more Adaptive Servers with distributed transaction management features, accessed by transactions from within a CICS, Encina, or TUXEDO transaction manager (TM) system. Application programmers using Embedded SQL or Client-Library to access data on one or more Adaptive Servers. This manual assumes the reader is familiar with: The TM operating environment Embedded SQL Open Client Client-Library Adaptive Server administration Use this guide to help configure your environment and code your application to access data stored on one or more Adaptive Servers from within a CICS, Encina, or TUXEDO TM. Chapter 1, Introduction summarizes the steps necessary to fully integrate the DTM XA Interface into your environment. Chapter 2, The Sybase XA Environment provides background information designed to help you place the Sybase XA environment into the larger context of distributed transaction processing and transaction management. It reviews the X/Open DTP model of distributed transaction processing and fits the Sybase DTM XA Interface into this model. In addition, it describes how the individual components of the Sybase XA environment work together to allow your application to access Adaptive Server data from a TM. Chapter 3, Configuring the XA Environment gives instructions for configuring your environment to fully integrate your application, Sybase DTM XA Interface, one or more Adaptive Servers, and your TM software. XA Interface Integration Guide for CICS, Encina, and TUXEDO vii

8 Related documents Chapter 4, Application Programming Guidelines explains how to make your Embedded SQL or Client-Library application conform to certain coding constraints that the Sybase XA environment imposes. The Sybase Adaptive Server Enterprise documentation set consists of the following: The release bulletin for your platform contains last-minute information that was too late to be included in the books. A more recent version of the release bulletin may be available on the World Wide Web. To check for critical product or document information that was added after the release of the product CD, use the Sybase Technical Library. The Installation Guide for your platform describes installation, upgrade, and configuration procedures for all Adaptive Server and related Sybase products. What s New in Adaptive Server Enterprise? describes the new features in Adaptive Server version 15.0, the system changes added to support those features, and changes that may affect your existing applications. ASE Replicator User s Guide describes how to use the Adaptive Server Replicator feature of Adaptive Server to implement basic replication from a primary server to one or more remote Adaptive Servers. Component Integration Services User s Guide explains how to use the Adaptive Server Component Integration Services feature to connect remote Sybase and non-sybase databases. The Configuration Guide for your platform provides instructions for performing specific configuration tasks for Adaptive Server. Full-Text Search Specialty Data Store User s Guide describes how to use the Full-Text Search feature with Verity to search Adaptive Server Enterprise data. Glossary defines technical terms used in the Adaptive Server documentation. Historical Server User s Guide describes how to use Historical Server to obtain performance information for SQL Server and Adaptive Server. Java in Adaptive Server Enterprise describes how to install and use Java classes as data types, functions, and stored procedures in the Adaptive Server database. viii Adaptive Server Enterprise

9 About This Book Job Scheduler User's Guide provides instructions on how to install and configure, and create and schedule jobs on a local or remote Adaptive Server using the command line or a graphical user interface (GUI). Messaging Service User s Guide describes how to usereal Time Messaging Services to integrate TIBCO Java Message Service and IBM WebSphere MQ messaging services with all Adaptive Server database applications. Monitor Client Library Programmer s Guide describes how to write Monitor Client Library applications that access Adaptive Server performance data. Monitor Server User s Guide describes how to use Monitor Server to obtain performance statistics from SQL Server and Adaptive Server. Performance and Tuning Guide is a series of four books that explains how to tune Adaptive Server for maximum performance: Basics the basics for understanding and investigating performance questions in Adaptive Server. Locking describes how the various locking schemas can be used for improving performance in Adaptive Server. Optimizer and Abstract Plans describes how the optimizer processes queries and how abstract plans can be used to change some of the optimizer plans. Monitoring and Analyzing explains how statistics are obtained and used for monitoring and optimizing performance. Quick Reference Guide provides a comprehensive listing of the names and syntax for commands, functions, system procedures, extended system procedures, datatypes, and utilities in a pocket-sized book. Reference Manual is a series of four books that contains the following detailed Transact-SQL information: Building Blocks Transact-SQL datatypes, functions, global variables, expressions, identifiers and wildcards, and reserved words. Commands Transact-SQL commands. Procedures Transact-SQL system procedures, catalog stored procedures, system extended stored procedures, and dbcc stored procedures. Tables Transact-SQL system tables and dbcc tables. XA Interface Integration Guide for CICS, Encina, and TUXEDO ix

10 Other sources of information System Administration Guide provides in-depth information about administering servers and databases. This manual includes instructions and guidelines for managing physical resources, security, user and system databases, and specifying character conversion, international language, and sort order settings. System Tables Diagram illustrates system tables and their entity relationships in a poster format. Available only in print version. Transact-SQL User s Guide documents Transact-SQL, Sybase s enhanced version of the relational database language. This manual serves as a textbook for beginning users of the database management system. This manual also contains descriptions of the pubs2 and pubs3 sample databases. Using Adaptive Server Distributed Transaction Management Features explains how to configure, use, and troubleshoot Adaptive Server DTM features in distributed transaction processing environments. Using Sybase Failover in a High Availability System provides instructions for using Sybase s Failover to configure an Adaptive Server as a companion server in a high availability system. Unified Agent and Agent Management Console User s Guide Describes the Unified Agent, which provides runtime services to manage, monitor and control distributed Sybase resources. Utility Guide documents the Adaptive Server utility programs, such as isql and bcp, which are executed at the operating system level. Web Services User s Guide explains how to configure, use, and troubleshoot Web Services for Adaptive Server. XA Interface Integration Guide for CICS, Encina, and TUXEDO provides instructions for using the Sybase DTM XA interface with X/Open XA transaction managers. XML Services in Adaptive Server Enterprise describes the Sybase native XML processor and the Sybase Java-based XML support, introduces XML in the database, and documents the query and mapping functions that comprise XML Services. Use the Sybase Getting Started CD, the SyBooks CD, and the Sybase Product Manuals Web site to learn more about your product: x Adaptive Server Enterprise

11 About This Book The Getting Started CD contains release bulletins and installation guides in PDF format, and may also contain other documents or updated information not included on the SyBooks CD. It is included with your software. To read or print documents on the Getting Started CD, you need Adobe Acrobat Reader, which you can download at no charge from the Adobe Web site using a link provided on the CD. The SyBooks CD contains product manuals and is included with your software. The Eclipse-based SyBooks browser allows you to access the manuals in an easy-to-use, HTML-based format. Some documentation may be provided in PDF format, which you can access through the PDF directory on the SyBooks CD. To read or print the PDF files, you need Adobe Acrobat Reader. Refer to the SyBooks Installation Guide on the Getting Started CD, or the README.txt file on the SyBooks CD for instructions on installing and starting SyBooks. The Sybase Product Manuals Web site is an online version of the SyBooks CD that you can access using a standard Web browser. In addition to product manuals, you will find links to EBFs/Maintenance, Technical Documents, Case Management, Solved Cases, newsgroups, and the Sybase Developer Network. Sybase certifications on the Web To access the Sybase Product Manuals Web site, go to Product Manuals at Technical documentation at the Sybase Web site is updated frequently. v v Finding the latest information on product certifications 1 Point your Web browser to Technical Documents at 2 Select Products from the navigation bar on the left. 3 Select a product name from the product list and click Go. 4 Select the Certification Report filter, specify a time frame, and click Go. 5 Click a Certification Report title to display the report. Finding the latest information on component certifications 1 Point your Web browser to Availability and Certification Reports at XA Interface Integration Guide for CICS, Encina, and TUXEDO xi

12 2 Either select the product family and product under Search by Product; or select the platform and product under Search by Platform. 3 Select Search to display the availability and certification report for the selection. v Creating a personalized view of the Sybase Web site (including support pages) Set up a MySybase profile. MySybase is a free service that allows you to create a personalized view of Sybase Web pages. Sybase EBFs and software maintenance Conventions v 1 Point your Web browser to Technical Documents at 2 Click MySybase and create a MySybase profile. Finding the latest information on EBFs and software maintenance 1 Point your Web browser to the Sybase Support Page at 2 Select EBFs/Maintenance. If prompted, enter your MySybase user name and password. 3 Select a product. 4 Specify a time frame and click Go. A list of EBFs/Maintenance releases is displayed. Padlock icons indicate that you do not have download authorization for certain EBFs/Maintenance releases because you are not registered as a Technical Support Contact. If you have not registered, but have valid information provided by your Sybase representative or through your support contract, click Edit Roles to add the Technical Support Contact role to your MySybase profile. 5 Click the Info icon to display the EBFs/Maintenance report, or click the product description to download the software. The following sections describe conventions used in this manual. xii Adaptive Server Enterprise

13 About This Book SQL is a free-form language. There are no rules about the number of words you can put on a line or where you must break a line. However, for readability, all examples and most syntax statements in this manual are formatted so that each clause of a statement begins on a new line. Clauses that have more than one part extend to additional lines, which are indented. Complex commands are formatted using modified Backus Naur Form (BNF) notation. Table 1 shows the conventions for syntax statements that appear in this manual: Table 1: Font and syntax conventions for this manual Element Example Command names,procedure names, utility names, and select other keywords display in sans serif font. sp_configure Database names and datatypes are in sans serif font. master database Book names, file names, variables, and path names are System Administration Guide in italics. sql.ini file column_name $SYBASE/ASE directory Variables or words that stand for values that you fill in when they are part of a query or statement, are in italics in Courier font. Type parentheses as part of the command. Double colon, equals sign indicates that the syntax is written in BNF notation. Do not type this symbol. Indicates is defined as. Curly braces mean that you must choose at least one of the enclosed options. Do not type the braces. Brackets mean that to choose one or more of the enclosed options is optional. Do not type the brackets. The comma means you may choose as many of the options shown as you want. Separate your choices with commas as part of the command. The pipe or vertical bar( ) means you may select only one of the options shown. An ellipsis (...) means that you can repeat the last unit as many times as you like. select column_name from table_name where search_conditions compute row_aggregate (column_name) ::= {cash, check, credit} [cash check credit] cash, check, credit cash check credit buy thing = price [cash check credit] [, thing = price [cash check credit]]... You must buy at least one thing and give its price. You may choose a method of payment: one of the items enclosed in square brackets. You may also choose to buy additional things: as many of them as you like. For each thing you buy, give its name, its price, and (optionally) a method of payment. XA Interface Integration Guide for CICS, Encina, and TUXEDO xiii

14 Accessibility features Syntax statements (displaying the syntax and all options for a command) appear as follows: sp_dropdevice [device_name] For a command with more options: select column_name from table_name where search_conditions In syntax statements, keywords (commands) are in normal font and identifiers are in lowercase. Italic font shows user-supplied words. Examples showing the use of Transact-SQL commands are printed like this: select * from publishers Examples of output from the computer appear as follows: pub_id pub_name city state New Age Books Boston MA 0877 Binnet & Hardley Washington DC 1389 Algodata Infosystems Berkeley CA (3 rows affected) In this manual, most of the examples are in lowercase. However, you can disregard case when typing Transact-SQL keywords. For example, SELECT, Select, and select are the same. Adaptive Server s sensitivity to the case of database objects, such as table names, depends on the sort order installed on Adaptive Server. You can change case sensitivity for single-byte character sets by reconfiguring the Adaptive Server sort order. For more information, see the System Administration Guide. This document is available in an HTML version that is specialized for accessibility. You can navigate the HTML with an adaptive technology such as a screen reader, or view it with a screen enlarger. xiv Adaptive Server Enterprise

15 About This Book Adaptive Server HTML documentation has been tested for compliance with U.S. government Section 508 Accessibility requirements. Documents that comply with Section 508 generally also meet non-u.s. accessibility guidelines, such as the World Wide Web Consortium (W3C) guidelines for Web sites. Note You might need to configure your accessibility tool for optimal use. Some screen readers pronounce text based on its case; for example, they pronounce ALL UPPERCASE TEXT as initials, and MixedCase Text as words. You might find it helpful to configure your tool to announce syntax conventions. Consult the documentation for your tool. If you need help For information about how Sybase supports accessibility, see Sybase Accessibility at The Sybase Accessibility site includes links to information on Section 508 and W3C standards. Each Sybase installation that has purchased a support contract has one or more designated people who are authorized to contact Sybase Technical Support. If you cannot resolve a problem using the manuals or online help, please have the designated person contact Sybase Technical Support or the Sybase subsidiary in your area. XA Interface Integration Guide for CICS, Encina, and TUXEDO xv

16 xvi Adaptive Server Enterprise

17 CHAPTER 1 Introduction Topic Page Overview 1 Requirements 2 Overview The DTM XA Interface is Sybase s implementation of the XA Interface standard, which is one element of the X/Open Distributed Transaction Processing (DTP) model. The X/Open DTP model provides an industry standard for developing distributed transaction processing applications. Use the XA Interface to access data stored on Adaptive Servers from within a CICS, Encina, or TUXEDO TM. To use native Adaptive Server distributed transaction management (DTM) features with or without a TM, see Using Adaptive Server Distributed Transaction Management Features. The Microsoft Transaction Server (MTS) also uses the XA Interface for transactional components. MTS XA configuration is handled through the Sybase ODBC driver setup. See the ODBC driver documentation for details. Other TMs, such as IBM MQ Services, also use the XA Interface. See the transaction manager documentation for details on how to configure the TM. XA Interface Integration Guide for CICS, Encina, and TUXEDO 1

18 Requirements v Enabling a TM transaction to access data stored on Adaptive Server 1 Install Adaptive Server, and the distributed transaction management feature. Software installation and feature licenses are described in the Adaptive Server Installation Guide for your platform. Note Distributed transaction management is a separately-licensed Adaptive Server feature. You must purchase and install a valid license for DTM before it can be used. 2 Install Sybase Open Client on all client machines. The DTM XA Interface is included with Open Client. 3 Start Adaptive Server with support for the distributed transaction management feature. See Using Adaptive Server Distributed Transaction Management Features for information. 4 Configure the TM software to run with an Embedded SQL or Client- Library application and Adaptive Server, as described in Chapter 3, Configuring the XA Environment. 5 Make the Embedded SQL or Client-Library application conform to certain coding constraints, as described in Chapter 4, Application Programming Guidelines. 6 Start the CICS, Encina, or TUXEDO TM. Note To administer global recovery manually in the Sybase XA environment, you must invoke XA-specific dbcc commands, as described in Using Adaptive Server Distributed Transaction Management Features. Requirements XA Interface for Adaptive Server version 12.5 is compatible with: Open Client 12.5 Embedded SQL 12.0 or later Adaptive Server 12.0 or later CICS/ Adaptive Server Enterprise

19 CHAPTER 1 Introduction Encina 2.5/TX Series 4.2 TUXEDO 6.4 (6.3/6.4 on IBM platforms) XA Interface Integration Guide for CICS, Encina, and TUXEDO 3

20 Requirements 4 Adaptive Server Enterprise

21 CHAPTER 2 The Sybase XA Environment This chapter describes the X/Open DTP model, and shows how the components of the Sybase XA environment including the DTM XA Interface, your application program, and Adaptive Server, among others fit into that model. It also discusses how connections are established and managed in the Sybase XA environment. Topic Page Definitions 5 Overview of the X/Open DTP model 6 The Sybase XA environment 11 Connections in the Sybase XA environment 13 Definitions The X/Open DTP model assumes an understanding of certain terms. transaction a whole unit of work consisting of one or more computational tasks. Most often, a transaction s tasks manipulate shared resources. committed transaction a completed transaction whose changes to any shared resources are permanent. rolled-back transaction a complete transaction whose changes to any shared resources are nullified. ACID test the test of a true transaction; to pass, the transaction must exhibit the following properties: Atomicity all or none of the results of the transaction take effect. Consistency if a transaction is rolled back, all resources that the transaction affected return to the state they were in prior to the transaction s execution. XA Interface Integration Guide for CICS, Encina, and TUXEDO 5

22 Overview of the X/Open DTP model Isolation a transaction s results are visible only to that transaction until the transaction commits. Durability permanent resource changes resulting from commitment survive subsequent system failures. transaction processing a system of coordinating the transactions that multiple users perform on shared, centralized resources. distributed transaction processing a transaction processing model in which the shared resources are located at distinct physical sites on a computer network. local transaction a transaction that affects data in a single database and whose tasks a single resource manager performs. See Overview of the X/Open DTP model on page 6 for a definition of resource managers. global transaction a transaction that spans more than one database and multiple resource managers. transaction branch a portion of the work that makes up a global transaction. transaction identifier an identifier that a TM assigns to a transaction. The transaction monitor uses the transaction identifier to coordinate all activity related to a global transaction. The resource manager uses the global identifier to match the recoverable tasks it performed for the transaction. recovery the process of bringing a transaction processing system into a consistent state after a failure. Specifically, this means resolving transactions left in a noncommitted state. Overview of the X/Open DTP model The X/Open DTP model is a model for software architecture that allows multiple application programs to share resources provided by multiple resource managers, and allows their work to be coordinated into global transactions. The X/Open DTP model identifies the key entities in a distributed transaction processing environment and standardizes their roles and interactions. The entities are: The transaction processing monitor (TM) 6 Adaptive Server Enterprise

23 CHAPTER 2 The Sybase XA Environment The resource manager (RM) The application program (AP) This section discusses the X/Open DTP functional model, including its major components and their interfaces. Figure 2-1 shows the X/Open DTP model. Figure 2-1: A conceptual view of the X/Open DTP model Application Program (AP) Native Interface TX Interface RM XA Interface TM These components communicate through the native, XA, and TX Interfaces as described in How the components communicate on page 8. Components of the model The X/Open DTP functional model consists of the following components: The application program (AP) The resource manager (RM) The transaction processing monitor (TM) The AP contains the code written to accomplish a particular transaction or portion thereof. As such, it designates the beginning and end of global transactions. The RM provides access to shared resources. Database servers, file servers, and print servers are examples of RMs. In a typical X/Open DTP environment, a single AP communicates with more than one RM. In the Sybase XA environment, the RM is an Adaptive Server database. XA Interface Integration Guide for CICS, Encina, and TUXEDO 7

24 Overview of the X/Open DTP model The TM coordinates the communication between all parties participating in the transaction. The TM assures that the work done by the AP is contained in a global transaction, which commits or aborts atomically. Specifically, the TM s tasks include: Assigning global identifiers to transactions. Monitoring the progress of global transactions. Coordinating the flow of transaction information between the APs and the RMs. Managing the transaction commitment protocol and failure recovery. For details, see How the components interact on page 8. How the components communicate The AP, the RM, and the TM communicate via three distinct interfaces: native, TX, and XA. The native interface is the medium by which the AP makes requests directly to the RM. This interface is RM specific. In the Sybase XA environment, the native interface is either Embedded SQL or Client-Library. The TX Interface is the medium between the AP and the TM. The AP uses TX calls to delineate transaction boundaries. In other words, the AP requests that the TM start and commit or roll back global transactions, via the TX Interface. This interface is TM specific. The XA Interface is the medium between the RM and the TM. The DTM XA Interface is Sybase s version of the interface for Adaptive Server. Using XA calls, the TM tells the RM when transactions start, commit, and roll back. The TM also handles recovery. How the components interact The components work together to process transactions from initiation through completion. 8 Adaptive Server Enterprise

25 CHAPTER 2 The Sybase XA Environment The AP delimits transaction boundaries. An AP informs the TM, via TX calls, that a global transaction is beginning. The TM then communicates with all available RMs, via XA calls, to associate a single transaction identifier with any work the RMs will do on behalf of the AP within the bounds of the global transaction. When the AP requests that the TM commit the global transaction, the TM and the RMs use the two-phase commit protocol to guarantee transaction atomicity. Transaction completion takes place in two phases the prepare phase and the commit phase. For a detailed description of the two-phase commit protocol, see the Open Client DB-Library/C Reference Manual. In the prepare phase, the TM requests each RM to prepare to commit its portion of the global transaction. This portion is known as a transaction branch. In the commit phase, the TM instructs the RMs to commit or abort their branches of the transaction. If all RMs report back that they have prepared their respective transaction branches, the TM commits the entire transaction. If any RM reports that it was unprepared or fails to respond, the TM rolls back the entire transaction. Figure 2-2 shows a typical transaction branch structure. XA Interface Integration Guide for CICS, Encina, and TUXEDO 9

26 Overview of the X/Open DTP model Figure 2-2: Transaction branches Application Program (AP) RM TM Application Program (AP) RM TM Application Program (AP) Application Program (AP) RM TM RM TM Recovery The TM is responsible for managing global recovery. In certain situations, an administrator may decide to complete its transaction branch independently of the TM. When this occurs, the administrator s decision is called a heuristic decision. 10 Adaptive Server Enterprise

27 CHAPTER 2 The Sybase XA Environment The heuristic decision may be in conflict with the TM s decision. For example, the administrator may commit a transaction branch and the TM may request to abort it. Such a conflict requires manual intervention from the System Administrator. For a discussion of heuristic decisions in the Sybase XA environment, see Using Adaptive Server Distributed Transaction Management Features. The Sybase XA environment The DTM XA Interface relies on Sybase s transaction processing model to implement X/Open s DTP model. Adaptive Server is used as an RM, as shown in Figure 2-3. XA Interface Integration Guide for CICS, Encina, and TUXEDO 11

28 The Sybase XA environment Figure 2-3: The Sybase XA DTP model Client application (AP) TX calls Embedded SQL, and/or Client-Library calls TM XA Calls Sybase Resource Manager Embedded SQL and/or Open Client XA Interface Connections Adaptive Server LRMs Components of the Sybase XA environment The Sybase XA environment consists of: The Sybase DTM XA Interface. This is Sybase s implementation of the XA Interface for Adaptive Server, described in How the components communicate on page Adaptive Server Enterprise

29 CHAPTER 2 The Sybase XA Environment The Open Client libraries. Client-Library calls can be part of the native interface between your application and the resource manager. Note XA Client libraries run in 32-bit mode on Solaris 64, AIX 64, HP- UX 64 and Windows platforms and in 64-bit mode on Solaris 64, AIX 64, HP-UX 64 platforms. Embedded SQL/C and Embedded SQL/COBOL. Embedded SQL calls can be part of the native interface between your application and the resource manager. One or more Adaptive Servers. These play the role of RMs. The XA configuration file. This file contains entries that define client/server connections for use with XA. A set of XA-specific dbcc commands. System Administrators use these to manage heuristic transactions. TM-specific configuration files and commands. Chapter 3, Configuring the XA Environment explains how to configure these components so that transactions can use the DTM XA Interface to access data stored on Adaptive Server. Connections in the Sybase XA environment The X/Open DTP model has no notion of connections, yet connections are central to the Sybase client/server architecture. The Sybase XA environment must resolve this discrepancy. To this end, the Sybase XA environment introduces the notion of a logical resource manager (LRM). Identifying connections via LRMs Each instance of the Sybase RM appears to the TM as one or more LRMs. XA Interface Integration Guide for CICS, Encina, and TUXEDO 13

30 Connections in the Sybase XA environment An LRM associates a symbolic name with a client/server connection. An AP uses the names to identify the specific physical connection to one or more Adaptive Servers. The TM uses the names to open connections on behalf of the AP. Where is the connection information stored? The following components of the Sybase XA environment contain information about LRMs. The System Administrator configures these files before starting up the TM. For information on the full configuration process, see Chapter 3, Configuring the XA Environment. The Sybase XA configuration file The CICS XA product definition (XAD) The Encina monadmin create rm command The Sybase XA configuration file contains one entry per LRM. The entry associates the LRM with a physical Adaptive Server name, and assigns pre-connection Client-Library capabilities and properties to the LRM. For details on the XA configuration file, see XA configuration file for DTM XA Interface on page 22. The CICS XAD contains one stanza per LRM. The stanza assigns each LRM a user name and password in the form of an open string. The user name and password enable the Sybase XA environment to control a particular connection s access to Adaptive Server resources. For details on the CICS XAD file, see Adding a Sybase stanza to the CICS region XAD definition on page 31. The monadmin create rm command assigns each LRM a user name and password in the form of an open string. The user name and password allow the Sybase XA environment to control a particular connection s access to Adaptive Server resources. For details on the Encina monadmin command, see Assigning an open string with monadmin create rm on page 33. Your current version of Encina may have additional commands for specifying RMs. Note You can use the Encina enconsole interactive command instead of the shell monadmin command. For detailed information, see the Encina Monitor System Administrator s Guide and Reference. 14 Adaptive Server Enterprise

31 CHAPTER 2 The Sybase XA Environment TUXEDO s UBBCONFIG file In addition to modifying the Sybase configuration files, integrating TUXEDO requires customizing the TUXEDO configuration file, UBBCONFIG. The open string is the only portion of the UBBCONFIG file that requires modification. It includes the user name and password, which allow XA-Server to control a connection s access to Adaptive Server resources. See Setting up the UBBCONFIG file on page 37 for details. Establishing connections The TM, together with the XA Interface, establishes connections between applications and RMs in several steps. v v Establishing connections in a CICS environment 1 When the CICS region starts up, it issues an XA open call to each LRM configured in an XAD, using the information contained in each open string. 2 The CICS region passes to the XA Interface library the open string associated with each stanza. The open string contains the LRM name, the user name, and the password. 3 The XA Interface looks up the LRM name in the Sybase XA configuration file and matches it to an actual RM name, that is, an actual physical Adaptive Server. The RM name matches an entry in the Adaptive Server interfaces file. 4 The XA Interface establishes one connection to an Adaptive Server for each LRM entry. The XA Interface confers on any connection the preconnection properties and capabilities configured for the LRM. Establishing connections in an Encina environment 1 An application issues a mon_registerrmi function, thereby requesting use of an LRM. 2 Using information contained in an open string, the TM issues an XA open call to the LRM (configured in the monadmin create rm command) whose name matches that issued in step 1, above. 3 The TM passes the open string associated with each monadmin create rm command to the XA Interface. The open string contains the LRM name. XA Interface Integration Guide for CICS, Encina, and TUXEDO 15

32 Connections in the Sybase XA environment 4 The XA Interface looks up the LRM name in the Sybase XA configuration file and matches it to an actual RM name that is, to an actual physical Adaptive Server. The RM name matches an entry in the Adaptive Server interfaces file. 5 The XA Interface establishes one logical connection to an Adaptive Server for each LRM entry. The XA Interface confers on any connection the preconnection properties and capabilities configured for the LRM. v Establishing connections in a TUXEDO environment 1 The application uses the LRM specified in the UBBCONFIG file to reference the logical connection for a branch of a global transaction. In using the LRM name, the application implicitly requests and establishes an LRM. 2 The transaction manager passes the appropriate open string to the XA Interface through the LRM whose name matches the one issued in step 1. The XA Interface uses the LRM name, the user name, and the password. 3 The XA Interface looks in the xa_config file to find an association between the LRM name and Adaptive Server. The Adaptive Server name matches an entry in the interfaces file where its network information is kept. 4 The XA Interface establishes one logical connection to an Adaptive Server for each LRM entry. The XA Interface confers on any connection the preconnection properties and capabilities configured for the LRM. Distributing work across LRMs The System Administrator and the application programmer together must agree on the number and names of LRMs that their Sybase XA environment includes. The System Administrator configures the TM and Sybase XA configuration files accordingly. The application programmer invokes a particular LRM name within the application code to send a portion of a global transaction across that connection. The TM coordinates this distribution. You can configure the Sybase XA environment for more connections than are actually used. That is, the XA configuration file may contain inactive entries. Figure 2-4 depicts the relationship between the Sybase XA configuration file, TM configuration file, application code, and Adaptive Server interfaces file for a CICS environment. 16 Adaptive Server Enterprise

33 CHAPTER 2 The Sybase XA Environment Figure 2-4: Relating components of the Sybase XA environment for CICS betaone: XAD File Stanza GroupName= ActivateOnStartup=yes ResourceDescription= XA Product Definition AmendCounter=2 Permanent=0 SwitchLoadFile= /usr/lpp/sybase/sample/xa_library/ connection_1 XA Configuration File CICS/switch/sybasexa XAOpen= -Uuser=1 -Ppassword_1 ; lrm -N- Names the logical connection as seen by -L/tmp/xa_log ; the application and the TP monitor. ; ; server - Names the physical server as found in ; the Sybase interfaces file. ; ; capabilities - Lists pre-connection capabilities to ; be set (optional). ; ; properties - Lists pre-connection properties to ; be set (optional). ; [xa] lrm=connection_1 Interfaces File server=sybxa_1 sybxa_1 query tcp ether groucho 6161 Application Program [xa] lrm=connection_3 server=sybxa_1 capabilities= CS_DATA_NOBIT=CS_TRUE properties= /* Select CS_BULK_LOGIN_CS_FALSE a record from the table based on user input. [xa] */ sprintf(name, %s, panel1.panel1i.newnamei); connection_1 EXEC SQL SET CONNECTION supplier_address,order_quantity INTO :name, :supplier, :supplier_address, :order_quantity XA Interface Integration Guide for CICS, Encina, and TUXEDO 17

34 Connections in the Sybase XA environment 18 Adaptive Server Enterprise

35 CHAPTER 3 Configuring the XA Environment This chapter describes how to configure the XA environment for use with CICS, Encina, and TUXEDO TMs. Topic Page Configuring Adaptive Server 19 Open string parameters for DTM XA Interface 20 XA configuration file for DTM XA Interface 22 Using the DTM XA Interface with CICS 28 Using the DTM XA Interface with Encina 33 Using the DTM XA Interface with TUXEDO 35 Build COBOL runtime environment 40 You must link the DTM XA Interface library with your X/Open XAcompliant transaction manager to use Adaptive Server as a resource manager. Note See the README file under the subdirectories of $SYBASE/$SYBASE_OCS/sample for detailed information about configuring the DTM XA Interface for your system. Configuring Adaptive Server To function in a Sybase XA environment, your Adaptive Server must be licensed and configured to use the distributed transaction management feature. See the Adaptive Server Installation Guide and Using Adaptive Server Distributed Transaction Management Features for more information. If your Adaptive Server is licensed to use distributed transaction management, you can enable the feature using the enable dtm configuration parameter: XA Interface Integration Guide for CICS, Encina, and TUXEDO 19

36 Open string parameters for DTM XA Interface sp_configure 'enable dtm', 1 You must restart Adaptive Server for this parameter to take effect. Open string parameters for DTM XA Interface The X/Open XA specification allows each resource manager vendor to define an open string and a close string. The DTM XA Interface does not require or use the close string. The DTM XA Interface uses the required and optional open string parameters described below. Open string parameters Parameter lrm_name username password logfile_name The format for parameters in the open string for the DTM XA Interface is: -Nlrm_name -Uusername -Ppassword [-Llogfile_name] [-Ttraceflags] [-V11] [-O1] [-O-1] Table 3-1 describes each component of the open string. Table 3-1: Sybase X/Open XA open string parameters Meaning The name of the LRM as defined in the XA configuration file. The user name used to log in to Adaptive Server. See dtm_tm_role required for username on page 21 for more information. The password accompanying the user name. The fully qualified file name to which the XA Interface writes tracing information (optional). The XA Interface initializes the log file and trace flag settings with the initial xa_open() call. If no logfile_name is specified, then the DTM XA Interface logs information to a file named syb_xa_log in the current directory. traceflags Trace flags control the output that is written to the log file (optional). See Parameter definitions for [all] section on page 23 for a list of valid trace flags. -V11 Specifies Open Client version 11 behavior for backward compatibility (optional). -O1 or -O-1 Specifies an option for transaction operation. At this time only -O1 (tightly coupled transaction branches) is supported. -O1 sets the option. -O-1 clears the option. -O-1 is the default. Warning! See Tightly coupled transactions on page 51 before setting -O1. 20 Adaptive Server Enterprise

37 CHAPTER 3 Configuring the XA Environment dtm_tm_role required for username In the open string for resource managers, the specified username must have the dtm_tm_role in the corresponding Adaptive Server. The System Security Officer can assign this role using sp_role or the grant command. For example: sp_role "grant", dtm_tm_role, user_name Log file and trace flag parameters With the DTM XA Interface to Adaptive Server, log file and trace flag parameters can be defined in the [all] section of the XA configuration file, rather than in the X/Open XA open string. See [all] section for defining common LRM parameters on page 23 for more information about the log file and trace flag components. Labels for logfile entries The DTM XA Interface marks each entry in the log file with a label indicating the severity or cause of the message. Table 3-2 describes each label. Label Error Fatal Error Message Warning Note XA trace RM trace Connection trace ASE I/F trace Misc trace Event trace Verbose trace Function trace Open Client trace Table 3-2: Logfile message labels Type of entry An error returned to the transaction manager A severe failure in the DTM XA Interface, with a possible application or transaction manager error Additional information about a previous error, or a description of the operational environment A condition that may indicate problems with the transactional system Information that does not indicate a problem, but may be useful if an error occurs Information logged as a result of the xa trace flag setting Information logged as a result of the xl trace flag setting Information logged as a result of the xc trace flag setting Information logged as a result of the xs trace flag setting Information logged as a result of the misc trace flag setting Information logged as a result of the event trace flag setting Information logged as a result of the v trace flag setting Information logged as a result of the cmn trace flag setting Information logged as a result of the ct trace flag setting XA Interface Integration Guide for CICS, Encina, and TUXEDO 21