Multi-installation queue manager coexistence on UNIX, Linux, and Windows

Queue manager association

A queue manager is permanently associated with an installation, until you choose to change the association with the setmqm command. You cannot associate a queue manager with an installation at a lower command level than the current command level of the queue manager.

In Figure 1, QM1 is associated with Inst_1. The association is made by running setmqm -m QM1 -n Inst_1. When QM1 is first started, after running setmqm, if QM1 is running IBM MQ 8.0 it is migrated to the later version. QM2 is associated with IBM MQ 8.0 because the association has not been changed.

Loading IBM MQ libraries

The application connections to the queue managers are established by calling MQCONN or MQCONNX in the normal way.

Which IBM MQ library an application loads depends on the configuration of the operating system loader, and on the IBM MQ installation the queue manager is associated with. In Figure 1, the operating system loads the IBM MQ library from the Inst_1 installation for applications 1 and 3. It loads the IBM MQ 8.0 library for application 2. The operating system has loaded the wrong library for application 3. Application 3 requires the IBM MQ 8.0 libraries.

Figure 2 shows what happens to application 3. Application 3 is connecting to QM2, and QM2 is associated with the IBM MQ 8.0 installation. IBM MQ detects that the operating system has loaded the wrong library to process calls from application 3 to QM2. IBM MQ loads the correct library from the IBM MQ 8.0 installation. It transfers the MQCONN or MQCONNX call to the IBM MQ 8.0 library. Subsequent MQI calls that use the connection handle returned by MQCONN or MQCONNX, call entry points in the IBM MQ 8.0 library.

If you attempt a connection to QM1 with application 2, IBM MQ returns an error; see 2059 (080B) (RC2059): MQRC_Q_MGR_NOT_AVAILABLE.

From IBM WebSphere® MQ 7.1, IBM MQ libraries include a routing capability that is based on the installation a queue manager is associated with. The operating system can load a library from any IBM WebSphere MQ 7.1 or later installation, and IBM MQ transfers MQI calls to the correct library.

The loading capability of IBM MQ libraries does not relax the restriction that an application compiled and linked at a later release level must not directly load an IBM MQ library at an earlier release level. In practice, as long as the operating system loads a library at the same or later level than the library the application was compiled and linked with, IBM MQ can call any other level of IBM MQ on the same server.

For example, suppose you recompile and link an application that is to connect to an IBM MQ 8.0 queue manager using the libraries shipped with IBM MQ 9.0. At run time the operating system must load the IBM MQ 9.0 libraries for the application, even though the application connects to an IBM MQ 8.0 queue manager. IBM MQ 9.0 detects the inconsistency and loads the IBM MQ 8.0 library for the application. The same applies to any future release. If the application is recompiled and linked against a later release, then the application must load an IBM MQ library that matches the later release, even if it continues to connect to an IBM MQ 9.0 queue manager.

Your application might not be linked to an IBM MQ library, but instead call the operating system directly to load an IBM MQ library. IBM MQ checks the library is from the installation that is associated with the queue manager. If it is not, IBM MQ loads the correct library.

Special migration considerations involving loading IBM MQ libraries

You might have modified the installation of an early IBM MQ release to satisfy the requirements of a build environment, or the IT standards in your organization. If you copied IBM MQ libraries to other directories, or created symbolic links, you ended up with an unsupported configuration. A common IT standard or build environment requirement is to include IBM MQ libraries in the default load path on UNIX and Linux systems. From IBM WebSphere MQ 7.5, you can install IBM MQ into a directory of your own choosing, and IBM MQ can create symbolic links in /usr and its subdirectories. If you make an IBM MQ installation primary by using the setmqinst command, IBM MQ inserts symbolic links to the IBM MQ libraries into /usr/lib. As a result, the operating system finds the IBM MQ libraries in the default load path, if that includes /usr/lib.

For more information, see Connecting applications in a multiple installation environment.

Command association

Examples of commands are dspmqver, setmqinst, runmqsc, and strmqm. The operating system must find a command in an IBM MQ installation. Many commands also require a queue manager as an argument, and assume the default queue manager if a queue manager name is not provided as a parameter.

Unlike loading libraries, if a command includes a queue manager as a parameter, the command is not switched to the installation that is associated with the queue manager. You must use the setmqenv command to set up your environment correctly, so that any commands that you issue are run from the correct installation. You can provide a queue manager as a parameter to setmqenv, to set up the command environment for that queue manager. For more information, see Running setmqenv.

On Windows, the setmqinst command sets global environment variables, and setmqenv local environment variables, including the PATH variable to find commands.

On UNIX and Linux, the setmqinst command copies symbolic links for a subset of the commands into /usr/bin. For more information, see External library and control command links to primary installation on UNIX and Linux. The setmqenv command sets up local environment variables, including the search path to the binary folder in the installation directory.

The following code shows two examples of running setmqenv to set up the command environment for the copy of IBM MQ that is associated with queue manager QM1.

"%MQ_INSTALLATION_PATH%\bin\setmqenv" -m QM1

. $MQ_INSTALLATION_PATH/bin/setmqenv -m QM1