582 lines
18 KiB
HTML
582 lines
18 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>Read Management Collection Object Data (QpmReadMgtcolData) API</title>
|
|
<!-- Begin Header Records -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Created for V5R2 -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!-- File cleanup completed Feb 2002 by v2cdijab -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="Top_Of_Page"></a>
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<h2>Read Management Collection
|
|
Object Data (QpmReadMgtcolData) API</h2>
|
|
|
|
<div class="box" style="width: 75%;">
|
|
<br>
|
|
Required Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="55%">Management collection object
|
|
repository handle</td>
|
|
<td align="left" valign="top" width="15%">Input</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Read options</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Record information</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Record data</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">Error code</td>
|
|
<td align="left" valign="top">I/O</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Service Program Name: QPMAAPI<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *EXCLUDE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Read Management Collection Object Data (QpmReadMgtcolData) API performs
|
|
the following actions:</p>
|
|
|
|
<ul>
|
|
<li>Positions to a specific record in a repository of a management collection
|
|
object.</li>
|
|
|
|
<li>Returns information about the record.</li>
|
|
|
|
<li>Optionally reads specified bytes of data from the record.</li>
|
|
</ul>
|
|
|
|
<p>The repository is identified by a handle which was previously created by the
|
|
<a href="qpmopenmgtcolrepo.htm">Open Management Collection Object Repository
|
|
(QpmOpenMgtcolRepo) API</a>.</p>
|
|
|
|
<p>Record processing options are specified in the read options parameter.</p>
|
|
|
|
<p>Information about the repository record is returned in the record
|
|
information parameter.</p>
|
|
|
|
<p>Data from a record is returned in the record data parameter.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<dl>
|
|
<dt><em>API Public Authority</em></dt>
|
|
|
|
<dd>*EXCLUDE</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Management collection object repository handle</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>A handle to an open repository of a management collection object. This
|
|
handle was created by the Open Management Collection Object Repository
|
|
(QpmOpenMgtcolRepo) API.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Read options</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>Contains control information that determines how the API will process the
|
|
record. See <a href="#HDRRDOPTPARM">Format of Read Options Parameter</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Record information</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>Information about the current repository record. See <a href=
|
|
"#HDRECINFOPARM">Format of Record Information Parameter</a>. This parameter
|
|
should be large enough to accommodate the entire record information structure.
|
|
Otherwise, results are unpredictable.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Record data</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>This parameter should be large enough to accommodate all data requested in
|
|
the read options parameter. Otherwise, results are unpredictable</p>
|
|
|
|
<p>See <a href="#HDRRDOPTPARM">Format of Read Options Parameter</a> for more
|
|
details.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Error code</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>The structure in which to return error information. For the format of the
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error code parameter</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRRDOPTPARM">Format of Read Options Parameter</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <a href="#HDRDESC">Field
|
|
Descriptions</a> below.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="center" valign="bottom">Dec</th>
|
|
<th align="center" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Bytes provided by API caller</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Record positioning option</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">BINARY(8)</td>
|
|
<td align="left" valign="top">Offset in record data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">16</td>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">BINARY(8)</td>
|
|
<td align="left" valign="top">Number of bytes to read</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="left" valign="top">CHAR(8)</td>
|
|
<td align="left" valign="top">Record key</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRECINFOPARM">Format of Record Information Parameter</a></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <a href="#HDRDESC">Field
|
|
Descriptions</a> below.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="center" valign="bottom">Dec</th>
|
|
<th align="center" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Record status</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Record type</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">BINARY(8)</td>
|
|
<td align="left" valign="top">Number of bytes returned</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">16</td>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">CHAR(8)</td>
|
|
<td align="left" valign="top">Record key</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="left" valign="top">CHAR(8)</td>
|
|
<td align="left" valign="top">Record timestamp</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="left" valign="top">BINARY(8)</td>
|
|
<td align="left" valign="top">Total record data length</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRDESC">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Bytes provided by API caller.</strong> The number of bytes of read
|
|
options provided. For the MCOD0100 format, this length should be at least 32
|
|
bytes.</p>
|
|
|
|
<p><strong>Number of bytes returned.</strong> The number of bytes of record
|
|
data returned by the API in the record data parameter.</p>
|
|
|
|
<p><strong>Number of bytes to read.</strong> 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.</p>
|
|
|
|
<p><strong>Offset in record data.</strong> 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.</p>
|
|
|
|
<p><strong>Record key.</strong> 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.</p>
|
|
|
|
<p>For the record information parameter, this field returns the key of the
|
|
record actually found.</p>
|
|
|
|
<p>Format of this field is DDHHMMSS, where:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="10 90" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>DD</em></td>
|
|
<td align="left" valign="top">Number of days from the beginning of collection
|
|
to this collection object. Day numbering starts from 0.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>HHMMSS</em></td>
|
|
<td align="left" valign="top">Time in hours, minutes and seconds when a
|
|
particular collection sample was scheduled.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><strong>Record positioning option.</strong> The record that is the target of
|
|
this call to the API. Supported positioning options are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top"><em>Read next record.</em> 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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top"><em>Read current record.</em> 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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>2</em></td>
|
|
<td align="left" valign="top"><em>Read first record.</em> 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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>3</em></td>
|
|
<td align="left" valign="top"><em>Read record by key equal.</em> 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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>4</em></td>
|
|
<td align="left" valign="top"><em>Read record by key less than or equal.</em>
|
|
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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>5</em></td>
|
|
<td align="left" valign="top"><em>Read record by key greater than or
|
|
equal.</em> 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.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Record status.</strong> The result of record positioning. Valid
|
|
values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Record was successfully found and processed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Record-not-found status. Possible causes for this
|
|
status are listed in the description of the record positioning option
|
|
field.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Record timestamp.</strong> The exact time when data collection
|
|
started for the current repository record. Time is represented in the system
|
|
timestamp format. See <a href="qwccvtdt.htm">Convert Date and Time Format
|
|
(QWCCVTDT) API</a> 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.</p>
|
|
|
|
<p><strong>Record type.</strong> The type of the current repository record. The
|
|
following record types can be returned:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Interval record</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Collection control record</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>2</em></td>
|
|
<td align="left" valign="top">Stop record</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>3</em></td>
|
|
<td align="left" valign="top">Unexpected record type</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Total record data length.</strong> Length in bytes of the record
|
|
data in the current repository record.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Usage Notes</h3>
|
|
|
|
<p>To understand how this API works, it is important to know how data is stored
|
|
in the management collection object.</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<ul>
|
|
<li><em>Collection control record.</em> This type of record can be used by the
|
|
performance collection category to store some kind of control information
|
|
necessary for the correct interpretation of the collected data. This type of
|
|
record is normally written as the first record of the collection session, but
|
|
can also be written as the last record before the stop record.</li>
|
|
|
|
<li><em>Interval record.</em> This type of record contains actual performance
|
|
data. One record of this type is produced for every collection interval.</li>
|
|
|
|
<li><em>Stop record.</em> This type of record is the last one in a series of
|
|
records pertaining to one collection session. If data collection for the
|
|
performance collection category was restarted without cycling the collector,
|
|
the stop record will be followed by an (optional) collection control record,
|
|
then interval records for the new session and so on.</li>
|
|
</ul>
|
|
|
|
<p>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).</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top" nowrap>Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24B4 E</td>
|
|
<td align="left" valign="top">Severe error while addressing parameter
|
|
list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF1 E</td>
|
|
<td align="left" valign="top">Error code parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
|
<td align="left" valign="top">Error(s) occurred during running of &1
|
|
API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C3C E</td>
|
|
<td align="left" valign="top">Value for parameter &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF0AA4 E</td>
|
|
<td align="left" valign="top">Lock request was not satisfied in a specified
|
|
time.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<hr>
|
|
API introduced: V5R2
|
|
|
|
<hr>
|
|
<table align="center" cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center">
|
|
<a href="#Top_Of_Page">Top</a> |
|
|
<a href="perfmgmt.htm">Performance Management APIs</a> |
|
|
<a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|