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: We 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, we are more likely to use the program with the various options described.


Syntax

amqsevt   -mQMgrName  -r Reconnection Options1dReconnect DisabledrReconnectmReconnect Queue manager  -b Browse Messages  -c Connect as Client  -d Print Definitions without formatting  -u User ID  -w Wait Time  -tTopic2  -qQueue2 -o<output format>Notes:

  • 1 Available only when being used as a client
  • 2 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 we 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
Parent topic: Event monitoring


Related concepts


Related reference


Related information