Retrieve Management Collection Object Attributes (QpmRtvMgtcolAttrs) API

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.

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.

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.

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.

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:

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:

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:

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:

Error Messages