AMQSCLM: Preparing and running the sample

The cluster queue monitoring sample can either be run locally connected to a queue manager, or as a client connected over a channel. The sample should be running whenever the queue manager is running, when running locally it can be configured as a queue manager service to automatically start and stop the sample with the queue manager.

Before starting

The following steps must be completed before running the cluster queue monitoring sample.

1. Create a working queue on each queue manager for the internal use of the sample.

   Each instance of the sample needs a local non-cluster queue for exclusive internal use. We can choose the name of the queue. The example uses the name AMQSCLM.CONTROL.QUEUE. For example, on Windows, we can create this queue by using the following MQSC command:

   DEFINE QLOCAL(AMQSCLM.CONTROL.QUEUE)
   

   We can leave the values of MAXDEPTH and MAXMSGL as default.
2. Create a directory for error and information message logs. The sample writes diagnostic messages to report files. We must choose a directory in which to store the files. For example, on Windows, we can create a directory using the following command:

   mkdir C:\AMQSCLM\rpts
   

   The report files created by the sample have the following naming convention:

    QmgrName.ClusterName.RPT0n.LOG
   

3. (Optional) Define the cluster queue monitoring sample as an IBM MQ service. To monitor queues, the sample must always be running. To ensure that the cluster queue monitoring sample is always running, we can define the sample as a queue manager service. Defining the sample as a service means that AMQSCLM is started when the queue manager starts. We can use the following example to define the cluster queue monitoring sample as an IBM MQ service.

   define service(AMQSCLM) +
         descr('Active Cluster Queue Message Distribution Monitor - AMQSCLM') +
         control(qmgr) +
         servtype(server) +
         startcmd('MQ_INSTALLATION_PATH\tools\c\samples\Bin\AMQSCLM.exe') +
         startarg('-m +QMNAME+ -c CLUSTER1 -q ABC* -r AMQSCLM.CONTROL.QUEUE -l c:\AMQSCLM\rpts') +
         stdout('C:\AMQSCLM\rpts\+QMNAME+.TSTCLUS.stdout.log') +
         stderr('C:\AMQSCLM\rpts\+QMNAME+.TSTCLUS.stderr.log')
   

   Definition	Description
   service	Specifies the service name. We can choose the service name.
   descr	Specifies a textual description of the service.
   control	Indicates that the service starts and stops at the same time as the queue manager.
   servtype	Indicates a server service object, meaning only one instance, can be executed at a time for this queue manager.
   startcmd	Specifies the location and name of the program.
   startarg	Specifies the arguments of the sample. Note the use of +QMNAME+. The name of the queue manager is automatically substituted.
   stdout	The fully qualified file name to which standard output is redirected. The sample writes to this file only messages confirming that the sample has terminated. The sample does this because the standard error file has already closed in an earlier stage of the sample termination process.
   stderr	The fully qualified file name to which standard error output is redirected. The sample writes to the standard error file any error messages prior to termination of the sample.

About this task

AMQSCLM -m QMgrName -c ClusterName (-q QNameMask| -f QListFile) -r MonitorQName
[-l ReportDir] [-t] [-u ActiveVal] [-i Interval] [-d] [-s] [-v]

-m QMGR1 -c CLUS1   -f c:\QList.txt -r CLMQ -l c:\amqsclm\rpts -s
-m QMGR2 -c CLUS1   -q ABC* -r CLMQ -l c:\amqsclm\rpts -i 600
-m QMGR1 -c CLUSDEV -q QUEUE.* -r CLMQ -l c:\amqsclm\rpts -t -u QMGR -d

Q1
QUEUE.*
ABC
ABD

Procedure

1. Start the cluster queue monitoring sample. We can start the sample in one of the following ways:
   • Use a command prompt with the appropriate user authorizations.
   • Use the MQSC START SERVICE command, if the sample is configured as an IBM MQ service.

   The argument list is the same in both cases. The sample does not start monitoring the queues for 10 seconds after the program is initialized. This delay allows consuming applications to connect to the monitored queues first, preventing unnecessary changes to the active state of the queue.

2. Stop the cluster queue monitoring sample. The sample automatically stops when the queue manager is stopped, stopping, quiescing, or if the connection to the queue manager is broken. There are ways to stop the sample without ending the queue manager:
   • Configure the local queue used exclusively by the sample to disable the Get function.
   • Send a message with a CorrelId of "STOP CLUSTER MONITOR\0\0\0\0", to the local queue used exclusively by the sample.
   • Terminate the sample process. This might result in the loss of non-persistent messages being transferred to active queues. It might also result in the local queue used by the sample being held open for a number of seconds after the termination. This situation prevents a new instance of the cluster queue monitoring sample from starting immediately.

   If the sample has been started as an IBM MQ service, STOP SERVICE has no effect. It is possible to use one of the termination methods described as a configured STOP SERVICE mechanism in the queue manager.

What to do next

Check the status of the sample.

QMgrName.ClusterName.RPT01.LOG

QMgrName.ClusterName.RPT02.LOG
QMgrName.ClusterName.RPT03.LOG

• at startup
• at termination
• when it marks a queue ACTIVE or INACTIVE
• when it requeues messages from an inactive queue to an active instance or instances

The sample creates an error message CLMnnnnE to report a problem that requires attention.

Every 30 minutes, the sample reports average processing time per polling interval, and elapsed processing time. This information is held in message CLM0045I.

• Time taken to process the queues (in milliseconds)
• Number of queues checked
• Number of active/inactive changes made
• Number of messages transferred

This information is reported in message CLM0048I.

Report files might grow rapidly in debug mode, and quickly wrap. In this situation, the 1 MB size limit for individual files might be exceeded.