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

We can install multiple copies of IBM MQ for UNIX, Linux , and Windows on the same server. The installations must be at Version 7.1 or later, with one exception. One Version 7.0.1 installation, at fix pack level 6, or later, can coexist with multiple Version 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 Version 7.0.1 installation.

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

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

A multi-version installation that includes Version 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 Version 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 Version 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 Version 7.1, queue managers on UNIX, Linux, or Windows were associated with the only installation on the server. With Version 7.1, or later, installed on the same server as Version 7.0.1, we can change the association of a queue manager to a later version by running setmqm ; see setmqm. We cannot change the association of a queue manager running a release of IBM MQ earlier than Version 7.0.1 because we cannot install a later version of the product on a server with an installation of IBM MQ earlier than Version 7.0.1.

A queue manager is permanently associated with an installation, until you choose to change the association with the setmqm command. We 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 Version 7.0.1, it is migrated to a later version. QM2 is associated with Version 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 Version 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 Version 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 Version 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 Version 7.0.1 installation. It transfers the MQCONN or MQCONNX call to the IBM WebSphere MQ Version 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 Version 7.0.1 library.

Because IBM WebSphere MQ Version 7.0.1 libraries cannot load IBM MQ libraries from other installations, there is no corresponding application in Figure 2 that loads a IBM WebSphere MQ Version 7.0.1 library and connects to a queue manager running Version 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.

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

The new loading capability of IBM MQ libraries in Version 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 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 MQ can call any other level of IBM MQ on the same server from Version 7.0.1 upwards.

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

Your application might not be linked to an IBM MQ library, but instead calls the operating system directly to load an IBM MQ library. If the library that is loaded is from Version 7.1 or later, 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 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. We can now install IBM MQ into a directory of your choosing. We 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 Version 7.1 has a solution. In Version 9.0 we 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 a Version 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 Version 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 we have a Version 7.0.1 installation on the server, because then we cannot define a Version 7.1, or later, installation as primary, and the Version 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.

We 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. We 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 Version 7.0.1 is installed on the server, no Version 7.1, or later, installation can be primary and IBM WebSphere MQ Version 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.

IBM WebSphere MQ for Windows Version 7.1

" MQ_INSTALLATION_PATH\bin\setmqenv" -m QM1

IBM WebSphere MQ Version 7.1 for UNIX and Linux

. MQ_INSTALLATION_PATH/bin/setmqenv -m QM1