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

Install user-defined extensions that you have developed yourself, or have acquired from other software vendors, with the minimum of user intervention.

Before you start

Complete the following tasks:

  1. Compiling a Java user-defined node or Compiling a C user-defined extension
  2. Creating the user interface representation of a user-defined node in the workbench
  3. Testing a user-defined node
  4. Packaging a user-defined node workbench project

You must install user-defined extensions on all appropriate broker computers, and, if the extension is a user-defined node, on the workbench computers (user-defined parsers have no workbench component). 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.

Start of changeIf 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. End of change

The Message Brokers Toolkit installation

Before installing a user-defined node, check the version of the Message Brokers Toolkit to which you are installing, because a specific version of the toolkit could 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.

If the product is shell-sharing with another product, the installation path is determined by the first Rational® program that was installed. To determine the location of the Message Brokers Toolkit installation, look at the cdi_ref.properties file which is set up by Rational. 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 used.

  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 within this file.

    For the location, look at the content of the variable: c_wmbt_specifc.b_wmbt_specific.location.

    Windows platform For example, C:\Program Files\IBM\MessageBrokersToolkit\6.0.

    Linux platform For example, /opt/ibm/MessageBrokerToolkit/6.0.

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

    Windows platform For example, C:\Program Files\IBM\MessageBrokersToolkit\6.0.

    Linux platform For example, /opt/ibm/MessageBrokerToolkit/6.0.

    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 discrepancy can occur if another Rational product has been installed before WebSphere Message Broker.

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

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

Copy the compressed file that you created in Packaging a user-defined node workbench project to the directory identified by your link file. Extract the contents into that directory. For example:

Linux platform The file named opt/ibm/MessageBrokerToolkit/6.0/eclipse/links/Myextension.link might contain the line path=/opt/My/Extension/Nodes/eclipse/plugins/your_node_name. The directory pointed to by the path variable must contain the contents of the compressed file that you created earlier when you packaged the project.

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.

If you are an experienced Eclipse user or plug-in developer, you might want to use more advanced Eclipse functions to handle additional products like user-defined extensions. For example, you can package user-defined extensions as Eclipse features, instead of plug-ins.

Features have several advantages:

  • You can include many related plug-ins in a single feature.
  • You can define a feature such that it is restricted to use with particular versions of your workbench.
  • You can provide automated updates to features using the Eclipse Update Manager.

For a full description of these and other advanced Eclipse options, see the PDE Guide which includes a section about creating features. You might also find useful the description of the feature manifest in "Navigating and customizing the workbench".

Runtime installation

You might need to detect the version of the runtime components 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 runtime installations on WebSphere Business Integration Message Broker Version 5.0 or later, and WebSphere Message Broker Version 6.0 and later, see Installing user-defined extension runtime files on a broker. For Version 2 brokers, add the user-defined extension files to install_dir/lil/, and restart the broker.

Installing a user-defined extension for single broker

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.

You cannot use the -l parameter to modify the user LILPATH for 64-bit extensions. Instead, append the directory containing the directory that holds the extension files to the environment variable MQSI_LILPATH64, as described in the following section.

Start of changeSee the mqsicreatebroker and mqsichangebroker commands for further information.End of change

Installing a user-defined extension for multiple brokers

To affect all brokers on a system, you must 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).

You can make this change by creating a custom environment script in the working directory:

  • Linux platformUNIX platform On Linux® and UNIX® systems, /var/mqsi/common/profiles
  • Windows platform On Windows, %ALLUSERSPROFILE%\Application Data\IBM\MQSI\common\profiles where the default setting for the environment variable %ALLUSERSPROFILE% is C:\Documents and Settings\All Users. The actual value might be different on your computer.

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 32-bit plug-ins
MQSI_LILPATH64
Defines the directories to search for 64-bit plug-ins
CLASSPATH
Defines the locations that Java should search for additional classes
Start of changeMQSI_CONSOLE_NLSPATHEnd of change
Start of changeOn Windows systems, defines the location of message catalogs (DLL files)End of change
NLSPATH
Start of changeOn Linux and UNIX systems, defines the location of message catalogues (CAT files)End of change
PATH
Defines the location of executable files. On Windows, this variable also defines the location of dependent libraries.
LIBPATH / SHLIB_PATH / LD_LIBRARY_PATH
Defines the location of dependent libraries on UNIX and Linux systems.

Example scripts

Windows platform This example shows the environment profile for MyExtension on Windows, which is installed in C:\Program Files\MyExtensions.

The script is called MyExtension.cmd and is stored in the working directory. The default location is %ALLUSERSPROFILE%\Application Data\IBM\MQSI\common\profiles. where the default setting for the environment variable %ALLUSERSPROFILE% is C:\Documents and Settings\All Users\.

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"

UNIX platform This example shows the environment profile for MyExtension on Linux, 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
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2009Copyright IBM Corporation 1999, 2009.
Last updated : 2009-01-07 15:23:07

as04540_