| 1 | Collection request parameters | I/O | Char(*) |
| 2 | Data buffer | Output | Char(*) |
| 3 | Work area | I/O | Char(*) |
| 4 | Return code | Output | Binary(4) |
A Collection Services Data Collection exit program is called by Collection Services to collect performance data for a user-defined performance category. The Collection Services collector will store this data in the management collection object. For the exit program to be called by the collector, it must first be registered using the Register Collector Data Category (QypsRegCollectorDataCategory) API. User-defined performance data that is stored in the management collection object can be read using the Read Management Collection Object Data (QpmReadMgtcolData) API.
At the time a user-defined category is registered, a single entry point is specified for the data collection program. This entry point can be a program object (*PGM) or an entry point in a service program (*SRVPGM).
Collection Services calls this entry point with parameters which specify the type of request to perform and the control information necessary for the data collection program to complete the request.
Collection Services provides a data buffer where the data collection program will return collected data.
Collection Services also provides a work area which can be used by the data collection program to save its state between the calls.
The parameter structure passed to the data collection program is mapped by the QPMDCPRM header file shipped with the system in the QSYSINC library.
None.
This is a structure in which Collection Services passes control information about the data collection request to the data collection program. The data collection program uses this structure to return information about actions performed. The format of the data in this structure is determined by the parameter format specified when the user-defined category was registered using the Register Collector Data Category (QypsRegCollectorDataCategory) API. Currently, PMDC0100 is the only format supported. The layout of this structure is described in Layout of Collection Request Structure below.
This is a data buffer in which the data collection program returns data to be stored in the management collection object. Collection Services will store this data in a record of the repository of the management collection object.
For start collection and end collection requests, this is control data and will be stored in a collection control record. For interval collection request, this is collected performance data and will be stored in an interval record.
The length of this buffer is defined in the data buffer bytes available field of the collection request parameters structure. Writing to the data buffer beyond this length will have unpredictable results.
The work area is a storage area created by Collection Services for the sole use of the data collection program. Initially, the work area is set to zeroes. The same work area is passed in every call to the data collection program. This work area can be used by the data collection program to save some state information between the calls. Collection Services will preserve the work area contents between the calls. The length of the work area is set at category registration time and is defined in the length of work area field of the collection request.
Return code set by the data collection program. Collection Services will take an action based on the code returned from the data collection program. The return code is ignored for the cleanup and terminate request. Possible return codes and Collection Services actions:
| 0 | Data collection request was performed successfully. |
| > 0 | Data collection request encountered recoverable
errors. A non-zero return code will be logged in the job log. Action taken by
Collection Services depends on the collection request:
|
| < 0 | Data collection request encountered unrecoverable errors. Collection Services will assume that no further data collection is possible for this category and stop collecting data for this category. The data collection program may use a negative return code to cause immediate termination of data collection for the user-defined category. |
The layout of the collection request structure is determined by the parameter format specified when the user-defined category was registered using the Register Collector Data Category (QypsRegCollectorDataCategory) API.
Currently, PMDC0100 is the only format supported. The table below shows the layout of the collection request structure for the PMDC0100 format. For detailed descriptions of the fields in the table, see Field Descriptions below.
| Offset | Input/Output | Type | Field | |
|---|---|---|---|---|
| Dec | Hex | |||
| 0 | 0 | INPUT | CHAR(8) | Format name |
| 8 | 8 | INPUT | CHAR(10) | Category name |
| 18 | 12 | -- | CHAR(2) | Reserved |
| 20 | 14 | INPUT | BINARY(4) | Request type |
| 24 | 18 | INPUT | BINARY(4) | Request type modifier |
| 28 | 1C | INPUT | BINARY(4) | Data buffer bytes available |
| 32 | 20 | INPUT | BINARY(4) | Offset to category parameter string |
| 36 | 24 | INPUT | BINARY(4) | Length of category parameter string |
| 40 | 28 | INPUT | BINARY(4) | Length of work area |
| 44 | 2C | -- | CHAR(4) | Reserved |
| 48 | 30 | INPUT | CHAR(8) | Interval key |
| 56 | 38 | INPUT | CHAR(8) | Interval time |
| 64 | 40 | OUTPUT | BINARY(4) | Data buffer bytes provided |
| 68 | 44 | OUTPUT | BINARY(4) | More data indicator |
| 72 | 48 | -- | CHAR(8) | Reserved |
Category name. Name of the user-defined category for which data collection is performed. This name was registered previously uisng the Register Collector Data Category (QypsRegCollectorDataCategory) API.
Data buffer bytes available. Size of the data buffer passed in the data buffer parameter.
Data buffer bytes provided. The data collection program indicates in this field how many bytes of data in the data buffer should be stored by Collection Services in the repository of the management collection object. If this field is set to 0 for start collection or end collection requests, a collection control record will not be created. If this field is set to 0 for an interval collection request, Collection Services will still create an interval record but will not store any data in it. This field is set to zero at entry to the data collection program.
Format name. Name of the collection request structure format passed to the data collection program. This is the parameter format specified when the user-defined category was registered using the Register Collector Data Category (QypsRegCollectorDataCategory) API. Currently, PMDC0100 is the only format supported.
Interval key. Record key of the repository record about to be written into the repository of the management collection object. Format of this field is DDHHMMSS, where:
| DD | Number of days from the beginning of collection to this collection object. Day numbering starts from 0. |
| HHMMSS | Time in hours, minutes and seconds when a particular collection sample was scheduled. |
Record keys of interval records, with the possible exception of the key of the first interval record in a collection period, are normalized to the collection interval boundary. For example, for a 15 minute collection interval, valid record keys will be 00124500 or 00223000, but not 00131014.
Interval time. Exact time in system timestamp format when the Collection Services collector initiated a particular request. This time is provided for reference only. Normally this time is close to the time implied by the interval key field but, unlike the interval key, this time is not normalized. See Convert Date and Time Format (QWCCVTDT) API for details about time formats.
Length of category parameter string. Length of the category parameter string. If the parameter string was not registered for this category, this field is set to 0.
Length of work area. Length of the work area passed in the work area parameter. The size of the work area is set during category registration.
More data indicator. By setting this field to a non-zero value, the data collection program may indicate to Collection Services that it has more data to store in the repository of the management collection object for this request. When this field is returned with a non-zero value, Collection Services will transfer the returned data to the current repository record then will call the data collection program again with all parameters identical to the previous call except that the request type modifier field will be set to 20. The data collection program may use the more data indicator field as many times as needed to transfer all collected data to Collection Services. This field is set to zero at entry to the data collection program.
Offset to category parameter string. Offset in bytes to the category parameter string starting from the beginning of the collection request. This parameter string was specified when the user-defined category was registered using the Register Collector Data Category (QypsRegCollectorDataCategory) API. The parameter string can be used to pass customization information to the data collection program. The length of this string is defined in the length of category parameter string field. If a parameter string was not registered for this category, this field is set to 0. The parameter string is only passed when the request type is set to 10 - start collection request.
Request type. Type of action requested from the data collection program. The data collection program must support the following request types:
| 10 | Start collection request. This is the first request that the data collection program will receive in a data collection session. When receiving this request, the data collection program is expected to initialize whatever interfaces it uses to collect the data. Optionally, in the provided data buffer, the data collection program may return collection control information to be stored in a collection control record in the repository of the management collection object. |
| 20 | End collection request. This is the last request the data collection program will receive in a data collection session. When receiving this request, the data collection program is expected to close whatever interfaces it uses to collect the data, release resources, and so on. Optionally, in the provided data buffer, the data collection program may return collection control information to be stored in a collection control record in the repository of the management collection object. |
| 30 | Interval collection request. The data collection program will receive a request of this type each time the interval collection for this user-defined category is scheduled. The time between interval collection requests is specified at category registration time. When receiving this request, the data collection program is expected to perform its regular collection of performance data and return collected data in the provided data buffer. This data will be stored in an interval record in the repository of the management collection object. |
| 40 | Cleanup and terminate (shutdown) request. This request is sent to the data collection program when Collection Services cannot continue data collection. An example of such a problem is the loss of contact with the Collection Services collector job. When receiving this request, the data collection program is expected to perform necessary cleanup, release resources, and so on. The data collection program cannot return any data for this request. Any data placed in the data buffer will be ignored. |
Request type modifier. This field modifies the meaning of the request type field. This field can have two values:
| 10 | Normal request to collect data. |
| 20 | Continuation of the previous request. This value is used to indicate to the data collection program that this is the continuation of the same collection request. When the data collection program returns with the more data indicator set to a non-zero value, Collection Services will transfer the returned data to the current repository record then will call the data collection program again with the same parameters except that the request type modifier field will be set to 20. In this way, the data collection program may store more collected data in the management collection object than fits into the data buffer. |
| Top | Performance Management APIs | APIs by category |