Adding configuration information to the queue manager

When you have created a switch load file for your database manager, and placed it in a safe location, you must specify that location to your queue manager.

Note: This topic is also available in IBM® MQ Version 8.0 and later versions. However, you cannot switch to a later version using the Change version list box. To go to the topic in a later version, edit the version number in the URL box in your browser.
To specify the location, perform the following steps:
  • On Windows and Linux® (x86 and x86-64 platforms) systems use the WebSphere® MQ Explorer. Specify the details of the switch load file in the queue manager properties panel, under XA resource manager.
  • On all other systems specify the details of the switch load file in the XAResourceManager stanza in the queue manager's qm.ini file.
Add an XAResourceManager stanza for the database that your queue manager is going to coordinate. The most common case is for there to be only one database, and therefore only one XAResourceManager stanza. For details of more complicated configurations involving multiple databases, see Multiple database configurations. The attributes of the XAResourceManager stanza are as follows:
Name=name
User-chosen string that identifies the resource manager. In effect, it gives a name to the XAResourceManager stanza. The name is mandatory and can be up to 31 characters in length.

The name you choose must be unique; there must be only one XAResourceManager stanza with this name in this qm.ini file. The name should also be meaningful, because the queue manager uses it to refer to this resource manager both in queue manager error log messages and in output when the dspmqtrn command is used. (See Displaying outstanding units of work with the dspmqtrn command for more information.)

Once you have chosen a name, and have started the queue manager, do not change the Name attribute. For more details about changing configuration information, see Changing configuration information.

SwitchFile=name
This is the name of the XA switch load file you built earlier. This is a mandatory attribute. The code in the queue manager and WebSphere MQ application processes tries to load the switch load file on two occasions:
  1. At queue manager startup
  2. When you make the first call to MQBEGIN in your WebSphere MQ application process
The security and permissions attributes of your switch load file must allow these processes to perform this action.
XAOpenString=string
This is a string of data that WebSphere MQ code passes in its calls to the database manager's xa_open function. This is an optional attribute; if it is omitted a zero-length string is assumed.
The code in the queue manager and WebSphere MQ application processes call the xa_open function on two occasions:
  1. At queue manager startup
  2. When you make the first call to MQBEGIN in your WebSphere MQ application process
The format for this string is particular to each database product, and will be described in the documentation for that product. In general, the xa_open string contains authentication information (user name and password) to allow a connection to the database in both the queue manager and the application processes.
XACloseString=string
This is a string of data that WebSphere MQ code passes in its calls to the database manager's xa_close function. This is an optional attribute; if it is omitted a zero-length string is assumed.
The code in the queue manager and WebSphere MQ application processes call the xa_close function on two occasions:
  1. At queue manager startup
  2. When you make a call to MQDISC in your WebSphere MQ application process, having earlier made a call to MQBEGIN
The format for this string is particular to each database product, and will be described in the documentation for that product. In general, the string is empty, and it is common to omit the XACloseString attribute from the XAResourceManager stanza.
ThreadOfControl=THREAD|PROCESS
The ThreadOfControl value can be THREAD or PROCESS. The queue manager uses it for serialization purposes. This is an optional attribute; if it is omitted, the value PROCESS is assumed.

If the database client code allows threads to call the XA functions without serialization, the value for ThreadOfControl can be THREAD. The queue manager assumes that it can call the XA functions in the database client shared library from multiple threads at the same time, if necessary.

If the database client code does not allow threads to call its XA functions in this way, the value for ThreadOfControl must be PROCESS. In this case, the queue manager serializes all calls to the database client shared library so that only one call at a time is made from within a particular process. You probably also need to ensure that your application performs similar serialization if it runs with multiple threads.

Note that this issue, of the database product's ability to cope with multi-threaded processes in this way, is an issue for that product's vendor. Consult the database product's documentation for details on whether you can set the ThreadOfControl attribute to THREAD or PROCESS. We recommend that, if you can, you set ThreadOfControl to THREAD. If in doubt, the safer option is to set it to PROCESS, although you will lose the potential performance benefits of using THREAD.