Installing the IBM MQ configuration and monitoring extensions

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

Related topics

Running-performance-and-availability-monitoring-extensions

Running-IBM-MQ-configuration-and-monitoring-extensions

Uninstalling-MVMM-performance-and-availability-monitoring-extensions

Installing the IBM MQ configuration and monitoring extensions on Windows

Before you begin

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

Important

The IBM MQ Monitor and Configuration extensions must be able to find the local MQ installation (either the server for Agent based configurations or the MQ Client for agent-less configurations) on the installed host. If MQ is installed and cannot be located or is not installed, you might see errors concerning the inability to locate mqm.dll. To find the MQ installation the MainView Middleware Monitor (MVMM ) extensions look in the default installation location automatically, but might fail to locate the installation when multiple IBM MQ versions are installed, when IBM MQ is not installed in the default location, or when no IBM MQ version is designated as the primary installation. In these situations you must configure the IBM MQ Monitor preference DefaultMQInstallationPath to point to the path to a valid IBM MQ installation. This can be configured via agentpref:

agentpref --set "WebSphere MQ Monitor" DefaultMQInstallationPath C:\My\Installation\Path --notify "WebSphere MQ Monitor" --notify "WebSphere MQ Configuration"

See also How-to-get-the-agent-to-monitor-qpmon-and-display-a-queue-manager-qpcfg.

To install the IBM MQ configuration and monitoring extensions on Windows

  1. If you are reinstalling or upgrading the MVMM  Extensible Agent, restore your backup copy of the eaa.xml file. 
  2. At a command prompt change to the directory where the MVMM  Extensible Agent is installed and enter qpea --status to check that the MVMM  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

Installing the IBM 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 MQ GSKit SSL/TLS libraries supplied with MQ depend on libstdc++.so.6.

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

Note

The IBM MQ Monitoring and Configuration extensions must be able to find the local MQ installation (either the server for Agent based configurations or the MQ Client for agentless configurations) on the installed host. The extensions look in the default installation location automatically, but might fail to locate the installation when multiple IBM MQ versions are installed, when IBM MQ is not installed in the default location, or when no IBM MQ version is designated as the primary installation. In these situations you must configure the IBM MQ Monitor preference DefaultMQInstallationPath to point to the path to any valid IBM MQ installation. This can be configured via agentpref. See also How-to-get-the-agent-to-monitor-qpmon-and-display-a-queue-manager-qpcfg

IBM MQ single version installation

On AIX with 32/64-bit Queue Managers and IBM 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 IBM MQ library directories. They should precede other directories, as in the examples below.

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

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

IBM MQ single installation with default installation path

No specific action is required.

IBM MQ single installation with non-default installation path

Set DefaultMQInstallationPath with agentpref.

IBM MQ multi-version installations

Set DefaultMQInstallationPath with agentpref to the most recent IBM 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 IBM 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 IBM 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 MVMM  Extensible Agent, restore your backup copy of the eaa.xml file.
  4. At a command prompt change to the directory where the MVMM  Extensible Agent is installed and enter qpea --status to check that the MVMM  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 MVMM  Extensible Agent and IBM MQ extensions to start automatically when the computer is restarted. 

32-bit extensions and IBM MQ 64-bit commands: When running some MVMM  Extensible Agent extensions (qpmon, qpcfg) you might run into a problem where the extensions attempt to load the wrong IBM MQ libraries. Whether this occurs depends on the version of the executable (32-bit or 64-bit), the version (and location) of the IBM MQ installation, and the entries in the library path.

This is an example of the error:

exec(): 0509-036 Cannot load program qpcfg because of the following errors: 0509-150 Dependent module /usr/mqm/lib64/libmqm.a(libmqm.o) could not be loaded.
0509-103 The module has an invalid magic number.

Beginning with IBM MQ 6, IBM MQ uses 64-bit commands and supplies lib and lib64 directories containing shared libraries that the extensions use (e.g. libmqm).

Most of MainView Middleware Monitor's extensions are 32-bit and require the 32-bit versions of the IBM MQ libraries. These extensions could fail to start if the library path (LIBPATH / LD_LIBRARY_PATH) includes IBM MQ's lib64 directory before its lib directory. (The inverse could also occur for the 64-bit extensions if the lib directory is specified before the lib64 directory.) To prevent the error, ensure that the library path is set correctly (the lib directory appear before the lib64 directory). You must keep both directories on the path because IBM MQ programs still require a reference to the lib64 directories to run.

Additionally, IBM hard-coded a path into their commands using RUNPATH. RUNPATH can help ensure that the correct libraries are loaded, but only if IBM MQ is installed in the default location. If the default location is not used, then setting the proper library path might be required.

Where to go from here

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

This section describes how to install the IBM MQ configuration and monitoring extensions on the following z/OS platforms:

Installing the IBM MQ configuration and monitoring extensions on z/OS (64-bit)

Before you begin

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

Determine the high-level qualifier for the DSN where MVMM  is to reside. Throughout this document, the high-level qualifier you select is referred to as HLQ. 

Each of the following items is unique to your installation and is used in the configuration of MVMM :

  • 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 MVMM  load library must be APF authorized to monitor z/OS queue manager performance metrics and to retrieve all defined IBM MQ queue managers on a system.

  • Know the DNS name and IP address of the MVMM  Topic Service.

  • Know the names of the IBM 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), IBM MQ, and TCP/IP data sets. Specific data sets are required when installing the MVMM  product.

  • Determine HEAP size and JCL updates. The table below lists how to determine the estimated heap size needed for each MVMM  task on z/OS. The allocation for these jobs is based on the storage size required per IBM 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:
    • CEEOP64    - LE run-time parameters
    • CEEOP64T  - LE run-time parameters (tuned. example)

      CEEOP64 and CEEOP64T 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-MVMM-Extensible-Agent-on-z-OS-platforms.
  • For more information regarding HEAP fine tuning see Tuning-the-z-OS-operating-system-to-optimize-MainView-Middleware-Monitor-applications.
  • z/OS does not require or use the MQS_HOME system environment variable. All logging is done using LOGINI64 and the log output can be read in BMMOUT DD.
  • You must, define the DD statement for QPTTAB (HLQ.INSTALL.CNTL(QPTTAB)) in QPCFG64. This member must be defined so that QPCFG can handle any required message format CCSID conversions.

Note

Procedures for QPEA64, QPCFG64, QPMON64 are different from the Agent (31-bit). All run-time parameters are included in a CEEOP64 member. You can create a CEEOP64 member for each component and specify it in the CEEOPTS DD statement, as shown below:

//CEEOPTS DD DSN=&THISPDS(<Your HEAP setting member name>),DISP=SHR

To install the MVMM  Extensible Agent and the IBM MQ configuration and monitoring extensions on z/OS (64-bit)

  1. Make sure the distribution files have been copied to MVS as described in Installing-the-bootstrap-package-on-z-OS.

  2. Edit HLQ.RECV.JCL to add the user name and target data sets, as explained in the job's inline instructions. Save and submit the job . 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 and executes rexx exec(automation) that updates the following JCL parameters in an include member called INCL in HLQ.INSTALL.CNTL, also updates these parameters in the started tasks QPCFG64 QPEA64 QPMON64. This PDS has JCL members that help you in completing the installation.

    If the user does not enter these parameters in RECV.JCL, it is required to edit the INCL member and the started tasks QPCFG64 QPEA64 QPMON64

    (OPTIONAL) CHANGE LOADLIBHLQ TO THE HIGH LEVEL DATA SET NAME QUALIFIER TO BE USED FOR BMC MainView Middleware Monitor LOAD MODULE LIBRARY.
    (OPTIONAL) CHANGE RTSPHLQ TO THE HIGH LEVEL DATA SET NAME QUALIFIER TO BE USED FOR BMC MainView Middleware Monitor RTSP*(RTSPCHK and RTSPXML) DATASETS.

    (OPTIONAL) CHANGE EAAXMLHLQ TO THE HIGH LEVEL DATA SET NAME QUALIFIER TO BE USED FOR BMC MainView Middleware Monitor EAAXML DATASET.

    (OPTIONAL) CHANGE MQHLQ TO THE HIGH LEVEL DATA SET NAME QUALIFIER TO BE USED FOR IBM MQ LIBRARY.

    After the receiving of the XMIT, edit the INCL member in HLQ.INSTALL.CNTL if necessary . The INCL member contains all the JCL symbols used in the JCLs. 

  3. Submit member JALLOC in HLQ.INSTALL.CNTL. Save and submit it. This allocates your MVMM load library and creates a place to store executables. For complete functionality, this load library must be PDSE.
  4. Submit member JLINK64. Save and submit it. This links MVMM  executable files and places them in the load library created in step 3.
  5. Run the job JRTSPXML before the initial run of QPEA64. JRTSPXML allocates data sets for the RTSPCHCK and RSTPXML DD statements in the QPEA64 JCL procedure. If you are upgrading, ensure that your QPEA64 JCL procedure is updated.

  6. The MVMM  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, (if necessary, RECV.JCL updates the parameters in these procedures if provided by the user) QPEA64, QPCFG64, and QPMON64 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, JQPEA64, JQPCFG64, and JQPMON64. See the details in each member.

    Note that since the z/OS Agent 64 bit can practically handle an unlimited number of IBM MQ queue managers and objects, which may result in allocation of large dataset on z/OS for RTSPCHCK and EAAXML, files RTSPCHCK and EAAXML can reside on z/OS UNIX file system:

    In this case the QPEA64 procedure must be edited and DD names changed for EAAXML and RTSPCHCK:

    //EAAXML   DD  PATH='<path>/&BMMDS..EAAXML',         
    // PATHDISP=(KEEP,KEEP),            
    // PATHOPTS=(ORDWR),           
    // PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)        

    //RTSPCHCK DD  PATH='<path>/&BMMDS..RTSPCHCK', 
    // PATHDISP=(KEEP,DELETE),       
    // PATHOPTS=(ORDWR,OCREAT),         
    // PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)   
     

  7. If you want to collect page set statistics, see 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.

Where to go from here

Installing the IBM MQ extension on i5/OS

See Running-performance-and-availability-monitoring-extensions.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*