Intro
|
The XA specification defines how applications use a transaction manager to coordinate a distributed transaction across multiple resource managers.
The XA interface defines the contract between a resource manager and a transaction manager in a distributed transaction processing (DTP) environment.
Distributed transactions enable independent resources - such as MQ and DB2 -
to participate in a single unit of work that assures data integrity,
even if one resource cannot commit or crashes while the transaction is in progress.
A transaction will commit only if all resources can commit successfully - otherwise it is rolled back.
WebSphere MQ on UNIX systems and WebSphere MQ for Windows support coordination of transactions
by external syncpoint managers that use the X/Open XA interface.
The XA specification requires each resource manager to provide a structure called an XA Switch.
This structure declares the capabilities of the resource manager,
and the functions that are to be called by the syncpoint coordinator.
There are two versions of this structure:
- MQRMIXASwitch - static XA resource management
- MQRMIXASwitchDynamic - dynamic XA resource management
For a list of the libraries containing this structure
see the WebSphere MQ System Administration Guide.
Consult your transaction manager documentation to determine whether to use the static or dynamic resource management interface.
The method that must be used to link them to an XA syncpoint coordinator is defined by the coordinator.
Consult the documentation provided by that coordinator to determine how to enable WebSphere MQ
to cooperate with your XA syncpoint coordinator.
|
The subject of this X/Open specification is interface (3) in the diagram above,
the XA interface by which TMs and RMs interact.
|
publib,
publib
Vocabulari
- transaction manager
- resource manager
- external syncpoint manager
- XA interface - this is the interface between the TM and the RM in an X/Open DTP system
XA spec
c193
xa_open()
In each thread of control,
the TM must call xa_open() for each RM directly accessible by that thread before calling any other xa_ routine.
RM name
Some XA transaction managers (TXSeries) require that each XA resource manager supplies its name.
This is the string called name in the XA switch structure.
The resource manager for WebSphere MQ on UNIX and Windows systems is named MQSeries_XA_RMI.
publib
Some external syncpoint coordinators (not CICS) require that each resource manager participating in a unit of work
supplies its name in the name field of the XA switch structure.
The WebSphere MQ resource manager name is MQSeries_XA_RMI.
publib
Structure questions
Question : how do you determine in a specific installation, if MQ is the XA coordinator,
or another software provides coordination ?
Looking at the verbs used in the code.
We define two scenarios for global units of work:
- in the first, the queue manager itself acts as the transaction manager.
In this scenario, MQI verbs control the global units of work;
they are started in applications using the MQBEGIN verb and then committed using MQCMIT or backed out using MQBACK.
- in the second, the transaction manager role is performed by other software, such as TXSeries, Encina, or Tuxedo.
In this scenario, an API provided by the transaction manager software is used to control the unit of work,
for example, EXEC CICS SYNCPOINT for TXSeries.
Question : MQ and DB must be local, or we can use Oracle remote client ?
The database server can reside on a different machine from the queue manager server,
as long as the database client is installed on the same machine as the queue manager, and it supports this function.
Consult the database product's documentation
to determine whether their client software can be used for two-phase commit systems.
url
Configuring MQ for XA
We do it in 4 steps:
- create the switch file, jdbcora.so (unix) or jdbcora.dll (win)
- modify qm.ini
- restart queue manager
- verify XA
An XA switch file is a shared library that defines the names of XA functions implemented in the resource manager.
On Windows, the switch libraries are precompiled and supplied in the install "%mqpath%\java\lib\jdbc".
Directory of \\MQ\java\lib\jdbc
04/06/2012 01:00 21.096 jdbcdb2.dll
04/06/2012 01:00 21.096 jdbcora10.dll
04/06/2012 01:00 21.096 jdbcora11.dll
Directory of \\MQ\java\lib64\jdbc
04/06/2012 01:00 24.168 jdbcdb2.dll
04/06/2012 01:00 24.168 jdbcora10.dll
04/06/2012 01:00 24.168 jdbcora11.dll
See configuration
here
On Unix, both 32-bit and 64-bit versions of the object files are supplied,
located in the install path/java/lib/jdbc and install path/java/lib64/jdbc directories respectively.
Makefiles to link the object files are also supplied.
These use DB2_HOME and ORACLE_HOME to define where the database has been installed, which must be set appropriately.
(AIXHOST):[root] /usr/mqm/java/lib64/jdbc-> make oracle
xlc -q64 -qmkshrobj -e MQStart -L/usr/mqm/lib64 -lmqmcs_r -L/lib -lclntsh -o /var/mqm/exits64/jdbcora jdbcora.o
ld: 0706-006 Cannot find or open library file: -l clntsh
ld:open(): A file or directory in the path name does not exist.
make: 1254-004 The error code from the last command is 255.
Configuring on other platforms
A 32-bit switch library will be copied to the /var/mqm/exits directory,
while a 64-bit switch library will be copied to /var/mqm/exits64.
On UNIX platforms, you must manually edit the qm.ini file.
Add the following stanza to the file:
XAResourceManager:
Name=ExampleDB
SwitchFile= < jdbcdb2 or jdbcora >
XAOpenString= < xa open string >
ThreadOfControl= < THREAD | PROCESS >
developerWorks
XA switch load file names
Some 64-bit transaction managers treat the long type in the XA specification as 64-bit, and some treat it as 32-bit.
WebSphere MQ supports both models.
If your transaction manager is 32-bit, or your transaction manager is 64-bit but treats the long type as 32-bit, use the switch load file
libmqmxa.a (AIX nonthreaded) or libmqmxa_r.a (AIX threaded)
If your transaction manager is 64-bit and treats the long type as 64-bit, use the switch load file
libmqmxa64.a (AIX nonthreaded) or libmqmxa64_r.a (AIX threaded)
url
Find them all in /usr/mqm/lib64/ !?!?!?
How does linker know which one to use ???
Unix makefile
See <mq install path>/java/lib64/jdbc/Makefile:
(ADLTAQMQ0):[root] /usr/mqm/java/lib64/jdbc-> cat Makefile
# These flags allow us to pick up the Oracle libraries
# This makefile assumes that ORACLE_HOME is set appropriately
ORALIBS=-lclntsh
#ORALIBPATH=-L$(ORACLE_HOME)/lib
#ORALIBPATH=-L/oraclient/product/11.2.0/client_1/lib
ORALIBPATH=-L/oraclient/product/11.2.0.3.5/lib
# The flags allow us to pick up the DB/2 libraries
# This is DB/2 8.1's standard installation directory. If you're using a
# different level of DB/2, override DB2LIBPATH accordingly
DB2LIBS=-ldb2
DB2LIBPATH=-L$(DB2_HOME)/lib64
# We need to specify the location of the WMQ libraries to build against
MQLIBS=-lmqmcs_r
MQLIBPATH=-L/usr/mqm/lib64
LINK_OPTIONS = -q64 -qmkshrobj -e MQStart ${MQLIBPATH} ${MQLIBS}
all:
@echo 'Usage: make [JAVA_HOME=jdk_path] [db2|oracle]'
db2:
xlc ${LINK_OPTIONS} ${DB2LIBPATH} ${DB2LIBS} -o /var/mqm/exits64/jdbcdb2 jdbcdb2.o
oracle:
xlc ${LINK_OPTIONS} ${ORALIBPATH} ${ORALIBS} -o /var/mqm/exits64/jdbcora jdbcora.o
We modify it to Makefile.RAT:
LINK_OPTIONS = -q64 -bnoquiet
oracle:
xlc $(LINK_OPTIONS) -o jdbcora.RAT jdbcora.o
Link using
make -f Makefile.RAT oracle
xa.h and xa_switch_t
The TM administrator can add or remove an RM from the DTP system by simply controlling the set of RMs linked to executable modules.
Each RM must provide a switch that gives the TM access to the RMs xa_ routines.
This lets the administrator change the set of RMs linked with an executable module without having to recompile the application.
An RM's switch uses a structure called xa_switch_t.
The switch contains the RMs name, non-null pointers to the RMs entry points,
a flag and a version word:
See xa.h at "\\MQ\tools\c\Samples\xatm\"
/* XA Switch Data Structure */
#define RMNAMESZ 32 /* length of resource manager name, including the null terminator */
#define MAXINFOSIZE 256 /* maximum size in bytes of xa_info strings, including the null terminator */
struct xa_switch_t {
char name [ RMNAMESZ ] ; /* name of resource manager */
long flags ; /* options specific to the resource manager */
long version ; /* must be 0 */
int ( * xa_open_entry ) (char *, int, long) ; /* xa_open function pointer */
int ( * xa_close_entry ) (char *, int, long) ; /* xa_close function pointer */
int ( * xa_start_entry ) (XID *, int, long) ; /* xa_start function pointer */
int ( * xa_end_entry ) (XID *, int, long) ; /* xa_end function pointer */
int ( * xa_rollback_entry ) (XID *, int, long) ; /* xa_rollback function pointer*/
int ( * xa_prepare_entry ) (XID *, int, long) ; /* xa_prepare function pointer */
int ( * xa_commit_entry ) (XID *, int, long) ; /* xa_commit function pointer */
int ( * xa_recover_entry ) (XID *, long, int, long) ; /* xa_recover function pointer */
int ( * xa_forget_entry ) (XID *, int, long) ; /* xa_forget function pointer */
int ( * xa_complete_entry ) (int *, int *, int, long) ; /* xa_complete function pointer*/
} ;
XA spec
xa_open() error
Our qm.ini is:
XAResourceManager:
Name=bwbd56
SwitchFile=jdbcora
XAOpenString=Oracle_XA+HostName=ORAHOST+PortNumber=2556+SqlNet=bwbd56+Acc=P/u/p+SesTm=35+LogDir=/var/log/mqbridge+threads=true
XACloseString=
ThreadOfControl=THREAD
See XAOpenString details and syntax
here
When queue manager starts, we get an error:
-------------------------------------------------------------------------------
03/13/13 18:35:15 - Process(3670036.1) User(mqm) Program(amqzxma0_nd) Host(MYHOST)
AMQ7605: The XA resource manager bwbd56 has returned an unexpected return code -5, when called for xa_open.
EXPLANATION:
WebSphere MQ received an unexpected return code when calling XA resource manager bwbd56 at its xa_open entry point.
This indicates an internal error, either within MQ or the resource manager.
ACTION:
Try to determine the source of the error.
A trace of the failure could be used to look at the XA flows between MQ and the resource manager.
MQ has allocated an RMId of 1 to this resource manager.
This will be useful when isolating the flows associated with the resource manager concerned.
The transaction indoubt is identified by the following XID of X''.
----- amqtmrma.c : 455 --------------------------------------------------------
We do a trace and see:
-------------------------------------------------------------------------------
16:01:40.708520 : xa_open >>
16:01:40.708527 : Xa_info:
16:01:40.708534 : Oracle_XA+HostName=MYHOST+PortNumber=2556+SqlNet=bwbd56+Acc=P/u/p+SesTm=35+LogDir=/var/log/mqbridge+threads=true
16:01:40.708540 : Rmid:
16:01:40.708547 : 0x0000: 00000001 |.... |
16:01:40.708554 : Flags:
16:01:40.708560 : 0x0000: 00000000 |.... |
16:01:40.708568 : Calling RM (Oracle_XA) using 64-bit XA
16:01:40.713477 : __________
16:01:40.713488 : xa_open <<
16:01:40.713496 : Xa_info : Input Parm
16:01:40.713503 : Rmid : Input Parm
16:01:40.713509 : Flags : Input Parm
16:01:40.713517 : Return value:
16:01:40.713524 : 0x0000: fffffffb |.... |
16:01:40.713533 : rc: XAER_INVAL
16:01:40.713540 : --------}! tmiCallXAOpen rc=Unknown(FFFFFFFB)
16:01:40.713547 : -------}! tmiXAOpen rc=Unknown(FFFFFFFB)
16:01:40.713556 : -------{ xcsBuildDumpPtr
Jo trobo
During an XA_OPEN, an error occurs and returns an XA rc -5.
This relates to XAER_INVAL (Invalid Parameter supplied to the XA_OPEN string)
Accessing Oracle XA trace files
The Oracle XA library logs any error and tracing information to its trace file.
This information is useful in supplementing the XA error codes.
For example, it can indicate whether an xa_open failure is caused by an incorrect open string,
failure to find the Oracle Database instance, or a logon authorization failure.
Oracle
See
trace file locations !
Switch load files
The sample source modules used to build the switch load files are:
- \\MQ\tools\c\Samples\xatm\oraswit.c (Oracle)
Description,
Creating switch load files
ETC concepts
A client application can participate in a unit of work that is managed by a queue manager to which it is connected.
Within the unit of work, the client application can put messages to, and get messages from, the queues that are owned by that queue manager.
The client application can then use the MQCMIT call to commit the unit of work or the MQBACK call to back out the unit of work.
In this situation, the queue manager is acting as a transaction manager.
However, within the same unit of work, the client application cannot update the resources of another resource manager,
the tables of a DB2 database, for example.
This means that the queue manager can act only as a resource manager, not as a transaction manager.
Using a WebSphere MQ extended transactional client removes this restriction.
ETC scenario
He had:
- AIX 5.3
- WebSphere MQ 6.0
- TXSEries 6.2
- Extended Transactional Client (ETC) configured for XA two phase commit support.
TXSeries acts as XA transaction manager for two XA resource managers: WebSphere MQ 6.0 and Oracle DBMD 10.2.
We would like XA static registration for Oracle DBMS and XA dynamic registration for WebSphere MQ.
The result is both Oracle and WebSphere MQ use static registration.
The switch load file is produced with this command:
xlc_r amqzscix.c -I/usr/include -I/usr/lpp/cics/include -e amqzscix -o amqczsc
/usr/lpp/cics/lib/regxa_swxa.o -L/usr/lpp/cics/lib
L/usr/mqm/lib -lmqmcs_r -lmqccics_r -lmqcxa_r -lmqiz_r -lcicsrt -lEncina -lpthreads lsarpc
The source code is "amqzscix" supplied with WebSphere MQ; this is a very trivial program:
- it includes "xa.h" header file supplied with TXSeries
- it references two instances of struct xa_switch_t supplied by "libmqcxa_r.a" (MQRMIXASwitch and MQRMIXASwitchDynamic)
- it retrieves the pointer to MQRMIXASwitchDynamic and assign the reference to an external pointer supplied by TXSeries (cics_xa_switch)
The function contains no logic and perform this unconditioned assignment:
cics_xa_switch = & MQRMIXASwitchDynamic ;
It seems WebSphere MQ declare itself as capable of dynamic registration.
I wrote a trivial program to inspect the content of the XA switch struct:
#include <string.h>
#include <stdio.h>
#include <tmxa/xa.h>
extern struct xa_switch_t MQRMIXASwitch;
extern struct xa_switch_t MQRMIXASwitchDynamic;
int main(int argc, char *argv[])
{
printf("flags: %d\n", MQRMIXASwitchDynamic.flags);
return 0;
}
Compiled with this command:
xlc_r pippo.c -I/usr/lpp/cics/include -o pippo -L/usr/mqm/lib -lmqcxa_r
The result is "3".
Looking at xa.h, it means:
#define TMREGISTER 0x00000001L /* resource manager dynamically registers */
#define TMNOMIGRATE 0x00000002L /* resource manager does not support association migration */
It should use dynamic registration, but inspecting the TXSeries console,
every time an application server starts, it performs Oracle and WebSphere MQ xa_open,
even if the application server starts just because you are connecting with a new terminal.
Removing Oracle definition does not change the behaviour:
even if WebSphere MQ is the only XA resource manager, every time an application server starts, the xa_open, xa_recover functions are called:
ERZ080088I/0801 CS1GDIA1 495824/0001 XA OPEN submitted for Server 102 connected to 'MQSeries_XA_RMI' using XA_OPEN string 'qmname=QS1GD0A1'
ERZ080006I/0801 CS1GDIA1 495824/0001 XA_OPEN succeeded: Application Server 102 connected to 'MQSeries_XA_RMI' using XA_OPEN string 'qmname=QS1GD0A1'
ERZ080089I/0801 CS1GDIA1 495824/0001 XA OPEN completed for Server 102 connected to 'MQSeries_XA_RMI' using XA_OPEN string 'qmname=QS1GD0A1'
ERZ080090I/0801 CS1GDIA1 495824/0001 XA RECOVER submitted for Server 102 connected to 'MQSeries_XA_RMI'
ERZ080091I/0801 CS1GDIA1 495824/0001 XA RECOVER completed for Server 102 connected to 'MQSeries_XA_RMI'
