Add Collector Notification (QypsAddCollectorNotification) API
Required Parameter Group:
1 | Collector name | Input | Char(10) |
2 | Qualified data queue name | Input | Char(20) |
3 | Notification type | Input | Binary(4) |
4 | Category list | Input | Array of Char(10) |
5 | Category count | Input | Binary(4) |
6 | Error Code | I/O | Char(*) |
Service Program Name: QYPSCOLL
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Add Collector Notification (QypsAddCollectorNotification) API registers with a collector to provide notifications to a specified data queue for a collection event. A collection event occurs when:
- The collector cycle interval is reached.
- The collector is ended.
- The default data collection interval is reached.
When a collector is ended, notifications are removed. When a collector is started, no notifications are registered.
Authorities and Locks
- API Public Authority
- *EXCLUDE
- Data Queue Authority
- *CHANGE
- Library Authority
- *EXECUTE
Required Parameter Group
- Collector name
- INPUT; CHAR(10)
The name of the collector that is adding a notification. One of these special values must be used:
*PFR Performance Collector
- Qualified data queue name
- INPUT; CHAR(20)
The data queue used to send the event notification. The first ten characters contain the data queue name, and the second ten characters contain the data queue library name. The data queue must already exist, and the user profile running the API must have *CHANGE authority to it. You can use these special values for the library name:
*CURLIB The job's current library. *LIBL The library list.
- Notification type
- INPUT; BINARY(4)
Notification is to be sent to the specified data queue when one of these events occur:
0 Collector - notify when a cycle, end, or interval event occurs. 1 Cycle - notify when the collection cycle interval occurs. 2 End - notify when the collection is ended. 3 Interval - notify when the collection interval occurs. 4 Category - notify when the category interval occurs. For more information on the format of the notification record, see Notification Record Format.
- Category list
- INPUT; ARRAY OF CHAR(10)
List of category names, for which notification is to be sent. This field is only applicable when Notification type is set to category notification (4). Category name can be a system-defined category name or a user-defined category name.
- System-defined category name
- A 10 character name of a system-defined category.
- Registered user-defined category name
- A 10 character name of a user-defined category registered by the Register
Collector Data Category (QypsRegCollectorDataCategory) API.
- Category count
- INPUT; BINARY(4)
The number of categories entered in input field Category list. This field is only applicable when Notification type is set to category notification (4). Category count must have a value of '0' when Notification type is not a category notification (4).
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Usage Notes
An application uses the Add Collector Notification (QypsAddCollectorNotification) API to start receiving notifications about collector events. The collector sends notifications using the data queue. The application program has to create a data queue and pass the qualified name of this data queue to the Add Collector Notification (QypsAddCollectorNotification) API. The collector sends notification messages or records to the specified data queue. The format of the notification records is shown below. The application program is responsible for reading and removing entries from the data queue.
When the application no longer needs to receive notifications from the collector, it uses the Remove Collector Notification (QypsRmvCollectorNotification) API.
The application is responsible for cleaning up the data queue.
Notification Record Format
For detailed descriptions of the fields in this table, see Notification Record Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | Char(10) | Entry type |
10 | A | Char(2) | Entry identifier |
12 | C | Char(10) | Collection object name |
22 | 16 | Char(10) | Library name |
32 | 20 | Char(8) | Sequence identifier |
40 | 28 | Char(10) | Category |
50 | 32 | Char(40) | Reserved |
Notification Record Field Descriptions
Category. The category associated with the notification. This field is only applicable when the notification event specified in Entry identifier is set to category notification ('04').
Collection object name. The name of the collection object where any data collected was placed. This name is generated when the collector starts , and is of the form QDDDHHMMSS.
Entry identifier. The notification event that occurred. Values are:
'01' | Cycle - a collection cycle interval occurred. |
'02' | End - a collection has ended. |
'03' | Interval - a collection interval occurred. |
'04' | Category - a category collection interval occurred. |
Entry type. The type of this data queue entry. Set to value '*COLNOT '.
Library name. The name of the library containing the collection object for which the event occurred.
Reserved. This space is reserved for possible future use.
Sequence identifier. A unique identifier assigned to this collection event. Its format is based on the time since the collector was started in the format DDHHMMSS , where 00000000 represents the time the collector was started.
Error Messages
Message ID | Error Message Text |
---|---|
CPF3C1E E | Required parameter &1 omitted. |
CPF3C3C E | Value for parameter &1 not valid. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9801 E | Object &2 in library &3 not found. |
CPF9802 E | Not authorized to object &2 in &3. |
CPF9810 E | Library &1 not found. |
CPF9820 E | Not authorized to use library &1. |
CPFB94A E | Collector communications error. Reason code &1. |
Introduced: V5R2