Installing a user-defined extension to current and past versions of the Broker

Before you start

  1. You must have compiled your user-defined node, as described in Compiling a Java user-defined node or Compiling a C user-defined extension.
  2. You must have tested your user-defined node as described in Testing a user-defined node.

This topic is for third-party users who want to install to WebSphere Message Broker with the least possible user intervention.

In order to install a user-defined extension, the extension needs to be installed to the runtime and to the toolkit. Components can be installed to separately, or as part of one process. The components could be on different systems, so you should ensure that the end-user runs the installations on all affected systems.

Toolkit installation

Before installing an extension, you might need to establish the version of the toolkit you are installing to, because a specific version of the toolkit could be a pre-requisite of the user-defined extension, or it might require specific files to run.

To determine the toolkit version, see Detecting Installed versions of WebSphere Message Broker.

If the product is shell-sharing with another product, the installation path will be that of whichever RAD program was installed first. Use the following steps to determine the location of the toolkit.

To determine the location of the toolkit installation, you need to look at the cdi_ref.properties file, as set up by RAD. This file is installed by the Message Brokers Toolkit and by Rational Version 6.x products: The first time one of these products is installed the file is created. It is shared by all subsequent installations. If all Message Brokers Toolkit and Rational Version 6.x products are uninstalled, the file is removed when the last product is uninstalled.

  1. If you are using Installshield Multiplatform Edition to determine the location, the location resolves to $D(os_main)/IBM/RAT60/.sdpinst/cdi_ref.properties

    In this instance, $D(os_main) is an Installshield variable, which the CDI install framework we use builds onto.

  2. If you are not using Installshield Multiplatform Edition:
    1. The location resolves to /etc/IBM/RAT60/.sdpinst/cdi_ref.properties
    2. Look for the file in two locations, in the following order:
      1. %windir%/IBM/RAT60/.sdpinst/cdi_ref.properties
      2. %SystemRoot%/IBM/RAT60/.sdpinst/cdi_ref.properties
  3. Use the cdi_ref.properties file to detect the presence of a Message Brokers Toolkit installation; search for c_wmbt_specific.products=wmbt

    For the location, look at the following variable: c_wmbt_specifc.b_wmbt_specific.location.

    For example, C:\Program Files\IBM\MessageBrokersToolkit\6.0

    For example, /opt/ibm/MessageBrokerToolkit/6.0

    For the location of the workbench look at variable c_wb.b_wb.location.

    For example, C:\Program Files\IBM\MessageBrokersToolkit\6.0

    For example, /opt/ibm/MessageBrokerToolkit/6.0

Note that the value of c_wb.b_wb.location might not be the same as the value of c_wmbt_specifc.b_wmbt_specific.location. This can happen if another RAD product has been installed before WebSphere Message Broker.

If cdi_ref.properties does not exist, there are no Rational products installed, and the Message Brokers Toolkit is not installed.

To set up Message Brokers Toolkit with icons and options for a new user-defined node, you should set up a new Eclipse link file pointing to the directory containing the Eclipse plug-in files. The link file should contain one line, which is the full path of the target directory. When you create the Eclipse link file, place it in <c.wb.b_wb.location>/eclipse/links/. For example:

The file named opt/ibm/MessageBrokerToolkit/6.0/Myextension might contain the line path=/opt/My/Extension/Nodes. The directory pointed to in that line should contain the plugin fragments you have assembled using the instructions in Distributing a user-defined extension.

When you have installed the extension, restart the target workbench with the -clean option. You can do this from the command line, or by modifying the menu shortcut. You should use the -clean option whenever any changes are made to user-defined extensions, to make sure the changes are picked up by the message flow node palette. When the workbench has restarted, the new category of nodes appears on the palette of the flow editor.

Runtime installation

You might need to detect the version of the runtime that is 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 runtime installations on WebSphere Business Integration Message Broker Version 5.0 or later,Start of change see Installing a user-defined extension on a broker domainEnd of change. For Version 2 brokers, add the plugin to <WebSphere Brokers Install Dir>/lil/ and restart the broker.

Single Broker extension

If the extension is to be made accessible from only one broker on the system, you can modify the user .lil path for that broker, by using the -l parameter on the mqsicreatebroker or mqsichangebroker command. For more information, see mqsicreatebroker command and mqsichangebroker command.

Multiple Brokers extension

To affect all brokers on a system, the system lil path must be modified. This can be done by appending the directory containing the directory with the extension to the MQSI_LILPATH environment variable. You can do this by creating a custom environment script in %ALLUSERSPROFILE%\Application Data\IBM\MQSI\common\profiles on Windows, or /var/mqsi/common/profiles on UNIX. 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 should limit the scope to only appending the following variables:
MQSI_LILPATH
Defines the directories to search for plug-ins
CLASSPATH
Defines the locations Java should search for additional classes
NLSPATH
Defines the location of message catalogues
PATH
Defines the location of executable files. On Windows it also defines the location of dependent libraries.
LIBPATH / SHLIB_PATH / LD_LIBRARY_PATH
Defines the location of dependent libraries.

Example Script

Environment profile for MyExtension, installed in C:\Program Files\MyExtensions. The script is called C:\Documents and Settings\All Users\Application Data\IBM\MQSI\common\profiles\MyExtension.cmd:
REM Added by MyExtension install, do not modify
set MQSI_LILPATH=%MQSI_LILPATH%;"C:\Program Files\MyExtension\bin"
Environment profile for MyExtension, installed in /opt/MyExtension. The script is called /var/mqsi/common/profiles/MyExtension.sh:
#!/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 only runs on a specific version of the broker.

MQSI_FILEPATH
Contains the full path to the installed file for WebSphere Message Broker
MQSI_WORKPATH
Contains 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