Adding configuration information to the queue manager

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

To specify the location, perform the following steps:

  • On Windows and Linux (x86 and x86-64 platforms) systems use the IBM 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 Display 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 Change 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 IBM 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 the IBM MQ application process

    The security and permissions attributes of our switch load file must allow these processes to perform this action.

    XAOpenString=string
    This is a string of data that IBM 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 IBM 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 the IBM 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.

    From IBM MQ Version 8.0.0, Fix Pack 4, when the XAOpenString contains a password, we can get IBM MQ to protect this information, rather than having the password visible in plain text in the qm.ini file. IBM MQ stores the user name and the password (in an encrypted form) in a different file, and uses these credentials to connect to the database. For details, see Protection of database authentication details.

    XACloseString=string
    This is a string of data that IBM 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 IBM 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 the IBM 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 the 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 we can set the ThreadOfControl attribute to THREAD or PROCESS. We recommend that, if we can, you set ThreadOfControl to THREAD. If in doubt, the safer option is to set it to PROCESS, although we will lose the potential performance benefits of using THREAD.

Parent topic: Configure the system for database coordination