See information about the latest product version
Installing a user-defined extension to current and past versions of WebSphere Message Broker
Install user-defined extensions that you have developed yourself, or have acquired from an independent software vendor, with the minimum of user intervention.
Complete the following tasks:
- Compiling a Java user-defined node, Compiling a C user-defined extension, or Creating a user-defined node from a subflow
- Creating the user interface representation of a user-defined node in the WebSphere Message Broker Toolkit
- Testing a user-defined node
- Packaging and distributing a user-defined node project
You must install user-defined extensions on all appropriate WebSphere Message Broker computers, and, if the extension is a user-defined node, on the WebSphere Message Broker Toolkit computers (user-defined parsers have no WebSphere Message Broker Toolkit component). If your extension is a user-defined node that contains a custom compiler, you must install the compiled user-defined extension file and the user-defined node plug-in on the brokers to which you want to deploy the node. Components can be installed separately, or as part of one process. The components can be on different systems, therefore check that the installations are completed on all affected systems.
If an extension writes messages to user trace, you must update the environment variable MQSI_CONSOLE_NLSPATH (Windows systems), or NLSPATH (all other systems), so that the mqsiformatlog command can find the message catalog.
The WebSphere Message Broker Toolkit installation
Before installing a user-defined node, check the version of the WebSphere Message Broker Toolkit to which you are installing, because a specific version of the WebSphere Message Broker Toolkit might be a prerequisite of the user-defined extension, or it might require specific files to run.
To determine the version, see Detecting installed versions of WebSphere Message Broker.
Broker installations
You might be required to detect the versions of WebSphere Message Broker that are installed, to ensure that the correct LIL file is loaded by the correct level of the broker. See Detecting installed versions of WebSphere Message Broker.
To add .jar or .lil files to broker installations on WebSphere Message Broker Version 8.0 and later, see Installing user-defined extension runtime files on a broker.
Installing a user-defined extension for single broker
- Version 7.0 and Version 8.0
- To make an extension accessible from only one broker on the system, modify the UserLilPath setting for the broker by specifying the -l parameter on the mqsicreatebroker or mqsichangebroker command.
- Version 6.1 and earlier
- To make a 32-bit extension accessible from only one broker on the system, modify the UserLilPath setting for the broker by specifying the -l parameter on the mqsicreatebroker or mqsichangebroker command.
- To make a 64-bit extension accessible from only one broker on the system, modify the UserLilPath64 setting for the broker by specifying the -r parameter on the mqsicreatebroker or mqsichangebroker command.
For more information, see mqsicreatebroker command and mqsichangebroker command.
Installing a user-defined extension for multiple brokers
- Version 7.0 and Version 8.0
- To affect all brokers on a system, you modify the system LILPATH. Append the directory containing the directory that holds the extension files to the environment variable MQSI_LILPATH. MQSI_LILPATH64 is not valid at this version.
- Version 6.1 and earlier
- To affect all brokers on a system, you modify the system LILPATH. Append the directory containing the directory that holds the extension files to the environment variable MQSI_LILPATH (for 32-bit extensions) or MQSI_LILPATH64 (for 64-bit extensions).
Make this change by creating a custom environment script in the working directory:
On Linux and UNIX systems: /var/mqsi/common/profiles
On Windows: %APPLICATIONDATA%\IBM\MQSI\common\profiles where %APPLICATIONDATA% is the environment variable that defines the system working directory. The default directory depends on the operating system:
- On Windows XP and Windows Server 2003: C:\Documents and Settings\All Users\IBM\MQSI\common\profiles
- On Windows 7 and Windows Server 2008: C:\ProgramData\IBM\MQSI\common\profiles
You can give the environment script any name, but the file extension must be .cmd on Windows and .sh on all other platforms. The script can perform all the operations of a shell script, but you must limit the scope to only appending the following variables:
- MQSI_LILPATH
- Defines the directories to search for plug-ins
- CLASSPATH
- Defines the locations that Java searches for additional classes
- MQSI_CONSOLE_NLSPATH
- On Windows: Defines the location of message catalogs (DLL files)
- NLSPATH
- On Linux and UNIX: Defines the location of message catalogs (CAT files)
- PATH
- Defines the location of executable files. On Windows: This variable also defines the location of dependent libraries.
- LIBPATH / SHLIB_PATH / LD_LIBRARY_PATH
- On UNIX and Linux: Defines the location of dependent libraries.
Example scripts
On Windows: This
example shows the environment profile for MyExtension, which is installed
in C:\Program Files\MyExtensions on Windows 32-bit, or in C:\Program
Files(x86)\MyExtensions on Windows 64-bit.
The script is called MyExtension.cmd and is stored in the working directory. The default location is %APPLICATIONDATA%\IBM\MQSI\common\profiles where the default setting for the environment variable %APPLICATIONDATA% depends on the operating system:
- On Windows XP and Windows Server 2003: C:\Documents and Settings\All Users\.
- On Windows 7 and Windows Server 2008: C:\ProgramData\IBM\MQSI\common\profiles.
The Windows script contains the following content:
REM Added by MyExtension install, do not modify
set MQSI_LILPATH=%MQSI_LILPATH%;"C:\Program Files\MyExtension\bin"
On Linux and UNIX: This example shows the environment
profile for MyExtension, which is installed in /opt/MyExtension.
The script is called MyExtension.sh and is stored
in the working directory /var/mqsi/common/profiles/.
The Linux script contains the following content:
#!/bin/ksh
# Added by MyExtension install, do not modify
export MQSI_LILPATH=/opt/MyExtension/lil${MQSI_LILPATH:+":"${MQSI_LILPATH}}
You can test the following variables in the profile script, for example if you want to ensure that a user-defined extension runs only on a specific version of the broker:
- MQSI_FILEPATH
- The full path to the installed file for WebSphere Message Broker
- MQSI_WORKPATH
- The full path to the configuration data for WebSphere Message Broker
- MQSI_VERSION
- WebSphere Message Broker version, in the form version.release.modification.fix
- MQSI_VERSION_V
- The value of WebSphere Message Broker major version
- MQSI_VERSION_R
- The value of WebSphere Message Broker release
- MQSI_VERSION_M
- The value of WebSphere Message Broker modification number
- MQSI_VERSION_F
- The value of WebSphere Message Broker fix level