XA-Server Integration Guide for TUXEDOusers.encs.concordia.ca/.../references/xatuxedo.pdf · • Documentation for BEA TUXEDO System/T, release 6.2 transaction processing monitor

XA-Server Integration Guidefor TUXEDO

XA-Server Release 11.1.1

Document ID: 35002-01-1111-01

Last Revised: May 30, 1997

Principal author: W.I.R.E.D. Information Products

Document ID: 35002-01-1111-01

This publication pertains to XA-Server Release 11.1.1 of the Sybase databasemanagement software and to any subsequent release until otherwise indicated innew editions or technical notes. Information in this document is subject to changewithout notice. The software described herein is furnished under a licenseagreement, and it may be used or copied only in accordance with the terms of thatagreement.

Document Orders

To order additional documents, U.S. and Canadian customers should callCustomer Fulfillment at (800) 685-8225, fax (617) 229-9845.

Customers in other countries with a U.S. license agreement may contact CustomerFulfillment via the above fax number. All other international customers shouldcontact their Sybase subsidiary or local distributor.

Upgrades are provided only at regularly scheduled software release dates.

Copyright © 1989–1997 by Sybase, Inc. All rights reserved.

No part of this publication may be reproduced, transmitted, or translated in anyform or by any means, electronic, mechanical, manual, optical, or otherwise,without the prior written permission of Sybase, Inc.

Sybase Trademarks

Sybase, the Sybase logo, APT-FORMS, Certified SYBASE Professional, DataWorkbench, Deft, First Impression, GainExposure, Gain Momentum, PowerBuilder,Powersoft, Replication Server, S-Designor, SQL Advantage, SQL Debug, SQLSMART, SQL Solutions, Transact-SQL, VisualWriter, and VQL are registeredtrademarks of Sybase, Inc. Adaptable Windowing Environment, Adaptive Server,ADA Workbench, AnswerBase, Application Manager, AppModeler, APT-Build,APT-Edit, APT-Execute, APT-Library, APT-Translator, APT Workbench, BackupServer, BayCam, Bit-Wise, Client-Library, Client/Server Architecture for theOnline Enterprise, Client/Server for the Real World, Client Services, CodeBank,Column Design, Connection Manager, DataArchitect, Database Analyzer,DataExpress, Data Pipeline, DataWindow, DB-Library, Deft Analyst, DeftDesigner, Deft Educational, Deft Professional, Deft Trial, Designor, DevelopersWorkbench, Dimensions Anywhere, Dimensions Enterprise, Dimensions Server,DirectCONNECT, Easy SQR, Embedded SQL, EMS, Enterprise Builder, EnterpriseClient/Server, Enterprise CONNECT, Enterprise Manager, Enterprise SQL ServerManager, Enterprise Work Architecture, Enterprise Work Designer, EnterpriseWork Modeler, EWA, Formula One, Gateway Manager, GeoPoint, InfoMaker,InformationCONNECT, Intermedia Server, InternetBuilder, iScript,KnowledgeBase, MainframeCONNECT, Maintenance Express, MAP, MDI, MDIAccess Server, MDI Database Gateway, media.splash, MetaWorks, MethodSet,Movedb, Navigation Server Manager, Net-Gateway, NetImpact, Net-Library, NewMedia Studio, ObjectCONNECT, ObjectCycle, OmniCONNECT, OmniSQL

Access Module, OmniSQL Server, OmniSQL Toolkit, Open Client, OpenClientCONNECT, Open Client/Server, Open Client/Server Interfaces, OpenGateway, Open Server, Open ServerCONNECT, Open Solutions, Optima++, PB-Gen, PC APT-Execute, PC DB-Net, PC Net Library, PowerBuilt, PowerBuilt withPowerBuilder, PowerScript, PowerSocket, Powersoft Portfolio, Power ThroughKnowledge, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst,esvReplication Agent, Replication Driver, Replication Server Manager, Report-Execute, Report Workbench, Resource Manager, RW-DisplayLib, RW-Library,SAFE, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS,smart.partners, smart.parts, smart.script, SQL Anywhere, SQL Central, SQL CodeChecker, SQL Edit, SQL Edit/TPU, SQL Remote, SQL Server, SQL Server/CFT,SQL Server/DBM, SQL Server Manager, SQL Server Monitor, SQL Server SNMPSubAgent, SQL Station, SQL Toolset, StarDesignor, Sybase Client/ServerInterfaces, Sybase Development Framework, Sybase Dimensions, SybaseGateways, Sybase Intermedia, Sybase Interplay, Sybase IQ, Sybase MPP, SybaseSQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase SynergyProgram, Sybase Virtual Server Architecture, Sybase User Workbench,SybaseWare, SyBooks, System 10, System 11, the System XI logo, SystemTools,Tabular Data Stream, The Architecture for Change, The Enterprise Client/ServerCompany, The Online Information Center, Turning Imagination Into Reality,Visual Components, VisualSpeller, Warehouse WORKS, Watcom, Watcom SQL,Watcom SQL Server, web.sql, WebSights, WebViewer, WorkGroup SQL Server,XA-Library, and XA-Server are trademarks of Sybase, Inc. 1/97

All other company and product names used herein may be trademarks orregistered trademarks of their respective companies.

Restricted Rights

Use, duplication, or disclosure by the government is subject to the restrictions setforth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forthin FAR 52.227-19(a)-(d) for civilian agencies.

Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.

XA-Server Integration Guide for TUXEDO v

Table of Contents

0. About This BookAudience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiRelated Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiOther Sources of Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Electronic Information Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiConventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivIf You Need Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

1. Introduction to the X/Open DTP ModelTransaction Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Overview of the X/Open DTP Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

The Functional Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Communication Between Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3X/Open DTP Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

2. XA-Server Overview and ConceptsModels for XA-Server and TUXEDO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

The Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2The TUXEDO TP Monitor and TM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2The Resource Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Open Client Client-Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4The Sybase XA Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

A Process Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6The Multiprocess Transaction Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7

Multiple Processes and Simultaneous Transactions . . . . . . . . . . . . . . . . . 2-7A DTP Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7

Scenario Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8Flow of Control for a Global Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 2-10

3. XA-Server Components, Files, and ConnectionsSybase XA Environment Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Relationships Between the Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

How the Files Are Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Configuration Files and LRMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

The Sybase Interfaces File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

vi Table of Contents


The Sybase xa_config File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4TUXEDO’s UBBCONFIG File and the Open String . . . . . . . . . . . . . . . . . . 3-9

4. Debugging ApplicationsState Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1The XA-Server Library Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2The XA-Server Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

5. Application Programming GuidelinesX/Open DTP Versus Traditional Sybase Transaction Processing . . . . . . . . . . . . . . . . 5-1Functionality Not Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2SQL Server User Names, Passwords, and Default Databases . . . . . . . . . . . . . . . . . . 5-2Transaction and Connection Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Connection Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

The Current Connection and Embedded SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4Getting a Client-Library Connection Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Changing Connection Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Synchronous and Asynchronous Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6Application Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

A. Heuristic Transaction Completion

Glossary

Index

XA-Server Integration Guide for TUXEDO vii

List of Figures

Figure 1-1: The X/Open DTP functional model ...........................................................................1-2Figure 2-1: Functional model of the Sybase XA implementation...............................................2-1Figure 2-2: The LRM: A logical connection to the server ............................................................2-3Figure 2-3: Process model of the Sybase XA implementation ....................................................2-6Figure 2-4: A DTP scenario ..............................................................................................................2-9Figure 2-5: Communication for a global transaction..................................................................2-11Figure 2-6: A three-node transaction in the prepare phase .......................................................2-16Figure 2-7: A network failure during rollback ............................................................................2-17Figure 3-1: Relationships between the configuration files and the application .......................3-2Figure 3-2: A sample interfaces file ..................................................................................................3-4Figure 3-3: A sample xa_config file ..................................................................................................3-5Figure 4-1: XA state diagram ...........................................................................................................4-2Figure 4-2: An excerpt from an XA-Server Library log file .........................................................4-3Figure 4-3: An excerpt from an XA-Server log file .......................................................................4-8

viii List of Figures


XA-Server Integration Guide for TUXEDO ix

List of Tables

Table 3-1: xa_config file components .............................................................................................3-6Table 3-2: XA-Server valid capabilities.........................................................................................3-7Table 3-3: XA-Server valid properties...........................................................................................3-8Table 3-4: XA-Server valid options ...............................................................................................3-8Table 5-1: Traditional TP and X/Open DTP model differences................................................5-1Table 5-2: Invalid commands.........................................................................................................5-3

x List of Tables


XA-Server Integration Guide for TUXEDO xi

About This Book 0.

The XA-Server Integration Guide for TUXEDO is a reference guide thathelps you build an XA-Server environment using BEA TUXEDOTransaction Processing Monitor. This guide supplies conceptualinformation about the XA-Server environment, installation andintegration instructions, and programming guidelines.

Audience

The XA-Server Integration Guide for TUXEDO is primarily intendedfor:

• Application developers using Embedded SQL™ or OpenClient™ Client-Library to communicate with Sybase SQL Serverin a TUXEDO environment.

• System administrators who set up Sybase XA-Servers for usewith BEA TUXEDO.

The secondary audiences for this guide are:

• Project managers who schedule and allocate resources for an XA-Server project.

• Other members of an XA-Server team who may not need athorough understanding of development aspects, but do need tounderstand general technical concepts and the tasks involved.

This guide assumes that the primary audience has substantialknowledge of:

• The X/Open Distributed Transaction Processing (DTP) Model

• Open Client Client-Library

‘‘Related Documents’’ on page xii lists references for moreinformation on these topics.

How to Use This Book

This guide contains the following chapters:

• Chapter 1, “Introduction to the X/Open DTP Model,” provides afoundation for the rest of the guide. It introduces andsummarizes the key concepts of the X/Open DTP model.

xii About This Book

Related Documents XA-Server Release 11.1.1

• Chapter 2, “XA-Server Overview and Concepts,” describesconcepts specific to XA-Server and provides a simple scenario toillustrate these components with a simple scenario.

• Chapter 3, “XA-Server Components, Files, and Connections,”supplies practical background information for the configurationprocedure and programming issues.

• Chapter 4, “Debugging Applications,” introduces debuggingtools and provides some information for using them.

• Chapter 5, “Application Programming Guidelines,” describesprogramming practices you must follow to create successfulTUXEDO applications that use Sybase SQL Server.

Appendix A, “Heuristic Transaction Completion,” describes systemstored procedures used to complete transactions manually.

The Glossary contains definitions for the key terms and acronymsused in this guide.

Related Documents

This guide refers to procedures in:

• The Open Client/Server Installation Guide for your platform forinstallation instructions.

• The Open Client/Server Supplement for your platform for advancedconfiguration topics.

You should also be familiar with the information in the followingdocuments:

• X/Open CAE Specification (December 1991) Distributed TransactionProcessing: The XA Specification

• X/Open Guide (October 1991) Distributed Transaction ProcessingReference Model

• Open Client Embedded SQL/COBOL Programmer’s Guide or OpenClient Embedded SQL/C Programmer’s Guide

• Open Client Embedded SQL Reference Manual

• Open Client Client-Library/C Reference Manual

• Open Client Client-Library/C Programmer’s Guide

• SYBASE System Administration Guide

• Documentation for BEA TUXEDO System/T, release 6.2transaction processing monitor.

XA-Server Integration Guide for TUXEDO xiii

XA-Server Release 11.1.1 Other Sources of Information

For additional information about transaction processing see:

• Transaction Processing: Concepts and Techniques. Gray, Jim andAndreas Reuter. (1993). San Mateo, CA: Morgan KaufmannPublishers, Inc.

Other Sources of Information

Electronic Information Sources

For the most up-to-date information on Sybase products, includinginformation on availability, certifications, bugs, and troubleshooting,refer to Sybase’s electronic services:

• AnswerBase™, Sybase’s CD-ROM knowledge base

• Sybase OpenLine and PrivateLine, the Sybase forums onCompuServe

• The SupportPlusSM Online Services and SyBooks-on-the-WebWorld Wide Web pages

SupportPlus Online Services and SyBooks-on-the-Web

To get to SupportPlus Online Services and Sybooks-on-the-Web:

1. Connect to the Sybase home page: www.sybase.com.

2. Follow links to Services and Support.

3. Follow links to Sybase Enterprise Technical Support.

4. Follow links to SupportPlus Online Services or SyBooks-on-the-Web.

SyBooks-on-the-Web is accessible to the public.

SupportPlus Online Services is intended for customer use only.Therefore, you must register to access SupportPlus Online Services.

Conventions

This section describes the font style and naming conventions used inthis guide.

• In all examples and syntax statements, each clause of a statementbegins on a new line. Clauses that have more than one partextend to additional lines, which are indented.

xiv About This Book

Conventions XA-Server Release 11.1.1

• Constant width type indicates keywords you enter exactly asshown.

• Italic type indicates syntax elements that you supply. In thefollowing example, connection_name, sql_server_name, andxa_server_name represent user-supplied identifiers:

[xa]lrm= connection_nameserver= sql_server_namexaserver= xa_server_name

• Square brackets indicate that a word, phrase, or item is optional.The following example shows a series of optional command-lineitems:

$SYBASE/bin/xaserver [-S xa_server_name ] [-L logfile_name ][-M maxuser ] [-Txa] [-Ttds] [-Tinternal] [-J char_set ][-z language ] [-v] [-help]

• Ellipses (...) mean that you can repeat the item that precedes themas many times as necessary. In the following example, you can listone or more trace flags in the SYBASE open string:

-Uusername -Ppassword -Nlrm_name -Llogfile -Ttrace_flag[, -T trace_flag]...

• The word “tab” within angle brackets (<tab>) indicates a tabcharacter. In the following example, you would replace the wordtab and the angle brackets with a tab character:

xa_server_name<tab> interface_type network_protocol device_address

• A Note calls out important information. For example:

➤ NoteBecause XA manages connections, you should specify capabilities,

properties, and options in the xa_config file before establishing a

connection.

• A Warning alerts you to the possibility of an action that coulddamage a file, result in the loss of data, or cause the system to fail.For example:

XA-Server Integration Guide for TUXEDO xv

XA-Server Release 11.1.1 If You Need Help

◆ WARNING!Create a new directory for the XA-Server installation. Installing XA-Server in an existing SYBASE directory will overwrite files.

If You Need Help

Each Sybase installation that has purchased a support contract hasone or more designated people who are authorized to contact SybaseTechnical Support. If you cannot resolve a problem using themanuals or online help, ask a designated person at your site tocontact Sybase Technical Support.

xvi About This Book

If You Need Help XA-Server Release 11.1.1

XA-Server Integration Guide for TUXEDO 1-1

1 Introduction to the X/Open DTPModel 1.

This chapter provides a foundation for the rest of the guide. Itsummarizes the key concepts of X/Open’s DTP model, an industrystandard for distributed transaction processing applications.

This chapter contains these topics:

• Transaction Processing 1-1

• Overview of the X/Open DTP Model 1-2

If you are already familiar with these topics, go to Chapter 2, “XA-Server Overview and Concepts”.”

Transaction Processing

Transaction processing is a way to for coordinate businesstransactions that modify databases. Transaction processing keeps arunning log of all the modifications made to a database over a periodof time. It is useful for databases that are constantly modified, such asbank accounts, to ensure that the data modifications are properlystored. If an error occurs or the system crashes while modificationsare being made, the log can be used to restore the database to aprevious error-free state.

In distributed transaction processing, shared resources, such asdatabases, files, and printers, are located at different physical sites onthe network or internetwork.

A transaction processing monitor (TP monitor) helps to facilitatedistributed transaction processing by supplying functions that areoften missing from a UNIX operating system. These functions mightinclude:

• Naming services

• Security at the transaction level

• Recovery coordination and services

• Fault tolerance features, such as failover redirection andtransaction mirroring

• Presentation services

• Load balancing

1-2


Overview of the X/Open DTP Model

The X/Open DTP model is a standard for distributed transactionprocessing software in which shared resources are located atdifferent sites on a network. It allows multiple application programsto share these resources, and allows work to be coordinated intoglobal transactions.

Figure 1-1 shows the X/Open DTP functional model’s basiccomponents and their interactions. The model identifies three keycomponents in a distributed transaction processing environment: theapplication program (AP), the resource managers (RM), and thetransaction manager (TM). The model constitutes a standard for thecomponents’ roles and interactions. Components communicatethrough the native, XA, and TX interfaces as described in“Communication Between Components” on page 1-3.

Figure 1-1: The X/Open DTP functional model

As the model shows, the application interacts with the native and TXinterfaces, but not with the XA interface. Understanding DTParchitecture is not essential for writing application programs, but itcan help you write more effective software for the XA environmentand can provide a background for understanding programmingissues.

RM

AP

TM

Native

XA

TXInterface Interface

Interface



The Functional Components

The major software components work together to accomplishtransactional tasks for the application as follows:

• The application program includes software to perform aparticular business transaction or part of one. It designatestransaction boundaries by identifying the beginning and end ofglobal transactions.

• The resource manager provides access to shared resources suchas database servers, file servers, and print servers. In a typicalX/Open DTP environment, a single application programcommunicates with more than one resource manager. In the XA-Server environment, at least one of the resource managers is aSybase SQL Server™.

• The transaction manager helps a software application access andmanage a variety of resources including database systems. Thetransaction manager provides transaction coordinationcapability for the TP monitor. It manages the transaction withinthe boundaries that the application program establishes. That is,the transaction manager assures that the application program’swork is contained in a global transaction that commits or abortsatomically. The transaction manager accomplishes this task byinforming the resource manager, through the XA interface, oftransaction events.

Specifically, the transaction manager’s tasks include:

- Assigning global identifiers to transactions

- Monitoring the progress of global transactions

- Coordinating the flow of transaction information between theapplication program(s) and the resource managers

- Managing the transaction commitment protocol and failurerecovery

Communication Between Components

The application program, the resource manager, and the transactionmanager communicate through three interfaces, as shown in Figure1-1:

• The native interface is the application programming interface(API) between the application and the resource manager.

1-4


• The TX interface is the X/Open-defined API between theapplication and the transaction manager. The applicationprogram uses TX calls to delineate transaction boundaries byrequesting that the transaction manager start and commit or rollback global transactions.

• The XA interface is an X/Open-defined system-level interfaceused for communication between the resource manager and thetransaction manager. Using XA calls, the transaction managertells the resource manager when transactions begin, commit, androll back.

X/Open DTP Behavior

The three components—the application program, the resourcemanager, and the transaction manager, work together to processtransactions from initiation through completion. Transactions aregoverned by the ACID (Atomicity, Consistency, Isolation, andDurability) test, and the components must function together toadhere to its rules. To pass the ACID test, a transaction must exhibitthe following properties:

• Atomicity – All portions of the transaction either succeed and arecommitted or they are rolled back and have no effect.

• Consistency – If a transaction is rolled back, all resources that thetransaction affected return to the state they were in before thetransaction took place.

• Isolation – Although transactions may run concurrently, eachtransaction’s dependencies will be before, after, or independentof another transaction’s dependencies.

• Durability – After a transaction commits, all the affectedresources are permanent and cannot be altered by subsequentsystem failures.

Initiating the Transaction

During transaction initiation, the application program delimitstransaction boundaries. Using TX calls (or TUXEDO TP calls), anapplication program informs the transaction manager that a globaltransaction is beginning. The transaction manager thencommunicates with all available resource managers, using XA calls,to associate a single transaction identifier with any work the resourcemanagers do on behalf of the application program.



Committing the Transaction

When the application program requests that the transaction managercommit the global transaction, the transaction manager and theresource managers use the two-phase commit protocol to guaranteetransaction atomicity.

The Two-Phase Commit Protocol

Problems can arise when a transaction attempts to modify more thanone resource and one of those attempts fails. When a failure occurs,all resources must be restored to the states they were in before thetransaction began to meet the conditions of the ACID test.

During transaction completion, the two-phase commit protocolensures integrity and consistency for all protected resources affectedby a distributed transaction. Transaction completion takes place intwo phases, as follows:

• In the prepare phase, the transaction manager requests that eachresource manager prepare to commit its portion of the globaltransaction.

• In the commit phase, the transaction manager instructs theresource managers to commit or abort their branches of thetransaction. If all resource managers report that they haveprepared their respective transaction branches, the transactionmanager commits the entire transaction. If any resource managerreports that it failed or does not respond, the transaction managerrolls back the entire transaction.

Recovery

If any branch of the transaction fails, the entire transaction must berolled back. This is referred to as global recovery.

The transaction manager has all the information it needs tocoordinate global recovery. However, the transaction manager canblock all the resources involved in a transaction, making themunavailable, while it waits for the impaired resource to be restored.

If it is unacceptable to wait for the entire system to recover, adatabase administrator may be able to perform a heuristiccompletion, manually running programs to complete a transactionbranch independent of the transaction manager.

The risk in performing a heuristic completion for a branch is that theglobal transaction may fail to maintain consistency. That is, the

1-6


decision made by the database administrator may be in conflict withthe decision the transaction manager makes when the system finallydoes recover. For example, the database administrator may haveinstructed the affected resource manager to commit its transactionbranch and later the resource manager receives a request from thetransaction manager to roll it back. If this happens, the transactionmanager reports a mixed heuristic condition or a transaction hazardwarning.

Such conflicts require manual intervention to complete the globaltransaction atomically.


2 XA-Server Overview and Concepts 2.

XA-Server is Sybase’s X/Open-compliant XA implementation. Thischapter introduces XA-Server architecture and concepts that arespecific to the XA-Server environment.

This chapter contains these topics:

• Models for XA-Server and TUXEDO 2-1

• A Process Model 2-6

• The Multiprocess Transaction Environment 2-7

• A DTP Scenario 2-7

Models for XA-Server and TUXEDO

Figure 2-1 shows a simple functional model of the Sybaseimplementation for the XA-Server and TUXEDO environment.

Figure 2-1: Functional model of the Sybase XA implementation

This section discusses each aspect of the XA-Server and TUXEDOfunctional model.

Client Application

Client-Library

XA

TXInterface

InterfaceTM

TUXEDOResource Manager

XA-Server Library

2-2


The Application

Applications that involve distributed transactions coordinated bytransaction processing monitors are often referred to as three-tierapplications. Each tier has specific responsibilities:

• The first tier provides support for presentation services on theclient system. Minimally, it includes support for windowingsystems to display and manipulate data. This tier might alsoprovide local validation of user input.

• The second tier provides support for distributed queryoptimization, enforcement of business rules, and referentialintegrity across all components of the third tier, global distributedtransaction management, and service mapping similar to agateway application.

• The third tier is a resource manager responsible for data integrityand local transaction branches. It has local responsibility forcontrolled resources.

Applications can use Sybase Client-Library APIs for most databasework, such as creating, deleting, and updating. TUXEDO establishesconnections and commits and rolls back operations for theapplication through the XA interface. The application program nevercalls XA directly.

The TUXEDO TP Monitor and TM

The X/Open DTP model defines specific behavior for the transactionmanager (TM), but does not limit the transaction monitor’s functionas long as it contains transaction manager capabilities. In fact, DTPsystems often employ a transaction-processing monitor (TPmonitor), which, in this case, is TUXEDO.

TUXEDO contains transaction manager capabilities as part of itsgreater functionality. TUXEDO offers presentation services, basicDTP, security and messaging services, and load balancing amongother functions.

The Resource Manager

In the XA-Server environment, at least one of the resource managersis a Sybase SQL Server.



The LRM

The Sybase resource manager includes a construct for establishingconnections, the Logical Resource Manager (LRM).

The X/Open DTP model does not recognize connections. Yet,connections are central to Sybase Open Client and Open Serverarchitecture. The Sybase XA implementation resolves thisdiscrepancy with the LRM, a logical connection to a SQL Serverthrough Client-Library and XA-Server, as shown in Figure 2-2.

LRMs associate names with client-to-server connections; thus theclient application uses LRMs to identify connections to SQL Server.Because the transaction manager issues an open call for each LRM,each LRM name implies a different connection. The work done ontwo different connections can be in two different transactions or inthe same transaction.

For programmers familiar with the Sybase programmingenvironment, important differences are that in XA, applications donot perform transaction demarcation or connection management;the XA-Server does both using LRMs to facilitate connectionmanagement.

Figure 2-2: The LRM: A logical connection to the server

XA-Server

Client Application

Client-Library

LRM

SQL Server

2-4


The LRM construct provides the following:

• Associated capabilities, properties, and options.

• Its own user name and password.

Open Client Client-Library

Open Client Client-Library (or simply Client-Library) is the nativeinterface in this environment. Client-Library is a member of a familyof Sybase software products for application programmers whodevelop client/server applications. It consists of routines that sendcommands to a server and routines that process the results returned.Other routines set application properties, handle error conditions,and provide a variety of information about an application’sinteraction with a server.

These Sybase Open Client Client-Library manuals provide moreinformation:

• The Open Client/Server Installation Guide for your platform forinstallation instructions

• The Open Client/Server Supplement for your platform for advancedconfiguration topics.

• Open Client Embedded SQL/COBOL Programmer’s Guide or OpenClient Embedded SQL/C Programmer’s Guide

• Open Client Embedded SQL Reference Manual

• Open Client Client-Library/C Reference Manual

• Open Client Client-Library/C Programmer’s Guide

The Sybase XA Implementation

Sybase XA implementation includes XA-Server Library and XA-Server.

The XA-Server Library

XA-Server Library is a client interface library that contains an entrypoint for each XA call defined in the XA specification. These entrypoints provide a simple access layer to the XA-Server process.



The XA-Server

XA-Server is a local or remote Open Server application that functionsas the back end for the XA implementation. All XA-related workpasses through the XA-Server process.

XA-Server coordinates remote requests for access to XA transactionbranches, enforcing the semantics of the XA protocol. Itcommunicates directly with the resource manager and TP Monitor tospecify and consolidate work for each transaction. For example, theresource manager communicates to specify the SQL Server and thetransaction boundaries. (The application originates this information,which is passed through the XA interface from the transactionmanager). The TP monitor communicates the prepare and commitinformation.

Internally, XA-Server manages a set of connections to one or moreSQL Servers using transaction IDs. The connections follow statetransitions as defined by the XA specification.

An important aspect of this DTP architecture is that it allows the TPmonitor to migrate transactions across both local and remoteoperating system processes.

2-6


A Process Model

Figure 2-3 is a process-level overview of a TUXEDO application andthe components within it. The figure shows how the componentsinteract.

Figure 2-3: Process model of the Sybase XA implementation

TUXEDO Client Process

Client Application

TM (TUXEDO Libraries)

TUXEDO Server Process

Application Service

RM (Client Library)

XA-Server Library

TM(TUXEDO Libraries)

XA-Server

SQL-SRV

TUXEDO TMS Process

RM (Client Library)

XA-Server Library

TM(TUXEDO Libraries)

TMS



The TUXEDO application servers include the application software,Sybase Client-Library and XA-Server Library, and the TUXEDOlibraries.

The TUXEDO TP monitor server (TMS) process links with XA-ServerLibrary to communicate with the XA-Server. The TMS process workswith the TUXEDO application process to accomplish comprehensivetransaction processing with the XA-Server.

Procedures and commands in Chapter 4 describe in detail howapplication processes link with the libraries.

The Multiprocess Transaction Environment

A single process transaction confines work to one process.Multiprocess transactions are possible when a single transactionconsists of many branches contained in many separate processes.

TP monitors that allow transactions to migrate across processesrequire a multiprocess interpretation of the X/Open DTP model inwhich an application can take full advantage of a multiprocessing TPmonitor’s capabilities. The TUXEDO System is an example of such aTP monitor.

Multiple Processes and Simultaneous Transactions

XA-Server works with the TUXEDO TP monitor to enableapplication program threads to share information across transactionbranches that span processes. This makes it possible for oneapplication program thread to initiate a transaction and anotherapplication thread to terminate it, while still other threads canperform intermediate operations that constitute work for thetransaction.

The TP monitor manages and controls the transaction as a unit. XA-Server keeps track of client requests, multiplexes access to SQLServers, and delivers services to the clients that request them.

A DTP Scenario

The following section uses an example scenario to tie together thechapter’s concepts and introduce a few new ones. The section coversconcepts rather than programming issues.

2-8


Scenario Description

Assume that a bank stores the savings account table for all itscustomers in a central office in Geneva. A checking account table isstored at the check processing center in New York. A money-transfertransaction that debits the savings account in Geneva (GVAServer)and credits the checking account in New York (NYCServer) dealswith two physically remote databases and resource managers.

Figure 2-4 depicts the scenario.



Figure 2-4: A DTP scenario

The teller’s interactions with the terminal prompt the client processto begin the transfer transaction.

This example illustrates how a global transaction can involve morethan one resource manager and span more than one physicallocation—multiple independent databases. However, all the work,

TP Monitor

XA-Server

TM

XA-Server

Connection_1

Client

GVAServer NYCServer

Checking DBSavings DB

Begin TransactionRequest 1Request 2

Commit Transaction

Client

Connection_2

TUXEDO

Client Application

TUXEDO

Server 1

TUXEDO

Server 2

2-10


even if it is performed on different resources, is treated as a singleunit of work—the transfer transaction.

Flow of Control for a Global Transaction

This section provides more information about what takes place in theX/Open DTP system as a whole for the banking scenario.

Figure 2-5 illustrates the communication and flow of control betweenthe applications (TUXEDO client and servers), the transactionmanager, and the resource managers throughout the life of thetransaction. Arrows indicate synchronous calls at the TX and XAinterfaces. The figure uses function names published in the formalspecifications.

TX API functions are prefixed with “tx_”. TUXEDO provides “tx_”functions and also implements corresponding functions with itsATMI. The discussion on following pages uses TX functions for thesake of a more general discussion about X/Open DTP software. XAAPI functions have the “xa_” prefix.

For more information about XA functions, see the X/Open CAESpecification’s Distributed Transaction Processing: The XA Specification.For more information about TUXEDO functions, see the TUXEDOReference.



Figure 2-5: Communication for a global transaction

tx_open

tx_ok

tx_okxa_ok

xa_commit

xa_ok

xa_prepare

xa_ok

xa_end

xa_ok

xa_start

xa_ok

xa_open

TM

TX

Initiate

Work

TerminateTransaction

RM2RM1

XA

SQL data

Start Up

Transaction

tx_close

tx_ok xa_ok

xa_closeShut Down

(Two-phasecommit)

Time

tx_open

tx_ok

tx_begin

tx_ok

tx_begin

tx_ok

tx_commit

tx_commit

tx_ok

tx_ok

tx_close

tx_ok

TUXEDO Client Appl.

Server 1 Server 2

TUXEDO

TUXEDO Client Appl.

2-12


The application uses the transaction manager’s services tocoordinate the global transaction, which consists of initiation, work,and termination.

Starting the Application Program Process

Before the application can initiate a transaction, it must make itselfknown to the transaction manager and define the resources itrequires. The sub-application processes do this using a tx_open callonce before starting any transactions. This call prompts thetransaction manager to issue xa_open calls for each LRM establishedin the configuration files (described in Chapter ), and initializes theresource managers and prepares them for use in a DTP environment.

The transaction manager also sets up logging capabilities, generatesan rmid corresponding to each LRM name, and performs otherinitialization tasks. The rmid, with other values, is used to establish aconnection to the server and transactional context, a way to associate allthe work that belongs to a particular transaction with thattransaction.

After the resource managers acknowledge that they have fulfilledthe transaction manager’s request (using xa_ok) the transactionmanager issues a tx_ok back to the sub-application processes,indicating that the resource managers are ready.

Initiating the Transaction

The application initiates the transaction using tx_begin. Thetransaction manager coordinates the resource managers fortransaction initiation using xa_start calls. The transaction manageracknowledges the start of the transaction with tx_ok and passescontrol back to the application.

Transactional Work

Sub-application processes perform useful work for the transactionby issuing commands directly to the resource managers. For thislong-distance banking example, the transaction first subtracts theamount from the savings account and then adds the same amount tothe checking account. Embedded SQL in the Sybase XA environmentcould look like this:



TUXEDO Server 1

exec sql at connection_1update SAVINGSset SAV_AMOUNT = SAV_AMOUNT - amountwhere ACCT_NO = account_no;

TUXEDO Server 2

exec sql at connection_2update CHECKINGset CHK_AMOUNT = CHK_AMOUNT + amountwhere ACCT_NO = account_no;

Note that the LRM logical connection construct means that you onlyhave to specify the table attribute and not the fully qualified name.For example, you can use statements such as update SAVINGS ratherthan update GVASERVER.BANKDB.JOE.SAVINGS (where JOE is the userid).

Maintaining Transactional Context

Transactional context identifies the branches of a transaction asbelonging to a specific transaction. Throughout the globaltransaction, transactional context is preserved through theconnection itself. Anything that goes over the connection is withinthe context of the transaction. This makes it possible for theapplication to communicate directly with the resource manager andto keep work done for a particular transaction associated with thattransaction.

In the example above, the at connection_name clause identifies thecontext.“The Current Connection and Embedded SQL” on page 5-4discusses this in more detail.

Terminating the Transaction

After all the work associated with the transaction is done, theapplication declares the end of the transaction using tx_commit. Thisinitiates the two-phase commit sequence between the transactionmanager and the RMs.

First, the transaction manager issues an xa_end to each RM to indicatethe end (or suspension) of the work performed on transactionbranches. The two xa_end calls are asynchronous with each other.Whether the calls themselves are synchronous or asynchronous is TPmonitor dependent.

2-14


The transaction manager then issues xa_prepare to request that theresource manager prepare to commit any work performed for thetransaction. Each resource manager places any resources it modifiedin such a state that it can make the results permanent when it receivesthe commit request. If any branch of the transaction fails, xa_preparereturns an error and any held changes to resources are rolled back. Inthe example, the transaction commits only if both of the actions(withdrawing from the savings account and depositing in thechecking account) are successful. If either action fails, the transactionis rolled back so that all shared resources (databases) are in the statethey were in before the transaction began.

If the results from xa_prepare are successful, the transaction managerissues xa_commit to commit the work done on behalf of a transactionbranch. Any changes made to the resources held during thetransaction are made permanent. In the example, GVAServersubtracts the amount from the savings account table, and NYCServeradds the amount to the checking account table.

Recovery: Transaction Rollback

If any branch of the transaction fails, the entire transaction is rolledback.

The two-phase commit algorithm has a narrow definition of failurefor prepare processing; any work done prior to the prepare phase isrolled back if there is a single failure.

Coordinating the Recovery

The TP monitor has all the information required to coordinate anatomic recovery at any state of the transaction. During some states,XA-Server and SQL Server also participate in recovery.

When the database recovers from a failure, XA-Server checks thestatus of transactions. Transactions may be active, prepared, orcommitted. There may be no record of the transaction. XA-Servertakes action depending on the status of the transaction:

• If there is no record for the transaction, the XA-Server and SQLServer roll back the work.

• If the roll back transaction is active, it implies that the transactionhas not yet been prepared, so it can still be rolled back. XA-Serverhas the information and ability to coordinate the recovery of SQLServer’s work because, if a resource has not acknowledged that it



is prepared, it has not committed work for the transaction and socan still roll work back.

• If the record indicates that the transaction is in the prepare state,the XA-Server involved with one branch does not know what theoutcome for other branches is. If a failure occurs at this point,only the TP monitor can coordinate an atomic outcome, so thesystem must wait until it is available.

• If the record indicates that the transaction is in the commit state,at least one branch has been committed. Others are in the processof committing or are being instructed to commit. The XA-Serverand SQL Server will commit the work.

Failure During the Prepare Phase

More complicated recovery scenarios pertain to transactions that failin the prepare phase when the TP Monitor system fails but thedatabase server and database are still available.

If one or more transactions under the transaction manager’s controlare in the prepare phase, the work associated with those transactionscannot be committed atomically until the transaction managersystem is available again. There are probably locks held anduncommitted updates, or updates that need to be rolled back.

The easiest thing to do is to wait for the transaction manager tobecome available and let it coordinate the recovery after the systemadministrator brings up the application and servers. However, if it isunacceptable to wait, XA-Server supplies two stored procedures toassist in a heuristic completion.

The stored procedures are sp_xa_scan_xact and sp_xa_finish_xact.sp_xa_scan_xact supplies a list of the transaction identifiers. Afterrunning sp_xa_scan_xact, use sp_xa_finish_xact with a transactionidentifier and a state (either commit or abort) to force the branch tocomplete. Appendix A discusses these stored procedures in moredetail.

Heuristic completion requires that the person using the storedprocedures analyze the software and, based on its state, takeresponsibility for committing or aborting the branches. The risk isthat you could commit a transaction that should have been rolledback or rollback a transaction that should have been committed. Ifthis occurs, when the transaction manager is available again it willreport a mixed heuristic condition or a transaction hazard warning.The database administrator must determine all affected resourcesand correct them.

2-16


Example: A Three-node Transaction

This illustrates a scenario that arises in a DTP environment when onebranch in a global transaction fails. Suppose that the transactionmanager is coordinating a three-node transaction as shown in Figure2-6.

Figure 2-6: A three-node transaction in the prepare phase

The transaction manager issues the prepare command. Branch 1 andBranch 2 prepare to commit their work and issue the OK response,but Branch 3 cannot prepare for some reason. The transactionmanager issues a rollback command to Branch 1 and Branch 2, but,while the transaction manager is sending the rollback commands,there is a network failure that affects branch 2. Branch 1 receives therollback command, but Branch 2 does not.

Branch 1 Branch 2 Branch 3

TMPrepare

OK

Prepare

OK

Prepare

PrepareCan’t



Branch 2 has its work prepared. Branch 1 and Branch 3 have rolledtheir work back as shown in Figure 2-7.

Figure 2-7: A network failure during rollback

If Branch 2 is in a physically separate system, as this exampleassumes, then work for Branch 2 is frozen.

The bank manager might decide that they can not afford to wait forBranch 2’s resources to become available to the transaction manager.So the bank manager makes an independent decision to commit orabort the transaction heuristically.

Later, the network is fixed and the transaction manager tries toresume the suspended transaction. It sees that a completion wasperformed and that the completion status is different from what itwould have assigned. The transaction manager reports a transactionhazard warning to alert the database administrator that there couldbe data inconsistencies.

The database administer must review all the work that was doneafter the heuristically completed transaction and fix inconsistenciesbased on the outcome dictated by the transaction manager.

Shutting Down the Application Process

The application issues tx_close telling the transaction manager that itis closing and no longer needs the services of a resource manager.

Branch 1 Branch 2 Branch 3

TM

Rolled Back Prepared Rolled Back

Central Branch

2-18



3 XA-Server Components, Files, andConnections 3.

This chapter contains:

• Sybase XA Environment Components 3-1

• Relationships Between the Components 3-1

• Configuration Files and LRMs 3-3

Sybase XA Environment Components

The Sybase XA environment consists of these software componentsand configuration files:

• The XA interface, consisting of XA-Server and theXA-Server Library

• 11.0 or later SQL Server

• A set of XA-specific SQL Server stored procedures that systemadministrators can use to manage heuristic transactions

• 11.1 or later Open Client Client-Library, the native interfacebetween the application and the SQL Servers

• 11.1 Embedded SQL with C or COBOL calls can be part of thenative interface between the application and the resourcemanagers. (Embedded SQL must be purchased separately fromthe XA-Server product.)

• The XA configuration file, xa_config, which contains entries thatdefine client-server connections for use in the XA environment

• The interfaces file, interfaces, which identifies XA-Servers andSQL Servers to the Sybase system

• TUXEDO’s configuration file, UBBCONFIG, which integrates theTUXEDO system

Chapter 4, “Debugging Applications”, explains how to install,configure, and integrate these components.

Relationships Between the Components

Figure 3-1 shows the relationship between the configuration files andthe application.

3-2


Figure 3-1: Relationships between the configuration files and the application

*GROUPSDEFAULT:BANKB1 TMSNAME=sybxatm TMSCOUNT=2 LMID=SITE1 GRPNO=1

OPENINFO="SYBASE_XA_SERVER: -Ubankus1 \-Pbankpw -N Syb_lrm1 -L/tmp/xa_log -Tall"

interfaces File

UBBCONFIG File

Application Program

SybSQL_1query tli tcp /dev/tcp \x00020eb782d65a4dmaster tli tcp /dev/tcp \x00020eb782d65a4d

SybaseXA_1query tli tcp /dev/tcp \x00020eb782d65a3amaster tli tcp /dev/tcp \x00020eb782d65a3a

xa_config File

; NOTE: First line must be a comment line!!!

; lrm - Names the logical connection as seen; by the application and the TM.

; server - Names the physical server as found in; the SYBASE interfaces file.

; xaserver - Names the physical XA-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).

; options - Lists pre-connection options; to be set(optional).

[xa]lrm=Syb_lrm1server=SybSQL_1xaserver=SybaseXA_1

[xa]lrm=Syb_lrm2server=SybSQL_1xaserver=SybaseXA_1

/* Begin a transaction */status = tx_begin();if (status != TX_OK) {

printf("tx_begin failed, status = %d\n", status);tx_close(); /* unconditionally close tx */exit(status);

}conn = get_conn(" Syb_lrm1 ");if (conn == NULL)

EXIT_ERR("get_conn failed");



The xa_config file defines the connections as LRM names. TheUBBCONFIG file and the application use this definition.

The interfaces file establishes the existence of the SQL Server and theXA-Server, which the xa_config file associates with the LRM.

The next section, “Configuration Files and LRMs” on page 3-3,discusses the contents of these files in detail.

How the Files Are Used

The following steps outline how the XA environment uses theconfiguration files to establish connections between applications andSQL Servers. Refer to Figure 3-1 while reading the steps.

1. The application uses the LRM specified in the UBBCONFIG fileto reference the logical connection for a branch of a globaltransaction. In using the LRM name, the application implicitlyrequests and establishes an LRM.

2. The transaction manager passes the appropriate open string tothe XA-Server through the LRM whose name matches the oneissued in step 1. The XA-Server uses the LRM name, the username, and the password.

3. The XA-Server looks in the xa_config file to find an associationbetween the LRM name and SQL Server. The SQL Server namematches an entry in the interfaces file where its networkinformation is kept.

4. The XA-Server establishes one logical connection to a SQLServer for each LRM entry. The XA-Server applies theconnection properties and capabilities configured for the LRM inthe xa_config file.

Configuration Files and LRMs

This section describes configuration file contents and formats.

The Sybase Interfaces File

The interfaces file contains network information for clients andservers. It has entries for all servers that a client might connect to. Itacts as an address directory for the clients, and servers use it todetermine where to listen for client queries. Every XA-Server andSQL Server must have an entry in the interfaces file.

3-4


Figure 3-2 shows a sample interfaces file in which there are two XA-Servers, SybaseXA_1 and SybaseXA_2, and two SQL Servers,SybSQL_1 and SybSQL_2.

Figure 3-2: A sample interfaces file

The Sybase xa_config File

As described in Chapter 2, LRMs associate a name with aclient/server connection. The xa_config file is where the symbolicnames for client/server connections are set up. It contains one entryper LRM. The entry associates the LRM with an XA-Server name anda SQL Server name, and assigns Client-Library capabilities andproperties to the LRM.

SybSQL_1query tli tcp /dev/tcp \x00020eb782d65a4dmaster tli tcp /dev/tcp \x00020eb782d65a4d

SybaseXA_1query tli tcp /dev/tcp \x00020eb782d65a3amaster tli tcp /dev/tcp \x00020eb782d65a3a

SybSQL_2query tli tcp /dev/tcp \x00020eb782d65a47master tli tcp /dev/tcp \x00020eb782d65a47

SybaseXA_2master tli tcp /dev/tcp \x00020d4782d65a26query tli tcp /dev/tcp \x00020d4782d65a26



Figure 3-3 shows a sample configuration file for the system depictedin the block diagram. It contains descriptions of three LRMs, eachdelimited by an [xa] character string. The fields are defined below.

Figure 3-3: A sample xa_config file

XA-Configuration File Components

xa_config file entries have the following general format:

[xa]<tab> lrm= connection_name<tab> server= sql_server_name<tab> xaserver= xa_server_name<tab> capabilities= capabilities…<tab> properties= properties…<tab> options= options…

SybSQL_1 SybSQL_2

; The first line of this file MUST be a; comment, which is denoted with the semicolon; in the first character position.[xa]

lrm=Syb_lrm_name_1server=SybSQL_1xaserver=SybaseXA_1

[xa]lrm=Syb_lrm_name_2server=SybSQL_1xaserver=SybaseXA_1

[xa]lrm=Syb_lrm_name_3server=SybSQL_2xaserver=SybaseXA_2

AP1

SybaseXA_1

Syb_lrm_name_3

SybaseXA_2

Syb_lrm_name_1 Syb_lrm_name_2

AP2 AP3

AP

3-6


There are six components for each LRM description in the xa_configfile.

The fields are described in Chapter 3, “xa_config file components”:

➤ NoteBecause XA manages connections, you must specify any capabilities or

properties that an application uses by adding them to the xa_config file

before the application attempts to establish a connection.

XA-Configuration File Syntax

The xa_config file has the following syntax restrictions:

• The file is case sensitive.

• White space created using tab and space keys is ignored.

• lrm, server, xaserver, capabilities, properties, and options arekeywords. Each must begin on its own line.

• Capability assignments take the form capability=value.

• Property assignments take the form property=value.

• Option assignments take the form option=value.

Table 3-1: xa_config file components

connection_name The symbolic name for the connection between theapplication and SQL.

sql_server_name The name of the SQL Server associated with theconnection. Must correspond to a SQL Server namedefined in the interfaces file.

xa_server_name The name of the XA-Server associated with theconnection. Must correspond to an XA-Server namedefined in the interfaces file.

capabilities… An optional list of capabilities. Valid capabilities arelisted in “XA-Configuration File Capabilities,Properties, and Options” on page 3-7.

properties… An optional list of properties. Valid properties arelisted in “XA-Configuration File Capabilities,Properties, and Options” on page 3-7.

options… An optional list of options. Valid capabilities are listedin “XA-Configuration File Capabilities, Properties,and Options” on page 3-7.



• Multiple capabilities and properties are separated by commas.

• Lines are extended with a backslash “\”.

• Comments begin with a semicolon “;” and extend to the end ofthe line.

XA-Configuration File Capabilities, Properties, and Options

XA-configuration file capabilities, properties, and options are CS-Library keywords. See the Open Client Client-Library/C ReferenceManual for specific descriptions.

The following tables summarize the valid capabilities, properties,and options for XA-Server.

Table 3-2: XA-Server valid capabilities

Capabilities

CS_CON_NOINBAND CS_CON_NOOOB

CS_DATA_NOBIN CS_DATA_NOVBIN

CS_DATA_NOLBIN CS_DATA_NOBIT

CS_DATA_NOBOUNDARY CS_DATA_NOCHAR

CS_DATA_NOVCHAR CS_DATA_NOLCHAR

CS_DATA_NODATE4 CS_DATA_NODATE8

CS_DATA_NODATETIMEN CS_DATA_NODEC

CS_DATA_NOFLT4 CS_DATA_NOFLT8

CS_DATA_NOIMAGE CS_DATA_NOINT1

CS_DATA_NOINT2 CS_DATA_NOINT4

CS_DATA_NOINT8 CS_DATA_NOINTN

CS_DATA_NOMNY4 CS_DATA_NOMNY8

CS_DATA_NOMONEYN CS_DATA_NONUM

CS_DATA_NOSENSITIVITY CS_DATA_NOTEXT

CS_PROTO_NOBULK CS_PROTO_NOTEXT

CS_RES_NOEED CS_RES_NOMSG

CS_RES_NOPARAM CS_RES_NOTDSDEBUG

CS_RES_NOSTRIPBLANKS

3-8


Table 3-3: XA-Server valid properties

Properties

CS_ASYNC_NOTIFS CS_ASYNC_NOTIFS

CS_DISABLE_POLL CS_HIDDEN_KEYS

CS_LOGIN_TIMEOUT CS_MAX_CONNECT

CS_NOINTERRUPT CS_PACKETSIZE

CS_SEC_APPDEFINED CS_SEC_CHALLENGE

CS_SEC_ENCRYPTION CS_SEC_NEGOTIATE

CS_TDS_VERSION CS_TEXTLIMIT

CS_TIMEOUT

Table 3-4: XA-Server valid options

Options

CS_OPT_ANSINULL CS_OPT_ANSIPERM

CS_OPT_ARITHABORT CS_OPT_ARITHIGNORE

CS_OPT_DATEFIRST CS_OPT_DATEFORMAT

CS_OPT_FIPSFLAG CS_OPT_FORCEPLAN

CS_OPT_FORMATONLY CS_OPT_GETDATA

CS_OPT_ISOLATION CS_OPT_NOCOUNT

CS_OPT_NOEXEC CS_OPT_PARSEONLY

CS_OPT_QUOTED_IDENT CS_OPT_RESTREES

CS_OPT_RESTREES CS_OPT_SHOWPLAN

CS_OPT_STATS_IO CS_OPT_STATS_TIME

CS_OPT_STR_RTRUNC CS_OPT_TEXTSIZE

CS_OPT_TRUNCIGNORE



TUXEDO’s UBBCONFIG File and the Open String

In addition to modifying the Sybase configuration files, integratingTUXEDO requires customizing the TUXEDO configuration file,UBBCONFIG.

The open string is the only portion of the UBBCONFIG file thatrequires modification. It includes the user name and password,which allow XA-Server to control a connection’s access to SQLServer resources.

Open and Close Strings

The XA specification allows each resource manager vendor to definean open string and a close string. (The Sybase implementation of XAdoes not require or use the close string.)

The format of the open string is:

-U username -P password -N lrm_name -L logfile-T trace_flag [-T trace_flag ] ...

The maximum length of an open string is 256 characters. For eachlrm_name that you specify in the UBBCONFIG file’s open string, youmust define a corresponding LRM name in the xa_config file.

➤ NoteUsers must deliberately assign a default database other than master so as

not to store tables in the master database. See “SQL Server User Names,

Passwords, and Default Databases” on page 5-2 for specific instructions.

Open-String Parameters

Table 3-4 describes open-string parameters:

Table 3-4: Open-string parameters

Parameter Meaning

username The user name used to log into SQL Server.

password The password accompanying the user name.

lrm_name The name of the LRM as defined in the xa_config file.

3-10


Here is a sample open string in the Group entry of theUBBCONFIG file for the rentapp sample. The rentapp sample isincluded on the XA-Server release media.

*GROUPS

DEFAULT: TMSNAME=scraptms TMSCOUNT=2FLEET LMID=site1 GRPNO=1OPENINFO="SCRAP_XA_SERVER:

-Uuserid -Ppassword -NFLEET_CON -L/scrap/fleet_xa.log -Tall"RESERVE LMID=site1 GRPNO=2OPENINFO="SCRAP_XA_SERVER:

-Uuserid -Ppassword -NRESERVE_CON -L/scrap/reserve_xa.log -Tall"

logfile The fully qualified file name to which XA-Serverwrites tracing information.

Not specifying the -L option and a logfile parameterdisables logging.

trace_flag(s) Specify these tracing levels only when instructed to doso by Sybase Technical Support.

The trace flag(s) that control the output that getswritten to the logfile. Specify one or more of thefollowing flags:

Tall– all tracing.

Tct– the ct_debug option (ct_debug functionality isavailable only from within the debug version ofClient-Library).

Tevent–XA-Server events tracing.

Txa– entry and exit point tracing at the xa_* level.

Txc– entry and exit point tracing at the xc_* level.

Txl– entry and exit point tracing at the xl_* level.

Tx*– entry and exit point tracing at the xa_* , xc_* , andxl_* levels.

Enabling tracing at the xa_* (XA specification) levelmay be useful to you, but tracing at the xc_* and xl_*levels is meaningful only to Sybase development.

Table 3-4: Open-string parameters (continued)

Parameter Meaning


4 Debugging Applications 4.

This chapter describes tools for debugging the application andtechniques for using those tools.

XA-Server can generate two types of log files; both are useful fordebugging. These files are associated with XA-Server and XA-ServerLibrary.

This chapter contains the following sections:

• State Transitions 4-1

• The XA-Server Library Log File 4-2

• The XA-Server Log File 4-4

➤ NoteThe log files were created primarily to serve as internal diagnostic tools for

SYBASE Technical Support personnel. Although this chapter does offer

some advice for using log files, it does not describe every aspect of them.

State Transitions

Figure 4-1 shows possible states and causes for transitions in aTUXEDO TM system. (TMRESUME, TMSUSPEND, TMFAIL, TMSUCCESS,and TMONEPHASE are flags defined in the X/Open CAE SpecificationDistributed Transaction Processing: The XA Specification.) You can use

4-2


Figure 4-1 with the log files to determine which state a transaction isin when a failure occurs.

Figure 4-1: XA state diagram

The XA-Server Library Log File

XA-Server can create an XA-Server Library log file for every RMinstance in the UBBCONFIG file. These log files contain informationfor TMSs and application servers.

Specify the XA-Server Library log file in the open string, as describedin Chapter 3, “TUXEDO’s UBBCONFIG File and the Open String”,”and repeated here:

PreparedTransaction

xa_start

InactiveTransaction

xa_endTMSUSPEND

xa_endTMFAIL

Idle and DisassociatedTransaction

xa_endTMSUCCESS

AssociationSuspended

xa_startTMRESUME

Rollback OnlyTransaction

xa_rollback

xa_rollback

ActiveTransaction

xa_rollback

xa_prepare

xa_commit

xa_commitTMONEPHASE

xa_endTMSUCCESS



OPENINFO="SYBASE_XA_SERVER: -Uusername -P password \-N lrm_name -L logfile -T trace_flag

You can specify a separate log file and log file path for each newgroup.

Figure 4-2 is a sample excerpt from an XA-Server Library log file.

An xa_start in the log file corresponds to a transition from the“Inactive Transaction” state to the “Active Transaction” state. xa_endwith a flag of TMSUCCESS causes the next state transition to “Idle andDisassociated Transaction.” xa_commit with a TMONEPHASE flagresults in a “No Active Transaction” state.

1995/02/22 18:08:04: 0x665d: xa_start: rmid: 0, flags:[] XID:40.24.28E696E600.00000000.00000000.10007870.F24DE77.00000010E696E600.00000000.00000000.10007870.00000010.00000010.00000000

Content-Length: 3644X-Lines: 66Status: RO1995/02/22 18:08:04: 0x665d: xc_get: Enter1995/02/22 18:08:04: 0x665d: xl_init: Enter1995/02/22 18:08:04: 0x665d: xl_get: Enter1995/02/22 18:08:04: 0x665d: xl_get: return, retstat: 1 ([CS_SUCCEED])1995/02/22 18:08:04: 0x665d: xl_init: return, retstat: 1 ([CS_SUCCEED])1995/02/22 18:08:04: 0x665d: xc_get: retstat: 0 ([XA_OK])1995/02/22 18:08:04: 0x665d: xc_rpc_start: Enter1995/02/22 18:08:04: 0x665d: xc_rpc_start: retstat: 0 ([XA_OK])1995/02/22 18:08:04: 0x665d: xc_execute: Enter1995/02/22 18:08:07: 0x665d: xc_fetch_status: Enter1995/02/22 18:08:07: 0x665d: xc_fetch_status: retstat: 0 ([XA_OK])1995/02/22 18:08:07: 0x665d: xc_execute: retstat: 0 ([XA_OK])1995/02/22 18:08:07: 0x665d: xa_start: retstat: 0 ([XA_OK])1995/02/22 18:08:08: 0x665d: xa_end: Enter1995/02/22 18:08:08: 0x665d: xa_end: rmid: 0, flags:[TMSUCCESS] XID: 40.24.28

E696E600.00000000.00000000.10007870.F2B4DE77.00000010E696E600.00000000.00000000.10007870.00000010.00000010.00000000

1995/02/22 18:08:08: 0x665d: xc_get: Enter1995/02/22 18:08:08: 0x665d: xl_init: Enter1995/02/22 18:08:08: 0x665d: xl_get: Enter1995/02/22 18:08:08: 0x665d: xl_get: return, retstat: 1 ([CS_SUCCEED])1995/02/22 18:08:08: 0x665d: xl_init: return, retstat: 1 ([CS_SUCCEED])1995/02/22 18:08:08: 0x665d: xc_get: retstat: 0 ([XA_OK])1995/02/22 18:08:08: 0x665d: xc_rpc_xid: Enter1995/02/22 18:08:08: 0x665d: xc_rpc_xid: retstat: 0 ([XA_OK])1995/02/22 18:08:08: 0x665d: xc_execute: Enter1995/02/22 18:08:08: 0x665d: xc_fetch_status: Enter1995/02/22 18:08:08: 0x665d: xc_fetch_status: retstat: 0 ([XA_OK])1995/02/22 18:08:08: 0x665d: xc_execute: retstat: 0 ([XA_OK])1995/02/22 18:08:08: 0x665d: xa_end: retstat: 0 ([XA_OK])1995/02/22 18:08:08: 0x665d: xa_commit: Enter1995/02/22 18:08:08: 0x665d: xa_commit: rmid: 0, flags:[TMONEPHASE] XID:40.24.28

E696E600.00000000.00000000.10007870.F2B4DE77.00000010E696E600.00000000.00000000.10007870.00000010.00000010.00000000

Figure 4-2: An excerpt from an XA-Server Library log file

4-4


The XA-Server Log File

XA-Server creates a log file when you turn on logging using thexaserver command. The command is:

$SYBASE/bin/xaserver [-S xa_server_name ] [-L logfile_name ][-Txa][-Ttds] [-Tinternal] [-J char_set ] [-z language ] [-v] [-help]

If you do not specify a path, XA-Server creates the log file in thedirectory in which it starts.

You can specify the name of the logfile as the -L command line optionwhen you start the XA-Server or let it default to xa_server_name.log,where xa_server_name corresponds to the XA-Server name specifiedin the interfaces file.

Figure 4-3 is an example excerpt from an XA-Server log file.1995/02/22 17:30:03: 0x7cfd4: xarpc_startparams: Enter1995/02/22 17:30:03: 0x7cfd4: xarpc_startparams: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:03: 0x7cfd4: xl_start: Enter1995/02/22 17:30:03: 0x7cfd4: xl_start: xa_rmid: 0, flags: [], XID: 40.24.28

E696E600.00000000.00000000.10007870.F2B44E28.00000010E696E600.00000000.00000000.10007870.00000010.00000010.00000000

1995/02/22 17:30:03: 0x7cfd4: xl_lookup_lrmid: Enter1995/02/22 17:30:03: 0x7cfd4: xl_lookup_lrmid: xa_rmid = 01995/02/22 17:30:03: 0x7cfd4: xl_lookup_lrmid: lrmid = 01995/02/22 17:30:03: 0x7cfd4: xl_lookup_lrmid: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:03: 0x7cfd4: xl_find_xaconn: Enter1995/02/22 17:30:03: 0x7cfd4: xl_find_xaconn: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:03: 0x7cfd4: xl_find_xaconn: Enter1995/02/22 17:30:03: 0x7cfd4: xl_find_xaconn: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:03: 0x7cfd4: xl_start: xaconn: 0x39bdb8, lrmid: 01995/02/22 17:30:03: 0x7cfd4: xl_start: new XID starting!1995/02/22 17:30:03: 0x7cfd4: xc_start: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_init: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_init: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:03: 0x7cfd4: xc_conn_init: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_init: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:03: 0x7cfd4: xc_conn_cs_start: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_cs_start: INIT the connection service1995/02/22 17:30:03: 0x7cfd4: xc_conn_do_cs_init: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_do_results: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_do_results: commid is 10

1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_do_results: return, retstat: 1([CS_SUCCEED])



1995/02/22 17:30:04: 0x7cfd4: xc_conn_do_cs_init: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_cs_start: START the connection service1995/02/22 17:30:04: 0x7cfd4: xc_conn_process_rpc_results: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_process_rpc_results: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_cs_start: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_start: xaconn: 0x39bdb8, xc_cs: 0x35a2e81995/02/22 17:30:04: 0x7cfd4: xc_conn_2pc: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_init: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_init: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_process_rpc_results: Enter

(Log entries removed…)1995/02/22 17:30:03: 0x7cfd4: xc_start: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_init: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_init: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:03: 0x7cfd4: xc_conn_init: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_init: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:03: 0x7cfd4: xc_conn_cs_start: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_cs_start: INIT the connection service1995/02/22 17:30:03: 0x7cfd4: xc_conn_do_cs_init: Enter1995/02/22 17:30:03: 0x7cfd4: xc_conn_do_results: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_do_results: commid is 10

1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_do_results: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_do_cs_init: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_cs_start: START the connection service1995/02/22 17:30:04: 0x7cfd4: xc_conn_process_rpc_results: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_fetch_data: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_process_rpc_results: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_cs_start: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_start: xaconn: 0x39bdb8, xc_cs: 0x35a2e81995/02/22 17:30:04: 0x7cfd4: xc_conn_2pc: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_init: Enter1995/02/22 17:30:04: 0x7cfd4: xc_conn_init: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:04: 0x7cfd4: xc_conn_process_rpc_results: Enter1995/02/22 17:30:05: 0x0: xaos_ctlib_error: Enter1995/02/22 17:30:05: 0x7c6ac: xaos_ctlib_error: now using srvproc from conn_ctx1995/02/22 17:30:05: 0x7c6ac: xaos_raise_error: Enter1995/02/22 17:30:05: 0x7c6ac: xaos_raise_error: CTLIB Message: xaserver -16842864/0/0: ct_results(): user api layer: external error: 1 rows affected.

4-6


1995/02/22 17:30:05: 0x7c6ac: xaos_sendinfo: Enter1995/02/22 17:30:05: 0x7c6ac: xaos_srvlib_error: Enter1995/02/22 17:30:05: 0x7c6ac: xaos_raise_error: Enter1995/02/22 17:30:05: 0x7c6ac: xaos_raise_error: SRVLIB Message: xaserver -16234/10/0: Cannot call srv_sendinfo() in user defined event handler

1995/02/22 17:30:05: 0x7c6ac: xaos_srvlib_error: return, retstat: -7([CS_CONTINUE])1995/02/22 17:30:05: 0x7c6ac: [xaos_error.c/572] xaos_sendinfo: srv_sendinfo()failed1995/02/22 17:30:05: 0x7c6ac: xaos_sendinfo: return, retstat: 0 ([CS_FAIL])1995/02/22 17:30:05: 0x7c6ac: xaos_raise_error: return, retstat: 0 ([CS_FAIL])1995/02/22 17:30:05: 0x7c6ac: xaos_ctlib_error: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xc_conn_process_rpc_results: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xc_conn_2pc: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xc_start: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xl_start: return, retstat: 0 ([CS_FAIL])1995/02/22 17:30:05: 0x7cfd4: xasrv_set_osconn: Enter1995/02/22 17:30:05: 0x7cfd4: xasrv_set_osconn: return, retstat:1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xa_rpc_start: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_rpc_handler: Enter1995/02/22 17:30:05: 0x7cfd4: xaos_rpc_passthru: Enter1995/02/22 17:30:05: 0x7cfd4: xaos_rpc_passthru: simprpc_sproc1995/02/22 17:30:05: 0x7cfd4: xaos_ctparams: Enter1995/02/22 17:30:05: 0x0: xaos_meminit: Enter1995/02/22 17:30:05: 0x0: xaos_mem_getblock: Enter1995/02/22 17:30:05: 0x0: xaos_mem_getblock: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x0: xaos_meminit: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3caec81995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cb0281995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cb0481995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cb0681995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cb0881995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cb1a81995/02/22 17:30:05: 0x0: xaos_memfree: Enter1995/02/22 17:30:05: 0x0: xaos_memfree: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_ctparams: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_ctsend: Enter1995/02/22 17:30:05: 0x7cfd4: xaos_ctsend: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_results: Enter1995/02/22 17:30:05: 0x7cfd4: xaos_procstat: Enter1995/02/22 17:30:05: 0x7cfd4: xaos_procstat: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_srvparams: Enter1995/02/22 17:30:05: 0x0: xaos_meminit: Enter1995/02/22 17:30:05: 0x0: xaos_mem_getblock: Enter1995/02/22 17:30:05: 0x0: xaos_mem_getblock: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x0: xaos_meminit: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3ca8e8



1995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3caa481995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cab081995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cab281995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cab481995/02/22 17:30:05: 0x0: xaos_memalloc: Enter1995/02/22 17:30:05: 0x0: xaos_memalloc: value: 3cab681995/02/22 17:30:05: 0x0: xaos_memfree: Enter1995/02/22 17:30:05: 0x0: xaos_memfree: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_srvparams: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x0: xaos_ctlib_error: Enter1995/02/22 17:30:05: 0x7cfd4: xaos_ctlib_error: now using srvproc from conn_ctx1995/02/22 17:30:05: 0x7cfd4: xaos_raise_error: Enter1995/02/22 17:30:05: 0x7cfd4: xaos_raise_error: CTLIB Message: xaserver -16842864/0/0: ct_results(): user api layer: external error: 1 rows affected.1995/02/22 17:30:05: 0x7cfd4: xaos_sendinfo: Enter1995/02/22 17:30:05: 0x7cfd4: xaos_sendinfo: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_raise_error: return, retstat:1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_ctlib_error: return, retstat:1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_results: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_rpc_passthru: return,retstat:1 ([CS_SUCCEED])1995/02/22 17:30:05: 0x7cfd4: xaos_rpc_handler: return, retstat:1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xa_rpc_end: Enter1995/02/22 17:30:06: 0x7cfd4: xarpc_xidparams: Enter1995/02/22 17:30:06: 0x7cfd4: xarpc_xidparams: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xl_end: Enter1995/02/22 17:30:06: 0x7cfd4: xl_end: xa_rmid: 0, flags: [TMSUCCESS], XID:40.24.28

E696E600.00000000.00000000.10007870.F2B44E28.00000010E696E600.00000000.00000000.10007870.00000010.00000010.00000000

1995/02/22 17:30:06: 0x7cfd4: xl_lookup_lrmid: Enter1995/02/22 17:30:06: 0x7cfd4: xl_lookup_lrmid: xa_rmid = 01995/02/22 17:30:06: 0x7cfd4: xl_lookup_lrmid: lrmid = 01995/02/22 17:30:06: 0x7cfd4: xl_lookup_lrmid: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xl_find_xaconn: Enter1995/02/22 17:30:06: 0x7cfd4: xl_find_xaconn: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xl_end: lrmid: 0, xaconn: 0x39bdb8, xc_cs:0x35a2e81995/02/22 17:30:06: 0x7cfd4: xl_end_wakeup: Enter1995/02/22 17:30:06: 0x7cfd4: xl_end_wakeup: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xl_end: retstat: 0 ([XA_OK])1995/02/22 17:30:06: 0x7cfd4: xasrv_set_osconn: Enter1995/02/22 17:30:06: 0x7cfd4: xasrv_set_osconn: return, retstat: 1([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xa_rpc_end: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xa_rpc_commit: Enter1995/02/22 17:30:06: 0x7cfd4: xarpc_xidparams: Enter1995/02/22 17:30:06: 0x7cfd4: xarpc_xidparams: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xl_commit: Enter1995/02/22 17:30:06: 0x7cfd4: xl_commit: xa_rmid: 0, flags: [TMONEPHASE], XID:40.24.28

E696E600.00000000.00000000.10007870.F2B44E28.00000010E696E600.00000000.00000000.10007870.00000010.00000010.00000000

4-8


1995/02/22 17:30:06: 0x7cfd4: xl_lookup_lrmid: Enter1995/02/22 17:30:06: 0x7cfd4: xl_lookup_lrmid: xa_rmid = 01995/02/22 17:30:06: 0x7cfd4: xl_lookup_lrmid: lrmid = 01995/02/22 17:30:06: 0x7cfd4: xl_lookup_lrmid: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xl_find_xaconn: Enter1995/02/22 17:30:06: 0x7cfd4: xl_find_xaconn: return, retstat: 1 ([CS_SUCCEED])1995/02/22 17:30:06: 0x7cfd4: xl_commit: lrmid: 0, xaconn: 0x39bdb8, xc_cs:0x35a2e8

(Log entries removed…)1995/02/22 17:30:06: 0x7cfd4: xl_commit: retstat: 0 ([XA_OK])1995/02/22 17:30:06: 0x7cfd4: xa_rpc_commit: return, retstat: 1 ([CS_SUCCEED])

Figure 4-3: An excerpt from an XA-Server log file


5 Application ProgrammingGuidelines 5.

Programming in an X/Open DTP environment is similar toprogramming in other client/server database environments in mostways. However, Embedded SQL and Open Client applications mustconform to certain programming constraints to function in the XA-Server environment. This chapter summarizes these constraints.

This chapter contains the following topics:

• X/Open DTP Versus Traditional Sybase Transaction Processing5-1

• Functionality Not Supported 5-2

• SQL Server User Names, Passwords, and Default Databases 5-2

• Transaction and Connection Management 5-2

• Getting a Client-Library Connection Handle 5-5

• Changing Connection Specifications 5-5

• Callbacks 5-6

• Application Samples 5-10

X/Open DTP Versus Traditional Sybase Transaction Processing

The X/Open DTP model of transaction processing differssubstantially from the traditional Sybase model. The traditionalSybase TP environment is connection oriented. Programs set upconnections directly between the application program and SQLServer using connection management SQL statements. In the XA-Server environment, the XA-Server, using LRMs, sets up connectionsfor the application.

Table 5-1 summarizes the differences.

Table 5-1: Traditional TP and X/Open DTP model differences

Traditional TP Model X/OPEN DTP Model

There is one or more transaction perclient/server connection.

There is no notion of connections.Components communicate throughinterfaces.

5-2


Functionality Not Supported

XA-Server does not support:

• Browse capability

• Bulk login

SQL Server User Names, Passwords, and Default Databases

You must establish the SQL Server user name and password for eachTUXEDO server in the UBBCONFIG file’s open string. Refer to“Open and Close Strings” on page 3-9.

You must also add these user id’s to the SQL Server using thesp_addlogin command, and assign an appropriate default database.

SQL Server assigns a default database to each associated user, which,if not deliberately assigned otherwise, is the master database. In theXA-Server environment, user transactions cannot take place in themaster database. The application must use a default database otherthan master to avoid storing tables in the master database.

Transaction and Connection Management

Applications running in a TUXEDO TM environment must payspecial attention to the commands that are related to transactionmanagement, connection management, and current connectionestablishment.

Transactions are usually local, witheach transaction confined to a singleSQL Server.

Transactions are global. They spanresource managers. The work donewithin a transaction is accomplishedusing more than one resource manager.

Each SQL Server is responsible forthe recovery of the data it contains.

The transaction manager is responsiblefor recovering the data stored in all ofthe resource managers.

Table 5-1: Traditional TP and X/Open DTP model differences (continued)

Traditional TP Model X/OPEN DTP Model



Transaction Management

The TUXEDO TM is responsible for transaction management whichincludes creating a global transaction in which all of an application’swork is either committed or rolled back. Consequently, applicationprogrammers must not use SQL statements that manage transactionsin applications.

Specifically, applications must not invoke the following EmbeddedSQL commands:

• begin transaction

• commit transaction, commit work

• rollback transaction, rollback work

Client-Library applications must not execute (through ct_command,ct_dynamic, or ct_cursor) these Transact-SQL® commands:

• begin transaction

• commit transaction, commit work

• rollback transaction, rollback work

• set (chained, noexec, isolation, parseonly, statistics io, statistics time)

• save transaction

Connection Management

Applications rely on XA-Server to manage client-to-serverconnections. These are transparent to the application. Therefore,applications cannot use the commands listed in Table 5-2.

Table 5-2: Invalid commands

Client-Library CS-Library

ct_close cs_config (CS_SET ofCS_THREAD_RESOURCE property)

ct_con_alloc cs_ctx_drop (with global context handle)

ct_con_drop cs_ctx_global

ct_con_props cs_diag

5-4


The Current Connection and Embedded SQL

The notion of a default connection, as described in the Open ClientEmbedded SQL documentation, does not exist in the XAenvironment. Consequently, applications must specify a currentconnection. To specify the current connection in Embedded SQL, youcan use one of the following:

• The set connection command

• The at connection_name clause

A current connection does not span transactions. For example, anapplication must reset the current connection after each tx_commitcommand. Using the at connection_name clause with all EmbeddedSQL statements helps to avoid confusion about the scope of thecurrent connection.

ct_config with parameters

CS_ENDPOINTCS_MAX_CONNECTCS_EXPOSE_FMTSCS_NETIOCS_HIDDENKEYSCS_TRANSACTION_NAME

cs_objects (CS_CLEAR, CS_SET)

ct_connect cs_ctx_drop (with global context handle)

ct_exit cs_objects (CS_CLEAR, CS_SET)

ct_getloginfo

ct_init

ct_options with parameters

CS_OPT_CHAINXACTSCS_OPT_PARSEONLYCS_OPT_FORCEPLANCS_OPT_STATS_IOCS_OPT_FORMATONLYCS_OPT_STATS_TIMECS_OPT_NOEXEC

ct_remote_pwd

ct_setloginfo

Table 5-2: Invalid commands

Client-Library CS-Library



Getting a Client-Library Connection Handle

Obtaining a connection handle is an issue specific to Client-Libraryapplications.

When the transaction manager calls the XA-Server library, it opens aconnection to XA-Server.

To get the connection handle, specify CS_GET for the cs_objectsroutine’s action parameter with an object type ofCS_CONNECTNAME. cs_objects’ objdata parameter returns astructure containing a connection field. This field contains the handleto XA-Server’s CS_CONNECTION structure.

◆ WARNING!XA-Server also allocates a CS_COMMAND structure whose handle isreturned in the command field of the structure to which the objdataparameter points. An application may not use this command handle,because XA-Server itself continues to use this handle.

The simprc and rentapp application examples demonstrate how toretrieve the handle to the CS_CONNECTION structure allocated byXA-Server.

Changing Connection Specifications

TUXEDO server processes re-use the same connections for differenttransactions, and may share the connections between differentapplication services within the server. Therefore, TUXEDO serverapplications should not generally change connection capabilities,properties or options.

If you need to implement a TUXEDO application that uses differentconnections with different properties, then you must establish morethan one LRM for the same SQL Server. The application can bewritten as a singe TUXEDO services that uses more than one LRM, oryou can write the application as separate TUXEDO servicespackaged into different TUXEDO servers, with different LRM's andconnection properties defined in the xa_config file.

5-6


Synchronous and Asynchronous Calls

All work on behalf of a transaction branch is serialized over aconnection between the XA-Server and SQL Server. Therefore, youcannot optimize application performance by mixing synchronousand asynchronous TUXEDO calls within a single transaction branch.

To optimize performance and execute TUXEDO services in parallel,you must initiate multiple asynchronous transaction branches fromthe TUXEDO client, and package the services used by these branchesinto different TUXEDO servers. That way, multiple TUXEDO serverscan run in parallel and use different connections from the XA-Serverto the SQL Server.

Callbacks

In the XA-Server environment, the application does not own theconnection handle or the context handle, XA-Server does. However,connection and context handles are the application’s onlymechanism for installing callbacks.

There are two important issues that should govern the way theapplication handles call backs.

One issue is an inter-application issue. An application must clear anycallbacks it installs on connection handles. If the application is notresponsible about clearing these connection handles, they could bepassed along to the next transaction that uses the connection orcontext handle.

The other issue is a connection and context-level issue. When theapplication installs a callback at the connection or context-level, itmust save the existing global callback, install the current one, andthen, when done, clear the current callback and restore the originalone.

The files shown on the next several pages illustrate the “wrapper”method of surrounding CS-Library calls with a CS-Library callbackthat is only installed for the minimum amount of time necessary. File1 shows the setupCB and teardownCB functions. setupCB saves theoriginal callback on the context handle, and installs a new one.teardownCB restores the original callback handle. File 2 shows how touse this around the call to cs_objects.

The same strategy applies to Client-Library and Server-Librarycallbacks. The sample installs callbacks after it has retrieved theconnection handle, and clears them before it goes away.



File 1

/*** setupCB() - Setup C/S-Lib callback. The C/S-Lib callback is only setup** around the few C/S-Lib calls we make in the application, and is torn down** afterward. This is because it has to be set up on the context handle, which,** like the connection handle, we don't own in the TM environment. Therefore,** we grab the existing callback (the one installed by XA-Lib), save it, and** restore it when we tear down our callback. Otherwise, we would leave our** callback installed on the context handle, and whatever application ran after** ours (or XA-Lib itself) would have our callback invoked upon any C/S-Lib** errors.*/

static RET_CODEsetupCB(ctx, cbfunc)

CS_CONTEXT*ctx;/* C/S-Lib context handle. */CS_VOID **cbfunc;/* Pointer to save existing callback */

{const char*thisFunc = "setupCB()";CS_RETCODEctrc = CS_SUCCEED; /* Return code from ct_* functions */RET_CODE rc = EX_OK;/* Function return code */

SYBENTER(thisFunc);

/*** Check parms for validity.*/if ((!ctx) || (!cbfunc))

rc = EX_BAD_PARMS;

/*** Get existing C/S-Library callback, if any.*/if (rc == EX_OK){

ctrc = cs_config(ctx, CS_GET, CS_MESSAGE_CB, cbfunc, CS_UNUSED, NULL);if (ctrc != CS_SUCCEED){

rc = EX_CS_CONFIG_FAILED;SYBLOG(CS_FAILURE, ctrc, "cs_config(CS_GET, CS_MESSAGE_CB)");

} /* if (ctrc != CS_SUCCEED) */} /* if (rc == EX_OK) */

/*** Install our C/S-Library callback.*/if (rc == EX_OK){

ctrc = cs_config(ctx, CS_SET, CS_MESSAGE_CB, cslibCB, CS_UNUSED, NULL);if (ctrc != CS_SUCCEED){

rc = EX_CS_CONFIG_FAILED;SYBLOG(CS_FAILURE, ctrc, "cs_config(CS_SET, CS_MESSAGE_CB)");

} /* if (ctrc != CS_SUCCEED) */} /* if (rc == EX_OK) */

5-8


/*** Something went wrong, so log it.*/if (rc != EX_OK)

SYBLOG(EX_FAILURE, rc, thisFunc);

SYBEXIT(thisFunc, rc);

return rc;} /* setupCB() */

/*** teardownCB() - Reset C/S-Lib callback. The C/S-Lib callback is only setup** around the few C/S-Lib calls we make in the application, to be reset here.** This is because it has to be set up on the context handle, which, like the** connection handle, we don't own in the TM environment. Therefore, we grab** the existing callback (the one installed by XA-Lib), save it, and restore it** when we tear down our callback. Otherwise, we would leave our callback** installed on the context handle, and whatever application ran after ours (or** XA-Lib itself) would have our callback invoked upon any C/S-Lib errors.*/static RET_CODEteardownCB(ctx, cbfunc)

CS_CONTEXT*ctx;/* C/S-Lib context handle. */CS_VOID **cbfunc;/* Pointer to saved callback */

{const char*thisFunc = "teardownCB()";CS_RETCODEctrc = CS_SUCCEED; /* Return code from ct_* functions */RET_CODE rc = EX_OK;/* Function return code */

SYBENTER(thisFunc);

/*** Check parms for validity.*/if (!ctx)rc = EX_BAD_PARMS;

/*** Install original C/S-Library callback.*/if ((rc == EX_OK) && (*cbfunc)){

ctrc = cs_config(ctx, CS_SET, CS_MESSAGE_CB, cbfunc, CS_UNUSED, NULL);if (ctrc != CS_SUCCEED){

rc = EX_CS_CONFIG_FAILED;SYBLOG(CS_FAILURE, ctrc, "cs_config(CS_SET, CS_MESSAGE_CB)");

} /* if (ctrc != CS_SUCCEED) */} /* if ((rc == EX_OK)... */



/*** Something went wrong, so log it.*/if (rc != EX_OK)

SYBLOG(EX_FAILURE, rc, thisFunc);

SYBEXIT(thisFunc, rc);

return rc;} /* teardownCB() */

File 2

/*** Establish our C/S-Lib callback.*/if (rc == EX_OK)

rc = setupCB(*ctx, &cbfunc);

/*** Look up the connection handle based upon LRM name.*/if (rc == EX_OK){

strcpy(objName.last_name, conn);objName.fnlen= CS_UNUSED;objName.lnlen= len;objName.object_type= CS_CONNECTNAME;objName.scopelen= CS_UNUSED;objName.thinkexists= CS_FALSE;objName.threadlen= CS_UNUSED;objData.actuallyexists= CS_FALSE;objData.buffer= (CS_VOID *)NULL;objData.buflen= CS_UNUSED;objData.command= (CS_COMMAND *)NULL;objData.connection= (CS_CONNECTION *)NULL;ctrc = cs_objects(*ctx, CS_GET, &objName, &objData);if (ctrc != CS_SUCCEED){ rc = EX_CS_OBJECTS_FAILED; SYBLOG(CS_FAILURE, ctrc, "cs_objects(CS_GET)");} /* if (ctrc == CS_SUCCEED) */

} /* if (rc == EX_OK) */

/*** Re-establish original C/S-Lib callback.*/if (rc == EX_OK)

rc = teardownCB(*ctx, &cbfunc);

5-10


Application Samples

The XA-Server release includes these sample programs to help youget started:

• simprpc.ct is a simple Client-Library program that uses one-phasecommit to make an RPC request of a SQL Server. This sample isuseful for verifying that the XA-Server installation andintegration with TUXEDO is functional. The XA-Server ReleaseBulletin provides procedures for using simprpc.ct in this way.

• rentapp is a more sophisticated example that simulates a car rentalsystem. You can use it for testing two-phase commit and multipleSQL Server functionality. Both Client-Library and ESQL versionsof rentapp are provided.

The samples reside in $SYBASE/sample/xaserver.

The rentapp sample simulates a very simple car rental system. It canbe used to verify the XA-Server environment’s two-phase commitcapabilities using two databases that reside on separate SQL Servers.The tables within the databases use referential integrity and domainintegrity to ensure validity of data and to show how these constraintswork in this environment.

When used with all of its capabilities enabled, rentapp verifies all thebasic components of an Sybase XA environment.

rentapp also supports a harness that emulates the TUXEDOenvironment, establishing connections to LRMs, storing theconnection handles for retrieval by the application, as well as otherXA-related tasks. The harness allows you to test the SYBASEenvironment outside the TM environment, such as to check that SQLServers are correctly configured for the application.

One way to use rentapp is to get the harness running without errorsfirst, and then integrate the TUXEDO parts of the application.

Refer to the README text file in $SYBASE/sample/xaserver/rentappfor more information.

XA-Server Integration Guide for TUXEDO A-1

A Heuristic Transaction Completion A.

Under certain circumstances, the System Administrator may need tointervene to complete transaction branches. This manualintervention can result in “heuristic completion” of transactionbranches, as described in Chapter 1.

The System Administrator would intervene to complete transactionsif:

• A transaction process died while still holding locks on SQLServer resources and the Encina TM was unable to recover.

• A SQL Server crashed and came back up, and the SystemAdministrator could not wait for the Encina TM to come up tomake the database available.

In the Sybase XA environment, the System Administrator uses threestored procedures to complete transaction branches. These are:

• sp_xa_clean_xact

• sp_xa_finish_xact

• sp_xa_scan_xact

These stored procedures are documented on the following pages.

◆ WARNING!In the Sybase XA environment, it is illegal for user transactions to takeplace in the master database. This means that users cannot storetables in the master database and must have a default database otherthan master.

A-2 Heuristic Transaction Completion

sp_xa_clean_xact XA-Server Release 11.1.1

sp_xa_clean_xact

Function

Purges obsolete XA transaction entries from SQL Server.

Syntax

sp_xa_clean_xact [“-F”]

Parameters

“-F” (optional). Use with care; see below for description of its use.

Comments

• sp_xa_clean_xact removes all XA-managed transaction branchesthat have been abandoned because of errors in the TransactionProcessing Monitor.

• Transaction branches are considered obsolete when they are inthe “begin” state and the client process is no longer connected toSQL Server. SQL Server is not able to remove these entriesautomatically, although the related resources are freed.

• sp_xa_clean_xact should only be invoked when SQL Server isquiescent (for example, during start-up).

• If there are any active processes, a message is displayed. The “-F”parameter forces cleanup in this case. Use -F to clean up once it iscertain that no active transactions are present. The -F parameterwill not clean up transactions associated with an active SQLServer SPID.

Messages

• WARNING: Active XA Transactions may be present.Use ‘F’ option to force cleanup.

Indicates that there are SQL Server processes which areidentified as working on transactions. The “-F” (force) option canbe used to clean up any transactions which are not associatedwith any SQL Server SPIDs.

• Deleting Commid ###!

Displayed for each transaction branch deleted.

• Completed sp_xa_clean_xact

Displayed upon completion.


XA-Server Release 11.1.1 sp_xa_clean_xact

Permissions

Only the System Administrator can execute sp_xa_clean_xact.

Tables Used

spt_commitab

See Also

sp_xa_finish_xact, sp_xa_scan_xact


sp_xa_finish_xact XA-Server Release 11.1.1

sp_xa_finish_xact

Function

Mark a transaction branch as heuristically committed or rolled back.

Syntax

sp_xa_finish_xact commid, status [, “-F”]

Parameters

commid – The commit id of the transaction branch.

status – Valid status values are “c” or “C” for commit and “a” or “A” forabort.

“-F” (optional). Use with care; see below for description of its use.

➤ Note“C” and “A” are used to force a heuristic completion indication on

transactions which are already marked as completed. This causes these

transactions to be reported to the TM as awaiting completion. This may be

necessary in extremely rare cases where the TM has not properly recorded

the completion.

Examples

1. sp_xa_finish_xact 8,c

Sets the status of the transaction associated with commit ID 8 to “c”for commit. SQL Server will commit the transaction.

2. sp_xa_finish_xact 56,a

Sets the status of the transaction associated with a commit ID of 56 to“a” for abort. The SQL Server will abort the transaction.

Comments

• There may be a delay before the SQL Server notices the statuschange and takes action.

• sp_xa_scan_xact returns a return status of “1” in response to aninvalid commid or status.

• sp_xa_finish_xact will not complete transactions which are activelyassigned to a SQL Server SPID. The “-F” (force” parameter forces


XA-Server Release 11.1.1 sp_xa_finish_xact

completion of transactions which are associated with a SQLServer SPID. This does not change SQL Server handling of thetransaction but does cause the TM to be notified of the stateduring its recovery handling or if it attempts transactiontermination.

Messages

• Commit status xx invalid (only ‘a’ or ‘c’ arepermitted).

An invalid status parameter (xx) was supplied.

• Commit ID ## not valid.

The supplied commit ID (##) is not present in the system.

• Warning: Transaction is already complete withstatus ‘xx’. You can use ‘A’ or ‘C’ to forcechange.

The transaction is already committed or aborted. The A or Cparameter can be used to change the state and mark it asheuristically completed.

• Commit ID ## is in use by spid ##--no actiontaken. Kill the spid and try again

The transaction branch could not be deleted due to the presenceof an associated SPID.

Permissions

Only the System Administrator can execute sp_xa_finish_xact.

Tables Used

spt_commitab

See Also

sp_xa_scan_xact


sp_xa_scan_xact XA-Server Release 11.1.1

sp_xa_scan_xact

Function

Returns the status of all XA-managed transaction branches known tothis SQL Server or the status of a transaction branch associated witha particular commit ID.

Syntax

sp_xa_scan_xact [ commid]

Parameters

commid – The commit ID of a particular XA-managed transactionbranch.

Examples

1. sp_xa_scan_xact

Returns a list containing the state of all XA-managed transactionbranches known to this SQL Server.

2. sp_xa_scan_xact 6

Returns the state of the transaction branch where commid is equalto 6.

Comments

• sp_xa_scan_xact finds all XA-managed transaction branches thathave failed because of errors in the Transaction ProcessingMonitor.

• commid is Sybase’s internal reference to any given transaction ID.

• sp_xa_scan_xact returns 0 rows in response to an invalid commid.

Messages

None.

Permissions

Only the System Administrator can execute sp_xa_scan_xact.

Tables Used

spt_commitab


XA-Server Release 11.1.1 sp_xa_scan_xact

See Also

sp_xa_finish_xact


sp_xa_scan_xact XA-Server Release 11.1.1

Title for Your Book’s Footers Glossary-1

Glossary

ACID testThe ACID (Atomicity, Consistency, Isolation, Durability) test is the test of a truetransaction; to pass, the transaction must exhibit the following properties:

Atomicity – All portions of the transaction either succeed and are committed orthey are all rolled back and have no effect.

Consistency – If a transaction is rolled back, all resources that the transactionaffected return to the valid state they were in before the transaction took place.

Isolation – A transaction’s results are visible only to that transaction, althoughother processes in the same transaction may access the data. After commitment,the results are visible outside the transaction.

Durability – After a transaction commits, all the affected resources are permanentand can not be altered by subsequent system failures.

Committed transactionA completed transaction whose changes to shared resources are permanent.

Distributed transaction processing (DTP)A transaction processing model in which the shared resources are located atdistinct physical sites on a computer network.

Global transactionA transaction that can involve more than one resource manager and can span morethan one physical location, such as multiple independent databases, but that istreated as one unit of work (or business function).

Local transactionA transaction that affects data in a single database and whose tasks are performedby a single resource manager.

Loosely coupled transactionsA transaction that does not share locks or other system resources with otherbranches.

Logical resource manager (LRM)Associates symbolic names with client/server connections, which an applicationuses to identify connections to SQL Server.

Glossary-2

Product Name & Release Number

Native interfaceThe application programming interface for the resource manager. In the SYBASEXA environment, the native interface that allows access to the database server iseither Embedded SQL or Client-Library calls.

Prepare phaseThe transaction monitor requests each resource manager to prepare to commit itsportion of the global transaction.

RecoveryThe process of bringing a transaction processing system into a consistent state aftera failure. Specifically, this means resolving the transactions that are left in a non-committed, non-rolled-back state.

Remote Procedure Call (RPC)A call to a software procedure that is stored and run on a server that is in a remotelocation from the calling client.

Resource manager (RM)Provides access to shared resources such as database servers, file servers, and printservers.

Rolled back transactionA completed transaction whose changes to any shared resources are nullified.

Tightly coupled transactionsShare locks and appear to the resource manager as one client.

TransactionA whole unit of work consisting of one or more computational tasks. Most often, atransaction’s tasks manipulate shared resources to accomplish a business function.An example is a deposit to a bank checking account.

Transaction boundaryAn application defines a transaction’s start and end points with begin and commitor rollback requests for that transaction.

Transaction branchA portion of the work that makes up a global transaction. Transaction branches arededicated: once the transaction manager starts the two-phase commit protocol ona branch, the resource manager cannot perform any other work on that branch.

Title for Your Book’s Footers Glossary-3


Transactional contextA way to associate all the work that belongs to a particular transaction with thattransaction.

Transaction identifierAn identifier that a transaction manager assigns to a transaction. The transactionmanager uses the transaction identifier to coordinate all activity related to a globaltransaction. The resource manager uses the transaction identifier to match therecoverable tasks it performed for the transaction.

Transaction monitor (TM)Assures that the application’s work is contained in a global transaction thatcommits or aborts atomically.

Transaction processingA system of coordinating the transactions that multiple users perform on shared,centralized resources. The application program defines the beginning and end of aglobal transaction. The transaction monitor oversees transaction completion.

TUXEDOA transaction processing monitor, available from BEA Systems Inc., that providestransaction management in the distributed environment.

Two-phase commit protocolA protocol that ensures the integrity and consistency of all protected resources thatare affected by a distributed transaction.

TX interfaceThe interface between a distributed transaction processing application and atransaction manager.

XA interfacesX/Open’s proposal for a portable application programming interface (API)between the resource manager and the transaction manager.

XA SpecificationAn X/Open specification that specifies an industry standard for the interfacebetween the distributed transaction processing components, resource managerand transaction manager.

Glossary-4


X/OpenA nonprofit organization founded to develop standards for interoperabilitybetween unlike systems.

X/Open DTP ModelAn industry standard for distributed transaction processing applications thatincludes the XA specification.

XA-Server Integration Guide for TUXEDO Index-1

Index

AApplication (AP) 1-2, 1-3, 2-2

and configuration files 3-2samples 5-10starting 2-12tools 2-4

Application server process 2-7Architectural overview 2-1 to 2-17at connection name clause 5-4ATMI 2-10Atomicity 1-4

Bbegin transaction command 5-3Boundaries, transaction 1-3, 1-4Branch

transaction A-1Branch, transaction 3-3

CCallbacks 5-6Capabilities 3-4, 3-6, 3-7

TP monitor 2-2valid for XA-Library 3-7

Client-Library 2-2, 2-4capabilities 3-4properties 3-4

Client queries 3-3Commit 1-3, 1-5, 2-15

example 2-14commit command 5-3Committed transaction 2-14commit transaction command 5-3Communication in X/Open Model 1-3Completion, heuristic 1-5, A-1Components

SYBASE 3-1X/Open DTP 1-3

Concepts 1-1 to 2-17scenario 2-7 to 2-17SYBASE DTP 2-1 to 2-17Sybase specific ?? to 3-10X/Open DTP 1-2 to 1-6

Configurationof servers 3-3

Configuration files 3-1, 3-1 to 3-10and application 3-2interfaces 3-3syntax 3-6UBBCONFIG 3-9XA configuration 3-4 to 3-8

Connection handle 5-5Connections 3-1, 3-1 to 3-3

and LRMs 2-3and X/Open DTP model 2-3, 5-1current 5-4default 5-4establishing 3-3in traditional SYBASE TP 5-1management 5-3

Consistency 1-4Context, transactional 2-12, 2-13Control

flow of 2-10Conventions, syntax xivCoordinating recovery 2-14create command 2-2CS_COMMAND structure 5-5cs_config command 5-3cs_ctx_drop command 5-3, 5-4cs_ctx_global command 5-3cs_diag command 5-3cs_objects command 5-4ct_close command 5-3ct_command command 5-3ct_con_alloc command 5-3ct_con_drop command 5-3ct_con_props command 5-3ct_config command 5-4

Index-2


ct_connect command 5-4ct_cursor command 5-3ct_dynamic command 5-3ct_exit command 5-4ct_getloginfo command 5-4ct_init command 5-4ct_options command 5-4ct_remote_pwd command 5-4ct_setloginfo command 5-4Current connection 5-4

DDatabase example 2-9Database work 2-2Debugging tools 4-1Default connection 5-4Default database 3-9, 5-2delete command 2-2Distributed transaction processing

X/Open DTP 1-1, 1-2Documents, related xiiDTP. See Distributed transaction

processingDTP Scenario 2-8Durability 1-4

EEmbedded SQL 2-12, 3-1, 5-4

invalid commands 5-3Establishing connections 3-3Example

commit 2-14initiating 2-12interfaces file 3-4terminating the transaction 2-13two-phase commit 2-13XA configuration file 3-5

FFailure example 2-16Failure recovery 1-3

Fault tolerance 1-1Files

example interfaces file 3-4example XA configuration file 3-5interfaces 3-3, 3-3 to 3-4XA configuration 3-3, 3-4 to 3-8

Flow of control 2-10Functionality, TP monitor 2-2Functions

TX 2-10XA 2-10

GGlobal identifiers 1-3Global recovery 1-5Global transaction 3-3

context 2-13coordinating 2-12example 2-9

HHarness 5-10Heuristic

completion 1-5, A-1condition, mixed 1-6, 2-15transactions, managing 3-1

IIdentifier 1-4

global 1-3Initiation, transaction 1-4, 2-12Interfaces 1-3

native 1-3, 3-1TX 1-4XA 1-4, 2-4

Interfaces file 3-1, 3-3, 3-3 to 3-4example 3-4

Introduction 1-1, 2-1Isolation 1-4



KKeywords 3-7

LLoad balancing 1-1Locks A-1logfile, in open string 3-10Log files 4-2, 4-4Logical Resource Manager (LRM) 3-1 to

3-10and connections 2-3description 3-6

lrm_name, in open string 3-9LRM name 3-9LRM names 2-3

MManagement

connection 5-3heuristic transactions 3-1transaction 5-3

Master database 3-9, 5-2Mixed heuristic condition 1-6, 2-15Model

functional 2-1process 2-7X/Open DTP 1-2

Money transfer example 2-8Multiple databases 2-9Multiple processes

and simultaneous transactions 2-7environment 2-7

Nnames 3-4Naming services 1-1Native interface 1-3, 3-1Note xiv

OOpen Client Client-Library 2-4, 3-1Open Server 2-5Open string 3-9

format 3-9parameters 3-9

Options 3-6, 3-7, 3-8Overview

architectural 2-1 to 2-17of basic concepts 1-1 to 2-17of this guide xii

PPassword 3-3, 3-9

in open string 3-9Prepare phase 2-15Presentation services 1-1Procedures

stored A-1Procedures, stored 3-1Process

model 2-7overview 2-6server 2-7shut down 2-17start up 2-12

Programming guidelines 5-1 to 5-10Properties 3-4, 3-6, 3-7

valid for XA-Library 3-7Protocol, two-phase commit 1-3, 1-5

RRecovery 1-1, 1-5, 2-14 to 2-17, 5-2, A-1Recovery scenarios 2-15References, additional xiiRelated documents xiirentapp 5-10Resource manager (RM) 1-2, 1-3rmid parameter 2-12Roll back 1-5, 2-14rollback command 5-3

Index-4


rollback transaction command 5-3

SSample programs 5-10Scenario 2-8Security 1-1Server process 2-7set command 5-3set connection command 5-4Shutting down 2-17Software

architecture 2-1components 3-1tools 2-4

sp_xa_clean_xact A-1, A-2sp_xa_finish_xact A-1, A-4 to A-5sp_xa_finish_xact procedure 2-15sp_xa_scan_xact A-1, A-6 to A-7sp_xa_scan_xact procedure 2-15SQL, embedded 2-12SQL commands, invalid 5-3SQL Server 2-5

configuration 3-3, 3-4identifying 3-1

Startingthe application 2-12the transaction 1-4

State transitions 2-5, 4-1, 4-2Stored procedures 3-1, A-1

sp_xa_finish_xact procedure 2-15sp_xa_scan_xact procedure 2-15

SYBASE DTP 2-1 to 2-17Sybase-specific information ?? to 3-10SYBASE TP, traditional

vs. X/Open DTP model ?? to 5-2Syntax, XA configuration file 3-6Syntax conventions xiv

TTable attribute 2-13Teller’s interactions 2-9Terminating the transaction 2-12, 2-13

Threads, sharing information 2-7Three-tier applications 2-2Tools, applications 2-4Tow-Phase Commit Protocol

commit phase 1-5TP monitor 2-5

and multiple processes 2-7and multithreading 2-7and spanning processes 2-7functionality 1-1, 2-2

trace_flag, in open string 3-10Transaction

branch A-1committed 1-5, 2-14completing 1-5context 2-13example 2-8global 3-3, 5-2identifier 1-4initiation 1-4, 2-12limitation on 5-1local 5-2management 5-3roll back 1-5, 2-14termination 2-12, 2-13work 2-12

Transactional context 2-12, 2-13Transaction boundaries 1-3, 1-4Transaction hazard warning 1-6, 2-15,

2-17Transaction ID 2-5Transaction manager (TM) 1-2, 1-3Transaction processing 1-1Transaction processing monitor.

See TP monitorTransact-SQL

invalid commands 5-3Two-phase commit 1-5, 2-14

in example 2-13Two-Phase Commit Protocol

prepare phase 1-5tx_begin command 2-12tx_close command 2-17tx_commit command 5-4



tx_ok command 2-12tx_open command 2-12TX interface 1-4

functions 2-10Typeface conventions xiv

UUBBCONFIG file 3-9update command 2-2User name 3-3, 3-9

in open string 3-9

WWarning, meaning of xvWork, transaction 2-12

XX/Open DTP model 1-2 to 1-6

and connections 2-3communication 1-3components 1-3interfaces 1-3vs SYBASE TP ?? to 5-2

X/Open DTP system 2-10xa_commit command 2-14xa_end command 2-13xa_ok command 2-12xa_open command 2-12xa_prepare command 2-14xa_start command 2-12XA configuration file 3-1, 3-3, 3-4 to 3-8

example 3-5syntax 3-6

XA environment components 3-1XA interface 1-4, 2-4, 3-1

functions 2-10XA-Library 2-4, 3-1XA-Server 2-5, 3-1

configuration 3-3, 3-4identifying 3-1introduction to 2-1

XA-Server Library log 4-2XA-Server log file 4-4XID. See Transaction ID

Index-6
