Migrating IBM MQ library loading to a later
version on UNIX and Linux
On UNIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the
product with the later version, based on the single stage scenario. However, if you choose to take
advantage of multi-installation in the later version of the product, based on the side-by-side or
multi-stage migration scenarios, you might have to configure the runtime environment differently,
for the operating system to load the later version of the IBM MQ library.
Before starting
To migrate applications from an earlier version of the product to the later version, we must
know how the operating system loads a IBM MQ library for
an application. Is the load path fixed by the application, and can you set the path in an
environment variable? It is not essential to know the name of the IBM MQ library that the application loads. The library name does
not change from an earlier version of the product to the later version, although the contents of the
library do.
In Version 7.0.1 and later, the build procedure for
IBM MQ applications is to include an explicit library
path to the location of the IBM MQ libraries, and to
/usr/lib, in the link step of the compiler, as shown in Figure 1. The build procedure is the same for the later version of the product.
Figure 1. Linux C server application, 32 bit, threaded
compile and link
The example shown in Figure 1 is for Linux, but the build step for UNIX platforms is similar.
If we have followed this build procedure in the earlier release, then the effect of installing
the later version of the product on the libraries that are loaded depends on which migration
scenario that we are following:
Single-stage scenario
If we are replacing an earlier version of the product with the later version, based on the
single stage scenario described in Migrating on UNIX and Linux: single-stage, we do not, in most cases, need to
make any changes to the way IBM MQ libraries are loaded.
The possible exception to this is if we changed the location of the libraries from the earlier
version, or created symbolic links to the libraries.
Side-by-side and Multi-stage scenarios
If we have chosen a multi-installation approach to installing the later version of the product,
based either on the side-by-side scenario described in Migrating on UNIX and Linux: side-by-side, or the
multi-stage migration scenario described in Migrating on UNIX and Linux: multi-stage, we must investigate
whether applications connecting to the later version of the product are linked to, and load
libraries from, the correct installation and then modify the environment for the operating system to
resolve IBM MQ dependencies for an application as
appropriate. Typically, we can modify the runtime environment, rather than relink the application.
We can use the following two commands to assist you in configuring the runtime environment:
setmqinst sets the primary installation; see setmqinst.
setmqenv initializes the command environment by setting environment
variables; see setmqenv.
Table 1 summarizes the actions needed for each of these scenarios. The
examples in Table 1 are all based on Linux, but the actions for UNIX are similar.
Scenario
Latest version replaces earlier version in the same location
Single-stage
Latest version replaces earlier version in a different location
Side-by-side
Latest version alongside earlier version
Multi-stage
Action
setmqinst
setmqinst makes the later version installation primary. Symbolic links to the
IBM MQ link libraries are inserted into
/usr/lib.
No. The later version installation can be primary, because an earlier version is
installed.
No other configuration actions
Library loading works correctly.
Library loading works, even without the later version installation being made primary, because
the libraries are installed in /opt/mqm/lib and the application was built with
the link option, -rpath=/opt/mqm/lib
Library loading works correctly.
Library loading works, because the installation is primary, and the application was built with
the link option, -rpath=/usr/lib.
The library loading continues to work with the earlier version correctly, nothing
works with the later version.
setmqenv, without setting the -k or -l
options.
Library loading works correctly.
setmqenv is unnecessary. Library loading works, because the libraries are
installed in /opt/mqm/lib and the application was built with the link option,
-rpath=/opt/mqm/lib.
Library loading works correctly.
setmqenv is unnecessary. Library loading works, because the installation is
primary, and the application was built with the link option, -rpath=/usr/lib.
The library loading continues to work with the earlier version correctly, nothing
works with the later version.
setmqenv, with the -k or -l options set.
Library loading works correctly.
Library loading works correctly, both for the earlier version and the later
version.
The correct earlier version is loaded, because the later version library loads
the earlier version library for queue managers that have not been migrated from the earlier version.
The operating system finds the IBM MQ library
location set by setmqenv. setmqenv adds the location to
LD_LIBRARY_PATH.
This is LIBPATH on AIX .
LD_LIBRARY_PATH is searched before paths set in the application or paths in the
default search path. Not all applications can load a library using LD_LIBRARY_PATH.
In which case the application works only if the library location is
/opt/mqm/lib or /usr/lib
Procedure
Consider which of the following questions apply to your configuration.
Did you follow the build procedure documented in the product documentation for the earlier
version of the product? We might be following a different build procedure tailored to your
development environment, or adapted from a development tool.
How did you specify the load path for the earlier version?
Is the application is loaded by another environment, such as Eclipse, or an application server?
We must modify the parameters that govern how the parent environment loads applications, not the
way the parent environment is loaded.
What constraints and requirements do you have on how the load path is specified in the later
version? Security rules might restrict the use of LD_LIBRARY_PATH.
Is the later version of the product installed alongside the earlier version? If Version 7.0.1 is installed:
We cannot make a later installation primary.
We cannot install the later version in the default installation path, that was referenced by
applications in Version 7.0.1.
Identify the installation of the later version of the product, from which the operating
system is going to load IBM MQ libraries:
If we have a multiple installations of the later versions to load from a server,
IBM MQ checks that the installation the library was
loaded from is the installation that is associated with any queue manager the application calls.
IBM MQ loads the correct library if the wrong library is
loaded. It is necessary to configure only one runtime environment for all IBM MQ applications.
A typical choice is to set the primary installation. Setting an installation to be primary
places symbolic links to the IBM MQ libraries in
/usr/lib. Applications built following the Version 7.0 instructions have an explicit link to
/usr/lib. /usr/lib is also normally in the default library
search path.
If you upgraded an earlier version installation to the later version, a link path to
the earlier version installation now points to an installation containing the later version.
Applications that have a fixed linkage path to the earlier version installation now load the
libraries for the later installation. They are then switched to the installation that is associated
with any queue manager they connect to.
If you rebuild an application, it must link to an installation of the later
version.
If you set LD_LIBRARY_PATH, or LIBPATH on
AIX, we must check that the application is able to
use LD_LIBRARY_PATH. setuid or setgid,
applications, or applications built in other ways, might ignore LD_LIBRARY_PATH for
security reasons.
What to do next
If you add further installations of the later version of the product, we must decide
which installation to make primary, if you have chosen to make any primary. As long as applications
load IBM MQ libraries from one of the later version
installations, such as the primary installation, they can connect to queue managers associated with
any other later version installation.