Retrieve Management Collection Object Attributes (QpmRtvMgtcolAttrs) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified object name | Input | Char(20) |
| 5 | Error code | I/O | Char(*) |
Service Program Name: QPMAAPI
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Retrieve Management Collection Object Attributes (QpmRtvMgtcolAttrs) API returns information about attributes of a management collection object and repositories of a management collection object.
Authorities and Locks
- API Public Authority
- *EXCLUDE
- Authority to library containing collection object
- *EXECUTE
While retrieving attributes, this API places a *SHRRD lock on the management collection object.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that receives 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.
- Length of receiver variable
- INPUT; BINARY(4)
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.
- Format name
- INPUT; CHAR(8)
The content and format of the information returned in the receiver variable for a specified management collection object. The possible format names are:
MCOA0100 Retrieve attributes of a management collection object only MCOA0200 Retrieve attributes of a management collection object and attributes of repositories of an object
- Qualified object name
- INPUT; CHAR(20)
Name of a management collection object for which you want to retrieve information and the library in which it is located. The first 10 characters contain the object name and the second 10 characters contain the library name.
The system supports management collection objects with different attributes, or objects that contain different information. The Management Collection Object APIs support collection objects that are created by the Collection Services collector only. These collection objects have attribute *PFR.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
MCOA0100 Format
The following information is returned for the MCOA0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(8) | Object size |
| 16 | 10 | BINARY(4) | Object retention period |
| 20 | 14 | BINARY(4) | Default collection interval |
| 24 | 18 | BINARY(4) | Number of repositories |
| 28 | 1C | CHAR(14) | Date and time when object was created |
| 42 | 2A | CHAR(14) | Date and time of last update to the object |
| 56 | 38 | CHAR(10) | Partition serial number |
| 66 | 42 | CHAR(1) | Object is active |
| 67 | 43 | CHAR(1) | Object was repaired |
| 68 | 44 | CHAR(1) | Summarization status |
| 69 | 45 | CHAR(3) | Reserved |
MCOA0200 Format
When the MCOA0200 format is requested, this API will return information about the management collection object (MCOA0100 format) plus information about all of the repositories found in this management collection object. This format returns zero or more repository entries, described later. The number of repository entries returned in this format is specified in the number of repository entries returned field. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Everything from MCOA0100 format | |
| 72 | 48 | BINARY(4) | Number of repository entries returned |
| 76 | 4C | BINARY(4) | Offset to repository information |
| 80 | 50 | CHAR(*) | Repository information |
| 80 | 50 | BINARY(4) | Offset to repository entry 1 |
| 84 | 54 | BINARY(4) | Length of repository entry 1 |
| 88 | 58 | BINARY(4) | Offset to repository entry 2 |
| 92 | 5C | BINARY(4) | Length of repository entry 2 |
| ... | |||
| CHAR(*) | Repository entry 1 | ||
| CHAR(*) | Repository entry 2 | ||
| ... | |||
Repository entry
Each repository entry contains attributes of one repository of a management collection object. It includes one or more collection period entries, described later.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Repository name |
| 10 | A | CHAR(10) | Category name |
| 20 | 14 | BINARY(4) | Number of collection period entries |
| 24 | 18 | BINARY(8) | Repository size |
| 32 | 20 | CHAR(*) | Collection period entry 1 |
Collection period entry
A new collection period entry is created each time a collection is started or a collection interval is changed for the performance category associated with a repository. Each repository has at least one collection period.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of collection period entry |
| 4 | 4 | CHAR(14) | Date and time of collection period start |
| 18 | 12 | CHAR(14) | Date and time of collection period end |
| 32 | 20 | BINARY(4) | Collection interval |
| 36 | 24 | CHAR(4) | Reserved |
Field Descriptions
Bytes available. The length of all the data available to return. All available data is returned if the receiver variable has sufficient length.
Bytes returned. The length of the data actually returned.
Category name. The name of the performance collection category that created this repository.
Collection interval. The collection interval in seconds for the performance category that created this repository. Each category can have its own collection interval. A performance category can have different collection intervals at different times during the collection (for different collection periods). If the collection interval is negative, this category was not configured to perform interval collections. Such categories perform one-time-only collections; in the beginning of the collection (collection interval is set to minus 1) or at the end of the collection (collection interval is set to minus 2).
Date and time of collection period end. The date and time when either the collection was ended in this repository or the collection interval was changed for the performance category associated with this repository. This is represented in a format YYYYMMDDHHMMSS, where:
| YYYY | Year |
| MM | Month |
| DD | Day of the month |
| HH | Hour |
| MM | Minute |
| SS | Second |
This field reports blanks for collection periods that are in progress.
Date and time of collection period start. The date and time when either the collection was started into this repository or the collection interval was changed for the performance category associated with this repository. For a description of the format of this field, see the date and time of collection period end field.
Date and time when object was created. The date and time the collection object was created. For a description of the format of this field, see the date and time of collection period end field.
Date and time of last update to the object. The date and time when the last update to collection object data occurred. For a collection object that is not active, this is the time when the collection ended to this collection object. For a description of the format of this field, see the date and time of collection period end field.
Default collection interval. The default collection interval in seconds for this collection object. Individual performance categories may have different collection intervals.
Length of collection period entry. The length of a collection period entry, in bytes.
Length of repository entry. The length of a repository entry, in bytes. A repository entry contains information about one particular repository and includes one or more collection period entries.
Number of collection period entries. The number of collection period entries reported for a repository. Each repository has at least one collection period entry. A new collection period starts when the collection is started for the performance category associated with this repository or a new collection interval is set for this category.
Number of repositories. The number of repositories found in this management collection object.
Number of repository entries returned. The number of repositories for which information is returned in a receiver variable. This can be different than the value in the number of repositories field if the receiver variable is not big enough to hold the entire result.
Object is active. Whether collection is currently in progress for this collection object. Possible values are:
| 0 | Collection into this collection object has ended |
| 1 | Collection into this collection object is in progress |
Object retention period. The number of hours the collection object should be kept on the system before it is deleted automatically. The retention period starts when the collection is ended for this collection object. When the collection object is set for permanent retention, the object retention period field is set to minus 1.
Object size. The size of the management collection object in Kbytes (K = 1024).
Object was repaired. Whether the collection object was repaired. When the collection object is not correctly closed, for example, during abrupt system termination, it is repaired when it is touched the first time after that. Such an object may have corrupted data inside. Using such an object may cause unpredictable results. Possible values are:
| 0 | Collection object did not require repair |
| 1 | Collection object was repaired |
Offset to repository information. The offset in bytes from the beginning of a receiver variable to the beginning of a repository information structure.
Offset to repository entry. The offset in bytes from the beginning of a receiver variable to the beginning of a particular repository entry.
Partition serial number. The logical serial number of a system partition where the collection object was created.
Repository information. A variable-size field that contains information about repositories in a management collection object. This field contains an array of offset and length pairs (see offset to repository entry field and length of repository entry field), followed by a series of corresponding repository entry structures.
Repository name. The 10-character name of a repository of a management collection object.
Repository size. The size of a repository in Kbytes (K = 1024).
Reserved. A reserved field.
Summarization status. When the Collection Services collector cycles the management collection object, a process is started for this collection object that will extract performance summary information to be used for historical data analysis. The summarization status field indicates the status of this process:
| 0 | Summarization was not performed for this collection object |
| 1 | Summarization is complete |
| 2 | Summarization is in progress |
| 3 | Summarization was attempted but failed |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0A2B E | Not able to process management collection object &1 in library &2. |
| CPF2105 E | Object &1 in &2 type &3 not found. |
| CPF2110 E | Library &1 not found. |
| CPF2114 E | Cannot allocate object &1 in &2 type *&3. |
| CPF2207 E | Not authorized to use object &1 in library &3 type *&2. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9810 E | Library &1 not found. |
API introduced: V5R2
[ Back to top | >Performance Management APIs | APIs by category ]