Register Filter Notifications (QNMRGFN) API
Required Parameter Group:
| 1 | Qualified filter name | Input | Char(20) |
| 2 | Filter type | Input | Char(10) |
| 3 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Notification name |
| 10 | A | CHAR(2) | Function code |
| 12 | C | CHAR(8) | Format |
| 20 | 14 | CHAR(10) | Filter name |
| 30 | 1E | CHAR(10) | Filter library name |
| 40 | 28 | CHAR(10) | Group name |
| 50 | 32 | CHAR(8) | Timestamp |
| 58 | 3A | CHAR(22) | Reserved |
| 80 | 50 | CHAR(*) | Event-specific notification data |
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 80 | 50 | CHAR(512) | Alert major vector |
Problem Log Filter
See Field Descriptions for descriptions of the fields in this format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 80 | 50 | CHAR(30) | Problem ID |
| 110 | 6E | CHAR(1) | Last event |
| 111 | 6F | CHAR(8) | Last event timestamp |
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:
| RGFN0100 | Alert filter |
| RGFN0200 | Problem log filter |
Function code. The event that caused the notification. Valid values are:
| 01 | Alert event |
| 02 | Problem log event |
Group name. The group into which the event was filtered.
Last event. The last event performed on the problem. Valid values are:
| 01 | Problem entry opened |
| 02 | Service request received code |
| 03 | Opened by alert |
| 10 | Problem analyzed |
| 11 | Verification test ran |
| 12 | Recovery procedure ran |
| 20 | Prepared to report |
| 21 | Service request sent |
| 22 | Problem answered |
| 23 | Response sent |
| 24 | Reported by voice |
| 25 | Fixes transmitted |
| 26 | Change request submitted |
| 27 | Change request ended |
| 30 | Fix verified |
| 41 | Remote analysis |
| 42 | Remote verification ran |
| 43 | Remote recovery ran |
| 50 | Alert created |
| 51 | APAR created |
| 52 | APAR data collected |
| 54 | APAR data restored |
| 55 | APAR data deleted |
| 60 | Changed by CHGPRB |
| 61 | Deleted by DLTPRB |
| 62 | Recurring problem |
| 70 | Status changed |
| 71 | Status query sent |
| 80 | Auto-PAR done |
| 81 | Auto-PAR not done - SRC OFF |
| 82 | Auto-PAR not done - SBMJOB |
| 83 | Auto-PAR failed |
| 86 | Auto-notify done |
| 87 | Auto-notify not done - SRC off |
| 88 | Auto-notify not done - SBMJOB |
| 89 | Auto-notify failed |
| 99 | Problem entry closed |
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
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C7C E | User index is full. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF91D2 E | Filter type &3 not correct for this operation. |
| CPF91D3 E | Filter &1/&2 with type &3 is already registered. |
| CPF9800 E | All CPF98xx messages could be signaled. xx is from 01 to FF. |
API introduced: V2R3
[ Back to top | Network Management APIs | APIs by category ]