Using the XA Gateway (Alpha Only)

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP OpenVMS System Manager's Manual, Volume 2:...

Managing DECdtm Services

Enabling DECdtm Services

Managing Special Processing Environments

Using the XA Gateway (Alpha Only)

DECdtm/XA provides support for coordinating and managing transactions that use XA. By using an XA Gateway, DECdtm/XA can join other Resource Managers (RM) in transactions that are managed by another Transaction Manager (TM). This section describes how to configure and use DECdtm XA Gateway support.

In this chapter, the term XA Specification refers to Distributed Transaction Processing: The XA Specification .

To use DECdtm/XA and ensure proper startup and shutdown of DECdtm/XA services, the following command files must be invoked:

SYS$STARTUP:DDTM$XA_STARTUP.COM

SYS$STARTUP:DDTM$XA_SHUTDOWN.COM

Add the command @SYS$STARTUP:DDTM$XA_STARTUP.COM to the startup database or to the command file SYS$MANAGER:SYSTARTUP_VMS.COM.

Add the command @SYS$STARTUP:DDTM$XA_SHUTDOWN.COM to the command file SYS$MANAGER:SYSHUTDWN.COM.

Perform the following steps to verify that DECdtm XA services are operating properly:

Use the XGCP utility to create a gateway log file with the same name as the local OpenVMS node. See Gateway Configuration and the HP OpenVMS System Management Utilities Reference Manualfor details.

Run SYS$TEST:DECDTM_XG_IVP.EXE.

Use the XGCP utility to stop and restart the gateway server. This step is essential if you choose to configure the gateway with a name different than that of the local OpenVMS node. For more information on the XGCP utility, see HP OpenVMS System Management Utilities Reference Manual: M--Z.

Gateway Configuration

The XA Gateway is configured into each transaction processing (TP) process as an XA-compliant resource manager. The XA Gateway handles XA calls from the XA transaction manager (TM) and maps them into calls to DECdtm system services. This allows DECdtm to send the appropriate events to any DECdtm compliant Resource Manager (RM) used in a TP process.

The operation of the XA Gateway is transparent to the RM; DECdtm RMs do not need any modification to be used with the XA Gateway.

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.

Create the gateway log file with the XGCP utility (see the HP OpenVMS System Management Utilities Reference Manual). The size of the gateway log file depends on the number of concurrently active transactions. Up to 600 bytes are required for each active transaction, depending on the size of the transaction ID (TID) used by the XA TM. The gateway log file expands automatically when required.

The gateway log file resides 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 file and each DECdtm log file 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 file. This association is managed by specifying a gateway name as follows:

Use the XGCP utility to create a gateway log file with the gateway name (see the HP OpenVMS System Management Utilities Reference Manual).

The gateway name is specified in the xa_open information string when the Gateway RM is configured in applications run under the control of an XA TM. (XA RM configuration is described in OpenVMS Programming Concepts: Volume II.)

The first XA application run by the XA TM binds the gateway name to the local node of the OpenVMS Cluster. The gateway name remains bound to that node until the gateway server is stopped.

All XA applications that run on the local node must be configured with the same gateway name. XA applications using the same name cannot run on other OpenVMS Cluster nodes. Therefore, you normally define one gateway name and create one gateway log file for each node of an OpenVMS Cluster.

You can change the association of a gateway name and bind the gateway name to a different OpenVMS Cluster node, provided that the node can access the gateway log file. To change the association of a gateway name, perform the following steps:

Stop all XA applications on the original node.

Use the XGCP utility to stop the gateway server on the original node.

Stop all XA applications on the new node.

Stop the gateway server on the new node and then restart the gateway server.

Run the original XA applications on the new node.

You must take care to protect against the loss of a gateway log file, perhaps by shadowing the device on which it resides. If you create a new log file, or if you use an out-of-date log file, 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.

Gateway log files are not large and it is better never to delete them. If you do delete an unwanted gateway log file, first use the DECdtm XGCP utility to verify that the gateway is not still a participant in any prepared transactions. The gateway participant name is DDTM$XG/name.

The gateway server uses the following system logical names:

SYS$DECDTM_XG_REQS

Number of concurrent requests processed by the server, in the range 100 to 100,000. This determines the size of the global section that DDTM$XG uses for communication with the server, and the quotas required by the server. The parameter is specified 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 the value of this parameter is exceeded during operation, client requests are blocked instead of being processed in parallel.

SYS$DECDTM_XA_TRANS

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. The parameter is specified 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 the value of this parameter is exceeded during operation, server CPU use will increase. However, the effect is unlikely to be noticeable until the value of this parameter is exceeded by a factor of 10 or more.

Enabling DECdtm Services

Managing Special Processing Environments