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

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 installed on the same server as Version 7.0.1, you can change the association of a queue manager to Version 7.1 by running setmqm; see setmqm. You cannot change the association of a queue manager running a release of IBM WebSphere MQ earlier than Version 7.0.1 because you cannot install IBM WebSphere MQ Version 7.1 on a server with an installation of IBM WebSphere 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. 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 Version 7.0.1, it is migrated to Version 7.1. QM2 is associated with Version 7.0.1 because the association has not been changed.

Loading IBM WebSphere MQ libraries

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

Which IBM WebSphere MQ library an application loads depends on the configuration of the operating system loader and on the IBM WebSphere MQ installation the queue manager is associated with.

In Figure 1, the operating system loads the IBM WebSphere 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 WebSphere MQ detects that the operating system has loaded the wrong library to process calls from application 3 to QM2. IBM WebSphere 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 WebSphere 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 WebSphere MQ returns an error; see 2059 (080B) (RC2059): MQRC_Q_MGR_NOT_AVAILABLE .

A Version 7.1 IBM WebSphere MQ 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 Version 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 Version 7.1 does not relax the restriction that an application compiled and linked at a later release level must not directly load a 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 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 WebSphere 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 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 Version 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 WebSphere MQ libraries

You might have been asked to modify the installation of an earlier IBM WebSphere MQ release to satisfy the requirements of a build environment, or the IT standards in your organization. If you copied IBM WebSphere MQ libraries to other directories, or created symbolic links, you ended up with an unsupported configuration. The requirement to move IBM WebSphere MQ libraries to other directories was one of the reasons for changing the installation of IBM WebSphere MQ on UNIX and Linux. You can now install IBM WebSphere MQ into a directory of your choosing. You can also load IBM WebSphere 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 WebSphere MQ libraries in the default load path on UNIX and Linux systems. IBM WebSphere MQ Version 7.1 has a solution. In Version 7.5 you can install IBM WebSphere MQ into a directory of your own choosing, and IBM WebSphere MQ can create symbolic links in /usr and its subdirectories. If you make a Version 7.1 installation primary by using the setmqinst command, IBM WebSphere MQ inserts symbolic links to the IBM WebSphere MQ libraries into /usr/lib. As a result, the operating system finds the IBM WebSphere MQ libraries in the default load path, if that includes /usr/lib.

Because IBM WebSphere MQ Version 7.1 libraries transfer calls to the correct installation, defining Version 7.1 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 a Version 7.0.1 installation on the server, because then you cannot define a Version 7.1 installation as primary, and the Version 7.0.1 libraries do not load libraries from other installations. As an alternative to setting the Version 7.1 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 a IBM WebSphere 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 Version 7.1 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 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 Version 7.1 installations on the server.

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

"MQ_INSTALLATION_PATH\bin\setmqenv" -m QM1

. MQ_INSTALLATION_PATH/bin/setmqenv -m QM1