HP OpenVMS Systems Documentation

HP OpenVMS Programming Concepts Manual

This section describes the following DECdtm Veneer extensions to the standard XA interface. Use of these functions is optional.

Makes a connection to DECdtm or starts recovery processing.

Format

#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)

Parameters

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.

Description

An application calls ax_bind_decdtm_2() to bind a resource manager into the local process, as follows:

1. Call xa_open() to open the resource manager.
2. Make a connection to DECdtm.
   Setting the DDTM_M_DECLARE flag allows XA calls for current transactions to be issued in the local process.
3. 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.
4. 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.

Return Values

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.

See Also

ax_unbind_decdtm()

Closes all statically bound resource managers.

Format

int ax_close_decdtm (void)

Description

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.

Return Values

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.

See Also

ax_open_decdtm()

Prevents the XA Veneer from making asynchronous calls to resource managers.

Format

#include <xa.h>

int ax_lock_decdtm (void)

Description

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.

Return Values

TM_OK

Normal execution.

See Also

ax_unlock_decdtm()

Opens all statically bound resource managers.

Format

int ax_open_decdtm (void)

Description

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.

Return Values

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.

See Also

ax_close_decdtm()

Disconnects a resource manager from DECdtm.

Format

#include <xa.h>

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 bind_decdtm() call.
flags	Must be set to TMNOFLAGS.

Description

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.

Return Values

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.

Related Information

ax_bind_decdtm_2()

Allows the XA Veneer to make asynchronous calls to resource managers again.

Format

#include <xa.h>

int ax_unlock_decdtm (void)

Description

This function removes the lock requested by ax_lock_decdtm().

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().

See Also

ax_lock_decdtm()

30.7.3 Using the XA Gateway

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:

1. Create a Gateway log with the Gateway name using the XGCP utility.
2. Specify the gateway name in the xa_open information string when you configure Gateway RM into applications run under the control of an XA TM. (XA RM configuration is described in Section 30.7.3.2.)
   The first XA application run by the XA TM binds the Gateway name to the local node of the OpenVMS Cluster. It remains bound to that node until the Gateway server is stopped.

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:

1. Stop any XA applications on the original node.
2. Stop the Gateway server on the original node, using the XGCP utility.
3. Stop any XA applications on the target node.
4. Stop the Gateway server on the target node, and restart it.
5. Run the original XA applications on the target node.

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:

• Number of concurrent requests processed by the server, in the range 100 to 100,000. This determines the size of the global section DDTM$XG, used for communication with the server, and the quotas required by the server. Specify the parameter by defining the logical name SYS$DECDTM_XG_REQS. Changes to the parameter do not take effect until after the server and all client processes have been stopped.
  If this parameter is exceeded in operation, client requests are simply blocked instead of being processed in parallel.
• Estimated number of concurrent XA transactions, in the range 1000 to 1,000,000. This determines the size of indexing tables used internally in the server. Specify the parameter by defining the logical name SYS$DECDTM_XA_TRANS. Changes to this parameter do not take effect until after the server has been stopped.
  If this parameter is exceeded in operation, server CPU use will increase. However, the effect is unlikely to be noticeable until the parameter is exceeded by a factor of 10 or more.

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).

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 XA switch name is uppercase. Some transaction managers specify exact case compilation when generating references to RM, so you should specify the switch name in uppercase.
• Check any OpenVMS documentation for your transaction manager as well as the generic documentation. For example, the generic documentation for Tuxedo uses a colon (:) to separate the resource manager name and XA information strings in a configuration table. However, on OpenVMS, the separator has been changed to a comma (,).

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:

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:

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.