____________________________________________________ DECdtm XA Profile November, 1993 This document describes Digital's implementation of the X/Open DTP XA interface. This is an interface between DECdtm and resource managers. This document is for third-party vendors, independent software vendors, and Digital customers for evaluation purposes only. The code is provided "as is". Use of this code is at the risk of the user. Digital does not guarantee conformance to the XA standard with this implementation. Digital welcomes any comments on this XA Profile. Please contact Digital using one of the addresses given below. Internet address: xa_profile@edo.mts.dec.com Postal address: XA Profile OpenVMS Engineering Peel House Livingston UK EH54 6AG DIGITAL Copyright Statement The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in subparagraphs (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1993 Digital Equipment Corporation. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: OpenVMS DIGITAL DECdtm services This document was prepared using VAX DOCUMENT, Version 2.1. _________________________________________________________________ Contents Preface................................................... iv 1 Differences 1.1 XA Functions.................................. 1-1 1.2 Threads....................................... 1-1 1.3 Return Values................................. 1-1 1.4 Asynchronous operations....................... 1-2 2 Using the XA Interface to DECdtm 2.1 Connecting a Resource Manager to DECdtm....... 2-1 2.2 Disconnecting a Resource Manager from DECdtm........................................ 2-2 2.3 Joining a Resource Manager to a Transaction... 2-2 2.4 Executing Transactions........................ 2-3 2.5 Performing Recovery........................... 2-3 2.5.1 Starting Recovery......................... 2-3 2.5.2 Recovery Processing....................... 2-4 2.6 Completing Transactions Heuristically......... 2-5 2.7 How To Access The XA Functions................ 2-5 3 XA Functions ax_bind_decdtm...................................... 3-3 iii ax_lock_decdtm...................................... 3-7 ax_reg.............................................. 3-9 ax_unbind_decdtm.................................... 3-11 ax_unlock_decdtm.................................... 3-13 ax_unreg............................................ 3-15 xa_close............................................ 3-16 xa_commit........................................... 3-18 xa_complete......................................... 3-21 xa_end.............................................. 3-22 xa_forget........................................... 3-24 xa_open............................................. 3-26 xa_prepare.......................................... 3-28 xa_recover.......................................... 3-31 xa_rollback......................................... 3-34 xa_start............................................ 3-37 4 XA Data Structures 4.0.1 The XA Switch Structure................... 4-1 4.0.2 The Transaction Identifier Structure, XID....................................... 4-2 A The XA Data Switch Structure B Rollback Statuses Index Figures 4-1 The XID Structure......................... 4-2 iv Tables B-1 XA_RB* - Values and Meanings.............. B-1 v _________________________________________________________________ Preface Intended Audience Read this document if you are implementing the XA interface between a resource manager and Digital's distributed transaction manager, DECdtm. Before you read this document, you should be familiar with: o Transaction processing o The software components in a distributed transaction processing environment o Database terminology o The XA standard Associated Documents See the following documents for more information: o The X/Open XA specification. o The DECdtm functional specification. Conventions The following conventions are used in this manual: XA_RB* A wildcard expression that refers to all XA return values beginning with XA_RB. iv . . . A horizontal ellipsis in examples indicates one of the following possibilities: o Additional optional arguments in a statement have been omitted. o The preceding item or items can be repeated one or more times. o Additional parameters, values, or other information can be entered. A vertical ellipsis indicates the omission . of items from a code example or command . format; the items are omitted because . they are not important to the topic being discussed. ( ) In format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. v 1 _________________________________________________________________ Differences This chapter summarizes the differences between the standard XA interface and Digital's implementation. 1.1 XA Functions The following functions are DECdtm extensions to the XA interface: o ax_bind_decdtm() - Makes a connection to DECdtm, or starts recovery processing o ax_unbind_decdtm() - Disconnects a resource manager from DECdtm o ax_lock_decdtm() - Prevents DECdtm from calling the resource manager o ax_unlock_decdtm() - Allows DECdtm to call the resource manager again DECdtm never calls the xa_complete() function. 1.2 Threads The Digital implementation does not support DECthreads or POSIX p-threads. When reading the XA specification, a thread should be regarded as equivalent to a process. 1.3 Return Values The Digital implementation does not support all the return values in the standard XA interface. Any return value that is not listed in a Return Values section of Chapter 3 is treated as a XAER_RMERR return value. Differences 1-1 Differences 1.4 Asynchronous operations 1.4 Asynchronous operations The Digital implementation does not permit asynchronous operations. 1-2 Differences 2 _________________________________________________________________ Using the XA Interface to DECdtm This chapter is divided into the following topics: o Connecting a resource manager to DECdtm (Section 2.1) o Disconnecting a resource manager from DECdtm (Section 2.2) o Joining a resource manager to a transaction (Section 2.3) o Executing transactions (Section 2.4) o Doing recovery (Section 2.5) o Completing transactions heuristically (Section 2.6) o How to access the XA functions (Section 2.7) For a detailed description of the XA functions, see Chapter 3. 2.1 Connecting a Resource Manager to DECdtm Before a resource manager can take part in transaction processing, it must make a connection to DECdtm. To make the connection, the resource manager calls ax_bind_ decdtm() with the DDTM_M_DECLARE flag set. On receiving the ax_bind_decdtm() call, DECdtm calls xa_open(). This allows the resource manager to do any initialization, such as opening files, or establishing a path to a server. Using the XA Interface to DECdtm 2-1 Using the XA Interface to DECdtm 2.2 Disconnecting a Resource Manager from DECdtm 2.2 Disconnecting a Resource Manager from DECdtm At the end of transaction processing, a resource manager should call ax_unbind_decdtm(). This disconnects the resouce manager from DECdtm services. A resource manager should call ax_unbind_decdtm(): o At the end of normal transaction processing o On detecting a serious error condition On receiving the ax_unbind_decdtm() call, DECdtm calls xa_ close(). 2.3 Joining a Resource Manager to a Transaction A resource manager is joined to a transaction in one of two ways: o DECdtm calls xa_start() If the TMREGISTER flag of the resource manager's xa_ switch_t structure is clear, DECdtm joins the resource manager to every transaction by calling xa_start(). The resource manager should clear the TMREGISTER flag before calling ax_bind_decdtm() if it wants to be considered part of all transactions. o The resource manager calls ax_reg() If the TMREGISTER flag of the resource manager's xa_ switch_t structure is set, the resource manager calls ax_reg() for each transaction it wants to join. The resource manager should set the TMREGISTER flag before calling ax_bind_decdtm() if it wants to join only a few transactions. The application program must instruct the resource manager when to join a transaction. Note that the resource manager passes the value of the TMREGISTER flag to DECdtm only when it calls ax_bind_ decdtm(). 2-2 Using the XA Interface to DECdtm Using the XA Interface to DECdtm 2.4 Executing Transactions 2.4 Executing Transactions While the resource manager is executing operations on behalf of a transaction, it must ensure that DECdtm does not roll back the transaction. Unlike the XA transaction processing model, DECdtm allows a transaction to be rolled back at any point in the transaction. To prevent DECdtm rolling back the transaction, the resource manager should call ax_lock_decdtm() straight after it receives a call from an application to do work on behalf of the transaction. This prevents DECdtm from making any xa_ calls. Before returning from the application's call, the resource manager should call ax_unlock_decdtm(). This allows DECdtm to make xa_ calls again. 2.5 Performing Recovery ________________________ Note ________________________ To perform recovery in user or supervisor mode, the resource manager must have the SYSPRV privilege. ______________________________________________________ This section describes: o Starting recovery o Recovery processing 2.5.1 Starting Recovery To start recovery, the resource manager must call ax_bind_ decdtm() with the DDTM_M_RECOVER flag set. The resource manager must also: o Specify the identifier of the transaction log to be used for recovery in logid_in. If the resource manager was running on a node in a VMScluster, it can be recovered from another node in the cluster. To start recovery from another node, the resource manager must: o Set both the DDTM_M_RECOVER and DDTM_M_OTHER flags in the ax_bind_decdtm() call. Using the XA Interface to DECdtm 2-3 Using the XA Interface to DECdtm 2.5 Performing Recovery o Specify the identifier of the transaction log to be used for recovery in logid_in. o Specify the name of the node whose transaction log is to be used for recovery in node_name_in. This is the node that the resource manager was running on when the failure occurred. 2.5.2 Recovery Processing On receiving an ax_bind_decdtm() call, DECdtm calls xa_ recover() with the TMSTARTRSCAN flag set. This call also passes the following parameters to the resource manager: o xids - An array into which the resource manager can place XID structures o count - The maximum number of XID structures that can fit into the xids array o rmid - The identifier of the resource manager On receiving the xa_recover() call, the resource manager starts a recovery scan. The resource manager places a list of transaction branch identifiers (XIDs) of transaction branches to be recovered into the xids array. These are transaction branches that are in a prepared or heuristically completed state. On successful completion of the xa_recover() call, the resource manager returns the number of XIDs that it placed in the xids array. If the resource manager fills the array, the DECdtm services call xa_recover() again, with the TMSTARTRSCAN flag clear. On receiving the call, the resource manager can continue the recovery scan, and place the next XIDs into the array. DECdtm continues to make xa_recover() calls until the return value from the last xa_recover() call is less than count. DECdtm then returns from ax_bind_decdtm(). Note that DECdtm may not have finished recovery before returning from ax_bind_decdtm(). The resource manager should not call ax_unbind_decdtm() until all the transactions are recovered. 2-4 Using the XA Interface to DECdtm Using the XA Interface to DECdtm 2.5 Performing Recovery For each transaction branch that was in a prepared state, DECdtm makes one of the following calls: o xa_commit() o xa_rollback() For each transaction branch that was heuristically completed, DECdtm sends a xa_forget() call. 2.6 Completing Transactions Heuristically ________________________ Note ________________________ Digital does not recommend that a resource manager completes transactions heuristically. ______________________________________________________ If a resource manager heuristically completes a transaction, it should return a XA_HEUR* value on completing a xa_commit() or a xa_rollback() call. The resource manager must do all notification and handling of the heuristic decision before returning from the call. It must not forget about the transaction branch until it receives an xa_forget() call from DECdtm. On receiving an XA_ HEUR* return value, DECdtm calls xa_ forget(). 2.7 How To Access The XA Functions To use the XA functions, you must link your resource manager's object modules against SYS$LIBRARY:DECDTM_XA.OBJ. This object module contains the code which provides the XA interface to DECdtm. Definitions of the data structures and constants required to use the XA interface can be found in SYS$LIBRARY:XA.H. Note for VAX users: This object module is compiled with VAX C, and so needs access to the VAX C run time library. Any program which links against DECDTM_XA.OBJ must also link against SYS$SHARE:VAXCRTL.EXE. Using the XA Interface to DECdtm 2-5 3 _________________________________________________________________ XA Functions This chapter describes Digital's implementation of the XA functions. The functions described in this chapter are: ___________________________________________________________ Function______________Description__________________________ ax_bind_decdtm()++ Connects a resource manager to DECdtm services, or starts recovery processing ax_lock_decdtm()++ Prevents DECdtm services from calling the resource manager ax_reg() Joins a resource manager to a transaction ax_unbind_ Disconnects a resource manager from decdtm()++ DECdtm services ax_unlock_ Allows DECdtm services to call the decdtm()++ resource manager again ax_unreg() Removes a resource manager from a transaction xa_close() Informs the resource manager that DECdtm is closing the connection to the resource manager xa_commit() Instructs the resource manager to commit work done on behalf of a transaction branch xa_complete()+ Asks the resource manager whether it completed an asynchronous transaction +DECdtm_never_calls_this_function._________________________ ++This function is an extension to the standard XA interface XA Functions 3-1 XA Functions ___________________________________________________________ Function______________Description__________________________ xa_end() Informs the resource manager that a transaction branch has ended xa_forget() Informs the resource manager that it can forget about a heuristically completed transaction xa_open() Instructs the resource manager to do any initialization needed xa_prepare() Instructs the resource manager to prepare to commit work done on behalf of a transaction branch xa_recover() Asks the resource manager for a list of transaction branches to be recovered xa_rollback() Instructs the resource manager to roll back work done on behalf of a transaction branch xa_start() Informs the resource manager that it ______________________is_joining_a_transaction_____________ Functions that the resource manager calls are prefixed by ax_. Functions that DECdtm calls are prefixed by xa_. Note that DECdtm always calls xa_ functions at non-AST level in the same mode that the resource manager is in. DECdtm never interrupts an xa_ call with another xa_ call. 3-2 XA Functions ax_bind_decdtm _________________________________________________________________ ax_bind_decdtm Makes a connection to DECdtm, or starts recovery processing. Synopsis #include int ax_bind_decdtm (xa_switch_t *rmswitch, long flags, int*rmid_out, char *node_name_out, ddtm_t_logid *logid_out, char *xa_info, char *node_name_in, ddtm_t_logid *logid_in) Parameters Input rmswitch The resource manager's switch structure. DECdtm uses this structure to call the xa_ functions provided by the resource manager. See Section 4.0.1 for a description of the switch structure. See Appendix A for a listing of the switch structure. XA Functions 3-3 ax_bind_decdtm flags Control whether ax_bind_decdtm() makes a connection to DECdtm, starts recovery processing, or both. _______________________________________________ Flag__________________Meaning__________________ DDTM_M_DECLARE Makes a connection between the resource manager and DECdtm . DDTM_M_RECOVER Starts recovery processing. DDTM_M_OTHER_LOG Specifies that DECdtm uses another node's transaction log for recovery processing. This flag is ignored unless the DDTM_M_RECOVER ______________________flag_is_also_set.________ xa_info A null-terminated character string containing contextual information for the resource manager. The maximum length of the string is 256 bytes, including the null terminator. DECdtm does not use the information in xa_info. DECdtm passes this parameter back to the resource manager in xa_open() and xa_close() calls. node_name_ The name of the node whose transaction log in is to be used for recovery. This parameter is ignored unless both the DDTM_M_RECOVER and DDTM_M_OTHER_LOG flags are set. logid_in The identification of the DECdtm transaction log to be used for recovery. This parameter is ignored unless the DDTM_M_RECOVER flag is set. 3-4 XA Functions ax_bind_decdtm Output rmid_out The identifier of the resource manager. This value is unique within the process. node_name_out The name of the local node. logid_out The identifier for the local node's transaction log. Description ________________________ Note ________________________ ax_bind_decdtm() is a DECdtm extension to the XA interface. ______________________________________________________ A resource manager calls ax_bind_decdtm() to: o Make a connection to DECdtm. A resource manager must make a connection to DECdtm before it can take part in transaction processing. To make a connection to DECdtm, the resource manager calls ax_bind_decdtm() with the DDTM_M_DECLARE flag set. Before returning from xa_bind_decdtm(), DECdtm calls xa_open() to instruct the resource manager to do any initialization needed. o Start recovery. To start recovery, the resource manager must call ax_ bind_decdtm() with the DDTM_M_RECOVER flag set. The resource manager must also: o Specify the identifier of the transaction log to be used for recovery in logid_in If the node that the resource manager was running on is in a VMScluster, the resource manager can start recovery from another node in the cluster by setting both the DDTM_M_RECOVER and DDTM_M_OTHER_LOG flags in the ax_ bind_decdtm() call. In this case, the resource manager must also specify the name of the node whose transaction log is to be be used for recovery in node_name_in. This XA Functions 3-5 ax_bind_decdtm is the node on which the resource manager was running when the failure occurred. Before returning from ax_bind_decdtm(), DECdtm calls xa_recover() to ask the resource manager for a list of transaction branches to be recovered. For more information on recovery, see Section 2.5. Note that a resource manager can both make a connection to DECdtm and start recovery processing by setting the DDTM_M_ DECLARE and DDTM_M_RECOVER flags. Return Values TM_OK Normal execution. TMER_TMERR An internal error occurred within DECdtm. TMER_INVAL One of the following errors occurred: o The arguments are invalid. o The string pointed to by xa_info is longer than 256 characters. Related Information ax_unbind_decdtm(), xa_open() 3-6 XA Functions ax_lock_decdtm _________________________________________________________________ ax_lock_decdtm Prevents DECdtm from calling the resource manager. Synopsis #include int ax_lock_decdtm (void) Description ________________________ Note ________________________ ax_lock_decdtm() is a DECdtm extension to the XA interface. ______________________________________________________ A resource manager calls ax_lock_decdtm() to prevent DECdtm calling the resource manager. This ensures that DECdtm cannot roll back a transaction while the resource manager is in the middle of a transaction operation. The resource manager should call ax_lock_decdtm() immediately after it is called by an application to do work on behalf of a transaction. Immediately before returning from the application's call, the resource manager must call ax_unlock_decdtm(). DECdtm keeps a count of the number of ax_lock_decdtm() calls that the resource manager makes. The count is incremented every time the resource manager calls ax_lock_ decdtm (), and decremented every time the resource manager calls ax_unlock_decdtm (). DECdtm can make calls only when the count is zero. Return Values TM_OK Normal execution. XA Functions 3-7 ax_lock_decdtm Related Information ax_unlock_decdtm() 3-8 XA Functions ax_reg _________________________________________________________________ ax_reg Joins a resource manager to a transaction. Synopsis #include int ax_reg (int rmid, XID *xid, long flags) Parameters Input rmid The identifier of the resource manager. This must be the same as the rmid_out value returned by DECdtm in the ax_bind_decdtm() call. flags Must be set to TMNOFLAGS. Output xid The identifier of the new transaction branch. Note that the resource manager must allocate enough space for the XID, or DECdtm may overwrite existing data. An XID is 44 bytes long. Description Before it can call ax_reg(), a resource manager must have the TMREGISTER flag of its xa_switch_t structure set. Note that a resource manager passes the value of the TMREGISTER flag to DECdtm only when it calls ax_bind_ decdtm(). XA Functions 3-9 ax_reg Providing the resource manager has not already called ax_ reg() during the lifetime of the current transaction, DECdtm: o Creates a new branch of the current transaction and associates the resource manager with this branch o Returns the identifier of the new transaction branch in *xid If the resource manager has already called ax_reg() during the lifetime of the current transaction, DECdtm returns the same *xid value as in the last ax_reg() call. DECdtm does not create a new transaction branch. If the process is not currently involved in a transaction, DECdtm sets the value of the formatID field of *xid to -1, and returns TM_OK. Return Values TM_OK Normal execution. Note that DECdtm returns TM_OK even if the process is not currently involved in a transaction. TM_JOIN Indicates that the resource manager has already joined the transaction. TMER_INVAL This value indicates one of the following: o The arguments are invalid. o The TMREGISTER flag in the resource manager's xa_switch_t data structure is not set. Related Information ax_unreg(), xa_start() 3-10 XA Functions ax_unbind_decdtm _________________________________________________________________ ax_unbind_decdtm Disconnects a resource manager from DECdtm. Synopsis #include int ax_unbind_decdtm (int rmid, long flags) Parameters Input rmid The identifier of the resource manager. This must be the same as the rmid_out value returned by DECdtm in the ax_bind_decdtm() call. flags Must be set to TMNOFLAGS. Description ________________________ Note ________________________ ax_unbind_decdtm() is a DECdtm extension to the XA interface. ______________________________________________________ A resource manager calls ax_unbind_decdtm() to disconnect the resource manager from DECdtm. On receiving the ax_ unbind_decdtm() call, DECdtm calls xa_close(). Return Values TM_OK Normal execution. TMER_INVAL The arguments are invalid. XA Functions 3-11 ax_unbind_decdtm TMER_TMERR The process has run out of ASTLM quota. Related Information ax_bind_decdtm(), xa_close() 3-12 XA Functions ax_unlock_decdtm _________________________________________________________________ ax_unlock_decdtm Allows DECdtm to call to the resource manager again. Synopsis #include int ax_unlock_decdtm (void) Description ________________________ Note ________________________ ax_unlock_decdtm() is a DECdtm extension to the XA interface. ______________________________________________________ A resource manager calls ax_unlock_decdtm() if it has previously called ax_lock_decdtm() and is now ready for calls from DECdtm again. For more information on when a resource manager should call ax_lock_decdtm(), see Section 2.4. DECdtm keeps a count of the number of ax_lock_decdtm () calls that the resource manager makes. The count is incremented every time the resource manager calls ax_lock_ decdtm (), and decremented every time the resource manager calls ax_unlock_decdtm (). DECdtm can call the resource manager only when the count is zero. Return Values TM_OK Normal execution. TMERR_INVAL The resource manager has called ax_ unlock_decdtm() more often than it has called ax_lock_decdtm(). XA Functions 3-13 ax_unlock_decdtm Related Information ax_lock_decdtm() 3-14 XA Functions ax_unreg _________________________________________________________________ ax_unreg Removes a resource manager from a transaction. Synopsis #include int ax_unreg (int rmid, long flags) Description DECdtm does not support ax_unreg(). The call always returns TMER_PROTO. Return Values TMER_PROTO Null operation. Related Information ax_reg() XA Functions 3-15 xa_close _________________________________________________________________ xa_close Informs the resource manager that DECdtm is closing the connection to the resource manager. Synopsis #include int xa_close (char *xa_info, int rmid, long flags) Parameters Input xa_info A null-terminated character string containing contextual information for the resource manager. This is the same as the *xa_info value passed to DECdtm in the ax_bind_decdtm() call. Note that the value of xa_info is valid only for the duration of the call. rmid The identifier of the resource manager. flags Always set to TMNOFLAGS. Description DECdtm calls xa_close() to inform the resource manager that DECdtm is closing the connection to the resource manager. DECdtm calls xa_close(): o After it receives an ax_unbind_decdtm() call. o When the resource manager returns an XAER_RMERR error. Return Values DECdtm ignores all return values. 3-16 XA Functions xa_close Related Information xa_open(), ax_unbind_decdtm() XA Functions 3-17 xa_commit _________________________________________________________________ xa_commit Instructs the resource manager to commit work done on behalf of a transaction branch. Synopsis #include int xa_commit (XID *xid, int rmid, long flags) Parameters Input xid The identifier of the transaction branch. Note that the value of xid is valid only for the duration of the call. If the resource manager refers to the XID after it returns from xa_commit(), it must make a local copy of the XID before returning. rmid The identifier of the resource manager associated with the transaction branch. flags Always set to TMNOFLAGS. Description DECdtm calls xa_commit() to instruct a resource manager to commit work done on behalf of a transaction branch. The resource manager must make the work done on behalf of the transaction branch permanent. DECdtm calls xa_commit() only if all resource managers involved in the transaction have prepared successfully. If it does not successfully complete the xa_commit() call, the resource manager must not forget about the transaction. 3-18 XA Functions xa_commit Return Values XA_OK Normal execution. XA_HEURCOM Due to a heuristic decision, the work done on behalf of the specified transaction branch was committed. DECdtm subsequently calls xa_ forget(). XA_HEURHAZ Due to a failure, the work done on behalf of the specified transaction branch may have been heuristically completed. DECdtm subsequently calls xa_ forget(). XA_HEURMIX Due to a heuristic decision, the work done on behalf of the specified transaction branch was partially committed and partially rolled back. DECdtm subsequently calls xa_ forget(). XA_HEURRB Due to a heuristic decision, the work done on behalf of the specified transaction branch was rolled back. DECdtm subsequently calls xa_ forget(). XA_RB* The resource manager did not commit the work done on behalf of the transaction branch. The transaction branch has been marked to be rolled back. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection. XA Functions 3-19 xa_commit XAER_RMERR An error occurred while trying to commit the transaction branch, and the transaction branch has been rolled back. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection. XAER_RMFAIL An error occurred that makes the resource manager unavailable. DECdtm makes no further calls to the resource manager, and closes the connection. Related Information xa_forget(), xa_rollback() 3-20 XA Functions xa_complete _________________________________________________________________ xa_complete Asks the resource manager whether it completed an asynchronous transaction. DECdtm never calls xa_complete(). XA Functions 3-21 xa_end _________________________________________________________________ xa_end Informs the resource manager that a transaction branch has ended. Synopsis #include int xa_end (XID *xid, int rmid, long flags) Parameters Input xid The identifier of the transaction branch. Note that xid is valid only for the duration of the call to xa_end(). If the resource manager refers to the XID after it returns from xa_ end(), it must make a local copy of the XID before returning. rmid Identifier of the resource manager. flags Indicate whether the application is aborting the transaction. _______________________________________________ Flag_________Meaning___________________________ TMFAIL DECdtm sets this flag when the application is aborting the transaction. TMSUCCESS DECdtm sets this flag when the application is ending the _____________transaction_normally._____________ 3-22 XA Functions xa_end Description DECdtm calls xa_end() when an application program completes its work on behalf of a transaction. Return Values XA_OK Normal execution. XAER_OUTSIDE Work is in progress outside a transaction. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection, and rolls back the transaction. XA_RB* The resource manager has ended the transaction branch by marking the transaction branch so that it will be rolled back. DECdtm subsequently calls xa_ rollback(). It does not call xa_ prepare() for this transaction branch. For a list of XA_RB* return values, see Appendix B . XAER_RMERR An error occurred while completing the transaction branch. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection, and rolls back the transaction. XAER_RMFAIL An error occurred that makes the resource manager unavailable. DECdtm makes no further calls to the resource manager. DECdtm closes the connection and rolls back the transaction. XA Functions 3-23 xa_forget _________________________________________________________________ xa_forget Informs the resource manager that it can forget about a heuristically completed transaction. Synopsis #include int xa_forget (XID *xid, int rmid, long flags) Parameters Input xid The identifier for the transaction branch to be forgotten. Note that xid is valid only for the duration of the call to xa_forget(). If the resource manager refers to the XID after it returns from xa_forget(), it must make a local copy of the XID. rmid The identifier for the connection. flags Always set to TMNOFLAGS. Description DECdtm calls xa_forget() to allow a resource manager to forget about a heuristically completed transaction branch. Return Values XA_OK Normal execution. 3-24 XA Functions xa_forget XAER_RMERR An error occurred when the resource manager tried to forget the transaction branch. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection. XAER_RMFAIL An error occurred that makes the resource manager unavailable. DECdtm makes no further calls to the resource manager, and closes the connection. Related Information xa_commit(), xa_rollback() XA Functions 3-25 xa_open _________________________________________________________________ xa_open Instructs the resource manager to do any initialization needed. Synopsis #include int xa_open (char *xa_info, int rmid, long flags) Parameters Input xa_info A null-terminated character string containing contextual information for the resource manager. This is the same as the xa_info value passed to DECdtm in the ax_bind_decdtm() call. Note that the value of xa_info is valid only for the duration of the call. rmid The identifier of the resource manager. flags Always set to TMNOFLAGS. Description DECdtm calls xa_open() to instruct the resource manager to do any initialization needed, such as opening files, or establishing a path to a server. DECdtm calls xa_open() when it receives an ax_bind_ decdtm() call. 3-26 XA Functions xa_open Return Values XA_OK Normal execution. XAER_RMERR An error occurred during initialization. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection. XAER_RMFAIL An error occurred that makes the resource manager unavailable. DECdtm makes no further calls to the resource manager, and closes the connection. Related Information ax_bind_decdtm() XA Functions 3-27 xa_prepare _________________________________________________________________ xa_prepare Instructs the resource manager to prepare to commit work done on behalf of a transaction branch, and allows the resource manager to return a vote. Synopsis #include int xa_prepare (XID *xid, int rmid, long flags) Parameters Input xid The identifier for the transaction branch. Note that xid is valid only for the duration of the call to xa_prepare(). If the resource manager needs to refer to the XID after it returns from the xa_prepare() call, it must make a local copy of the XID before returning. rmid Identifier of the resource manager. flags Always set to TMNOFLAGS. Description DECdtm calls xa_prepare() to instruct the resource manager to prepare to commit work done on behalf of a transaction branch. The resource manager returns a vote indicating whether it can commit the transaction. On returning XA_OK, the resource manager must guarantee that the transaction branch can be either committed or rolled back, regardless of any failure. It must not forget about the transaction branch until DECdtm calls xa_ commit() or xa_rollback(). 3-28 XA Functions xa_prepare As an optimization, a resource manager can return XA_RDONLY in either of the following cases: o The work done on behalf of the transaction branch was read-only o The resource manager was not accessed on behalf of the transaction branch If this is done, no xa_commit() or xa_rollback() callback will be made for this transaction branch. If the resource manager returns any value other than XA_OK, it can release all resources allocated to this transaction branch and forget about the transaction branch. DECdtm makes no further calls for this transaction branch. Return Values XA_OK Normal execution. DECdtm subsequently calls xa_ commit() or xa_rollback(). XA_RB* The resource manager cannot prepare to commit the work done on behalf of the transaction branch, and has marked the transaction branch so that it will be rolled back. DECdtm subsequently rolls back the transaction. XA_RDONLY The work done on behalf of the transaction branch was read-only, or the resource manager was not accessed. XAER_RMERR An error occurred while preparing to commit the transaction branch. DECdtm subsequently calls xa_close() to inform the resource manager that it is closin the connection, and rolls back the transaction. XA Functions 3-29 xa_prepare XAER_RMFAIL An error occurred that makes the resource manager unavailable. DECdtm makes no further calls to the resource manager. DECdtm closes the connection, and rolls back the transaction. Related Information xa_commit(), xa_rollback() 3-30 XA Functions xa_recover _________________________________________________________________ xa_recover Asks the resource manager for a list transaction branches to be recovered. Synopsis #include int xa_recover (XID *xids, long count, int rmid, long flags) Parameters Input xids An array into which the resource manager places XIDs for the transaction branches to be recovered. count The maximum number of XIDs that fit into xids. rmid The identifier of the resource manager. flags Indicate whether the resource manager should begin a new recovery scan. _______________________________________________ Flag_________Meaning___________________________ TMNOFLAGS The resource manager should continue with the current recovery scan. TMSTARTRSCAN The resource manager should begin _____________a_new_recovery_scan.______________ Description DECdtm calls xa_recover() to ask the resource manager for a list of transaction branches to be recovered. These are transaction branches that are in a prepared or a heuristically completed state. XA Functions 3-31 xa_recover DECdtm calls xa_recover(): o When it receives a ax_bind_decdtm() call with the DDTM_ M_RECOVER flag set. DECdtm sets the TMSTARTRSCAN flag in the xa_recover() call to indicate that the resource manager should start a new recovery scan. o When the resource manager returns from a xa_recover() call with a value equal to count. DECdtm clears the TMSTARTRCAN flag in the next xa_ recover() call to indicate that the resource manager should continue the same recovery scan. For more information on recovery processing, see Section 2.5. _______________________ Caution _______________________ If the resource manager places more XIDs into the array than the count value indicates, xa_recover() may overwrite data space. ______________________________________________________ Return Values 0, and count Total number of XIDs placed in *xids. XAER_RMERR An error occurred while trying to determine the number of XIDs to return. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection. XAER_RMFAIL An error occurred that makes the resource manager unavailable. DECdtm makes no further calls to the resource manager, and closes the connection. 3-32 XA Functions xa_recover Related Information ax_bind_decdtm(), xa_commit(), xa_rollback() XA Functions 3-33 xa_rollback _________________________________________________________________ xa_rollback Instructs the resource manager to roll back work done on behalf of a transaction branch. Synopsis #include int xa_rollback (XID *xid, int rmid, long flags) Parameters Input xid Identifier of the transaction branch. Note that xid is valid only for the duration of the call to xa_recover(). If the resource manager needs to refer to the XID after it returns from xa_recover(), it must make a local copy of the XID before returning. rmid Identifier of the resource manager. flags Always set to TMNOFLAGS. Description DECdtm calls xa_rollback() to instruct the resource manager to roll back work done on behalf of a transaction branch. After rolling back the work, the resource manager can release resources held for the transaction branch and forget about the transaction. If the resource manager already completed the work heuristically, the resource manager must do all notification and handling of the heuristic decision before returning. It must not forget about the transaction branch until it receives an xa_forget() call from DECdtm. 3-34 XA Functions xa_rollback Return Values XA_OK Normal execution. XA_HEURCOM Due to a heuristic decision, the work done on behalf of the transaction branch was committed. DECdtm subsequently calls xa_ forget(). XA_HEURHAZ Due to a failure, the work done on behalf of the specified transaction branch may have been heuristically committed. DECdtm subsequently calls xa_ forget(). XA_HEURMIX Due to a heuristic decision, the work done on behalf of the transaction branch was partially committed and partially rolled back. DECdtm subsequently calls xa_ forget(). XA_HEURRB Due to a heuristic decision, the work done on behalf of the transaction branch was rolled back. DECdtm subsequently calls xa_ forget(). XA_RB* The resource manager has already marked the transaction branch so that it will be rolled back. These return values are treated as equivalent to XA_OK for this callback. XAER_RMERR An error occurred while rolling back the transaction branch. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection. XA Functions 3-35 xa_rollback XAER_RMFAIL An error occurred that makes the resource manager unavailable. DECdtm makes no further calls to the resource manager, and closes the connection. Related Information xa_commit(), xa_forget() 3-36 XA Functions xa_start _________________________________________________________________ xa_start Informs the resource manager that it is joining a transaction. Synopsis #include int xa_start (XID *xid, int rmid, long flags) Parameters Input xid The identifier of the new transaction branch. Note that xid is valid only for the duration of the call to xa_start(). If the resource manager refers to the XID after it returns from xa_start(), it must make a local copy of the XID before returning. rmid Identifier of the resource manager. flags Always set to TMNOFLAGS. Description DECdtm calls xa_start() when it joins a resource manager to a transaction. To allow DECdtm to call xa_start() call, the resource manager must have the TMREGISTER flag clear in the xa_ switch_t structure. Note that the resource manager passes the value of the TMREGISTER flag to DECdtm only when it calls ax_bind_ decdtm(). When DECdtm calls xa_start(), it creates a new branch of the transaction and associates the resource manager with the branch. DECdtm passes a unique identifier for the transaction branch in *xid. XA Functions 3-37 xa_start Return Values XA_OK Normal execution. XA_RB* The resource manager has rejected the transaction branch, and has marked the *xid rollback-only. DECdtm subsequently calls xa_ rollback(). XAER_OUTSIDE Work is in progress outside a transaction. DECdtm subsequently calls xa_ close(), and rolls back the transaction. XAER_RMERR An error occurred while joining the transaction. DECdtm subsequently calls xa_close() to inform the resource manager that it is closing the connection, and rolls back the transaction. XAER_RMFAIL An error occurred that makes the resource manager unavailable. DECdtm makes no further calls to the resource manager. DECdtm closes the connection, and rolls back the transaction. Related Information ax_reg() 3-38 XA Functions 4 _________________________________________________________________ XA Data Structures This chapter describes two important data structures used to communicate between DECdtm and a resource manager: o The xa_switch_t structure. o The XID sdtructure. 4.0.1 The XA Switch Structure Each resource manager must provide a switch structure that gives DECdtm access to the resource manager's xa_ routines. The switch structure is called xa_switch_t. For a listing of the xa_switch_t structure, see Appendix A. The XA switch structure contains: o The name of the resource manager. o Pointers to each of the resource manager's entry points. o A longword specifying the flags used by the resource manager. These are: - TMNOFLAGS - no resource manager features are selected. - TMREGISTER - indicates whether the resource manager is automatically joined to a transaction, or has to request to join. - TMNOMIGRATE - this flag must be clear. - TMUSEASYNC - this flag must be clear. asynchronously. o A version word. The resource manager passes the values in the switch structure to DECdtm only when it calls ax_bind_decdtm(). XA Data Structures 4-1 XA Data Structures 4.0.2 The Transaction Identifier Structure, XID Figure 4-1 shows the XID format. Figure 4-1 The XID Structure o formatID specifies the XID format. For DECdtm this is set to 1. o gtrid_length specifies the number of bytes (up to a maximum of 64) that constitute gtrid, starting at the first byte of the data element (that is, at data[0]). For DECdtm, this is set to 16. o bqual_length specifies the number of bytes (up to a maximum of 64) that constitute bqual, starting at the first byte after gtrid (that is, data[gtrid_length+1]). For DECdtm, this is set to 16. o The data field comprises two contiguous components: o A global transaction identifier, gtrid o A branch qualifier, bqual. When calling xa_start(), DECdtm generates a unique XID for each new transaction branch. DECdtm also generates a unique XID when it is called with ax_reg() to dynamically join a resource manager to a transaction. 4-2 XA Data Structures A _________________________________________________________________ The XA Data Switch Structure This appendix lists the xa_switch_t structure. This data structure is in SYS$LIBRARY:XA.H. * XA Switch Data Structure */ #define RMNAMESZ 32 /*length of resource manager name, */ /* including the null terminator */ #define MAXINFOSIZE 256 /* maximum size in bytes of xa_info strings, */ /* including the null terminator */ /* xa_info is always null in DECdtm */ struct xa_switch_t { char name[RMNAMESZ]; /* name of resource manager */ long flags; /* resource manager specific options */ long version; /* must be 0 */ #ifdef __STDC__ int (*xa_open_entry)(char *, int, long);/* xa_open function pointer */ int (*xa_close_entry)(char *, int, long);/* xa_close function pointer */ int (*xa_start_entry)(XID *, int, long);/* xa_start function pointer */ int (*xa_end_entry)(XID *, int, long);/* xa_end function pointer */ int (*xa_rollback_entry)(XID *, int, long);/* xa_rollback function pointer */ int (*xa_prepare_entry)(XID *, int, long);/* xa_prepare function pointer */ The XA Data Switch Structure A-1 The XA Data Switch Structure int (*xa_commit_entry)(XID *, int, long);/* xa_commit function pointer */ int (*xa_recover_entry)(XID *, long, int, long);/* xa_recover function pointer */ int (*xa_forget_entry)(XID *, int, long);/* xa_forget function pointer */ int (*xa_complete_entry)(int *, int *, int, long); /* xa_complete function pointer */ #else /* ifndef __STDC__ */ int (*xa_open_entry)(); /* xa_open function pointer */ int (*xa_close_entry)(); /* xa_close function pointer */ int (*xa_start_entry)(); /* xa_start function pointer */ int (*xa_end_entry)(); /* xa_end function pointer */ int (*xa_rollback_entry)(); /* xa_rollback function pointer */ int (*xa_prepare_entry)(); /* xa_prepare function pointer */ int (*xa_commit_entry)(); /* xa_commit function pointer */ int (*xa_recover_entry)(); /* xa_recover function pointer */ int (*xa_forget_entry)(); /* xa_forget function pointer */ int (*xa_complete_entry)(); /* xa_complete function pointer */ #endif /* ifndef __STDC__ */ }; A-2 The XA Data Switch Structure B _________________________________________________________________ Rollback Statuses This appendix lists the XA_RB* return values. Table_B-1_XA_RB*_-_Values_and_Meanings_____________________ Value____________Meaning___________________________________ XA_RBROLLBACK The resource manager marked the transaction branch rollback-only for an unspecified reason. XA_RBCOMMFAIL A communication failure occurred within the resource manager. XA_RBDEADLOCK The resource manager detected a deadlock. XA_RBINTEGRITY The resource manager detected a violation of the integrity of its resources. XA_RBOTHER The resource manager marked the transaction branch rollback-only for a reason not on this list. XA_RBPROTO A protocol error occurred within the resource manager. XA_RBTIMEOUT The work represented by this transaction branch took too long. XA_RBTRANSIENT The resource manager detected a transient _________________error.____________________________________ Rollback Statuses B-1 _________________________________________________________________ Index Index-1