How to: Write a message to the console for a situation
You can use the Take Action command ZOSWTO (z/OS WTO) to write a
message to the z/OS operator console for a situation.
Before you begin
You can use the Take Action command ZOSWTO when creating a situation using any
of the available methods (such as, Tivoli Enterprise Portal,
enhanced 3270 user interface, tacmd CLI).
When defined for a situation, the Take Action command ZOSWTO writes a
multi-line write-to-operator (WTO) message to the operator console when the situation occurs. The
multi-line WTO is issued on the z/OS monitoring server (TEMS)
that an agent is connected to or on a z/OS monitoring agent (TEMA).
The message is produced when the situation is true or false. Any data that follows the command name
will be present in the multi-line message.
To use the command, when creating a situation,
include the ZOSWTO Take Action command in the following
format:
ZOSWTO user_supplied_content
Where the
user_supplied_content defines the content to include in the WTO message and can
include text and product variables.
When the situation is triggered, message KO41041I is issued in the operator console in the
following format:
The situation event is identified in the multi-line message by the
situation_event_id. situation_name is the name of the
situation, and node_name is the origin node related to the event.
optional_display_item_value is the display item, if one is defined for the
situation. The message is produced when the situation is true (T) or false
(F). The user_supplied_content is the content as defined in the
ZOSWTO command. When the situation is false, the values of substitution variables
in the user_supplied_content are N/A.
The message data is
divided into 70-character sections on a maximum of five consecutive lines.
Tip: If
you will be using automation to react to a situation based on the message in the operator console,
when you define the ZOSWTO command for a situation, consider adding identifying
information in the user_supplied_content, such as a unique identification number
or a label. Because every triggered situation with a defined ZOSWTO command will
produce message KO41041I, you will need to parse other details to differentiate the
messages. The ability to scan for unique, known information can help to quickly identify the
messages for a specific situation.
By default, ZOSWTO uses the WTO
options routing code 2 (operator information) and descriptor code 12 (important information). You
can change the default values for these options by specifying parameters
ZOSWTO_ROUTE_CODE and ZOSWTO_DESCRIPTOR_CODE in the
KppENV member of RKANPARU, where
pp is the code for the OMEGAMON product or component that you want to update. You
can also override these values when specifying the ZOSWTO command using the
following
format:
Note: In addition to defining the ZOSWTO command as an action in a situation, you
can also use the Tivoli Enterprise Portal Take Action feature to manually enter the
ZOSWTO command, which requires the following format to override the routing code
and descriptor
code:
Using any of the available methods (such as, Tivoli Enterprise Portal,
enhanced 3270 user interface, tacmd CLI), create a situation that includes Take Action command
ZOSWTO and defines the content (including product variables) to appear in the WTO
message.
When the situation occurs, message KO41041I, with a maximum of five
consecutive lines, is written to the operator console.
Example
This example describes how to use the ZOSWTO command to write a message to the
console for a specific situation that is detected by the IBM OMEGAMON for Messaging on z/OS, IBM MQ
Monitoring agent. This example provides implementation steps for both the enhanced 3270 user
interface and the Tivoli Enterprise Portal, and also provides sample output messages.
The scenario for this example is to detect when the MQ Event for Queue Depth High has occurred,
and, when this event occurs, to issue a message to the operator console that provides the name of
the MQ queue manager, the name of the MQ resource (queue name), and the label
MQ01W, which will be used for message identification in the log.
Tip: Using a label is optional and can help simplify automation if there are multiple situations using
the ZOSWTO command.
The following ZOSWTO command contains the label, the custom text, and the
appropriate product variables to report to the operator console for this
event:
ZOSWTO MQ01W Event queue depth high for Qmgr:&{Current_Events.Reporting_MQ_Manager_Name}; Queue:&{Current_Events.Resource_Name}
To associate this WTO message with the situation, you must define it as a Take Action System
Command in the situation. The following sections show how to do this in the enhanced 3270 user
interface and the Tivoli Enterprise Portal. Examples of the produced messages in the operator
console are also provided.
Define the ZOSWTO command using the enhanced 3270 user interface
Use the Formula tab in the Situation Editor to define the criteria for the situation, as shown in
the following figure:
Figure 1. Defining the situation formula using the enhanced 3270 user
interface
Notice the following in this example:
A display item is set so that it will become true for each possible queue. The display item will
be included in the WTO message (as
<optional_display_item_value>) when the situation event
occurs.
Then, use the Action Tab of the Situation Editor to enter the ZOSWTO command
as a System Command. You must type S next to Command
to enter the complete value of the command, as shown in the following figures:
Figure 2. Defining the situation action using the enhanced 3270 user
interfaceFigure 3. Defining the ZOSWTO command using the enhanced
3270 user interface
Define the ZOSWTO command using the Tivoli Enterprise Portal
Use the Formula tab in the Situation Editor to define the criteria for the situation. For this
example, the formula is the == Queue Depth High event, as shown in the
following figure.
Note: This situation also has a display item set so that it will become true for
each possible queue. The display item will be included in the WTO message (as
<optional_display_item_value>) when the situation event
occurs.
Figure 4. Defining the situation formula using the Tivoli Enterprise
Portal
Then, on the Action Tab of the Situation Editor, enter the ZOSWTO command as a
System Command, as shown in the following figure:
Figure 5. Defining the ZOSWTO command using the Tivoli
Enterprise Portal
View the WTO messages in the operator console
When this situation occurs (that is, when the situation is true), the following WTO
message appears in the operator console:Figure 6. Example WTO
message when the situation is
true
2023096 11:53:18.36 S0780082 00000090 KO41041I SITUATION EVENT 607
607 00000090 MQ_Queue_Depth_High:QK20:RSB2:MQESA<ABCAPPL_TYPE2_RECEIVING_Q> T MQ01W
607 00000090 Event queue depth high for Qmgr:QK20; Queue:ABCAPPL_TYPE2_RECEIVING_Q
607 00000090
607 00000090
607 00000090
When this situation clears (that is, when the situation is false), the
following WTO message appears in the operator console:Figure 7. Example WTO message when the situation is
false
2023096 12:02:18.35 S0780082 00000090 KO41041I SITUATION EVENT 621
621 00000090 MQ_Queue_Depth_High:QK20:RSB2:MQESA<ABCAPPL_TYPE2_RECEIVING_Q> F MQ01W
621 00000090 Event queue depth high for Qmgr:N/A; Queue:N/A
621 00000090
621 00000090
621 00000090
What to do next
Optionally, based on the occurrence or resolution of the situation event, you can parse the
WTO message to drive automation or notify the z/OS systems programmer of the situation.
Notice the following in this example:
