| 1 | Collector name | Input | Char(10) |
| 2 | Receiver variable | Input | Char(*) |
| 3 | Length of Receiver variable | Input | Binary(4) |
| 4 | Format name to retrieve | Input | Char(8) |
| 5 | Error code | I/O | Char(*) |
The Retrieve Collection Services Attributes (QypsRtvColSrvAttributes)
API retrieves system or global collection attributes. It is a replacement for and
extension of the Retrieve System Collector Attributes (QYPSRSCA,
QypsRtvSysCollectorAttributes) API.
The name of the collector whose default values are to be retrieved. The special value is:
| *PFR | Performance collector |
The variable that is to receive the requested information. It can be smaller than the format requested as long as the next parameter, length of receiver variable, specifies the length correctly. When this variable is smaller than the format, the API returns only the data that the variable can hold.
The length of the receiver variable. The minimum length is 8 bytes. Do not specify a length that is longer than the receiver variable; the results are unpredictable.
The content and format of the information returned. The possible format names are:
| SCAI0010 | Collection services status |
| SCAI0100 | Basic collection services attributes |
| SCAI0200 | Performance database file options |
| SCAI0300 | Management Central Monitor options |
| SCAI1000 | All previous formats |
These are described in the following sections.
The structure in which to return error information. For the format of the structure, see Error code parameter.
This format contains collection services status information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Collection overrides |
| 12 | C | CHAR(14) | Collection start time |
| 26 | 1A | CHAR(10) | Current collector definition |
| 36 | 24 | CHAR(10) | Management collection object name |
| 46 | 2E | CHAR(10) | Management collection object library |
Bytes available. The length of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length of the data actually returned.
Collection overrides. Indicates if collection overrides are in effect.
Collection services normally collects data because a system profile collection was started. However, it can also collect data to support the needs of other functions such as Management Central Monitors and user applications via the Work with Collector (QAPMWKCOL) API. This is referred to as collection overrides. Collection overrides can cause data collection whether or not a system profile collection was started. The following values will be returned
| 0 | No collector override is active. |
| 1 | Data is being collected per override requests. |
Collection start time. The UTC time that the current (active) collection was started. Format of string is YYYYMMDDHHMMSS. If there is no active collection, this value will be blank.
Current collector definition. The name of the currently running collector definition (also called collection profile). The following values may be returned:
| *CUSTOM | A profile where both the categories to collect and category interval times may be customized. |
| *ENHCPCPLN | Enhanced Capacity Planning. Same as *STANDARDP plus the PEX Data - Processor Efficiency category. |
| *MINIMUM | The minimum set of categories required to support performance reporting functions |
| *NONE | A profile collection is not active |
| *STANDARD | All categories that are typically used for performance reporting except for communications protocol related data |
| *STANDARDP | Same as *STANDARD but communications protocol categories are included. |
Management collection object library. Specifies the name of the library into which the currently active management collection object is stored. If there is no active collection, this value will be blank. Note: This may not be the same as the currently configured collection library.
Management collection object name. The name of the current management collection object. If there is no active collection, this value will be blank.
This format contains basic collection services attributes (also referred to as properties or configuration options).
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Default collection interval |
| 12 | C | BINARY(4) | Collection retention period |
| 16 | 10 | BINARY(4) | Cycle time |
| 20 | 14 | BINARY(4) | Cycle interval |
| 24 | 18 | BINARY(4) | Companion user job |
| 28 | 1C | CHAR(10) | Collection library |
| 38 | 26 | CHAR(10) | Default collector definition |
Bytes available. The length of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length of the data actually returned.
Collection library. The name of the library used to store the collection data.
Collection retention period. The collection retention period indicates how long collection data is to exist.
Collection data older than the retention period may be deleted. Collection Services stores this data in Management Collection (*MGTCOL) Objects with the *PFR attribute. This retention period is used to calculate an expiration date for the object. Expired objects will be automatically deleted by the Collection Services server job (QYPSPFRCOL) the next time a collection is started or cycled. Collection objects are deleted only when they exist in the system's configured collection library.
The retention period is specified in hours. The following special value may be returned:
| -1 | Permanent |
Companion user job. Specifies whether or not a job is started to run in concert with the collector. One of the following values will be returned:
| 0 | No companion user job is started. |
| 1 | A companion user job is started. (For the *PFR collector, this is the CRTPFRDTA job which creates the standard performance database collection from the current *MGTCOL collection.) |
Cycle interval. The elapsed time between cycles. The cycle time is specified in hours, and can range from a minimum value of one hour to a maximum value of 24 hours.
Cycle time. The time at which the first cycle is to occur. The cycle time is specified in minutes past midnight. The maximum allowed value is 1439 minutes, which is one minute less than 24 hours.
Default collector definition. The name of the collector definition (also called a collection profile) to run. The following values may be returned:
| *CUSTOM | A profile where both the categories to collect and category interval times may be customized. |
| *ENHCPCPLN | Enhanced Capacity Planning. Same as *STANDARDP plus the PEX Data - Processor Efficiency category. |
| *MINIMUM | The minimum set of categories required to support performance reporting functions |
| *STANDARD | All categories that are typically used for performance reporting except for communications protocol related data |
| *STANDARDP | Same as *STANDARD but communications protocol categories are included. |
Default collection interval. The default interval to use when collecting data for a category. Valid interval values are: 15, 30, 60, 300, 900, 1800, or 3600 seconds. The following special value may be returned:
| 0 | Do not collect on interval. |
This format contains additional attribute information regarding how collection services supports performance database file collections.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Standard file data retention |
| 12 | C | BINARY(4) | Summary data creation |
Bytes available. The length of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length of the data actually returned.
Standard file data retention. Standard file data is that data normally collected for a collection profile on an ongoing basis that has been exported to performance data base files (QAPM*). The standard file data retention period is used to determine how long performance database file collections should be retained on the system. When standard data in the configured collection library is older than the current retention period, it will be automatically deleted by the Collection Services server job (QYPSPFRCOL) the next time the collector is started or cycled. The retention period is specified in days. The following special value may also be returned:
| -1 | Permanent |
Summary data creation. This option controls the automatic generation of additional performance database summary data as supported by the CRTPFRSUM command. This data facilitates quicker processing of the performance database data by tools such as the Performance Viewer. If this option is enabled, and the Companion user job flag of format SCAI0100 is set to 1, the CRTPFRSUM function will be performed for the database collection created by the CRTPFRDTA job. The following values will be returned:
| 0 | Summary file data is not generated. |
| 1 | Summary file data is generated. |
This format contains Management Central Monitor support options. Collection Services provides the configuration support for certain Management Central monitor functions. Those configuration options are contained in this table.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Graph data creation |
| 12 | C | BINARY(4) | Graph data retention |
| 16 | 10 | BINARY(4) | Historical data creation |
| 20 | 14 | BINARY(4) | Historical data retention |
Bytes available. The length of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length of the data actually returned.
Graph data creation. Indicates whether or not Management Central graph data is created when the collection is cycled. Graph data is created and maintained by Management Central monitors and is stored in a *MGTCOL with the *PFRDTL attribute. One of the following values will be returned:
| 0 | Graph data is not created. |
| 1 | Graph data is created. |
Graph data retention. The graph data retention period is used to determine how long Management Central graph data is to exist. Graph data older than the retention period is deleted. The retention period is specified in days.
Historical data creation. Indicates whether or not Management Central historical data (also called summary data within System i™ Navigator) is created when the collection is cycled. Historical data is created and maintained by Management Central monitors. It is stored in a *MGTCOL with the *PFRHST attribute. The following values may be returned:
| 0 | Historical data is not created. |
| 1 | Historical data is created. |
Historical data retention. The historical data retention period is used to determine how long Management Central historical data is to exist. Historical data older than the retention period is deleted. The retention period is specified in months.
This format includes all the previously defined formats.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Format count |
| 12 | C | BINARY(4) | Format offset table entry size |
| 16 | 10 | Array(*) | Format offset table |
Format offset table entry:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Format name |
| 8 | 8 | BINARY(4) | Format offset |
Bytes available. The length of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length of the data actually returned.
Format count. The number of formats returned within the SCAI1000 format. Also the number of format offset table entries.
Format name. The name of a format being returned.
Format offset. The offset to the indicated format in the receiver variable.
Format offset table. An array of entries that describe the formats being returned by SCAI1000.
Format offset table entry size. The size of an entry in the format offset table.
| Message ID | Error Message Text |
|---|---|
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3C E | Value for parameter &1 is not valid. |
| CPF3CF2 E | Errors occurred during running of &1 API. |
| CPFB94F E | Could not allocate a collection services resource. |
[ Back to top | Performance Management APIs | APIs by category ]