Restrictions for applications using multiple installations

There are restrictions when using CICS® server libraries, fast path connections, message handles, and exits in a multiple installation environment.


CICS server libraries

If you are using the CICS server libraries, IBM MQ does not automatically select the correct library level for you. You must compile and link our applications with the appropriate library level for the queue manager to which the application connects. For more information, see Building libraries for use with TXSeries® for Multiplatforms version 5.


Message handles

Message handles that use the special value of MQHC_UNASSOCIATED_HCONN are limited to use with the first installation loaded in a process. If the message handle cannot be used by a particular installation, reason code MQRC_HMSG_NOT_AVAILABLE is returned.

This restriction affects message properties. We cannot use message handles to get message properties from a queue manager on one installation and put them to a queue manager on a different installation. For more information about message handles, see MQCRTMH - Create message handle.


Exits

In a multiple installation environment, existing exits must be updated for use with IBM WebSphere MQ Version 7.1, or later, installations. Data conversion exits generated using the crtmqcvx command must be regenerated using the updated command.

All exits must be written using the MQIEP structure, cannot use an embedded RPATH to locate the IBM MQ libraries, and cannot link to the IBM MQ libraries. For more information, see Writing exits and installable services on UNIX, Linux , and Windows .


Fast path

On a server with multiple installations, applications using a fast path connection to IBM WebSphere MQ Version 7.1 or later must follow these rules:

  1. The queue manager must be associated with the same installation as the one from which the application loaded the IBM MQ run time libraries. The application must not use a fast path connection to a queue manager associated with a different installation. An attempt to make the connection results in an error, and reason code MQRC_INSTALLATION_MISMATCH.
  2. Connecting non-fast path to a queue manager associated with the same installation as the one from which the application has loaded the IBM MQ run time libraries prevents the application connecting fast path, unless either of these conditions are true:

    • The application makes its first connection to a queue manager associated with the same installation a fast path connection.
    • The environment variable, AMQ_SINGLE_INSTALLATION is set.
  3. Connecting non-fast path to a queue manager associated with a Version 7.1 or later installation, has no effect on whether an application can connect fast path.
  4. We cannot combine connecting to a queue manager associated with a Version 7.0.1 installation and connecting fast path to a queue manager associated with a Version 7.1, or later installation.
With AMQ_SINGLE_INSTALLATION set, we can make any connection to a queue manager a fast path connection. Otherwise almost the same restrictions apply:

  • The installation must be the same one from which the IBM MQ run time libraries were loaded.
  • Every connection on the same process must be to the same installation. If you attempt to connect to a queue manager associated with a different installation, the connection fails with reason code MQRC_INSTALLATION_MISMATCH. Note that with AMQ_SINGLE_INSTALLATION set, this restriction applies to all connections, not only fast path connections.
  • Only connect one queue manager with fast path connections.