Loading IBM MQ libraries

When deciding how to load IBM MQ libraries, we need to consider a number of factors, including: the environment, whether we can change your existing applications, whether we want a primary installation, where IBM MQ is installed, and whether the location of IBM MQ is likely to change.

This information applies to IBM WebSphere MQ Version 7.1, or later version, libraries.

How IBM MQ libraries are located and loaded depends on your installation environment:

  • On UNIX and Linux systems, if a copy of IBM WebSphere MQ Version 7.1, or later version, is installed in the default location, existing applications continue to work in the same way as previous versions. However, if the applications need symbolic links in /usr/lib, we must either select a Version 7.1, or later version, installation to be the primary installation, or manually create the symbolic links.
  • If IBM WebSphere MQ Version 7.1, or later version, is installed in a non-default location, which is the case if IBM WebSphere MQ Version 7.0.1 is also installed, you might need to change your existing applications so that the correct libraries are loaded.

How IBM MQ libraries can be located and loaded also depends on how any existing applications are set up to load libraries. For more information about how libraries can be loaded, see Operate system library loading mechanisms.

Optimally, we should ensure the IBM MQ library, that is loaded by the operating system, is the one with which the queue manager is associated.

The methods for loading IBM MQ libraries vary by platform, and each method has benefits and drawbacks.

Platform Option Benefits Drawbacks
UNIX and Linux systems Set or change the embedded runtime search path (RPath) of the application.

This option requires you to recompile and link the application. For more information about compiling and linking applications, see Building a procedural application.

  • Scope of the change is clear.

  • We must be able to recompile and link the application.
  • If the location of IBM MQ changes, we must change the RPath.

UNIX and Linux systems Set the LD_LIBRARY_PATH environment variable, using setmqenv, or crtmqenv, with the -k or -l option. (

On AIX, this environment variable is LIBPATH

  • No changes to existing applications required.
  • Overrides embedded RPaths in an application.
  • Easy to change the variable if the location of IBM MQ changes.

  • setuid and setgid applications, or applications built in other ways, might ignore LD_LIBRARY_PATH for security reasons.
  • Environment specific, so must be set in each environment where the application is run.
  • Possible impact on other applications that rely on LD_LIBRARY_PATH.
  • Linux: The compiler used to build the application might disable the use of LD_LIBRARY_PATH. For more information, see Runtime linking considerations for Linux .

Windows systems Set the PATH variable using setmqenv, or crtmqenv.

  • No changes required for existing applications.
  • Easy to change the variable if the location of IBM MQ changes.

  • Environment specific, so must be set in each environment where the application is run.
  • Possible impact on other applications.

UNIX, Linux, and Windows systems Set the primary installation to a Version 7.1, or later, installation. See Change the primary installation.

For more information about the primary installation, see Choose a primary installation.

  • No changes required for existing applications.
  • Easy to change the primary installation if the location of IBM MQ changes.
  • Gives similar behavior to previous versions of IBM MQ.

  • When IBM WebSphere MQ Version 7.0.1 is installed, we cannot set the primary installation to Version 7.1, or later.
  • UNIX and Linux: Does not work if /usr/lib is not in the default search path.


Library loading considerations for Linux

Applications compiled using some versions of gcc, for example, version 3.2.x, can have an embedded RPath that cannot be overridden using the LD_LIBRARY_PATH environment variable. We can determine if an application is affected by using the readelf -d applicationName command. The RPath cannot be overridden if the RPATH symbol is present and the RUNPATH symbol is not present.


Operate system library loading mechanisms

On Windows systems, several directories are searched to find the libraries:

  • The directory the application is loaded from.
  • The current directory.
  • The directories in the PATH environment variable, both the global PATH variable and the PATH variable of the current user.

On UNIX and Linux systems, there are a number of methods that might have been used to locate the libraries to load:

  • Use the LD_LIBRARY_PATH environment variable (also LIBPATH on AIX). If this variable is set, it defines a set of directories that are searched for the required IBM MQ libraries. If any libraries are found in these directories, they are used in preference of any libraries that might be found using the other methods.
  • Use an embedded search path (RPath). The application might contain a set of directories to search for the IBM MQ libraries. If the LD_LIBRARY_PATH is not set, or if the required libraries were not found using the variable, the RPath is searched for the libraries. If your existing applications use an RPath, but we cannot recompile and link the application, we must either install IBM WebSphere MQ Version 7.1 in the default location, or use another method to find the libraries.
  • Use the default library path. If the IBM MQ libraries are not found after searching the LD_LIBRARY_PATH variable and RPath locations, the default library path is searched. Usually, this path contains /usr/lib or /usr/lib64. If the libraries are not found after searching the default library path, the application fails to start because of missing dependencies.

We can use operating system mechanisms to find out if the applications have an embedded search path. For example:

  • AIX: dump
  • Linux: readelf

Parent topic: Connect applications in a multiple installation environment


Related concepts


Related tasks


Related information