[UNIX, Linux, Windows]

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

You can install multiple copies of IBM® MQ for UNIX, Linux®, and Windows on the same server. The installations must be at IBM WebSphere® MQ 7.1 or later, with one exception. One IBM WebSphere MQ 7.0.1 installation, at fix pack level 6, or later, can coexist with multiple IBM WebSphere MQ 7.1, or later installations.

Figure 1 shows two IBM MQ installations, two queue managers, and three applications. Applications 2 and 3 are connected to QM2, and application 1 is connected to QM1. Applications 1 and 3 load IBM MQ libraries from the Inst_1 installation, and application 2 loads libraries from the IBM WebSphere MQ 7.0.1 installation.

Figure 1. Coexistence of two queue managers using IBM WebSphere MQ 7.0.1 and a later version installations
The diagram shows three applications. Applications 2 and 3 are connected to QM2, and application 1 is connected to QM1. Applications 1 and 3 are linked to Inst_1, and application 2 is linked to IBM WebSphere MQ 7.0.1. The connections to the queue managers are established by calling MQCONN or MQCONNX in the normal way.

When you upgrade from IBM WebSphere MQ 7.0.1 to a later version, you can choose to run IBM WebSphere MQ 7.0.1 alongside the later version. The installation, illustrated in Figure 1, is called a multi-version installation. You can also install multiple copies of IBM WebSphere MQ 7.1 alongside each other. That would be called multi-installation. Multi-installation is the more general term.

IBM WebSphere MQ 7.0.1 did not support multi-installation on Multiplatforms. Before IBM WebSphere MQ 7.1 became available, IBM WebSphere MQ 7.0.1 Fix Pack 6 was shipped with some fixes to make IBM WebSphere MQ 7.0.1 compatible with a later version on the same server. With IBM WebSphere MQ 7.0.1 Fix Pack 6 installed, you can run one copy of IBM WebSphere MQ 7.0.1 alongside multiple copies of the later version. You do not have to apply the fix pack to upgrade IBM WebSphere MQ 7.0.1 to 7.1 in-place ; see Migrating on UNIX and Linux: single-stage or Migrating on Windows: single stage.

A multi-version installation that includes IBM WebSphere MQ 7.0.1, does not behave the same way as a multi-installation that does not. The differences primarily affect how you might choose to configure how applications load IBM MQ libraries, and run IBM MQ commands. Because of these differences, think of the multi-version support provided in IBM WebSphere MQ 7.0.1 Fix Pack 6, as a migration aid to moving to a later version multi-installation environment. The topics that explain the restrictions in IBM WebSphere MQ 7.0.1 multi-version are listed in related links.

If you run multiple installations of IBM MQ on a server you must consider three questions:

  1. Which installation is a queue manager associated with; see Queue manager association ?
  2. Which installation does an application load; see Loading IBM MQ libraries ?
  3. Which installation is an IBM MQ command run from; see Command association ?

Queue manager association

Before IBM WebSphere MQ 7.1, queue managers on UNIX, Linux, or Windows were associated with the only installation on the server. With IBM WebSphere MQ 7.1 or later installed on the same server as IBM WebSphere MQ 7.0.1, you can change the association of a queue manager to a later version by running setmqm ; see setmqm. You cannot change the association of a queue manager running a release of IBM MQ earlier than IBM WebSphere MQ 7.0.1 because you cannot install a later version of the product on a server with an installation of IBM MQ earlier than IBM WebSphere MQ 7.0.1.

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 was running IBM WebSphere MQ 7.0.1, it is migrated to a later version. QM2 is associated with IBM WebSphere MQ 7.0.1 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 WebSphere MQ 7.0.1 library for application 2. The operating system has loaded the wrong library for application 3. Application 3 requires the IBM WebSphere MQ 7.0.1 libraries.

Figure 2 shows what happens to application 3. Application 3 is connecting to QM2, and QM2 is associated with the IBM WebSphere MQ 7.0.1 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 WebSphere MQ 7.0.1 installation. It transfers the MQCONN or MQCONNX call to the IBM WebSphere MQ 7.0.1 library. Subsequent MQI calls that use the connection handle returned by MQCONN or MQCONNX, call entry points in the IBM WebSphere MQ 7.0.1 library.

Because IBM WebSphere MQ 7.0.1 libraries cannot load IBM MQ libraries from other installations, there is no corresponding application in Figure 2 that loads an IBM WebSphere MQ 7.0.1 library and connects to a queue manager running IBM WebSphere MQ 7.1. If you attempt a connection to QM1 with application 2, IBM MQ returns an error; see 2059 (080B) (RC2059): MQRC_Q_MGR_NOT_AVAILABLE.

Figure 2. Loading calls in a different library
The diagram shows two applications. Applications 2 and 3 are connected to QM2. Application 2 loads a library from IBM WebSphere MQ 7.0.1. Application 3 loads a library from IBM WebSphere MQ 7.1. IBM WebSphere MQ loads the correct IBM WebSphere MQ 7.0.1 library for application 3. The connections to the queue managers are established by calling MQCONN or MQCONNX in the normal way.

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

The new loading capability of IBM WebSphere MQ libraries in IBM WebSphere MQ 7.1, or later, does not relax the restriction that an application compiled and linked at a later release level must not directly load an IBM WebSphere MQ library at an earlier release level. In practice the restriction is of less significance than in earlier releases, because 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 WebSphere MQ can call any other level of IBM WebSphere MQ on the same server from IBM WebSphere MQ 7.0.1 upwards.

For example, suppose you recompile and link an application that is to connect to an IBM WebSphere MQ 7.0.1 queue manager using the libraries shipped with IBM WebSphere MQ 7.1. At run time the operating system must load the IBM WebSphere MQ 7.1 libraries for the application, even though the application connects to an IBM WebSphere MQ 7.0.1 queue manager. IBM WebSphere MQ 7.1 detects the inconsistency and loads the IBM WebSphere MQ 7.0.1 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 WebSphere MQ library that matches the later release, even if it continues to connect to an IBM WebSphere MQ 7.1 queue manager.

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

Special migration considerations involving loading IBM MQ libraries

You might have been asked to modify the installation of an earlier 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. The requirement to move IBM MQ libraries to other directories was one of the reasons for changing the installation of IBM MQ on UNIX and Linux. You can now install IBM MQ into a directory of your choosing. You can also load IBM MQ libraries from the /usr/lib directory, which is normally on the default load path on UNIX and Linux systems.

A common IT standard or build environment requirement is to include IBM MQ libraries in the default load path on UNIX and Linux systems. IBM WebSphere MQ 7.1 has a solution. In IBM MQ 9.0 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 WebSphere MQ 7.1 or later 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.

Because IBM WebSphere MQ 7.1, or later, libraries transfer calls to the correct installation, defining that version installation as primary, also results in the correct libraries being loaded for any application that is built with a link to /usr/lib, regardless of which queue manager it connects to. Unfortunately, this solution does not work if you have an IBM WebSphere MQ 7.0.1 installation on the server, because then you cannot define an IBM WebSphere MQ 7.1 or later installation as primary, and the IBM WebSphere MQ 7.0.1 libraries do not load libraries from other installations. As an alternative to setting the later version installation primary, use setmqenv with the -k or -l options to achieve a similar result.

You can find more information in 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; see Figure 3.

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 ; 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.

setmqenv must be on the search path in order to run it. One reason for having a later version installation as primary is to be able to run setmqenv without having to configure the search path. If IBM WebSphere MQ 7.0.1 is installed on the server, no IBM WebSphere MQ 7.1, or later, installation can be primary and IBM WebSphere MQ 7.0.1 does not have a setmqenv command. The consequence is, you must provide a path to run the setmqenv command to set up the command environment for any of the later version installations on the server.

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

Figure 3. Running setmqenv

IBM WebSphere MQ for Windows 7.1


" MQ_INSTALLATION_PATH\bin\setmqenv" -m QM1

IBM WebSphere MQ 7.1 for UNIX and Linux


. MQ_INSTALLATION_PATH/bin/setmqenv -m QM1