IBM Navigator for i (the web console) added support for message monitors and system monitors in the 7.2 release. For those of you familiar with Management Central monitors, the Navigator monitors are quite similar; however, the underlying implementation is different.
This week I want to review the ability to use replacement variables when creating automatic notifications for your monitors. This information applies to both the Management Central monitors as well as the monitors in Navigator for i.
When you use monitors, the most significant value comes from the automation you add; it allows the system to notify you when a condition occurs, freeing you from checking on the system manually. I’m going to focus specifically on how to enhance the automation to include additional information when a threshold value is hit.
When you configure a metric in a system monitor, you add the automation by enabling a threshold and specifying the trigger (and optionally, reset) value, along with the duration for which the condition must persist. You then add an Operating System Command, which is the action you want taken when that condition occurs. The following screen capture shows the System Monitor Configure Metric panel:
For message monitors, this automation is added with the IBM i trigger command or the IBM i reset command, as the following screen capture shows:
Regardless of the type of monitor or the command used for your automation, you can extend your automation by using replacement variables. These replacement variables allow you to pass information to the command (which could be the CALL command).
Here is a simple example:
I want to monitor the Average CPU Utilization for my IBM i production partition. If the Average CPU Utilization goes over 80%, I want to send a message to the QSYSOPR message queue because the system operator is always paying attention to the messages sent there.
If I did a simple message, the operating system command could be:
SNDMSG MSG(“Threshold triggered”) TOUSR(*SYSOPR)?
The system operator would know something happened, but would not have enough information to take the correct action immediately.
However, if I add replacement variables to my command, the operator would have much more information. For example:
SNDMSG ?MSG('Monitor &MON exceeded threshold &TVAL for &TDUR interval(s); current value is &VAL.') TOUSR(*SYSOPR)
Now the system operator will know which monitor (&MON) triggered, the trigger value (&TVAL) and duration (&TDUR), as well as the current value of the metric (&VAL).
Where do you find the documentation on these replacement variables? That’s the super-secret trick … it is not documented in the IBM i Knowledge Center, but rather is located in the Navigator help. In the upper right hand corner of the Configure Metric window (for System Monitors) or the Message Set window (for Message Monitors), you will see a question mark.
Click the question mark for the Navigator help. Use the following drilldown to find the documentation on the replacement variables:
- For System Monitors:
- Threshold Trigger and Threshold Reset → Parameters for Operating System Command
- For Message Monitors:
- Message Set 1 (or 2) → IBM i Trigger Command → IBM i Trigger or Reset Commands
For easy reference, I have provided a link to the IBM Support documentation on replacement variables, followed by information pulled from those sources.
System Monitor Replacement Variables
You can use the following parameters for the operating system commands when the threshold for a system monitor is triggered or reset. The parameters must be entered in uppercase exactly as shown. See the examples below.
| Parameter | Passed Data |
| &DATE | Date |
| &ENDPOINT | Endpoint system name |
| &INTVL | Collection interval |
| &MON | Monitor name |
| &RDUR | Reset duration |
| &RVAL | Reset value |
| &TDUR | Trigger duration |
| &TIME | Time |
| &TVAL | Trigger value |
| &VAL | Current value |
Message Monitor Replacement Variables
| Parameter | Passed Data |
| &DATE | Date (format MMDDYYYY) |
| &ENDPOINT | Date (format MMDDYYYY) |
| &EVENTTYPE | Event type (See note) |
| &FRMJOBNAME | The name of the job that sent the message |
| &FRMJOBNUMBER | The number of the job that sent the message |
| &FRMPROGRAM | The name of the program that sent the message |
| &FRMUSER | The name of the user that sent the message |
| &MON | Monitor name |
| &MSGCOUNT | The count of messages that caused the trigger |
| &MSGID | ID of the message that caused the trigger |
| &MSGKEY | 4-byte message key (as a hex string) for the message that caused the trigger |
| &MSGSEV | Severity of the message that caused the trigger |
| &MSGTYPE | Type of the message that caused the trigger |
| &OWNER | User profile name of the user who owns the monitor |
| &THRESHOLD | Threshold number that caused the trigger |
| &TIME | Time (format HHMMSS) |
| &TOLIB | The library containing the message queue to which the message was sent |
| &TOMSGQ | The name of the message queue to which the message was sent |
For further reference, find links below to prior blog articles I’ve written on Navigator System Monitors:
IBM i Navigator System Monitors: Collection Interval
IBM i 7.3 System Monitor Enhancements
New Monitor Metrics in 7.2
IBM i 7.2 – Navigator Monitors
This blog post was edited for currency on November 3, 2020.
This blog post was originally published on IBMSystemsMag.com and is reproduced here by permission of IBM Systems Media.