Installing the WebSphere MQ configuration and monitoring extensions

This section describes how to install the WebSphere MQ configuration and monitoring extension on various platforms, and includes:

Installing the WebSphere MQ configuration and monitoring extensions on Windows 

Before you begin

Ensure that the TMTM Extensible Agent is installed on the agent machine.

The WebSphere MQ Monitoring and Configuration extensions are built to use the current versions of the WebSphere MQ APIs. When running against older versions of MQ (such as MQ version 6.0), you might see error messages similar to the ones below in the TMTM log files. These errors are expected when running against WebSphere MQ 6.0 and can be ignored.

>map_symbol: Unable to load [MQSETMP]
>map_symbol: Unable to load [MQCRTMH]
>map_symbol: Unable to load [MQDLTMH]
>MQ7 API symbols not loaded (expected in MQ V6 and lower)

To install the WebSphere MQ configuration and monitoring extensions on Windows 

1. If you are reinstalling or upgrading the TMTM Extensible Agent, restore your backup copy of the eaa.xml file.
2. At a command prompt change to the directory where the TMTM Extensible Agent is installed and enter qpea --status to check that the TMTM Extensible Agent is running. If it is not running, start it with qpea --start.
3. Install and start the extensions:
   • Configuration extension, enter: qpcfg --install and qpcfg --start
   • Monitoring extension enter: qpmon --install and qpmon --start

Where to go from here

• To control and configure the extension, see Running WebSphere MQ configuration and monitoring extensions.

• To view uninstall instructions, see Uninstalling the WebSphere MQ configuration and monitoring extensions.

Installing the WebSphere MQ configuration and monitoring extensions on UNIX 

Before you begin

Verify that libstdc++.so.6 is installed on Linux. This is required for SSL/TLS because the IBM WebSphere MQ GSKit SSL/TLS libraries supplied with MQ depend on libstdc++.so.6.

Ensure that the TMTM Extensible Agent is installed on the agent machine.

IBM WebSphere MQ 7.0.1 single version installation

On AIX with 32/64-bit Queue Managers and IBM WebSphere MQ symbolic links are pointing from /usr/lib/ to /usr/mqm/lib, you need to set the LIBPATH environment variable to contain the 64 IBM WebSphere MQ library directories. They should precede other directories, as in the examples below.

On AIX with 64-bit Queue Managers without IBM WebSphere MQ symbolic links pointing from /usr/lib/ to /usr/mqm/lib, set the DefaultMQInstallationPath with agentpref.

On all other UNIX/Linux IBM WebSphere MQ 7.0.1 installations, set the DefaultMQInstallationPath with agentpref.

IBM WebSphere MQ 7.1, MQ 7.5 and 8.x single installation with default installation path

No specific action is required.

IBM WebSphere MQ 7.x and 8.x single installation with non-default installation path

Set DefaultMQInstallationPath with agentpref.

IBM WebSphere multi-version installations

Set DefaultMQInstallationPath with agentpref to the most recent IBM WebSphere MQ version.

Agentpref examples:

AIX: agentpref.sh --set "WebSphere MQ Monitor" DefaultMQInstallationPath /usr/mqm

Linux/Solaris: agentpref.sh --set "WebSphere MQ Monitor" DefaultMQInstallationPath /opt/mqm

Agentpref.sh --set "WebSphere MQ Monitor" DefaultMQInstallationPath /opt/My/Installation/Path --notify "WebSphere MQ Monitor" --notify "WebSphere MQ Configuration"

You might encounter a port conflict for port 6001 betwen the WebSphere MQ Monitoring Extension (and qpmon) and the X Window System on UNIX. The qpmon port is changeable and can be redefined as necessary. The port is changed by setting the ServicePort extension preference, which can be modified using agentpref. See agentpref for details.

To install the WebSphere MQ configuration and monitoring extensions on UNIX 

1. Open a command prompt and change to the directory containing the distributed files.
2. Use chmod +x filename to make the following files executable:
   • qpmon
   • qpcfg
     
     Depending on your monitoring needs other files might need to be executable. The binary files and the *.ksh files for your operating system should be executable.
3. If you are reinstalling or upgrading the TMTM Extensible Agent, restore your backup copy of the eaa.xml file.
4. At a command prompt change to the directory where the TMTM Extensible Agent is installed and enter qpea --status to check that the TMTM Extensible Agent is running. If it is not running, start it with qpea --start.
5. Install and start the extensions:
   • Configuration extension, enter: qpcfg.sh --start
   • Monitoring extension enter: qpmon.sh --start
6. (Optional) Using cron or the /etc/rc.d/init.d directory, configure the TMTM Extensible Agent and WebSphere MQ extensions to start automatically when the computer is restarted.

Where to go from here

• To control and configure the extension, see Running WebSphere MQ configuration and monitoring extensions.

• To view uninstall instructions, see Uninstalling the WebSphere MQ configuration and monitoring extensions.

Installing the WebSphere MQ configuration and monitoring extensions on z/OS 

Before you begin

A systems programmer and a z/OS security administrator are needed to set up the TMTM Extensible Agent and extensions on this platform.

Each of the following items is unique to your installation and is used in the configuration of TrueSight Middleware and Transaction Monitor (TMTM):

• Determine the high-level qualifier for the DSN where TMTM is to reside. Throughout this document, the high-level qualifier you select is referred to as HLQ.
• BMC recommends that you run the z/OS agent and extensions as started tasks, although they can be run as batch jobs if required. Determine the name of the batch job or started task.
• The TMTM load library must be APF authorized to monitor z/OS queue manager performance metrics and to retrieve all defined IBM WebSphere MQ queue managers on a system.
• Know the DNS name and IP address of the TMTM Topic Service.
• Know the names of the WebSphere MQ queue managers on the z/OS platform and their respective command prefixes. This information can be found in the subsystem name table. This information is in member IEFSSNxx of SYS1.PARMLIB. Alternatively, you can issue the D OPDATA console command.
• Know the high-level qualifier of your LE (Language Environment), WebSphere MQ, and TCP/IP data sets. Specific data sets are required when installing the TMTM product.
• Determine HEAP size and JCL updates. The table below lists how to determine the estimated heap size needed for each TMTM task on z/OS. The allocation for these jobs is based on the storage size required per WebSphere MQ queue being monitored. These numbers are tuned to provide optimal performance and are listed as recommended maximums.
• Installation library contains two members for setting up the HEAP. Member names are:
  • CEEOPTS - LE run-time parameters
  • CEEOPTST - LE run-time parameters (tuned. example)

CEEOPTS and CEEOPTST also contain the Time zone environment variable (TZ). By default, it is commented out but must be set before starting the agent and extensions. See the Setting TZ environment variable (ENVAR) in runtime option member (CEEOPTS DD) section in Controlling the TMTM Extensible Agent on z/OS platforms.  

• For monitoring large number of objects setting up IOBAlternate attribute to 'true' for each component (QPEA, QPMON, QPCFG) reduces HEAP usage.
• For more information regarding HEAP fine tuning see Tuning the z/OS operating system to optimize TrueSight Middleware and Transaction Monitor applications.
• If you are upgrading your z/OS agent, resolve any differences between the production JCL and the new JCL included with your upgrade version.
• Heap pools are turned on by default using HEAPP(ON). BMC strongly suggests all users use heap pools. See the JCL and refer to the IBM manual z/OS Language Environment Customization for details.
• If you plan to monitor message rates on z/OS, you must enable Performance Events in WebSphere MQ on each queue manager that contains queues whose message rates are monitored. This includes the following attributes: MsgEnqCount, MsqEnqRate, MsgEnqTotal, MsgDeqCount, MsgDeqRate, and MsgDeqTotal.
• z/OS does not require or use the system environment variable. All logging is done using LOGINI and the log output can be read in QPBTM's SYSOUT. QPBTM is installed as part of the TMTM Extensible Agent and is contained in INSTALL.XMIT.
• You must, however, define the DD statement for QPTTAB (HLQ.INSTALL.CNTL(QPTTAB)). This member must be defined so that any of your transactions that must have their message format CCSID converted can be monitored.

Worst case HEAP size estimates

To install the TMTM Extensible Agent and the WebSphere MQ configuration and monitoring extensions on z/OS 

1. Edit the file HLQ.RECV.JCL to add the user name and target data sets. Save and submit the JCL. Verify the completion code.
   
   HLQ.RECV.JCL executes the TSO RECEIVE command in batch. Sometimes special authorization is required. HLQ.RECV.JCL takes HLQ.INSTALL.XMIT as input and creates HLQ.INSTALL.CNTL. This PDS has JCL members that help you in completing the installation.
2. Edit member JALLOC in HLQ.INSTALL.CNTL. Save and submit it. This allocates your TMTM load library and creates a place to store executables. For complete functionality, this load library must be PDSE.
3. Edit member PLINK in HLQ.INSTALL.CNTL. Save but do not submit PLINK, as it is a JCL procedure.
4. Edit member JLINK. Save and submit it. This links TMTM executable files and places them in the load library created in step 2.
5. The TMTM Extensible Agent and extensions can be run as started tasks or as batch jobs. To run the agent and extensions as started tasks, customize the JCL procedures, QPEA, QPCFG, QPMON, and QPBTM as each member instructs. You must install them into a system procedure library (e.g. SYS1.PROCLIB). Most environments require RACF, ACF2 or Top Secret changes to authorize started tasks. To run the agent and extensions as batch jobs, customize and submit the JCL members, JQPEA, JQPCFG, JQPMON, and JQPBTM. See details in each member.
6. Edit and run the job JRTSPXML before the initial run of QPEA. JRTSPXML allocates data sets for the RTSPCHCK and RSTPXML DD statements in the QPEA JCL procedure. If you are upgrading, ensure that your QPEA JCL procedure is updated.
7. If you want to collect page set statistics, see Monitor z/OS buffer pools and page sets, then return here.

8. To APF Authorize your loadlib:
   
   SETPROG APF,ADD,DSNAME=YOUR.LOADLIB,VOLUME=YOURVOL
   APF authorization should be made permanent by updating the appropriate PROGxx or IEAAPFxx member in the PARMLIB concatenation.
    

9. If this is a reinstall or an upgrade of TMTM, see To restore EAAXML below. If this is a new installation, see To customize EAAXML below.

To restore EAAXML

Perform these steps if this is a re-install or upgrade of TMTM.

1. Restore your backup copy of the EAAXML file.
2. If you need to customize EAAXML, see To customize EAAXML below.

To customize EAAXML

Perform these steps if this is a new installation of TMTM. In a new installation, ensure a default EAAXML file was distributed, see Distributing the Agent and extensions via the launch page for details. This procedure describes how to modify that default file to conform to your installation needs. You should make a backup of this default EAAXML file in case you run into problems with the configuration process. Note that the TMTM Extensible Agent does not start if EAAXML is corrupt.

The DSN for the EAAXML file is HLQ.EAAXML. It must be edited on the host platform.

1. Create a backup copy of the default EAAXML file. If necessary, see your operating system's documentation for details.

2. In the <PreferenceAttribute> RTServer_Port of the EAAXML file (see the list below), specify the port used by the TMTM Topic Service. The default port used by the TMTM Topic Service is 15001.
   
   In the <PreferenceAttribute> ServicePort of the EAAXML file (see the list below), ensure that the ServicePort matches the port you are using. The monitoring extension uses port 6001 and the configuration extension uses port 6002. If this port is not compatible with your TCP/IP environment, you can change it here.
   
   EAAXML example:
   <ExtensionPreferences>
<Extension>
<ExtensionName>WebSphere MQ Monitor</ExtensionName>
<Preferences>
<PreferenceAttribute>
<PreferenceName>SampleInterval</PreferenceName>
<PreferenceValue>30</PreferenceValue>
</PreferenceAttribute>
<PreferenceAttribute>
<PreferenceName>ServicePort</PreferenceName>
<PreferenceValue>6001</PreferenceValue>
</PreferenceAttribute> 

   Note

   The EAAXML file in the distributed package contains general initial startup information.
3. In the <Agent> section of the EAAXML file in the <PreferenceAttribute> RTServer_Hostname (see the list below), specify the host name or IP address of your TMTM Topic Service between the <PreferenceValue> and </PreferenceValue> tags.
   
   RTServer section of EAAXML
   <Preferences>
<PreferenceAttribute>
<PreferenceName>RTServer_Hostname</PreferenceName>
<PreferenceValue>LONDON</PreferenceValue>
</PreferenceAttribute>
<PreferenceAttribute>
<PreferenceName>RTServer_Port</PreferenceName>
<PreferenceValue>15001</PreferenceValue>
</PreferenceAttribute>
</Preferences>
4. If you want the TMTM Extensible Agent to not use the local hostname, then in the EAAXML file, add or edit the stanza in the list below.
   
   Local_HostName in EAAXML:
   <Agent>
<Preferences>
<PreferenceAttribute>
<PreferenceName>Local_HostName</PreferenceName>
<PreferenceValue>NEW_NAME_HERE</PreferenceValue>
</PreferenceAttribute>
</Preferences>
</Agent>

Where to go from here

• To control and configure the extension, see Running WebSphere MQ configuration and monitoring extensions.

• To view uninstall instructions, see Uninstalling the WebSphere MQ configuration and monitoring extensions.

Installing the WebSphere MQ extension on i5/OS 

See Running performance and availability monitoring extensions.