Installing the WebSphere MQ BTM extension

This topic describes how to install the WebSphere MQ BTM extension on the following supported platforms:

Before you begin

  • Deploy either the 32-bit or 64-bit BMC runtime toolkit to a staging area. Use the version that matches your WebSphere MQ installation. See Working with the runtime toolkit for details. Unzip the contents of the jar file to its own directory.
  • Install the Microsoft Visual C++ 2017 Redistributable Package. If your Windows operating system is 32-bit install the vcredist_x86.exe located in the agent distribution directory. If your Windows operating system is 64-bit install both vcredist_x86 and vcredist_x64.exe located in the agent distribution directory. You might have already done this for other BTM extension types. It only needs to be done once but make sure the correct version (32-bit or 64-bit) is installed.

Installing the WebSphere MQ BTM extension on Windows

  1. Copy the dll files for WebSphere MQ 7.1 or later:
    • Copy the 32-bit btmmq_71.dll from the staging directory to the default 32-bit exits directory. For example: C:\Program Files (x86)\IBM\WebSphere MQ\exits
    • Copy the 64-bit btmmq_71.dll from the staging directory to the default 64-bit exits directory. For example: C:\Program Files (x86)\IBM\WebSphere MQ\exits64
  2. Ensure that the Microsoft Runtime Environment is installed.
  3. Stop the queue manager.
  4. Stop the WebSphere MQ configuration (qpcfg) and monitoring (qpmon) extensions.
  5. Stop WebSphere MQ programs that do not end with the queue manager such as listeners that are configured for manual start/stop and trigger monitors.
  6. Stop all of your WebSphere MQ applications.
  7. Stop the queue manager using endmqm –w
  8. Stop any forgotten WebSphere MQ programs or applications that are preventing the queue manager from stopping. Do not continue until endmqm –w ends.
  9. Navigate to Start > Programs > IBM WebSphere MQ > WebSphere MQ Explorer and expand WebSphere MQ Explorer.
  10. Right-click the queue manager you are using and select Properties > Exits.
  11. If you have an existing exit for TrueSight Middleware and Transaction Monitor, select it and click Remove and the click Add.
  12. Give the exit a name and enter EntryPoint in the Function field. Use only the library name btmmq71.dll and not the full path (do not browse to its location).
  13. Click Open.
  14. Click OK repeatedly to exit the Explorer.
  15. Start the queue manager, MQ applications, listeners, trigger monitors and WebSphere MQ configuration (qpcfg) and monitoring (qpmon) extensions as required.

Installing the WebSphere MQ BTM extension on UNIX

  1. View the qm.ini file to determine the default exit paths. The following are the normal defaults. If the keywords do not exist you should add the keywords with appropriate locations but do so later after the queue manger is stopped. Note the default paths already configured or to be configured for the next step.

    qm.ini
    ExitPath:
    ExitsDefaultPath=/var/mqm/exits/
    ExitsDefaultPath64=/var/mqm/exits64/

  2. From the staging directory, move OperatingSystem_Technology_Runtime_Toolkit.jar to a temporary location/var/mqm/ and extract the contents. The contents include exit and exit64 directories. Extract the contents to a separate location and copy the appropriate files to the ExitsDefaultPath /var/mqm/exits and ExitsDefaultPath64 /var/mqm/exits64 directories from qm.ini. The contents includes an exit directory, and if you are installing on a 64-bit UNIX, an exits64 directory. These directories contain btmmq71 and btmmq71_r (or appropriately named files depending on the WebSphere MQ and UNIX versions).

    Files to use for WebSphere MQ 7.1 or later:
    • Copy the exits/btmmq71* to the ExitsDefaultPath
    • Copy exits64/btmmq71* to the ExitsDefaultPath
    • Note the versions of the files and use btmmq71 in the ini file when edited later
  3. Change to the the ExitsDefaultPath directory where you extracted the files and make the copied files executable by using: chmod +x btmmq*

    It is recommended that the libraries are owned by mqm and in the mqm group.
    chown mqm btmmq*
    chgrp mqm btmmq*

  4. Repeat the above step with the ExitsDefaultPath64 directory.
  5. Any user running a WebSphere application, especially WebSphere MQ channels and WebSphere Message Brokers started by inetd, must set the MQS_HOME system environment variable. See Configuring the MQS_HOME system environment variable for the Default layout.
  6. Edit the QPLog.ini file to place log files in a common directory if required. This makes it easier to find the log files if there is a problem. As is, all log files are in the directory specified by the MQS_HOME system environment variable.
  7. Stop the WebSphere MQ configuration (qpcfg) and monitoring (qpmon) extensions.
  8. Stop WebSphere MQ programs that do not end with the queue manager such as listeners that are configured for manual start/stop and trigger monitors.
  9. Stop all of your WebSphere MQ applications.
  10. Stop the queue mangaer using endmqm –w
  11. Stop any forgotten WebSphere MQ programs or applications that are preventing the queue manager from stopping. Do not continue until endmqm –w ends.
  12. Edit the qm.ini file to add the default paths if necessary and include the exit information.

    qm.ini

    ExitPath:
    ExitsDefaultPath=/var/mqm/exits/
    ExitsDefaultPath64=/var/mqm/exits64/
    ApiExitLocal:
    Name=BTMExtension
    Sequence=3
    Function=EntryPoint
    Module=<btmmq71>

  13. (Optional) To add the WebSphere MQ BTM Extension to all future queue managers, edit the mqs.ini file to include the exit information. Refer to the IBM Application Programming Guide for more information about setting exits. The following shows mqs.ini with exits added.

    mqs.ini with added exits

    ApiExitTemplate:
    Name=BTMExtension
    Sequence=3
    Function=EntryPoint
    Module=btmmq
    ApiExitCommon:
    Name=BTMExtension
    Sequence=3
    Function=EntryPoint
    Module=<btmmq71>

    Note that for Solaris add the exit with the file extension to the Module stanza. Instead of btmmq71 add bmtmmq7.1.so to the Module stanza.
  14. Restart the queue manager, MQ applications, listeners, trigger monitors and WebSphere MQ Configuration (qpcfg) and Monitoring (qpmon) Extensions as required.

Installing the WebSphere MQ BTM extension on i5/OS

Before you begin

In addition to the instructions in the Before you begin section at the top of this section, perform the following:

  • Ensure that the BTMMQ exit was installed with the distribution files.
  • The BTM WebSphere MQ API exit, BTMMQ, must load the libbtmutil.so file from the directory specified by the MQS_HOME system environment variable that was created and defined - see Configuring the MQS_HOME system environment variable for the Default layout. The libbtmutil.so file is located in the OS/400 runtime toolkit, which can be deploy from the Monitor Console at any time.
  • Ensure that PASE is installed on your OS/400 system. PASE is an optional OS/400 component required for the BTM WebSphere MQ API exit.

To install the WebSphere MQ BTM extension on i5/OS

  1. From your staging directory, extract libbtmutil.so from OS_400_WebSphere_MQ_Runtime_Toolkit.jar to the directory specified by the MQS_HOME system environment variable (for example, /MQS_HOME/BTM/logs). Make the file executable using:
    • chmod +x libbtmutil.so
    • chown qmqm libbtmutil.so
    • chgrp qmqmadm libbtmutil.so
  2. Edit the qm.ini file to include the BTM WebSphere MQ API exit information. This adds the extension to existing queue managers.

    The full path to the exit library must be readable by the /QIBM/UserData/mqm group. The exit libraries must be executable.

    qm.ini

    ApiExitLocal:
    Name=BTMExtension
    Sequence=3
    Function=EntryPoint
    Module=lib/BTMMQ

    where:
    lib is the library name to which the agents files were restored.
  3. (Optional) To add the WebSphere MQ BTM Extension to all future queue managers, edit the mqs.ini file to include the exit information. Refer to the IBM Application Programming Guide for more information about setting exits. The following shows mqs.ini with exits added.

    mqs.ini with added exits

    ApiExitTemplate:
    Name=BTMExtension
    Sequence=3
    Function=EntryPoint
    Module=lib/BTMMQ
    ApiExitCommon:
    Name=BTMExtension
    Sequence=3
    Function=EntryPoint
    Module=lib/BTMMQ

    where:
    lib is the library name to which the agents files were restored.
  4. Restart the queue manager, MQ applications, listeners, trigger monitors and WebSphere MQ Configuration (qpcfg) and Monitoring (qpmon) Extensions as required.

Installing the WebSphere MQ BTM extension on z/OS

There is no run time toolkit for WebSphere MQ on z/OS because TrueSight Middleware and Transaction Monitor does not use a queue manager API exit on z/OS. Instead, QPBTM runs as a started task or JQPBTM batch job that is included in the BMC MM Extensible Agent distribution. Note the QPBTM started task does not run unless your loadlib is APF authorized.

The WebSphere MQ BTM Extension interfaces with WebSphere MQ to collect data and then forwards that data to the subtasks within QPBTM for processing. As queues and other objects are opened by applications it is determined whether they have been configured for monitoring. Periodically this information is updated so that messages from WebSphere MQ API calls that are not monitored are not forwarded. In some environments, default settings for the period of time and other criteria for controlling this filtering need to be adjusted for optimum performance. This is done by setting extension preferences for the "WebSphere MQ BTM Ext" extension. Refer to Managing the Agent and Extension preferences using agentpref for help setting preferences.

Preference name

Description

Default value

ActivityFilterThreshold

How many messages must be received before messages from an unmonitored job are filtered. In some environments, filtering on all unmonitored jobs can increase memory size. Many jobs are very low volume and it does not matter if a few messages are forwarded or the resource threshold can be used. In this case, the threshold can be higher.

0

ResourceFilterThreshold

How many messages must be received before messages from a WebSphere MQ API for a particular queue or topic are filtered. In some applications, many messages can be put or gotten from an unmonitored queue or topic in relation to a monitored queue or topic. With a high threshold this can result in higher CPU and memory usage. In this case, the threshold can be lowered.

10

ResourceExpireSeconds

On occasion an application might not properly close an object handle. If there is no activity on an object handle it is removed after a period of time. In some environments there might be burts of activity. If the resource is removed in between these bursts it can result in higher CPU and memory usage until filtered. In this case, increase the expiration.

600

CheckFiltersInterval

How often the thresholds and expiration are evaluated. Must be larger than the batch interval, but note that this is only performed if the period of time since the last check has exceeded this value.

BatchInterval

Where to go from here

Was this page helpful? Yes No Submitting... Thank you

Comments