ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qpmrtvmgtcolattrs.htm

825 lines
25 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>Retrieve Management Collection Object Attributes (QpmRtvMgtcolAttrs)
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>Retrieve Management Collection
Object Attributes (QpmRtvMgtcolAttrs) API</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;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="50%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Qualified object name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</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>
&nbsp;&nbsp;Service Program Name: QPMAAPI<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Management Collection Object Attributes (QpmRtvMgtcolAttrs) API
returns information about attributes of a management collection object and
repositories of a management collection object.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*EXCLUDE</dd>
<dt><em>Authority to library containing collection object</em></dt>
<dd>*EXECUTE</dd>
</dl>
<p>While retrieving attributes, this API places a *SHRRD lock on the management
collection object.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>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.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>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.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information returned in the receiver variable
for a specified management collection object. The possible format names
are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em><a href="#HDRMCOA0100FMT">
MCOA0100</a></em></td>
<td align="left" valign="top">Retrieve attributes of a management collection
object only</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#HDRMCOA0200FMT">
MCOA0200</a></em></td>
<td align="left" valign="top">Retrieve attributes of a management collection
object and attributes of repositories of an object</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Qualified object name</strong></dt>
<dd>INPUT; CHAR(20)
<p>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.</p>
<p>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.</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="HDRMCOA0100FMT">MCOA0100 Format</a></h3>
<p>The following information is returned for the MCOA0100 format. For detailed
descriptions of the fields in the table, see <a href="#HDRDESC">Field
Descriptions</a>.</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 returned</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">Bytes available</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">Object size</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Object retention period</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Default collection interval</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of repositories</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(14)</td>
<td align="left" valign="top">Date and time when object was created</td>
</tr>
<tr>
<td align="center" valign="top">42</td>
<td align="center" valign="top">2A</td>
<td align="left" valign="top">CHAR(14)</td>
<td align="left" valign="top">Date and time of last update to the object</td>
</tr>
<tr>
<td align="center" valign="top">56</td>
<td align="center" valign="top">38</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Partition serial number</td>
</tr>
<tr>
<td align="center" valign="top">66</td>
<td align="center" valign="top">42</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Object is active</td>
</tr>
<tr>
<td align="center" valign="top">67</td>
<td align="center" valign="top">43</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Object was repaired</td>
</tr>
<tr>
<td align="center" valign="top">68</td>
<td align="center" valign="top">44</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Summarization status</td>
</tr>
<tr>
<td align="center" valign="top">69</td>
<td align="center" valign="top">45</td>
<td align="left" valign="top">CHAR(3)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRMCOA0200FMT">MCOA0200 Format</a></h3>
<p>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 <a href="#HDRREPENT">repository entries</a>, 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 <a href="#HDRDESC">Field Descriptions</a>.</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%">&nbsp;</td>
<td align="left" valign="top" width="60%">Everything from MCOA0100 format</td>
</tr>
<tr>
<td align="center" valign="top">72</td>
<td align="center" valign="top">48</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of repository entries returned</td>
</tr>
<tr>
<td align="center" valign="top">76</td>
<td align="center" valign="top">4C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to repository information</td>
</tr>
<tr>
<td align="center" valign="top">80</td>
<td align="center" valign="top">50</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Repository information</td>
</tr>
<tr>
<td align="center" valign="top">80</td>
<td align="center" valign="top">50</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to repository entry 1</td>
</tr>
<tr>
<td align="center" valign="top">84</td>
<td align="center" valign="top">54</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of repository entry 1</td>
</tr>
<tr>
<td align="center" valign="top">88</td>
<td align="center" valign="top">58</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to repository entry 2</td>
</tr>
<tr>
<td align="center" valign="top">92</td>
<td align="center" valign="top">5C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of repository entry 2</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">...</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Repository entry 1</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Repository entry 2</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">...</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRREPENT">Repository entry</a></h3>
<p>Each repository entry contains attributes of one repository of a management
collection object. It includes one or more <a href="#HDRCOLPERENT">collection
period entries</a>, described later.</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%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Repository name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Category name</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of collection period entries</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(8)</td>
<td align="left" valign="top">Repository size</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Collection period entry 1</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRCOLPERENT">Collection period entry</a></h3>
<p>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.</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%">Length of collection period
entry</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(14)</td>
<td align="left" valign="top">Date and time of collection period start</td>
</tr>
<tr>
<td align="center" valign="top">18</td>
<td align="center" valign="top">12</td>
<td align="left" valign="top">CHAR(14)</td>
<td align="left" valign="top">Date and time of collection period end</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Collection interval</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRDESC">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The length of all the data available to
return. All available data is returned if the receiver variable has sufficient
length.</p>
<p><strong>Bytes returned.</strong> The length of the data actually
returned.</p>
<p><strong>Category name.</strong> The name of the performance collection
category that created this repository.</p>
<p><strong>Collection interval.</strong> 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).</p>
<p><strong>Date and time of collection period end.</strong> 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:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>YYYY</em></td>
<td align="left" valign="top">Year</td>
</tr>
<tr>
<td align="left" valign="top"><em>MM</em></td>
<td align="left" valign="top">Month</td>
</tr>
<tr>
<td align="left" valign="top"><em>DD</em></td>
<td align="left" valign="top">Day of the month</td>
</tr>
<tr>
<td align="left" valign="top"><em>HH</em></td>
<td align="left" valign="top">Hour</td>
</tr>
<tr>
<td align="left" valign="top"><em>MM</em></td>
<td align="left" valign="top">Minute</td>
</tr>
<tr>
<td align="left" valign="top"><em>SS</em></td>
<td align="left" valign="top">Second</td>
</tr>
</table>
<p>This field reports blanks for collection periods that are in progress.</p>
<p><strong>Date and time of collection period start.</strong> 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.</p>
<p><strong>Date and time when object was created.</strong> 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.</p>
<p><strong>Date and time of last update to the object.</strong> 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.</p>
<p><strong>Default collection interval.</strong> The default collection
interval in seconds for this collection object. Individual performance
categories may have different collection intervals.</p>
<p><strong>Length of collection period entry.</strong> The length of a
collection period entry, in bytes.</p>
<p><strong>Length of repository entry.</strong> 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.</p>
<p><strong>Number of collection period entries.</strong> 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.</p>
<p><strong>Number of repositories.</strong> The number of repositories found in
this management collection object.</p>
<p><strong>Number of repository entries returned.</strong> 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.</p>
<p><strong>Object is active.</strong> Whether collection is currently in
progress for this collection object. Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Collection into this collection object has
ended</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Collection into this collection object is in
progress</td>
</tr>
</table>
<p><strong>Object retention period.</strong> 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.</p>
<p><strong>Object size.</strong> The size of the management collection object
in Kbytes (K = 1024).</p>
<p><strong>Object was repaired.</strong> 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:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Collection object did not require repair</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Collection object was repaired</td>
</tr>
</table>
<p><strong>Offset to repository information.</strong> The offset in bytes from
the beginning of a receiver variable to the beginning of a repository
information structure.</p>
<p><strong>Offset to repository entry.</strong> The offset in bytes from the
beginning of a receiver variable to the beginning of a particular repository
entry.</p>
<p><strong>Partition serial number.</strong> The logical serial number of a
system partition where the collection object was created.</p>
<p><strong>Repository information.</strong> 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.</p>
<p><strong>Repository name.</strong> The 10-character name of a repository of a
management collection object.</p>
<p><strong>Repository size.</strong> The size of a repository in Kbytes
(K = 1024).</p>
<p><strong>Reserved.</strong> A reserved field.</p>
<p><strong>Summarization status.</strong> 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:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Summarization was not performed for this
collection object</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Summarization is complete</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Summarization is in progress</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Summarization was attempted but failed</td>
</tr>
</table>
<br>
<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">CPF0A2B E</td>
<td align="left" valign="top">Not able to process management collection object
&amp;1 in library &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2105 E</td>
<td align="left" valign="top">Object &amp;1 in &amp;2 type &amp;3 not
found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2110 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2114 E</td>
<td align="left" valign="top">Cannot allocate object &amp;1 in &amp;2 type
*&amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2207 E</td>
<td align="left" valign="top">Not authorized to use object &amp;1 in library
&amp;3 type *&amp;2.</td>
</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">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not
valid.</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 &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</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>