Register Filter Notifications (QNMRGFN) API

The Register Filter Notifications (QNMRGFN) API registers a filter to send notifications for a specific event to a data queue. This data queue is defined in the *SNDDTAQ action entry field of the registered filter. These notification records are the asynchronous output of this API. All CL filter commands can be performed against a registered filter.

A filter can only be registered once. If a registered filter is being registered again, an error is returned. No checking is done to see if the registered filter is the same as another filter, such as an active user filter.

A check to prevent duplicate notifications for a single event is made when the registered filters are processed. If a notification record for a registered filter is a duplicate of another notification record (such as an active user filter) the registered filter is not processed.

If an error occurs in accessing a registered filter, or while enqueuing the notification record, the filter is automatically deregistered, and an informational message (CPI91D5) is sent to the system operator (QSYSOPR) message queue. This prevents the system from encountering the error again.

The registration for a filter remains active after the initial program load of a system. This ensures that a product receives all notifications. A product should register its filter either when the product is installed or when the product is started. A product should check to see that its filter is registered at its start-up time to ensure that its filter was not automatically deregistered. You do not have to deregister a filter to change the filter.

Authorities and Locks

Registered Filter

*USE

Registered Filter Library

*USE

Required Parameter Group

Qualified filter name

INPUT; CHAR(20)

The qualified filter name that is being registered. The first 10 characters are the filter name, and the last 10 characters are the library name. Special values *LIBL and *CURLIB are not supported for the library name.

Filter type

INPUT; CHAR(10)

The type of filter. The following filter types are specified in the format field.

Special values supported are:

*ALR	Alert filter. (See Alert Filter for details about the format.)
*PRB	Problem log filter. (See Problem Log Filter for details about the format.)

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of Registered Filter Data Queue Notification

See Field Descriptions for descriptions of the fields in this format.

The types of event-specific notification data used by the format field are described below.

Alert Filter

See Field Descriptions for descriptions of the fields in this format.

Problem Log Filter

See Field Descriptions for descriptions of the fields in this format.

Field Descriptions

Alert major vector. The actual alert that caused the notification.

Event-specific notification data. Data specific to the event identified in the function code. The data is in the format specified by the format variable.

Filter library name. The library that contains the filter.

Filter name. The name of the filter that sent the notification.

Format. The format of the event-specific data of a problem log filter. Valid values are:

Function code. The event that caused the notification. Valid values are:

Group name. The group into which the event was filtered.

Last event. The last event performed on the problem. Valid values are:

Last event timestamp. The time at which the last event was performed.

Notification name. The type of notification record. It is set to *RGFN for all registered filter notifications.

Problem ID. The ID of the problem that caused the notification.

Reserved. An ignored field.

Timestamp. The time at which the event was processed.

Error Messages