Configuring the queue manager to coordinate JMS resources on Windows

Use IBM® MQ Explorer to configure the global (XA) resource managers for the queue manager.

About this task

Before you deploy a message flow in which the Transaction mode property is set to Global or Yes, and is intended to use XA coordinated transactions, modify the queue manager .ini file to include extra definitions for each JMS provider resource manager that participates in globally coordinated transactions.

To configure the queue manager for Windows:

Procedure

  1. Open IBM MQ Explorer.
  2. Select the queue manager for your integration node and click Properties.
  3. Select XA resource managers in the left pane and click Add.
  4. Complete the fields to define a new resource manager:
    1. Name: Enter the name of the resource manager; for example, IIBWMQJMS.
    2. SwitchFile: Enter DynJMSSwitch.
    3. On XAOpenString, enter the following values, which are comma delimited and positional. Represent missing optional parameters by a comma if you include other parameters later in the string.
      Initial Context Factory
      The Initial Context Factory identifier for the JMS provider; this value is required.
      Location of JNDI bindings
      Either the file path to the bindings file, or the LDAP directory location of the JNDI administered objects that can be used to create an initial context factory for the JMS connection. If you supply the file path to the bindings file, do not include the file name. See the JMSInput or JMSOutput node for further details about creating the JNDI administered objects; this value is required.

      The values for the Initial Context factory and Location of JNDI bindings in the stanza must match the values that you specified in the JMS or SOAP nodes in the message flows.

      LDAP Principal
      Optional: The principal (user ID) that might be required when an LDAP database is used to hold the JNDI administered objects. LDAP Principal is not currently supported, it is reserved for future use.
      LDAP Credentials
      Optional: The credentials (password) that might be required if a password protected LDAP database is used to hold the JNDI administered objects.

      All LDAP parameters must match the values that you specified on the mqsicreatebroker or mqsichangebroker command. LDAP Credentials is not currently supported, it is reserved for future use.

      Recovery Connection Factory Name
      Optional: The name of a Queue Connection Factory object in the JNDI administered objects for recovery purposes, when the non-default name is required.

      The Recovery Factory Name must match a Queue Connection Factory name that is created in the JNDI administered objects. If you do not specify a name, a default factory that is called recoverXAQCF is used. In either case, this value must refer to a JNDI administered object that has already been created.

      JMS Principal
      The user ID that is required to connect to a JMS provider, using a secure JMS Connection Factory. JMS Principal is not currently supported, it is reserved for future use.
      JMS Credentials
      The password that is required to connect to the same JMS provider with the JMS principal. JMS Credentials is not currently supported, it is reserved for future use.

      The JMS Principal and JMS Credentials must be configured together.

    1. XACloseString: Leave this field blank.
    2. ThreadOfControl: Set the value to Thread.
  5. Click OK to complete the XA resource manager definition.
  6. Click OK to close the queue manager properties dialog.
  7. Click File > Exit to close IBM MQ Explorer.
  8. Copy the DynJMSSwitch.dll file to the \exits64 folder in the IBM MQ installation directory.
  9. Copy the DynJMSSwitch32.dll file to the \exits directory in the IBM MQ installation directory and then rename the file to DynJMSSwitch.dll.
  10. Set the XAOpenString property to a string value as follows: Initial Context,location JNDI,Optional_parms.
  11. Set the ThreadOfControl property to Thread.

What to do next

  • Check your configuration:
    • In the message flow, ensure that the coordinated property is enabled by using the IBM Integration Bus Archive editor.
    • Ensure that each node that must be part of the XA transaction is set to the global transaction mode.
    • Ensure that the service ID that is used for the integration node and the queue manager is the same user ID.
    • Ensure that the JNDI connection factory objects that the JMS nodes use for a global transaction are configured to be of the type MQXAConnectionFactory, MQXAQueueConnectionFactory, or MQXATopicConnectionFactory.
      • If you create the bindings by using JMSAdmin, use the command DEF XAQCF or DEF XATCF, instead of DEF QCF or DEF TCF, when you define your connection factory.
  • Authorize the integration node and queue manager to access shared resources that are associated with the JMS provider; see Windows systems: modifying the queue manager authorization.

For more information, see Transactional support in the IBM MQ Version 7.5 product documentation online.

Troubleshooting

IBM Integration Bus examines the IBM MQ registry to determine if the queue manager is XA enabled. If IBM Integration Bus is unable to locate the location of the queue managers working directory, an error is issued at startup. You can specify this location by setting the following environment variable in the mqsiprofile script: MQ_DATA_PATH For example:
MQ_DATA_PATH="C:\Program Files (x86)\IBM\WebSphere MQ"