|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
This section describes the following DECdtm Veneer extensions to the standard XA interface. Use of these functions is optional.
| Function | Description |
|---|---|
| ax_bind_decdtm_2() | Connects an XA resource manager to DECdtm services. |
| ax_close_decdtm() | Closes all statically bound resource managers. |
| ax_lock_decdtm() | Prevents the XA Veneer from making asynchronous calls to RMs. |
| ax_open_decdtm() | Opens all statically bound resource managers. |
| ax_unbind_decdtm() | Disconnects a resource manager from DECdtm services. |
| ax_unlock_decdtm() | Allows the XA Veneer to call RMs again. |
Makes a connection to DECdtm or starts recovery processing.
#include <xa.h>int ax_bind_decdtm_2 (xa_switch_t *rmswitch, long flags, int*rmid_out, char *xa_info_open, char *xa_info_close, char *instance_name)
Input Rmswitch The address of the XA Switch data structure. Flags Control whether ax_bind_decdtm_2() makes a connection to DECdtm, starts recovery processing, or both. See Table 30-4 for the flags and their meaning. xa_info_open 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. The Veneer passes this parameter to the resource manager with an xa_open() call. xa_info_close The same as xa_info_open, except that the Veneer passes this parameter to the resource manager with an xa_close() call. instance_name Resource manager instance name. The maximum size of the name is 24 characters, excluding the null terminator. Output rmid_out The identifier of the resource manager. This value is unique within the process.
| Flag | Meaning |
|---|---|
| DDTM_M_DECLARE | Makes a connection between the resource manager and DECdtm. |
| DDTM_M_RECOVER | Allows xa_recover() to be called in the current process. |
An application calls ax_bind_decdtm_2() to bind a resource manager into the local process, as follows:
- Call xa_open() to open the resource manager.
- Make a connection to DECdtm.
Setting the DDTM_M_DECLARE flag allows XA calls for current transactions to be issued in the local process.- Allow XA recover to be performed in the current process.
Setting the DDTM_M_RECOVER flag enables the local process to call xa_recover() when necessary. At least one process must be enabled to perform recovery . If multiple processes are enabled, the XA Veneer will choose one.- Start recovery.
Before returning from ax_bnd_decdtm_2(), DECdtm calls xa_recover() in one of the processes enabled to perform recovery.The parameter rmid_out may be specified as NULL if the corresponding value is not required.
XA_OK Normal execution. XAER_INVAL One of the following errors occurred:
- The arguments are invalid.
- The xa_info_open or xa_info_close string is longer than 256 characters.
- Both the instance name and the RM name in rmswitch are null.
- The instance name or the RM name is longer than 32 characters.
- The xa_info_open string is invalid.
XAER_RMERR A resource manager error occurred when opening the resource. XAER_RMFAIL A DECdtm error occurred.
ax_unbind_decdtm()
Closes all statically bound resource managers.
int ax_close_decdtm (void)
This function is provided to allow an implementation of the X/Open TX specification to implement tx_close().The function has a nonstandard name to allow a TX implementation other than DECdtm TX to be linked without name conflicts.
This function must not be called from an AST, or with ASTs disabled.
TX_OK Normal execution. TX_ERROR One or more of the resource managers encountered a transient error. All resource managers that could be closed are closed. TX_FAIL One or more of the resource managers encountered a fatal error.
ax_open_decdtm()
Prevents the XA Veneer from making asynchronous calls to resource managers.
#include <xa.h>int ax_lock_decdtm (void)
An application program or resource manager may call ax_lock_decdtm() to prevent the XA Veneer from issuing XA calls to resource managers. This ensures that the Veneer cannot make a call to an RM to end and roll back a transaction while the RM is concurrently processing a call from the application.An application program that calls an XA-compliant RM and that may be run under a TP framework using unsynchronized DECdtm branches should protect all RM calls. This may be done either by locking the Veneer at the start of the transaction, and unlocking it at the end, or by locking the Veneer for each individual RM call.
This function is provided as a temporary measure. Applications do not need to use it if one of the following is true:
- Application processing is performed in a single branch.
- The application is run under a TP framework that executes branches serially, not concurrently. This is true for ACMS.
- The application is run under a TP framework known to use synchronized branches.
The XA Veneer keeps a count of the number of ax_lock_decdtm() calls. The matching number of ax_unlock_decdtm() calls must be made to remove the lock.
TM_OK Normal execution.
ax_unlock_decdtm()
Opens all statically bound resource managers.
int ax_open_decdtm (void)
This function is provided to allow an implementation of the X/Open TX specification to implement tx_open().The function has a nonstandard name to allow a TX implementation other than DECdtm TX to be linked without name conflicts.
TX_OK Normal execution. TX_ERROR One or more of the resource managers encountered a transient error. No resource managers are open. TX_FAIL One or more of the resource managers encountered a fatal error.
ax_close_decdtm()
Disconnects a resource manager from DECdtm.
#include <xa.h>int ax_unbind_decdtm (int rmid, long flags)
Input rmid The identifier of the resource manager. This must be the same as the rmid_out value returned by DECdtm in the bind_decdtm() call. flags Must be set to TMNOFLAGS.
A dynamically bound resource manager calls ax_unbind_decdtm() to disconnect itself from DECdtm. On receiving the ax_unbind_decdtm() call, DECdtm calls xa_close().This function must not be called from an AST, or with ASTs disabled.
XA_OK Normal execution. XAER_INVAL Either the arguments are invalid or the rm_info_close string is invalid. XAER_RMERR An error occurred when closing the resource. XAER_RMFAIL A DECdtm error occurred.
ax_bind_decdtm_2()
Allows the XA Veneer to make asynchronous calls to resource managers again.
#include <xa.h>int ax_unlock_decdtm (void)
This function removes the lock requested by ax_lock_decdtm().
TM_OK Normal execution. TMERR_INVAL The resource manager has called ax_unlock_decdtm() more often than it has called ax_lock_decdtm().
ax_lock_decdtm()
30.7.3 Using the XA Gateway
This section describes how to use a resource manager compliant with
DECdtm, such as RMS Journaling or Oracle Rdb, with an XA-compliant
transaction processing system.
The XA Gateway is configured into each TP process as an XA-compliant resource manager. It handles XA calls from the XA TM and maps these into DECdtm system services. This causes DECdtm to send the appropriate events to any DECdtm compliant Resource Manager (RM) used in a TP process.
The operation of the Gateway is transparent to the RM; DECdtm RMs do
not need any modification to be used with the Gateway.
30.7.3.1 Gateway Configuration
The XA Gateway uses a log file to record the mapping between XA transactions and DECdtm transactions. The log file is managed by the Gateway server process DDTM$XG_SERVER.
As of Version 2.1, HP DECdtm/XA Gateway has clusterwide transaction recovery support. Transactions from applications that use a clusterwide DECdtm Gateway Domain Log can be recovered from any single-node failure. Gateway servers running on the remaining cluster nodes can initiate the transaction recovery process on behalf of the failed node.
Use the XGCP utility (described in Section 30.7.4 of this manual) to create the Gateway log. The size of the log file depends on the number of concurrently active transactions. Each active transaction requires up to 600 bytes, depending on the size of the transaction ID used by the XA TM. However, the log expands automatically when required.
The log file is created in the directory specified by the logical name SYS$JOURNAL and has a name of the form SYSTEM$name.DDTM$XG_JOURNAL. For optimum performance, move each Gateway log and each DECdtm log to a separate physical device, and define SYS$JOURNAL as a search list for the set of physical devices.
The XA Gateway requires an association on each OpenVMS Cluster node between an XA transaction manager and the XA Gateway log. You manage this association by specifying a Gateway name as follows:
You must configure all XA applications run on the local node with the same Gateway name. XA applications using the same name cannot run on other OpenVMS Cluster nodes. Therefore, you should normally define one Gateway name and create one log for each node of an OpenVMS Cluster.
However, you can move a Gateway name to a different node, provided that the Gateway log can be accessed from that node. Move the name to another node as follows:
Take care to protect against the loss of a Gateway log, perhaps by shadowing the device that holds it. If a new log has to be created, or an out-of-date log is used, transactions that were originally recorded as committed may be incorrectly rolled back. This can cause databases to become inconsistent with each other or inconsistent with reports given to other systems or users.
In general, Gateway logs are not large and it is better never to delete them. Before deleting an unwanted Gateway log, use the DECdtm XGCP utility to check that the Gateway is not still a participant in any prepared transactions. The Gateway participant name is DDTM$XG/name.
The Gateway server has the following parameters:
Each XA-compliant transaction manager (TM) defines its own method for including resource managers (RMs). Typically, a configuration file is edited and used as input to build application programs that run under the control of the TM. You may also need to configure and build a separate TM worker process that performs transaction prepare and commit operations.
See the documentation for your XA TM for specific instructions. You will need the following information about the XA Gateway RM. This is published in the XA Specification (Section 7.2).
| xa_switch_t structure name: | DDTM$XG_RM_SWITCH |
| RM name within the RM switch: | DDTM$XG |
| Information string for xa_open: | "SYSTEM$ gateway", where gateway is the name of the gateway for the local node of an OpenVMS Cluster. |
| Information string for xa_close: | Ignored. May be null. |
| Sharable image library: | SYS$LIBRARY:DDTM$XG.EXE |
| Transaction semantics: | See Section 30.7.3.3.2 |
| Protocol optimizations: | See Section 30.7.3.3.3 |
| Association migration: | Not allowed. |
| Dynamic registration: | Not used. |
| Asynchrony: | Not supported. |
| Heuristics: | Not used. |
The Gateway is implemented by the shareable image SYS$LIBRARY:DDTM$XG.EXE.
You must install the privileged sharable image
SYS$LIBRARY:DDTM$XG_SS.EXE. It provides system services for internal
use by the Gateway and the XGCP utility.
30.7.3.2.1 Hints
You may find the following hints to be of help:
The following sections describe the implementation characteristics of
the XA Gateway.
30.7.3.3.1 Default Transaction
The XA Gateway sets the DECdtm default transaction for each XA transaction.
Most DECdtm RMs join the default transaction if an explicit TID is not
specified on a call to the RM. If an RM does require an explicit TID,
the application can use the $GET_DEFAULT_TRANS system service to read
the current default TID.
30.7.3.3.2 Locking Between Processes
DECdtm does not distinguish between loosely coupled and tightly coupled threads, as defined by the XA specification. Instead, each RM makes its own decision whether to allow transaction branches in different processes to share data.
The Gateway allocates a separate DECdtm TID for each branch of an XA global transaction. This allows a branch to be prepared while other branches continue to perform work, as required by Section 2.2.6 of the XA specification.
Consequently, DECdtm RMs enforce isolation between the branches of an XA global transaction. This behavior is consistent with the XA specification, but not required by it.
When multiple processes perform work on a single branch within a single node of an OpenVMS Cluster, the gateway allocates a single DECdtm TID for the branch. In principle, this allows the RMs to recognize that work in multiple processes is part of a single transaction, and to use tightly coupled threads. However, it depends on the RM whether this is implemented.
The Gateway does not use the same TID for a single branch of a
transaction seen on multiple nodes of an OpenVMS Cluster. However, it
is unlikely that any XA TM will use the same branch on different nodes,
or that any DECdtm RM is capable of implementing tightly coupled
threads between nodes.
30.7.3.3.3 Read-Only Optimization
DECdtm RMs may choose to implement a read-only optimization when a
transaction is prepared (see Section 2.3.2 of the XA specification). If
all DECdtm RMs use the optimization for a given transaction, the
Gateway uses the same optimization on the xa_prepare call for the
transaction.
30.7.3.3.4 Blocking Conditions
The Gateway is unable to determine if a blocking condition exists or
not. Consequently, it always returns XA_RETRY when the TMNOWAIT flag is
set.
30.7.3.3.5 XA Return Values
The Gateway translates DECdtm reason codes to XA return codes as follows:
| DECdtm Reason Code | XA Return Code |
|---|---|
| DDTM$_ABORTED | XA_RBROLLBACK |
| DDTM$_COMM_FAIL | XA_RBCOMMFAIL |
| DDTM$_INTEGRITY | XA_RBINTEGRITY |
| DDTM$_PART_SERIAL | XA_RBDEADLOCK |
| DDTM$_PART_TIMEOUT | XA_RBTIMEOUT |
| DDTM$_SERIALIZATION | XA_RBDEADLOCK |
| DDTM$_TIMEOUT | XA_RBTIMEOUT |
| DDTM$_VETOED | XA_RBROLLBACK |
| All others | XA_RBOTHER |
The Gateway uses XAER_RMFAIL to indicate a failure to access data on disk, while XAER_RMERR indicates an internal failure. It translates DECdtm error codes to XA return codes as follows:
| DECdtm Error Code | XA Return Code |
|---|---|
| SS$_ALRCURTID | XAER_PROTO |
| SS$_BRANCHSTARTED | XAER_PROTO |
| SS$_NOLOG | XAER_RMFAIL |
| SS$_TPDISABLED | XAER_RMFAIL |
| SS$_WRONGSTATE | XAER_RBROLLBACK |
| All others | XAER_RMERR |
An exception is xa_commit. This function returns XAER_RMFAIL instead of XA_RMERR, because the XA specification states that XA_RMERR indicated a catastrophic failure for this function.
| Previous | Next | Contents | Index |