INGALERT

Purpose

The INGALERT command allows you to send alerts to event notification targets such as:

• System Automation for Integrated Operations Management (SA IOM)
• Tivoli Enterprise Console (TEC)
• Tivoli® Netcool/OMNIbus
• Tivoli Service Request Manager®
• A user-defined alert handler.

Parameters

NETVASIS

Prefix the INGALERT command with NETVASIS if you want to pass USRn information in lower or mixed case.

resource

This can be:

• A fully-qualified resource name, in the form name/type/sys (where type is APL, APG or MTR)
• The text MVSESA (that is, the content of the AOFSYSTEM variable)
• A job or subsystem name

The subsystem name takes precedence over the job name.

If there is more than one resource with the given subsystem or job name, the corresponding local system resource is used. If there is no such resource on the local system, the first resource found is used.

If the resource name is not specified as a parameter, the value of the JOBNAME parameter is used to determine the resource name. If the JOBNAME parameter is not specified either, and INGALERT is called from the automation table, the job name is taken from the message’s job name field. If no job name can be determined, MVSESA is used as the resource name.

ID

This is the alert identifier for the resource. Refer to the "Enable Alerting" section in IBM Z® System Automation Customizing and Programming for further details on the pre-defined alerts for SA z/OS. If INGALERT is called from the NetView automation table (AT), alert_id can be omitted, in which case the message ID of the triggering message is used.

When you create clearing events by specifying MODE=CLEARING, you can set the ID=* to clear all outstanding events for the specified resource.

MODE

This specifies the type of created event.

PROBLEM

Creates a problem event. This is the default value.

CLEARING

Creates a clearing event only if the event is addressed to the EIF or USR target. For other targets, no event is created.

INFORM

This specifies the notification target for the created event to be sent to. An event is only sent to a specified target, if the event notification for this target is enabled and if the target is included in the inform policy list of the resource.

The value for the INFORM parameter can be specified as:

• The name of a supported event notification target. Supported targets are IOM, EIF, TTT or USR
• A list of supported event notification targets, enclosed in parentheses.
• An asterisk, *, which means the list of all supported event notification targets.

MSG

This is the ID of a message defined in the NetView message catalog.

Note that if you enter an invalid message ID, the message AOF000I is sent to the specified event notification targets.

The message can have variables &1 through &9 that are filled with parameters that are specified after msgid. If a message parameter is omitted the following defaults are used:

&1

INGALERT

&2

The date and time stamp when the message was generated

&3

The alert ID that was specified or the default that was used

&4

The resource that was specified or the default that was used

&5

The system that INGALERT was called on

MSG cannot be used together with TEXT.

TEXT

This is a text string that is to be used for the alert.

TEXT cannot be used together with MSG.

JOBNAME

This specifies the name of the job that caused the alert. If not specified, the job name is taken from the message's job name field if INGALERT is called from the automation table. Otherwise N/A is used as the default value.

USRn

Specifies the name and the value of a user field. n can be 1-9. User fields are passed on to notification targets EIF, TTT, and USR. For EIF events, the value is limited to 255 characters.

CDEn

Specifies the value to replace '&n' placeholders in the CDEMATCH data. n can be 1-9.

If neither MSG nor TEXT are specified and INGALERT is called from the automation table, the text of the triggering message is first obtained from the default SAFE and if not found from the named AOFMSAFE safe. If there is still no message text, MSG=ING140I is used.

Note that the text or message text may be truncated by SA IOM.

Return Codes

0

All alerts were sent successfully. In addition, there might be alerts that have been ignored.

1

All alerts were ignored.

3

Besides alerts that were successfully sent, at least one alert could not be sent. In addition, there might be alerts that have been ignored.

4

Parameter error.

6

Environment check failed.

8

No alert could be sent. In addition, there might be alerts that have been ignored.

Restrictions and Limitations

SA z/OS must be fully initialized.

Usage

Alert transmission can be controlled as follows:

• Alerting can be enabled and disabled system-wide with the INGCNTL command.
• If an event notification target is specified in the Inform List field of the resource's policy, alerting is enabled; otherwise it is disabled.
• Alerting is disabled for a resource if code processing for it is unsuccessful or returns a value of IGNORE.

An event is only sent to the specified target if event notification for this target is not prevented by one of these control mechanisms.

SA z/OS does not keep track of alerts that have been sent. Once the data has been successfully delivered to the event notification target, responsibility for delivering the event is passed on to this target as follows:

• For IOM, the event is passed on to SA IOM via the peer-to-peer connection
• For EIF, the event is passed on to the message adapter service or the confirmed message adapter service of the NetView event/automation service
  Note: With the INGCNTL command you can specify, whether EIF events are sent via the confirmed or unconfirmed message adapter. Refer to INGCNTL for further details on setting up the confirmation mode of EIF events.
• For TTT, the event is passed on to the Tivoli Directory Integrator server
• For USR, the event is passed on to the user defined alert handler

If an alert cannot be sent to the target a message is written to the netlog. No further attempts are made to deliver the alert.