UNIX and Linux: Migrating IBM WebSphere MQ library loading from Version 7.0.1 to Version 7.5

Investigate whether applications connecting to IBM® WebSphere® MQ for Windows Version 7.5 are linked to, and load libraries from, the correct installation.

Before you begin

Read Multi-installation queue manager coexistence on UNIX, Linux, and Windows and Migrating IBM WebSphere MQ library loading from Version 7.0.1 to Version 7.5 before starting this task.

Plan and install IBM WebSphere MQ for Windows Version 7.5, and remember the installation name and whether the installation was set to primary.

About this task

In Version 6.0 and Version 7.0.1, the documented build procedure for IBM WebSphere MQ applications is to include an explicit library path to the location of the IBM WebSphere MQ libraries, and to /usr/lib, in the link step of the compiler; see Figure 1. The same build procedure is documented for Version 7.5. Previous versions of IBM WebSphere MQ, before Version 6.0, did not document a specific location to load run time libraries from.

Figure 1. Linux C server application, 32 bit, threaded compile and link Version 7.0.1

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 documented build step for other UNIX platforms is similar. The examples in Table 1 are all based on Linux.

If you have followed this build procedure, then the effect of installing Version 7.5 on library loading depends on the migration scenario; see Table 1:

Table 1. UNIX and Linux configurations
	Scenario	Version 7.5 replaces Version 7.0.1 in the same location Single-stage	Version 7.5 replaces Version 7.0.1 in a different location Side-by-side	Version 7.5 alongside Version 7.0.1 Multi-stage
Action	Scenario			Version 7.5 alongside Version 7.0.1 Multi-stage
setmqinst		setmqinst makes the Version 7.5 installation primary. Symbolic links to the IBM WebSphere MQ link libraries are inserted into /usr/lib.		No Version 7.5 installation can be primary, because Version 7.0.1 is installed.
No other configuration actions		Library loading works correctly. Library loading works, even without the Version 7.5 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 Version 7.0.1 correctly, nothing works with Version 7.5.
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 Version 7.0.1 correctly, nothing works with Version 7.5.
setmqenv, with the -k or -l options set.		Library loading works correctly.		Library loading works correctly, both for Version 7.0.1 and Version 7.5. The correct Version 7.0.1 is loaded, because the Version 7.5 library loads the Version 7.0.1 library for queue managers that have not been migrated from Version 7.0.1.
setmqenv, with the -k or -l options set.		The operating system finds the IBM WebSphere MQ library location set by setmqenv. setmqenv adds the location to `LD_LIBRARY_PATH`¹. `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

Identify which Version 7.5 installation the operating system is going to load IBM WebSphere MQ libraries from:

If you have a multiple Version 7.5 installations to load from on a server, IBM WebSphere MQ checks that the installation the library was loaded from is the installation that is associated with any queue manager the application calls. IBM WebSphere MQ loads the correct library if the wrong library is loaded. It is necessary to configure only one runtime environment for all IBM WebSphere MQapplications.
A typical choice is to set the primary installation. Setting an installation to be primary places symbolic links to the IBM WebSphere MQ libraries in /usr/lib. Applications built following the Version 6.0 or 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 a Version 7.0.1 installation to Version 7.5, a link path to the Version 7.0.1 installation now points to a Version 7.5 installation. Applications that have a fixed linkage path to the Version 7.0.1 installation now load the Version 7.5 libraries. 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 a Version 7.5 installation.
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 Version 7.5 installations, you must decide which installation to make primary, if you have chosen to make any primary. As long as applications load IBM WebSphere MQ libraries from one of the Version 7.5 installations, such as the primary installation, they can connect to queue managers associated with any other Version 7.5 installation.

¹ LIBPATH on AIX®. On HP-UX LD_LIBRARY_PATH is set, not SHLIB_PATH.