INGMON
Purpose
INGMON is a command that can be called from the NetView automation table. You use it to inform SA z/OS of the status of a monitoring resource and to issue commands in response to a message or an OMEGAMON® exception.
Syntax
Parameters
- monitor
- This is the name of a monitor resource. It can be specified in automation manager notation
(for example, SAPMON/MTR/AOC8) or in agent notation. Note: If you specify monitor in automation manager notation (that is, xxx/MTR/yyy) and such a resource does not exist on the local system, no search for a monitored object is performed. An error message is issued instead.
- object
- This is the name of a monitored object as defined in the MTR policy
in the customization dialog.
INGMON automatically finds the corresponding monitor resources and
operates on them.
Note that a monitor resource with that name is searched first. Then, if it is not found, a search for a monitored object is performed.
Notes:- Be careful not to specify objects that have the same name as an existing monitor resource, otherwise INGMON will only find the entry for the monitor resource and not for the object. For example, if you have a monitor resource, ABC, and you define a second monitor resource, XYZ, with a monitored object called ABC, the call INGMON ABC will always find the monitor resource ABC and never the object ABC that has been defined for XYZ.
- If you specify object in automation manager notation (that is, xxx/MTR/yyy) and such a resource does not exist on the local system, no search for a monitored object is performed. An error message is issued instead.
- STATUS
- This is the new state that the monitor has determined. The state
represents either the health status of the objects that the monitor
is watching, or the state that the monitor is in. The latter can be
one of the following:
- FAILED
- The monitor has failed. Recovery may be in progress. No acceptable health status was provided.
- BROKEN
- Both the monitor and recovery failed. This is a permanent condition. The monitor will not be re-invoked.
- UNKNOWN
- The health status is not yet available.
- NORMAL
- The monitor has obtained good results from the object, or objects, that it is watching.
- WARNING
- The monitor detected a certain degree of degradation in the operation of the monitored object.
- MINOR
- The same as WARNING, but more severe.
- CRITICAL
- The same as MINOR, but more severe.
- FATAL
- The same as CRITICAL, but more severe.
- INFO
- This defines the message that is associated with the new health
status. The parameter value must be enclosed in parentheses, or single
or double quotation marks. If not present, the value of the MSG parameter
will be used instead. If neither parameter is present, text will be
constructed from whatever is in the default safe.
- MSG,text
- The specified text is associated with the new health status.
In SDF, when displaying the new health status via message AOF550I, the text is shortened to "MESSAGE message_ID RECEIVED", where message_ID is the first token of the given text.
- text
- The specified text is associated with the new health status.
- NONE
- No message is associated with the status.
- MSG
- This defines the text of the message that commands or replies
are defined for in the MESSAGES/USER DATA policy item of the policy
database.
- message
- The message must be enclosed in parentheses, or single or double quotation marks. If not present, the content of the default safe will be taken instead.
- MSGTYPE
- This is the value entered in the Message ID field
in the customization dialog for
the MESSAGES/USER DATA policy item (the entry type field in the automation
control file entry for the command). MSGTYPE is typically coded with
the message ID or the OMEGAMON exception
identifier, such as XCHN or SWPC. If not present, the first token
of the value of MSG parameter will be used instead. If neither parameter
is present, the message ID will be extracted from the message in the
default safe.
The task global variables EHKVARn contain the parsed message from either the MSG parameter or, if not present, the message in the default safe.
- CODEn
- When specified, the passed codes are used to search the code entries
for a particular Message ID or exception that is specified in the
policy item MESSAGES/USER DATA. The first token of the value returned
is used as an option to select the commands to be issued from the
automation control file (the value gives a set of commands). If no
match occurs for the specified codes, or if no codes are specified,
the value ALWAYS is used to select the commands to be issued. As a selection you must specify one of the following:
- #
- Perform pass processing and execute all commands with a selection
matching the current pass or blank.
Note that this overrides the PASSES keyword with YES.
- #type
- Interpret type as a message type. Perform
pass processing for this message and execute all commands with a selection
matching the current pass or blank.
Note that this overrides the PASSES keyword with YES.
This is like calling INGMON with MSGTYPE=type.
- Others
- Execute all commands with the given selection, or blank.
The CODE parameters are mutually exclusive to the PASSES=YES parameter.
- PASSES
- Specifies whether passes are used to issue the commands. The INGMON
command interrogates the automation control file to see if passes
are specified in the command entries. If so, PASSES=YES is defaulted
unless PASSES=NO was specified when calling INGMON.
- NO
- Passes are not used to issue the commands.
- YES
- Passes are used to issue the commands. The pass count is incremented every time INGMON is called. The pass count is keyed by monitor name and by message type or exception (that is, the OM exception). The count is automatically reset when the monitor resource is deactivated, or when INGMON is invoked with the CLEARING option.
- CLEARING
- Indicates that this is a clearing event. The situation that caused the message or exception is no longer present. It resets the pass count and removes the mask (DISABLETIME) for this message or exception.
- EHKVAR
- This parameter determines whether the tokens of the parsed message
text are to be stored in task global variables EHKVAR0 through EHKVAR9
and EHKVART.
- YES
- The tokens of the triggering message are to be assigned to the task global variables EHKVARn.
- NO
- No values are to be assigned to the task global variables EHKVARn.
- JOBNAME
- Indicates that the job name that is given is to be used rather
than the one obtained by the jobname() function to match a monitored
object to the corresponding monitor resources.
If the monitor resource contains a value in the monitored job name field it is only considered a match when both the monitored object and the given job name match.
If JOBNAME is omitted the jobname() function is used to determine the name of the job that issued the triggering message. If a job name cannot be determined the value N/A is used.
JOBNAME is required when INGMON is not message driven.
- WAIT
- Specifies the number of seconds to wait before reporting that
a timeout occurred if the automation manager does not provide the
requested data. The maximum time interval is 999 seconds.
If omitted, the time interval is 30 seconds.
- RESET=YES
- Specifies that the status is to be reset. When the monitor status is BROKEN, it is reset to INACTIVE. When the monitor status is INACTIVE, it remains INACTIVE. Any other monitor status is changed to NORMAL. Additional parameter specifications other than INFO and JOBNAME are ignored.
Return Codes
- 0
- Okay.
- 1
- An error occurred.
- 2
- A monitor resource or monitored object with the specified name does not exist.
Restrictions and Limitations
Status cannot be changed via STATUS=option while the monitor is in status BROKEN. Consider the RESET=YES option.
Usage
You should normally call the INGMON command from the NetView automation table.
For more details about
the task global variables that can be used with INGMON see Task Global Variables
in
IBM Z® System Automation Customizing and Programming.