Installing the WebSphere MQ configuration and monitoring extensions

Installing the WebSphere MQ configuration and monitoring extensions on Windows

Before you begin

Ensure that the MVMM 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 MVMM 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 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

• 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 MVMM 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

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 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 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

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

• Installing on z/OS 31-bit (see below)
• Installing on z/OS 64-bit (see here)

Installing the WebSphere MQ configuration and monitoring extensions on z/OS (31-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.

Each of the following items is unique to your installation and is used in the configuration of MainView Middleware Monitor (MVMM):

• Determine the high-level qualifier for the DSN and which DASD volumes MVMM will be installed on. Throughout this document, the high-level qualifier that you select is referred as HLQ. For upgrade, this may be the high-level qualifier for the DSN of an existing installation or a new DSN.
• 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 discover all defined IBM WebSphere MQ queue managers on a system.
• Know the DNS name and IP address of the MVMM 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 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 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 MVMM 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, update the production JCL with any changes introduced by the new JCL included with this upgrade.
• 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
  • 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 MVMM Extensible Agent and is contained in INSTALL.XMIT.
• 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.
  
  

Worst case HEAP size estimates

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

1. Edit the file 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. 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 a new MVMM load library. For complete functionality, this load library must be PDSE.
3. Edit member PLINK in HLQ.INSTALL.CNTL. Save it but do not submit PLINK.
4. Edit member JLINK. Save and submit it. This links MVMM executable files and places them in the load library created in step 2.
5. 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, QPEA, QPCFG, QPMON, and QPBTM as each member instructs. You must install them into a system procedure library (e.g. SYS1.PROCLIB). You will need the appropriate SAF Access, RACF, ACF2 or Top Secret, to update the procedure library. 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. 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.
8. If this is a reinstall or an upgrade of MVMM, see below. If this is a new installation, see To customize EAAXML below.

Perform these steps if this is a re-install or upgrade of MVMM:

To restore RTSPCHCK and RTSPXML

1. Restore RTSPCHCK and RTSPXML from the agent backup. Copy the previous RTSPCHCK and RTSPXML that you backed up, to the new agent dataset.

To restore EAAXML

1. Restore EAAXML from the agent backup. Copy the previous EAAXML that you backed up, to the new agent dataset.
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 MVMM. 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 MVMM 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 MVMM Topic Service. The default port used by the MVMMTopic 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 MVMM 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 MVMM 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 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 and which DASD volumes MVMM will be installed on. 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 discover all defined IBM WebSphere MQ queue managers on a system.
• Know the DNS name and IP address of the MVMM 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 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 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:
  • 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 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.

To install the MVMM Extensible Agent and the WebSphere 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. This PDS has JCL members that help you in completing the installation.
3. Edit member JALLOC in HLQ.INSTALL.CNTL. Save and submit it. This allocates a newMVMMload library. For complete functionality, this load library must be PDSE.
4. Edit member PLINK64 in HLQ.INSTALL.CNTL. Save but do not submit PLINK64.
5. Edit member JLINK64. Save and submit it. This links MVMM executable files and places them in the load library created in step 3.
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, QPEA64, QPCFG64, and QPMON64 as each member instructs. You must install them into a system procedure library (e.g. SYS1.PROCLIB). You will need the appropriate SAF Access,  RACF, ACF2 or Top Secret, to update the procedure library.  
   
   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.
   
   
7. Edit and 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.
   
   Note that since the z/OS Agent 64 bit can practically handle an unlimited number of MQ 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 the 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)   
   
   
8. If you want to collect page set statistics, see Page sets, then return here.

9. 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.

Perform these steps if this is a re-install or upgrade of MVMM:

To restore RTSPCHCK and RTSPXML

1. Restore RTSPCHCK and RTSPXML from the agent backup. Copy the previous RTSPCHCK and RTSPXML that you backed up, to the new agent dataset.

To restore EAAXML

1. Restore EAAXML from the agent backup. Copy the previous EAAXML that you backed up, to the new agent dataset.
2. If you need to customize EAAXML, see To customize EAAXML below.

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.