Files distributed with the Agent and monitoring extensions

The following TrueSight Middleware and Transaction Monitor (TMTM) 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 TMTM Extensible Agent and extension files to distribute to determine if a file is used on that system.

Related topics

Installing

Installing the Agent and monitoring extensions

agentdist.xml

This file exists on the server in AGENT_DIST. It does not exist on the agent machines themselves. Used by the TMTM when distributing files. See Organization of the AGENT_DIST directory on the server machine.

checkpoint.bin

Checkpoint.bin caches updates from the TMTM Extensible Agent to the TMTM 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 TMTM 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 TMTM 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 TMTM Extensible Agent, the monitoring extensions, and a list of all topics that are registered with the TMTM Extensible Agent and are located on the local node.

Normally, this file should not be directly edited. Editing this file directly might cause the TMTM 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 TMTM 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 TMTM 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 WebSphere MQ 6.0 libraries with TMTM in a z/OS environment.

mqsutil.dll

File used by the TMTM Extensible Agent on Windows.

MQS_HOME

A system environment variable used by TMTM that determines where TMTM 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, TMTM does not run without having libbtmutil.so in the directory specified by the system environment variable. For all other operating systems, TMTM 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.

TMTM 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-WebSphere MQ V7 that contains all of the TMTM 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 TMTM configuration extension should be distributed to every computer running WebSphere MQ where WebSphere MQ is configured using TMTM.

QPCONF.DEF or QPCDEF

This file defines all WebSphere MQ attributes for TMTM.

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

qpea

qpea is the Agent executable. This program must be installed and running for TMTM 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 WebSphere 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 TMTM monitoring extensions on a computer must connect to qpea to pass their information to the TMTM Topic Service. In turn, the TMTM Topic Service passes the information to the various TMTM interfaces. qpea also stores information in the eaa.xml file.

When QPCFG connects, it appears as WebSphere 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 TMTM 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 WebSphere MQ (qpmon) monitors the performance metrics of WebSphere MQ objects.

qpmon continues to collect monitoring data as long as it is running, even if it is not connected to the TMTM 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 WebSphere MQ. One instance of qpmonsub exists for each queue manager that you monitor.

qpmqsi.jar or qpmqsi.par

The qpmqsi file is the BMC PA Websphere Message Broker Message Processing Node extension (qpmqsi.zip). It monitors the performance metrics of the WebSphere Message Broker message flows primarily for elapsed time between message processing nodes.

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

The table below lists the possible values for the input file for qpreg. Note that the ExtensionName and TypePath are case sensitive.

ExtensionName	TypePath
DB2 Monitor	ComMQSoftwareDB2Host
DB2 Monitor	ComMQSoftwareDB2Database
Oracle Monitor	ComMQSoftwareOracleDatabase
MQSI Monitor (C++) OR ComMqsoftwareQPasaWMQIExtension (Java)	ComMQSoftwareWebSphereMQIBroker
	ComMQSoftwareWebSphereMQIExecutionGroup
	ComMQSoftwareWebSphereMQIMessageFlow
	ComMQSoftwareWebSphereMQIMessageProcessingNode

QPSMFMON

QPSMFMON is an z/OS subtask of QPMON. QPSMFMON retrieves the data in the CSA and passes it to TMTM. All load libraries allocated to QPMONjoblib/steplib dd must be APF-authorized to collect SMF data.

QPSMFMON must be running before SMF data can be collected. It also must reside in an APF-authorized load library.

This file is distributed inside of INSTALL.XMIT.

QPTTAB or QPTTAB.DAT

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

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 TMTM environment.

qpwas.jar

Java jar file used by qpwas.

qpwmb

Script file for the TMTM Websphere Message Broker monitoring extension (qpmqsi.zip). It monitors the performance metrics of the WebSphere Message Broker message flows.

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 WebSphere 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 TMTM installation directory or the working directory (.) of this registration script prevents the script from running.

To register many WebSphere 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 TMTM 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 TMTM Topic Service re-establish communication, the information in the rstp.xmlfile is sent to the TMTM 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 TMTM Extensible Agent is not communicating with the TMTM 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 TMTM 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.