| 1 | Management collection object repository handle | Input | Binary(4) |
| 2 | Read options | Input | Char(*) |
| 3 | Record information | Output | Char(*) |
| 4 | Record data | Output | Char(*) |
| 5 | Error code | I/O | Char(*) |
The Read Management Collection Object Data (QpmReadMgtcolData) API performs the following actions:
The repository is identified by a handle which was previously created by the Open Management Collection Object Repository (QpmOpenMgtcolRepo) API.
Record processing options are specified in the read options parameter.
Information about the repository record is returned in the record information parameter.
Data from a record is returned in the record data parameter.
The formats of the read options, record information and record data parameters are determined by the format name that was passed to the Open Management Collection Object Repository (QpmOpenMgtcolRepo) API at the time the repository was opened for processing.
A handle to an open repository of a management collection object. This handle was created by the Open Management Collection Object Repository (QpmOpenMgtcolRepo) API.
Contains control information that determines how the API will process the record. See Format of Read Options Parameter.
Information about the current repository record. See Format of Record Information Parameter. This parameter should be large enough to accommodate the entire record information structure. Otherwise, results are unpredictable.
If requested in the read options parameter, data from the current repository record is returned in this parameter. The format of the data returned in this parameter is determined by the format name passed to the Open Management Collection Object Repository (QpmOpenMgtcolRepo) API at the time the repository was opened for processing.
The only format supported in this release is MCOD0100. For the MCOD0100 format, the API returns an unformatted sequence of bytes from the current repository record.
This parameter should be large enough to accommodate all data requested in the read options parameter. Otherwise, results are unpredictable
See Format of Read Options Parameter for more details.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The format of the read options parameter is determined by the format name passed to the Open Management Collection Object Repository (QpmOpenMgtcolRepo) API at the time the repository was opened for processing.
The only format supported in this release is MCOD0100. The table below shows the structure of the read options parameter for the MCOD0100 format. For detailed descriptions of the fields in the table, see Field Descriptions below.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes provided by API caller |
| 4 | 4 | BINARY(4) | Record positioning option |
| 8 | 8 | BINARY(8) | Offset in record data |
| 16 | 10 | BINARY(8) | Number of bytes to read |
| 24 | 18 | CHAR(8) | Record key |
The format of the record information parameter is determined by the format name passed to the Open Management Collection Object Repository (QpmOpenMgtcolRepo) API at the time the repository was opened for processing.
The only format supported in this release is MCOD0100. The table below shows the structure of the record information parameter for MCOD0100 format. For detailed descriptions of the fields in the table, see Field Descriptions below.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Record status |
| 4 | 4 | BINARY(4) | Record type |
| 8 | 8 | BINARY(8) | Number of bytes returned |
| 16 | 10 | CHAR(8) | Record key |
| 24 | 18 | CHAR(8) | Record timestamp |
| 32 | 20 | BINARY(8) | Total record data length |
Bytes provided by API caller. The number of bytes of read options provided. For the MCOD0100 format, this length should be at least 32 bytes.
Number of bytes returned. The number of bytes of record data returned by the API in the record data parameter.
Number of bytes to read. The number of bytes of record data that should be returned in the record data parameter. If this field is set to zero, no record data will be returned. If the repository record contains less data than requested by this field, the API returns only the available data. The number of bytes returned field in the record information parameter will be set to the actual number of bytes returned.
Offset in record data. Byte offset into the record data identifying the first byte of the record data to be returned in the record data parameter. This field and the number of bytes to read field together define which part of the record data will be returned.
Record key. For the read options parameter, this field is used together with the record positioning option field to specify the record key used in the record search.
For the record information parameter, this field returns the key of the record actually found.
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 repository records, with the possible exception of the first record in the collection period, are normalized at the collection interval boundary. For example, for a 15-minute collection interval, valid record keys will be 00124500 or 01223000, but not 00131014.
Record positioning option. The record that is the target of this call to the API. Supported positioning options are:
| 0 | Read next record. For this option, the API returns the next repository record in relation to the one processed by the previous call to the API. If no records have been read from the repository, the very first record is returned. If the previous record was the last one in the repository or if the repository is empty, the API returns record-not-found record status. |
| 1 | Read current record. For this option, the API returns the same record that was processed by the previous call to the API. This option is used to read different parts of the same record. If no records have been read from repository, the API returns a record-not-found record status. |
| 2 | Read first record. For this option, the API returns the very first record in the repository. This option is used to start reading the repository from the beginning. If the repository is empty, the API returns record-not-found record status. |
| 3 | Read record by key equal. For this option, the API returns the record with the key specified in the record key field of the read options parameter. If no record is found, the API returns record-not-found record status. |
| 4 | Read record by key less than or equal. For this option, the API returns the record with the largest key that is less than or equal to the key specified in the record key field of the read options parameter. If no record is found, the API returns record-not-found record status. |
| 5 | Read record by key greater than or equal. For this option, the API returns the record with the smallest key that is greater than or equal to the key specified in the record key field of the read options parameter. If no record is found, the API returns record-not-found record status. |
Record status. The result of record positioning. Valid values are:
| 0 | Record was successfully found and processed. |
| 1 | Record-not-found status. Possible causes for this status are listed in the description of the record positioning option field. |
Record timestamp. The exact time when data collection started for the current repository record. Time is represented in the system timestamp format. See Convert Date and Time Format (QWCCVTDT) API for details about time formats. Unlike the time represented by the record key field, this time is not normalized. Note that data collection can be a time-consuming process. The record timestamp field contains the time when data collection started for the current record, not necessarily the time when the collection was completed and the last piece of data was written into this record.
Record type. The type of the current repository record. The following record types can be returned:
| 0 | Interval record |
| 1 | Collection control record |
| 2 | Stop record |
| 3 | Unexpected record type |
Total record data length. Length in bytes of the record data in the current repository record.
To understand how this API works, it is important to know how data is stored in the management collection object.
Collection Services stores performance data collected for a performance collection category in a repository of a management collection object. Data is stored as a sequence of repository records of different types. The following record types are defined:
The repository records contain control information such as record type, record key, record timestamp, and so on, and a variable amount of record data (between 0 and 4GB).
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF0AA4 E | Lock request was not satisfied in a specified time. |
[ Back to top | >Performance Management APIs | APIs by category ]