+

Search Tips | Advanced Search

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 you begin

To migrate applications from an earlier version of the product to the later version, you 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.

Read Multi-installation queue manager coexistence on UNIX, Linux, and Windows before starting this task.

Plan and install the later version of IBM MQ, and remember the installation name and whether the installation was set to primary.


To migrate an application from an earlier version of the product to the later version, we do not have to recompile or relink the application, because the IBM MQ libraries are compatible with later versions; see Application compatibility and interoperability with later versions of IBM MQ.

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 
gcc -m32 -o amqsput_32_r amqsput0.c -I/opt/mqm/inc -L/opt/mqm/lib
-Wl,-rpath=/opt/mqm/lib -Wl,-rpath=/usr/lib -lmqm_r -lpthread

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 you are following:

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.

Table 1. UNIX and Linuxconfigurations
 

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

  1. 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? You 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? You 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 we 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.
  2. 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, you 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, you must decide which installation to make primary, if we 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.

1 LIBPATH on AIX . On HP-UX