XA dynamic registration

The XA specification provides a way of reducing the number of xa_* calls that a transaction manager makes to a resource manager. This optimization is known as dynamic registration. Dynamic registration is supported by DB2(R). Other databases might support it; consult the documentation for your database product for details.

Why is the dynamic registration optimization useful? In your application, some global units of work might contain updates to database tables; others might not contain such updates. When no persistent update has been made to a database's tables, there is no need to include that database in the commit protocol that occurs during MQCMIT.

Whether or not your database supports dynamic registration, your application calls xa_open during the first MQBEGIN call on a WebSphere MQ connection. It also calls xa_close on the subsequent MQDISC call. The pattern of subsequent XA calls depends on whether the database supports dynamic registration:

If your database does not support dynamic registration...
Every global unit of work involves several XA function calls made by WebSphere MQ code into the database client library, regardless of whether you made a persistent update to the tables of that database within your unit of work. These include: In addition, the queue manager agent process also calls xa_open during the first MQBEGIN.
If your database supports dynamic registration...
The WebSphere MQ code makes only those XA function calls that are necessary. For a global unit of work that has not involved persistent updates to database resources, there are no XA calls to the database. For a global unit of work that has involved such persistent updates, the calls are to:

For dynamic registration to work, it is vital that the database has a way of telling WebSphere MQ when it has performed a persistent update that it wants to be included in the current global unit of work. WebSphere MQ provides the ax_reg function for this purpose.

The database's client code that runs in your application process finds the ax_reg function and calls it, to dynamically register the fact it has done persistent work within the current global unit of work. In response to this ax_reg call, WebSphere MQ records that the database has participated. If this is the first ax_reg call on this WebSphere MQ connection, the queue manager agent process calls xa_open.

The database client code make this ax_reg call when it is running in your process, for example, during an SQL UPDATE call or whatever call in the database's client API is responsible

Error conditions

There is an opportunity here for a confusing failure in the queue manager. Here is a common example. If you forget to set your database environment variables properly before starting your queue manager, the queue manager's calls to xa_open fail. No global units of work can be used.

To avoid this, ensure that you have set the relevant environment variables before starting the queue manager. Review your database product's documentation, and the advice given in Checking the DB2 environment variable settings, Checking the Oracle environment variable settings, and Checking the Sybase environment variable settings.

With all database products, the queue manager calls xa_open once at queue manager startup, as part of the recovery session (as explained in Administration tasks). This xa_open call fails if you set your database environment variables incorrectly, but it does not cause the queue manager to fail to start. This is because the same xa_open error code is used by the database client library to indicate that the database server is unavailable. We do not treat this as a serious error, as the queue manager must be able to start to continue processing data outside global units of work involving that database.

Subsequent calls to xa_open are made from the queue manager during the first MQBEGIN on a WebSphere MQ connection (if dynamic registration is not being used) or during a call by the database client code to the WebSphere MQ-provided ax_reg function (if dynamic registration is being used).

The timing of any error conditions (or, occasionally, FFST(TM) reports) depends on whether you are using dynamic registration:

Ensure that your environment variables are set correctly in your application and queue manager processes.

Summarizing XA calls

Table 14 lists the calls that are made to the XA functions in a database client library as a result of the various MQI calls that control global units of work. This is not a complete description of the protocol described in the XA specification; we have provided it as a brief overview.

Note that xa_start and xa_end calls are always called by WebSphere MQ code in the application process, whereas xa_prepare, xa_commit, and xa_rollback are always called from the queue manager agent process, amqzlaa0.

The xa_open and xa_close calls shown in this table are all made from the application process. The queue manager agent process calls xa_open in the circumstances described in Error conditions.

Table 14. Summary of XA function calls
MQI call XA calls made with dynamic registration XA calls made without dynamic registration
First MQBEGIN
xa_open
xa_open
xa_start
Subsequent MQBEGIN No XA calls
xa_start
MQCMIT (without ax_reg being called during the current global unit of work) No XA calls
xa_end
xa_prepare
xa_commit
xa_rollback
MQCMIT (with ax_reg being called during the current global unit of work)
xa_end
xa_prepare
xa_commit
xa_rollback
Not applicable. No calls are made to ax_reg in non-dynamic mode.
MQBACK (without ax_reg being called during the current global unit of work) No XA calls
xa_end
xa_rollback
MQBACK (with ax_reg being called during the current global unit of work)
xa_end
xa_rollback
Not applicable. No calls are made to ax_reg in non-dynamic mode.
MQDISC, where MQCMIT or MQBACK was called first. If they were not, MQCMIT processing is first done during MQDISC.
xa_close
xa_close
Notes:
  1. For MQCMIT, xa_commit is called if xa_prepare is successful. Otherwise, xa_rollback is called.