Files distributed with the Agent and monitoring extensions

The following MainView Middleware Monitor (MVMM ) files are distributed with the Agent and monitoring extensions.

See the file list for your operating system in the AGENT_DIST directory (see Organization-of-the-AGENT_DIST-directory-on-the-server-machine) or in MVMM Extensible Agent and extension files to distribute to determine if a file is used on that system.

checkpoint.bin

Checkpoint.bin caches updates from the MVMM Extensible Agent to the MVMM Topic Service. If communication between the two is lost, then updates are appended to the checkpoint.bin file. After a connection is reestablished, all updates are sent to the MVMM Topic Service. Refer to services.cfg keywords to control when this is reset.

You can limit the size of the checkpoint.bin file using a MVMM Extensible Agent preference. The number is the size of the file in megabytes. Note, if this size is exceeded, updates are lost. Add this stanza to eaa.xml.

<PreferenceAttribute>
<PreferenceName>Max_Checkpoint_MB</PreferenceName>
<PreferenceValue>2</PreferenceValue>
</PreferenceAttribute>

This preference is not honored by z/OS. Under z/OS, the checkpoint.bin file must be pre-allocated and initialized via job JRTSPXML. The maximum size of checkpoint.bin is governed by that job. Its default allocation is:
SPACE=(CYL,(3,1),RLSE),
DCB=(LRECL=0,DSORG=PS,RECFM=U,BLKSIZE=32000)

dbghelp.dll

dbghelp.dll is a Microsoft Windows library to assist in the creation of mini-dumps after an unexpected runtime exception.

eaa.xml or EAAXML

The eaa.xml file contains the configuration preferences for the MVMM Extensible Agent, the monitoring extensions, and a list of all topics that are registered with the MVMM Extensible Agent and are located on the local node.

Normally, this file should not be directly edited. Editing this file directly might cause the

MVMM

Extensible Agent and monitoring extensions to lose information and report inaccurate information. It is recommended to use the agentpref utility to modify the file, see Using agentpref.

Special characters: when editing EAAXML in a z/OS environment you must escape the characters: ">", "<", and "&" as these have special meaning in XML. Escape these characters as follows:

mFor "<" use "<"
mFor ">" use ">"
mFor "&" use "&"

eaa_dist.xml

This is the initially installed, default copy of eaa.xml. When the agent first starts, if no copy of eaa.xml exists, this is copied to eaa.xml for future use.

eaapi

This file contains the application programming interface (API) used by the MVMM Extensible Agent. The eaapi.dll is the API for the C language. The com.bmc.mmpa.eaapi.jar is the API for the Java language.

eaapi.ini

See Creating-eaapi-ini-for-the-MVMM-Extensible-Agent-and-extensions for details.

HTTPMonitor.jar

This file is a needed to run the BMC MMPA Monitoring Extension for IBM HTTP Server.

INSTALL.XMIT

A TSO XMIT file that is uploaded to the z/OS mainframe. The file is input to the RECV.JCL.

jst

A third-party dll or jar file used to start Java extensions.

log4j-1.2.14.jar

Java jar file used to write log messages.

MQSTUB

Allows linking of IBM MQ 6.0 libraries with MVMM in a z/OS environment.

mqsutil.dll

File used by the MVMM Extensible Agent on Windows.

MQS_HOME

A system environment variable used by MVMM that determines where MVMM stores and searches for its files. You need to create the system environment variable.

The system environment variable defines where to find QPLog.ini, which is used for logging. For i5/OS, MVMM does not run without having libbtmutil.so in the directory specified by the system environment variable. For all other operating systems, MVMM runs without setting this system variable, the log files might be scattered around your system. By defining this variable, the logs are in the same (and predictable) place.

MVMM searches for log, registry, state, and some *.ini files in this order. The search is hierarchical, which means that if the file is not found in the first location, a search is completed until it is found. If the file is not found, the lowest priority location is used.

For an *.ini (log configuration files) file
Current working directory
Directory specified by the system environment variable on UNIX and Windows or LOGINIon z/OS installation PDS.
/etc (UNIX only)
Log files
Directory specified in QPLog.ini file
Directory specified by the system environment variable on UNIX and Windows or LOGINIon z/OS installation PDS.
Current working directory
/tmp(UNIX only) or the directory specified by the %TEMP% variable on Windows (generally, C:\Temp) or LOGINIon z/OS installation PDS.
Registry XML files (eaa.xml, rtsp.xml)
Current working directory
Directory specified by the system environment variable on UNIX and Windows or LOGINIon z/OS installation PDS.
/etc (UNIX only)
Agent state file (Checkpoint.bin)
Current working directory
Directory specified by the system environment variable on UNIX and Windows or LOGINIon z/OS installation PDS.

qpagent.savf

i5/OS save file for pre-IBM MQ V7 that contains all of the MVMM Extensible Agent files for i5/OS.

qpasamq.dll

File used by qpmon and qpcfg on Windows.

QPCDEF

See QPCONF.DEF or Qpconf.def or QPCDEF.

qpcfg

The MVMM configuration extension should be distributed to every computer running IBM MQ where IBM MQ is configured using MVMM.

QPCONF.DEF or QPCDEF

This file defines all IBM MQ attributes for MVMM.

The QPCONF.DEF file is used by the configuration process to decode output from the IBM MQ PCF commands. This file should not be edited.

qpea

qpea is the Agent executable. This program must be installed and running for MVMM to receive any monitoring or configuration information. The Agent processes information passed from all BMC provided extensions and any user-written monitoring extensions.

If there is not an eaa.xml file, the Agent creates a blank eaa.xml file with the parameters the Agent uses in it. Then each extension (at run-time) creates any type definitions and attributes that it requires. The IBM MQ configuration extension (qpcfg) synchronizes the attributes in its definition files (qpconf.def), so if you have an old definition file then you might lose some updates that are in the new one.

All MVMM monitoring extensions on a computer must connect to qpea to pass their information to the MVMM Topic Service. In turn, the MVMM Topic Service passes the information to the various MVMM interfaces. qpea also stores information in the eaa.xml file.

When QPCFG connects, it appears as IBM MQ Configuration. Both items can appear simultaneously in the Management Console.

For more information about this program and how to use it, see Running-performance-and-availability-monitoring-extensions.

qphttp

The BMC MMPA Monitoring Extension for HTTP Server monitors the various HTTP Server properties. For more information about this script and how to use it, see Running-performance-and-availability-monitoring-extensions.

qplog.props

Controls certain aspects of the log files. Most monitoring extensions use a file called qplog.props. This can occasionally cause problems if multiple monitoring extensions are in the same directory. The first time a qplog.props (or framework.props) file is found, that file sets the behavior of the log files for that monitoring extension.

If two or more applications are monitored on the same system, each monitoring extension should be in its own sub-directory of the MVMM Extensible Agent to prevent log files from being overwritten by another monitoring extension. You can also modify the logging capabilities of one monitoring extension without affecting the logging for any other monitoring extensions. For instance, you might create a directory structure like this (with qpea being in /Agent):

.../Agent/qpmon
.../Agent/qpwmb

If the applications (and monitoring extensions) are on separate systems, all of the files can be in the /Agent directory.

qpmon

The BMC MMPA Monitoring Extension for IBM MQ (qpmon) monitors the performance metrics of IBM MQ objects.

qpmon continues to collect monitoring data as long as it is running, even if it is not connected to the MVMM Extensible Agent. If the Agent is restarted, the monitoring extensions sends the most current value for all monitored topics and an updated list of monitored topics, which could contain status information that could trigger alerts and might affect system performance.

On Windows the monitoring extension is multi-threaded. On all other systems, the monitoring extension spawns a child process for each monitored queue manager.

qpmonsub

Program used on i5/OS to monitor IBM MQ. One instance of qpmonsub exists for each queue manager that you monitor.

qpreg

Program used to register objects with a monitoring extension (for instance, qpmon, qpwas). If the monitoring extension is running when you issue the preg command, restart the monitoring extension after running qpreg. The syntax for qpreg is shown below.

Command	Function
qpreg [-u] [-l] extension_name type name
	Registers the listed objects. See the table below for a list of possibilities.
-u	Unregisters instead of registering.
-l	Causes qpmon to restart and read the new definitions. When using -l the extension_name must be Websphere MQ Monitor. Otherwise an error occurs as -l restarts the IBM MQ monitoring extension. If -l is specified in file mode, qpmon is be restarted even if no changes were made for that monitoring extension. -l can be used to restart qpmon after registering or unregistering objects. For z/OS use the following syntax: // PARM=('MSGFILE(SYSOUT),POSIX(ON)/-l file DD:SYSIN')
--version	Lists the version of qpreg

Note

To register an object on z/OS, use a file with the objects defined within it.

QPTTAB or QPTTAB.DAT

File used to contain the code sets for national language support in MVMM.

You can edit this file or add additional code sets to it. If you make any changes to this file, then make the same changes to all of the QPTTAB files in your MVMM environment.

qpwas.jar

Java jar file used by qpwas.

README_ASCII.TXT

Information that should be read prior to installation of the z/OS agent (readable on Windows and other distributed platforms).

README_EBCDIC.TXT

Information that should be read prior to installation of the z/OS agent (readable on the Mainframe).

RECV.JCL

z/OS file used to perform a receive on the INSTALL.XMIT file and create the INSTALL.CNTL PDS.

regq

Registers IBM MQ queues with qpmon.

Usage:
regq QMgrName QueueName [-u]

where:
QMgrName is the queue manager name
QueueName is the queue name.
u unregisters the queue manager

On UNIX, the directory from which this reg* script is run must be on the path. Failure to have the MVMM installation directory or the working directory (.) of this registration script prevents the script from running.

To register many IBM MQ queues at the same time, use a batch file. The batch file should look like the following:

cmd.exe /c regq FARGO INVENTORY
cmd.exe /c regq LONDON ORDER.PROCESSING
cmd.exe /cregq MADRID DLQ

rtsp.xml or RTSPXML

File created by qpea that stores connection information to the MVMM Topic Service when the connection between the two is broken or lost. This file is benign and only contains information when no connection can be established.

After qpeaand the MVMM Topic Service re-establish communication, the information in the rstp.xmlfile is sent to the MVMM Topic Service. If the agent cannot parse this file, do not worry. If there is no information in this file to parse, this warning appears. It is common for there to be no data to parse.

On z/OS, the RTSPXML data set exists to temporarily store data so if the MVMM Extensible Agent is not communicating with the MVMM Topic Service, all the agent information is cached in that data set until the connection is established. The information is then transferred from RTSPXML to the MVMM Topic Service and the information in the data set is discarded.

RTSPCHCK

The z/OS equivalent to checkpoint.bin. See checkpoint.bin above for more details.

setqpwas.sh

File used to set environment variables for qpwas. It must be run before (and in addition to) qpwas --config. This file should be executed from the current shell using the dot operator (.). If the file is not executed from the current shell, then the variables are set only within the sub-shell in which it runs and not in the current shell. Additionally, you might want to add this script to your .profile file so that it runs and sets the variables whenever you log on.

srvcl

File used by the Agent on Windows. Requires that jvm.dll be on the system path.