Sample program to monitor instrumentation events on Multiplatforms

amqsevt formats the instrumentation events that a queue manager can create, and is supplied with IBM® MQ for Multiplatforms. The program reads messages from event queues, and formats them into readable strings.

As a sample program, both source and binary are provided. The sample is provided on all the Multiplatforms, including IBM i.

The single binary file amqsevt (or amqsevt.exe) is shipped in the samples fileset and is installed in the samples bin (tools\c\samples\bin or bin64) directory.

The source files amqsevta.c is also shipped in the samples fileset, and is installed in the samples directory, that is, tools\c\samples on Windows.

Note that the program can read from multiple event queues, and subscribe to multiple topics, by using MQCB to retrieve the messages.

When running as a client, the sample can connect to any queue manager including z/OS®.

Attention: You can use the program without specifying any parameters, in which case the program attempts to connect to the default queue manager and read messages from the standard set of event queues (SYSTEM.ADMIN.*.EVENT).

In this situation, the program waits forever for messages, until you press the Enter key to end the program.

However, you are more likely to use the program with the various options described.

Syntax

Notes:

¹ Available only when being used as a client
² Queues and topics can have multiple entries

Optional parameters

-m QueueManagerName

Specify a specific queue manager for reading events.

-r Reconnection Options

Auto reconnection options when used as a client. The possible values are:

d: Reconnect the client disabled
r: Reconnect the client
m: Reconnect the queue manager

-b

Browse records only, rather than destructively reading the messages

-c

Selects connection as a client.

-d

Selects the printing mode used in the second example. The MQI constants are printed exactly as they appear in the header files.

-u User ID

Specify a specific user and causes a prompt to appear requesting a password

-w Wait

Causes the program to exit if no event messages have arrived within the number of seconds specified.

Note that, if you do not specify a time, the program only ends normally when you press the Enter key.

-t Topic and

-q Queue

Both the -q and -t options can be given multiple times on the command line.

Therefore, it is possible to read from some standard queues and also from topics (if events are being sent to them) from a single run of the program.

If no queues or topics are named on the command line, the default event queues are opened.

Note: The program detects if it has connected to a z/OS queue manager as a client, and changes the default set of event queues appropriately, as z/OS does not have the SYSTEM.ADMIN.LOGGER.EVENT queue.

When topics are used, the program uses a non-durable subscription with a managed queue so that everything gets cleaned out when it exits.

-o <output format>

The format of the output. Possible values are:

text: Standard text format; this is the default value.
json: Standard JSON format; any application that understands JSON can take this output and process it directly.

Sample output

The following three examples show the output from the program.

The first example uses the default formatting option where the program takes the MQI definition of a field and formats the output to make the output more readable.

**** Message (320 Bytes) on Queue SYSTEM.ADMIN.QMGR.EVENT ****
Event Type                       : Queue Mgr Event
Reason                           : Unknown Alias Base Queue
Event created                    : 2015/06/17 13:47:07.02 GMT
  Queue Mgr Name                 : V8003_A
  Queue Name                     : EVT.NO.BASE.QUEUE
  Base Object Name               : EVT.NOT.DEFINED
  Appl Type                      : Unix
  Appl Name                      : amqsput
  Base Type                      : Queue

The second example shows the alternative formatting, using the -d option, that does not try to translate MQI constants. This might be preferable for some scripting tools that look for specific MQI values.

**** Message (320 Bytes) on Queue SYSTEM.ADMIN.QMGR.EVENT ****
Event Type                       : MQCMD_Q_MGR_EVENT
Reason                           : MQRC_UNKNOWN_ALIAS_BASE_Q
Event created                    : 2015/06/17 13:52:48.18 GMT
  MQCA_Q_MGR_NAME                : V8003_A
  MQCA_Q_NAME                    : EVT.NO.BASE.QUEUE
  MQCA_BASE_OBJECT_NAME          : EVT.NOT.DEFINED
  MQIA_APPL_TYPE                 : MQAT_UNIX
  MQCACF_APPL_NAME               : amqsput
  MQIA_BASE_TYPE                 : MQOT_Q

The third example shows the JSON output from the command

amqsevt -m QM1 -q SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE -o json

{
"eventSource" : { "objectName": "SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE",
                    "objectType" : "Queue" },
"eventType" : {
    "name" : "Activity Trace",
    "value" : 209
  },
"eventReason" : {
    "name" : "None",
    "value" : 0
  },
"eventCreation" : {
    "timeStamp"  : "2018-07-10T12:44:26Z",
    "epoch"      : 1531226666
  },
"eventData" : {
  "queueMgrName" : "QM1",
  "hostName" : "<yourhostname>",
  "startDate" : "2018-07-10",
  "startTime" : "13:44:25",
  "endDate" : "2018-07-10",
  "endTime" : "13:44:26",
  "commandLevel" : 910,
...

Example usage

The following example shows you how to use more than one queue:

amqsevt -m QM1 -q SYSTEM.ADMIN.QMGR.EVENT -q SYSTEM.ADMIN.PERM.EVENT -w 1