HP OpenVMS Systems Documentation

OpenVMS Programming Concepts Manual

By default, the XA Veneer calls xa_recover in any process that has bound an RM instance. This is undesirable if the process called to perform recovery runs at low priority or executes an application that may be blocked for link periods with an active transaction. It is especially undesirable if the process uses a resource manager such as Oracle that waits during an active transaction if it finds data that needs recovery.

It is therefore preferable to create one or more processes that are available to perform recovery but which do not execute transactions. You can do this in the following way:

1. Define the logical name SYS$DECDTM_XA_RECOVER as "FALSE" or "F" for all processes that may execute transactions. This will prevent xa_recover from being called in those processes. The logical name may be defined group or system wide.
2. Create a recovery process that binds all XA RMs and has the logical name SYS$DECDTM_XA_RECOVER defined as "TRUE" or "T". This will prevent the process from joining active XA transactions.
3. Ensure that one or more instances of the recovery process are started before starting any application processes.

The executable code of the process is provided by the module SYS$LIBRARY:DDTM$XA_RECOVERY.OBJ. Alternatively, you can create a custom process using the following code as a starting point:

    #define DESC_INIT_S(p1, p2, p3)       \
        (p1).dsc$w_length = p2,           \
        (p1).dsc$b_dtype = DSC$K_DTYPE_T, \
        (p1).dsc$b_class = DSC$K_CLASS_S, \
        (p1).dsc$a_pointer = (char *) (p3)
    main() {

        int             status;
        struct dsc$descriptor  dscName;
        struct dsc$descriptor  dscValue;

        /* enable recovery in this process */
        DESC_INIT_S(dscName, strlen("SYS$DECDTM_XA_RECOVER"),
                             "SYS$DECDTM_XA_RECOVER");
        DESC_INIT_S(dscValue, 1, "T");
        status = lib$set_logical(&dscName, &dscValue);
        if ((status & 1) != 1) {
            printf("Failed to define logical name, status %d\n", status);
            exit(EXIT_FAILURE);
        }

        /* open XA RMs */
        status = ax_open_decdtm();
        if (status != TX_OK) {
               printf("Error %d on ax_open_decdtm\n", status);
           exit(EXIT_FAILURE);
        }

        /* wait for recovery requests */
        while (1)
            sys$hiber();
    }

To link the process, include the following object modules and libraries:

• SYS$LIBRARY:DDTM$XA_RECOVERY.OBJ, or the code shown previously.
• An object module binding each RM to the XA Veneer, as described in Section 30.7.1.3.1.
• Shareable images or object files for each XA RM.
• SYS$LIBRARY:DDTM$XA_RM.OBJ.
• SYS$LIBRARY:DDTM$XA.EXE / SHARABLE.

To restore the default behavior (process joins active transactions and may perform recovery) when SYS$DECDTM_XA_RECOVER has been defined as a group or systemwide logical, define SYS$DECDTM_XA_RECOVER as 0 (zero) for the process.

30.7.1.6 Error Logging

The DECdtm XA log file records heuristic decisions and other serious errors that may impact transaction consistency. Typically, these occur on xa_commit() or xa_rollback(), or during recovery. Less serious errors, such as on xa_prepare, are not logged.

To enable logging, define the logical name SYS$DECDTM_XA_LOG to specify a log file. You can define the logical name processwide, groupwide or systemwide. The log file is created automatically and is shared between processes.

Each record on the log file has the following format:

  tid, bid, time, error_name, rm_name, [reserved], additional_information

Error names are fixed-length 8-character strings with space padding as shown in Table 30-3.

The XA Veneer includes a trace facility to help investigate problems of interaction between DECdtm and XA resource managers. The trace file shows the sequence of operations. It also shows more detailed error information than that revealed by XA return values.

To enable tracing, define the logical name SYS$DECDTM_XA_TRACE to specify a trace file. You can define the logical name processwide, groupwide or systemwide. The trace file is created automatically and is shared between processes.

The trace file records the following information:

• All ax_ calls from the application and the resource managers.
• All xa_ calls to the resource managers.
• XA and OpenVMS error status results returned by the above functions. If no status return is included in the trace, success can be assumed.
• DECdtm events and their corresponding acknowledgements.

Trace records have the following formats:

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.

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.