ISO/IEC 14834:1996
(Main)Information technology — Distributed Transaction Processing — The XA Specification
Information technology — Distributed Transaction Processing — The XA Specification
Specifies the bidirectional interface between a transaction manager and a resource manager (the XA interface) in an X/Open Distributed Transaction Processing (DTP) environment. Technically identical to X/Open CAE Specification. Contains also the text of the X/Open DTP Reference Model Version 3.
Technologies de l'information — Traitement transactionnel réparti — La spécification XA
General Information
Standards Content (Sample)
ISO/IEC
INTERNATIONAL
14834
STANDARD
First edition
1996-08-I 5
Information technology - Distributed
Transaction Processing - The XA
Specification
Traitemen t transactionnel rkparti -
Technologies de /‘information -
La spkifica bon XA
Reference number
ISO/1 EC 14834: 1996(E)
---------------------- Page: 1 ----------------------
ISO/IEC 14834: 1996(E)
Contents
Chapter 1 General .
1.1 Scope .
I .2 X/Open DTP Model .
1.3 Document Structure .
1.4 Normative References .
3
2 Model and Definitions .
Chapter
4
2.1 X/Open DTP Model .
2.2 Definitions . 5
5
2.2.1 Transaction .
5
2.2.2 Distributed Transaction Processing .
5
2.2.3 Application Program .
5
2.2.4 Resource Manager .
6
2.2.5 Global Transactions .
6
2.2.6 Transaction Branches .
6
2.2.7 Transaction Manager .
7
2.2.8 Thread of Control .
7
2.2.9 Tightly- and Loosely-coupled Threads .
8
.........................................
2.3 Transaction Completion and Recovery
2.3.1 . 8
Rolling Back the Global Transaction
2.3.2 . 8
Protocol Optimisations
..................................................... 9
2.3.3 Heuristic Branch Completion
9
2.3.4 .
Failures and Recovery
11
Interface Overview .
Chapter 3
. Index to Services in the XA Interface . 12
31
Opening and Closing Resource Managers . 13
32
Association of Threads with Transaction Branches. . 14
3:3
.......................................... 15
3.3.1 Registration of Resource Managers
...................................................................... 16
3.4 Branch Completion
............... 17
35 . Synchronous, Non-blocking, and Asynchronous Modes
17
36 . Failure Recovery .
19
Chapter 4 The “xa.h”Header .
.................................................................... 19
4.1 Naming Conventions
.............................................................. 19
4.2 Transaction Identification
........................................................... 21
43 Resource Manager Switch
22
414 Flag Definitions .
0 ISO/IEC 1996
All rights reserved. Unless otherwise specified, no part of this publication may be repro-
duced or utilized in any form or by any means, electronic or mechanical, including photo-
copying and microfilm, without permission in writing from the publisher.
lSO/IEC Copyright Office l Case postale 56 l CH-1211 Geneve 20 l Switzerland
Printed in Switzerland
ii
---------------------- Page: 2 ----------------------
olSO/IEC ISO/IEC 14834:1996(E)
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~.
4.5 24
Reference Manual Pages
Chapter 5 . 27
.........................................................................................
28
m-ql()
ax-unreg( ) . 31
xa-close( ) . 32
xa-commit( ) . 34
xa-complete() . 37
xa-end( ) . 38
41
xa-forget() .
...................................................................................... 43
xuwn()
xa-prepare( ) . 45
xa-recover( ) . 48
xa-rollback( ) . 50
xa-start() . 53
Chapter 6 State Tables . 57
61 . Resource Manager lnitialisation . 58
62 Association of Threads of Control with Transactions. . 59
6'2 1 Dynamic Registration of Threads . 59
6:3' Transaction States . 61
64 . Asynchronous Operations . 63
Implementation Requirements . 65
Chapter 7
7.1 Application Program Requirements . 65
7.2 Resource Manager Requirements . 66
7.2.1 The Application Program (Native) Interface . 68
7.3 Transaction Manager Requirements . 69
Complete Text of “xa.h” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Appendix A
DTP Model - Introduction . 75
Appendix B
Overview . 75
Bl .
Benefits of X/Open DTP . 76
B2 .
................................................................... 76
B3 . Areas Not Addressed
........................................ 76
84 . Relationship to International Standards
..................................................... 77
Appendix C DTP Model - Definitions
................................................................. 77
Cl . Transaction Definitions
......................................................................... 79
c2 . Model Definitions
...................................................... 81
Appendix D DTP Model - The Model
82
Dl . Functional Model .
............................................................... 83
D2 Functional Components
.......................................................... 83
D’2 . 1 Application Program (AP)
........................................................ 83
D’2 . 2 Transaction Manager (TM)
........................................................... 83
D-2 . 3 Resource Manager (RM)
............................... 84
D-2 . . 4 Communication Resource Manager (CRM)
. . .
III
---------------------- Page: 3 ----------------------
I SO/I EC
ISO/IEC 14834:1996(E)
.......................... . . . . . . . 85
03 Interfaces between Functional Components
....................................... . . . . . . . 85
D-3 . 1 Functional Component Interfaces
87
D-3 . . 2 Data Interfaces .
....................................................... 88
D4 Activity Involving a Single AP
................................................................. 88
D’4 . 1 Transaction Initiation
............................................................ 88
D’4 . 2 Transaction Association
88
D-4 . 3 Transaction Commitment .
89
D’4 . 4 Transaction Rollback .
.............................................. 89
D-4 . 5 Heuristic Transaction Completion
90
D-4 . . 6 Recovery after Failure .
............................................ 91
D5 Distributed Communication Facilities
.......................................... 91
D’5 . 1 Communication within TM Domains
......................................... 91
D-5 . 2 Communication across TM Domains
91
D’5 . 3 Sharing Resources across TM Domains .
91
D’5 . 4 Global Transaction Demarcation .
91
D’5 . 5 Global Transaction Tree Structure .
........................... 92
D’5 . 6 Global Transactions and the Transaction Tree
....................................... 93
D-5 . 7 Tightly- and Loosely-coupled Threads
93
D’5 . . 8 Commitment Coordination .
94
D6 Activity Involving Two or More APs .
94
D’6 * 1 Transaction Initiation .
94
D’6 . 2 Transaction Association .
94
D’6 . 3 Transaction Commitment .
95
D’6 . 4 Transaction Rollback .
95
D’6 . 5 Heuristic Transaction Completion .
95
Recovery after Failure .
D’6 . l 6
96
CRM Communication Paradigms with APs .
D7
96
D’7 . 1 The TxRPC Interface .
96
D-7 . 2 The XATMI Interface .
97
. The CPI-C Version 2 Interface .
D’7 3
97
Relationships between the Communication Paradigms. .
D’7 . . 4
............................................................... 98
D8 . High-level TP Language
- Frequently Asked Questions . . . . . . . . . . . . . . . . . . . 99
Appendix E DTP Model
103
Appendix F Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
105
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of Figures
4
2-1 Functional Components and Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
The XA Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-1
79
A TM Domain with Four Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .”
C-l
82
Functional Components and Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D-l
92
Global Transaction Tree Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D-2
101
Projection of Model onto Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E-l
iV
---------------------- Page: 4 ----------------------
oISO/lEC
ISO/IEC 14834:1996(E)
List of Tables
4-1 Flags used in Particular Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6-l State Table for Resource Manager lnitialisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6-2 State Table for Transaction Branch Association .a.,*. 59
6-3 State Table for Transaction Branch Association (Dynamic Registration) 60
6-4 State Table for Transaction Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
State Table for Asynchronous Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6-5
---------------------- Page: 5 ----------------------
ISO/IEC 14834:1996(E) 0 lSO/IEC
Foreword
IS0 (the International Organization for Standardization) and IEC (the Inter-
national Electrotechnical Commission) form the specialized system for
worldwide standardization. National bodies that are members of IS0 or
IEC participate in the development of International Standards through
technical committees established by the respective organization to deal
with particular fields of technical activity. IS0 and IEC technical com-
mittees collaborate in fields of mutual interest. Other international organiz-
ations, governmental and non-governmental, in liaison with IS0 and IEC,
also take part in the work.
In the field of information technology, IS0 and IEC have established a joint
technical committee, ISO/IEC JTC 1. Draft International Standards adopted
by the joint technical committee are circulated to national bodies for vot-
ing. Publication as an International Standard requires approval by at least
75 % of the national bodies casting a vote.
International Standard ISO/IEC 14834 was prepared by X/Open Company
Ltd. (as XO/CAE/91/300) and was adopted, under a special “fast-track pro-
cedure”, by Joint Technical Committee lSO/IEC JTC 1, information tech-
nology, in parallel with its approval by national bodies of IS0 and IEC.
Appendix A forms an integral part of this International Standard. Appen-
dices B to F are for information only.
vi
---------------------- Page: 6 ----------------------
0 lSO/IEC ISOJIEC 14834: 1996(E)
Introduction
(This introduction is not a normative part of ISO/IEC 14834, Information technology-Distributed
-The XA Specification, but is included for information only.)
Transaction Processing
This International Standard specifies the bidirectional interface between a transaction manager
and resource manager (the XA interface) in an X/Open Distributed Transaction Processing
(DTP) environment. It is based on X/Open CAE Specification, Distributed Transaction
Processing: The XA Specification (December 1991). This International Standard is technically
identical to the X/Open version. For informative purposes, this International Standard also
contains the text of the X/Open DTP Reference Model Version 3 which X/Open has published as
a separate Guide.
Typographical Conventions
The following typographical conventions are used throughout this document:
l Constant width strings are code examples or literals and are to be typed just as they
appear.
l italic strings are used for emphasis or to identify the first instance of a word requiring
definition. Italics also denote:
- variable names
- commands or utilities
- functions; these are shown as follows: name().
l The notation “fi1e.h” indicates a header.
l The notation [ABCD] is the name of a return value.
l Ellipses (. . .) are used to show that additional arguments are optional.
Trademarks
@
X/Open is a registered trade mark, and the “X” device is a trade mark, of X/Open Company
Limited.
vii
---------------------- Page: 7 ----------------------
This page intentionally left blank
---------------------- Page: 8 ----------------------
INTERNATIONAL STANDARD 0 lSO/IEC ISO/IEC 14834:1996(E)
Information technology - Distributed Transaction
Processing - The XA Specification
Chapter I; General
11 8 Scope
This International Standard specifies the XA interface: the bidirectional interface between a
transaction manager and a resource manager in an X/Open Distributed Transaction Processing
(DTP) environment. The XA interface is not an ordinary Application Programming Interface
(API); it is a system-level interface between DTP software components.
This International Standard is technically identical to X/Open CAE Specification, Distributed
Transaction Processing: The XA Specification (December 1991). Like that specification, this
International Standard does not define the full aspects of the DTP model that pertain to
communication.
12 . X/Open DTP Model
The X/Open Distributed Transaction Processing (DTP) model is a software architecture that
allows multiple application programs to share resources provided by multiple resource
managers, and allows their work to be coordinated into global transactions.
The full X/Open DTP model comprises five basic functional components:
l an Application Program (AP), which defines transaction boundaries and specifies actions that
constitute a transaction
as databases or file access systems, which provide access
l Resource Managers (RMs) such
to resources
l a Transaction Manager (TM), which assigns identifiers to transactions, monitors their
progress, and takes responsibil ity for transaction completion and for coordinating failure
recovery.
---------------------- Page: 9 ----------------------
OlSO/IEC
lSO/IEC 14834:1996(E)
l Communication Resource Managers (CRMs), which control communication between
distributed applications within or across TM domains.
l a communication protocol, which provides the underlying communication services used by
distributed applications and supported by CRMs.
1.3 Document Structure
Relevant definitions and other important concepts that pertain to this International Standard are
discussed in Chapter 2. That chapter also defines the AP, TM, and RM in more detail, and
describes their interaction. Chapter 3 is an overview of the XA interface, describing the
situations in which each of the services is used. Chapter 4 discusses the data structures that
are part of the XA interface. Reference manual pages for each routine in the XA interface are
presented in Chapter 5; state tables follow in Chapter 6. Chapter 7 summarises the implications
of this International Standard on the implementors of RMs and TMs; it also identifies features
that are optional. Appendix A presents the contents of an “xa.h” header file in both ANSI C and
Common Usage C. Appendix F contains a bibliography.
For informative purposes, this International Standard also contains the text of the X/Open DTP
Reference Model Version 2 (November 1993) which X/Open publishes as a separate Guide.
(See Appendix B, Appendix C, Appendix D, and Appendix E.)
14 m Normative References
The following standards contain provisions which, through reference in this text, constitute
provisions of this International Standard. At the time of publication, the editions indicated were
valid. All standards are subject to revision, and parties to agreements based on this
International Standard are encouraged to investigate the possibility of applying the most recent
editions of the standards indicated below. Members of IEC and IS0 maintain registers of
currentlv valid International Standards.
a
Systems Interconnection-
1 . ISOAEC 8824:1990, lnforma tion technology-Open
Specification of Abstract Syntax Notation One (ASN. I).
Interconnection-
2 . ISOAEC 8825:1990, lnforma tion technology-Open Systems
Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN. I).
3 . I SO/I EC 9804: 1994, lnforma tion technology-Open Sys terns Interconnection-Service
definition for the commitment, concurrency and recovery service element.
4 . ISOAEC 9805-l : 1994, Information technology-Open Systems Interconnection-Protocol
for the Commitment, Concurrency and Recovery service element: Protocol Specification.
5 . ISOAEC 9899: 1990, Programming languages-C.
6 . lSO/IEC 10026-l :1992, Information technology-Open Systems Interconnection-
Distributed Transaction Processing-Part 1: OSI TP Model.
7 . ISOAEC 10026-2:1996, Information technology-Open Systems Interconnection-
Distributed Transaction Processing-Part 2: OSI TP Service.
.
8 ISOAEC 10026-3:1996, Information technology-Open Systems Interconnection-
Distributed Transaction Processing-Part 3: Protocol Specification.
See 4ppendix F for bibliographic references.
---------------------- Page: 10 ----------------------
OISO/IEC
ISO/IEC 14834:1996(E)
Chapter 2: Model and Definitions
This chapter discusses the XA interface in general terms and provides necessary background
material for the rest of this International Standard. The chapter shows the relationship of the
interface to the X/Open DTP model. The chapter also states the design assumptions that the
interface uses and shows how the interface addresses common DTP concepts.
3
---------------------- Page: 11 ----------------------
ISO/IEC 14834:1996(E)
olSO/I EC
2.1 X/Open DTP Model
The boxes in Figure 2-l are the functional components and the connecting lines are
the
interfaces between them. The arrows indicate the directions in which control may flow.
SUPERIOR NODE
I
Application Program (Al?)
piz&Kq ]I /
SUBORDINATE NODE
I
I I I I ttt
I
Al?
(1) (2) (5) I
I
I
1
I
7 I’ VT
1’ ,I l ,
1
I
(4) Communication
(3)
Resource .
,.Transaction., +.
I
Resource
*- Manager .* *.
b- Managers I
ww _- (TM)
(C~s) I
L 1
t
I
I
I
I
I
I
I
Figure 2-I Functional Components and Interfaces
The numbers in brackets in Figure 2-l represent the different X/Open interfaces that are used in
the DTP model. The subject of this International Standard is interface (3): the XA interface by
which TMs and RMs interact. Descriptions of the functional components relevant to this
International Standard can be found in Section 2.2 on page 5. For more details of the the DTP
model as shown in Figure 2-1, including definitions of all components and interfaces, see
Appendix B, Appendix C, Appendix D, and Appendix E.
---------------------- Page: 12 ----------------------
OISO/IEC
ISOhEC 14834:1996(E)
2.2 Definitions
2.2.1 Transaction
A transaction is a complete unit of work. It may comprise many computational tasks, which may
include user interface, data retrieval, and communications. A typical transaction modifies
(The referenced OSI TP standard (model) defines transactions more
shared resources.
precisely.)
Transactions must be able to be rolled back. A human user may roll back the transaction in
response to a real-world event, such as a customer decision. A program can elect to roll back a
transaction. For example, account number verification may fail or the account may fail a test of
its balance. Transactions also roll back if a component of the system fails, keeping it from
retrieving, communicating, or storing data.
Every DTP software component subject to
transaction control must be able to undo its work in a transaction that is rolled back at any time.
When the system determines that a transaction can complete without failure of any kind, it
commits the transaction. This means that changes to shared resources take permanent effect.
Either commitment or rollback results in a consistent state. Completion means either
commitment or rollback.
2.2.2 Distributed Transaction Processing
Within the scope of this International Standard, DTP systems are those where work in support of
a single transaction may occur across RMs. This has several implications:
l The system must have a way to refer to a transaction that encompasses all work done
anywhere in the system.
l The decision to commit or roll back a transaction must consider the status of work done
anywhere on behalf of the transaction. The decision must have uniform effect throughout the
DTP system.
Even though an RM may have a standard interface, such as Structured Query Language (SQL),
it must also address these two items to be useful in the DTP environment.
2.2.3 Application Program
The AP defines transactions and accesses resources within transaction boundaries. Each AP
specifies a sequence of operations that involves resources such as terminals and databases.
This International Standard generally uses the term AP to refer to a single instance of an
application program.
2.2.4 Resource Manager
An RM manages a certain part of the computer’s shared resources. Many other software
entities can request access to the resource from time to time, using services that the RM
provides. Here are some examples of RMs:
l A database management system (DBMS) is an RM. Typical DBMSs are capable of defining
transactions and committing work atomically.
l A file access method such as the Indexed Sequential Access Method (ISAM) can be the
basis for an RM. Typically, an ISAM RM must be enhanced to support transactions as
defined herein.
l A print server might be implemented as an RM.
---------------------- Page: 13 ----------------------
ISO/IEC 14834:1996(E) @ISO/IEC
A single RM may service multiple independent resource domains. An RM instance services one
of these domains. (See also Section 3.2 on page 13.) Unless specified otherwise, operations
this International Standard allows on an RM are allowed on each RM instance.
2.2.5 Global Transactions
Every RM in the DTP environment must support transactions as described in Section 2.2.1 on
page 5. Many RMs already structure their work into recoverable units.
In the DTP environment, many RMs may operate in support of the same unit of work. This unit
of work is a global transaction (which is normally equivalent to an OSI TP transaction when OSI
TP is used as the communication protocol; see the referenced OSI TP standards). For
example, an AP might request updates to several different databases. Work occurring
anywhere in the system must be committed atomically. Each RM must let the TM coordinate
the RM’s recoverable units of work that are part of a global transaction.
Commitment of an RM’s internal work depends not only on whether its own operations can
succeed, but also on operations occurring at other RMs, perhaps remotely. If any operation fails
anywhere, every participating RM must roll back all operations it did on behalf of the global
transaction. A given RM is typically unaware of the work that other RMs are doing. A TM
informs each RM of the existence, and directs the completion, of global transactions. An RM is
responsible for mapping its recoverable units of work to the global transaction.
2.2.6 Transaction Branches
A global transaction has one or more transaction branches (or branches). A branch is a part of
the work in support of a global transaction for which the TM and the RM engage in a separate
but coordinated transaction commitment protocol (see Section 2.3 on page 8). Each of the
RM’s internal units of work in support of a global transaction is part of exactly one branch. (The
term transaction branch does not necessarily have the same meaning as in OSI TP. The
concept is the same, but the parties may be different; see the referenced OSI TP standards.)
A global transaction might have more than one branch when, for example, the AP uses multiple
processes or is involved in the same global transaction by multiple remote APs.
After the TM begins the transaction commitment protocol, the RM receives no additional work to
do on that transaction branch. The RM may receive additional work on behalf of the same
transaction, from different branches. The different branches are related in that they must be
completed atomically.
Each transaction branch identifier (or XID - see Section 4.2 on page 19) that the TM gives the
RM identifies both a global transaction and a specific branch. The RM may use this information
to optimise its use of shared resources and locks.
2.2.7 Transaction Manager
TMs manage global transactions, coordinate the decision to commit them or roll them back, and
coordinate failure recovery. The AP defines the start and end of a global transaction by calling a
TM. The TM assigns an identifier to the global transaction (see Section 4.2 on page 19). The
TM manages global transactions and informs each RM of the XID on behalf of which the RM is
doing work. Although RMs can manage their own recoverable work units as they see fit, each
RM must accept XlDs and associate them with those work units. In this way, an RM knows
what recoverable work units to complete when the TM completes a global transaction.
---------------------- Page: 14 ----------------------
OISO/IEC
ISOhEC 14834:1996(E)
2.2.8 Thread of Control
A thread of control (or a thread) is the entity, with all its context, that is currently in control of a
processor. A thread of control is an operating-system process: an address space and single
thread of control that executes within that addr
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.