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

547 lines
16 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>Work with Collector (QPMWKCOL) 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. -->
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File edited for tagging cleanup Oct 2001 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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Work with Collector (QPMWKCOL) API</h2>
<div class="box" style="width: 65%;">
<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%">Type of action to perform</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Type of resource</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Time between collections</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Qualified user space 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">First sequence number</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</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;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#usage">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Work with Collector (QPMWKCOL) API starts, ends, or changes the
collection of performance data for a particular resource on your system. The
performance collector used by the API has the following attributes:</p>
<ul>
<li>It collects data for user-specified resource types that can include job,
pool, disk, input/output processor (IOP), and communications.<br>
<br>
</li>
<li>It collects data at time intervals ranging from 15 seconds to four
minutes.<br>
<br>
</li>
<li>It deposits the collected data into user spaces.<br>
<br>
</li>
<li>Multiple users can collect data at the same time.<br>
<br>
</li>
<li>The same resource type data can be collected by different users with the
same or different interval lengths.<br>
<br>
</li>
<li>Different resources can be collected at different interval times.<br>
<br>
</li>
<li>It will collect data until all collections have been explicitly ended or
all of the user's jobs have ended.<br>
<br>
</li>
<li>It does not calculate deltas on the data collected. For more information on
deltas, see the <a href="QPMLPFRD.htm">List Performance Data</a> (QPMLPFRD)
API.<br>
<br>
</li>
<li>It will report job data for a job or task that is active when the data is
collected. A job or task that terminates during an interval will no longer be
reported.<br>
<br>
</li>
<li>Its intent is to provide performance data useful for real-time monitoring
of system performance. Thus, it will not support all of the counters that
collection services supports. It is not intended to be used in place of
collection services for detailed performance analysis, capacity planning, and
other such functions.</li>
</ul>
<p>When the first user of the collector issues a call to the QPMWKCOL API, two
jobs (QPMASERV and QPMACLCT) are submitted to batch. QPMASERV acts as a server,
communicating between the APIs (QPMWKCOL and QPMLPFRD) and the QPMACLCT job,
which does the actual data collection. These jobs run at priority 0 in
subsystem QSYSWRK. No matter how many users are collecting data, there will
only be one instance of each job running. The programs will continue to run
until all users have ended all of their collections. They will also end if none
of the users' jobs are still active.</p>
<p>To start a data collection for a resource, call the QPMWKCOL API using the
following:</p>
<ul>
<li>The value *START for the type of action to perform parameter<br>
<br>
</li>
<li>The type of resource data to collect (job, pool, disk, input/output
processor (IOP), or communications)<br>
<br>
</li>
<li>The length of time between collections (15, 30, 60, 120, or 240
seconds)<br>
<br>
</li>
<li>The name and library of the user space the data should be copied into. The user space must be created in the
system ASP or in a basic ASP and not in an independent ASP. This ensures that
the server job QPMASERV, which processes the API request, can access the user
space.<br>
<br>
</li>
<li>The error code parameter</li>
</ul>
<p>A separate request must be made for each resource desired. When the request
is valid, the sequence number of the first collection will be passed back to
the user. The sequence number is increased by the user-specified interval time
and can be used to see if an interval collection was missed. For example, if 15
is the first sequence number received back from the QPMWKCOL API but 30 is the
sequence number received back from the List Performance Data (QPMLPFRD) API,
you missed the collection of data with a sequence number of 15.</p>
<p>By using *CHANGE for the type of action to perform parameter, the interval
time or the user space for a resource can be changed.</p>
<p>To end a collection, use *END for the type of action to perform parameter.
Because a collection will continue to be active until it is ended, it is
important that any collections that are no longer needed be ended. If an *END
request is from the last user of a resource, data collection of the resource
stops. If not, the resource will still be collected, but this user will no
longer have access to data until a *START request is issued again. After the
last user of the collector ends all of his collections, the collector jobs
(QPMASERV and QPMACLCT) end.</p>
<p>Because QPMWKCOL works with the QPMLPFRD API, the parameters selected for
QPMWKCOL will affect QPMLPFRD. For example, the interval time selected
determines how often QPMLPFRD should be called. Because the new data replaces
old data, if QPMLPFRD is not called before the next interval is collected, the
data from the previous interval will be lost, although the deltas may still be
calculated for the longer interval. The qualified user space is also an
important parameter to QPMLPFRD because this is the space that QPMLPFRD will
copy the performance data into. If the space is not large enough to hold all
the data or if the space is locked, an error message will be issued to the
user.</p>
<p>Starting in Version 5 Release 1, performance data is collected by the
performance data collector used by collection services. This has the following
implications:</p>
<ul>
<li>The collection services performance data collector (QYPSPFRCOL) job runs in
addition to the QPMASERV and QPMACLCT jobs.<br>
<br>
</li>
<li>Performance data is stored in the management collection (*MGTCOL) object,
allowing it to be processed by the create performance data (CRTPFRDTA)
command.<br>
<br>
</li>
<li>The collection services performance data collector supports data collection
at one-minute intervals, but not at two- or four-minute intervals. Therefore,
when the API user requests data at two- or four-minute intervals, the data will
be collected at one-minute intervals, but reported back to the user every two
or four minutes.</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>User Space Authority</em></dt>
<dd>*CHANGE</dd>
<dt><em>Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>User Space Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Type of action to perform</strong></dt>
<dd>INPUT; CHAR(10)
<p>Whether you want to start, end, or change the collection of a resource. The
following values may be specified:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*START</em></td>
<td align="left" valign="top">Start the collection of the specified
resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*END</em></td>
<td align="left" valign="top">End the collection of the specified
resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CHANGE</em></td>
<td align="left" valign="top">Change the collection of the specified
resource.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Type of resource</strong></dt>
<dd>INPUT; CHAR(10)
<p>The type of resource to start, end, or change. The following values may be
specified.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*JOB</em></td>
<td align="left" valign="top">Job-related information</td>
</tr>
<tr>
<td align="left" valign="top"><em>*POOL</em></td>
<td align="left" valign="top">Pool-related information</td>
</tr>
<tr>
<td align="left" valign="top"><em>*DISK</em></td>
<td align="left" valign="top">Disk-related information</td>
</tr>
<tr>
<td align="left" valign="top"><em>*IOP</em></td>
<td align="left" valign="top">IOP-related information</td>
</tr>
<tr>
<td align="left" valign="top"><em>*COMM</em></td>
<td align="left" valign="top">Communications-related information</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Time between collections</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of seconds between each new collection of data. The following
values may be specified.</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>15</em></td>
<td align="left" valign="top">Collect every 15 seconds.</td>
</tr>
<tr>
<td align="left" valign="top"><em>30</em></td>
<td align="left" valign="top">Collect every 30 seconds.</td>
</tr>
<tr>
<td align="left" valign="top"><em>60</em></td>
<td align="left" valign="top">Collect every 60 seconds.</td>
</tr>
<tr>
<td align="left" valign="top"><em>120</em></td>
<td align="left" valign="top">Collect every 120 seconds (2 minutes).</td>
</tr>
<tr>
<td align="left" valign="top"><em>240</em></td>
<td align="left" valign="top">Collect every 240 seconds (4 minutes).</td>
</tr>
</table>
<p><strong>Notes:</strong></p>
<ol>
<li>The disk- and IOP-related data require a minimum of 30 seconds between
collections.<br>
<br>
</li>
<li>The communication-related data requires a minimum of 60 seconds between
collections.<br>
<br>
</li>
<li>The jobs-related data should be collected as infrequently as possible to
minimize the impact on system performance.</li>
</ol>
<br>
</dd>
<dt><strong>Qualified user space name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the user space that is to receive the data for this type of
resource. The first 10 characters contain the user space name, and the second
10 characters contain the name of the library where the user space is located.
The user space must be created in
the system ASP or in a basic ASP and not in an independent ASP. This ensures
that the server job QPMASERV, which processes the API request, can access the
user space. The special values for
the library name are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">Library list is used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">Current library is used.</td>
</tr>
</table>
<p>The library name value is resolved when this API is called. If no library is
specified as the current library for the job, QGPL is used. Both entries are
left-justified.</p>
</dd>
<dt><strong>First sequence number</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The sequence number of the first data collection that will be available for
the user.</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="usage">Usage Notes</a></h3>
<p>The QPMWKCOL API has been classified as conditionally threadsafe. This
classification is the result of a dependency on the Submit Job (SBMJOB)
command, which has been classified conditionally threadsafe. Refer to the
SBMJOB command in the <a href="../rbam6/rbam6clmain.htm">Control Language</a>
information for restrictions.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top" width="15%">CPF0A37 E</td>
<td align="left" valign="top" width="85%">Request type &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A38 E</td>
<td align="left" valign="top">Resource type &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A39 E</td>
<td align="left" valign="top">Interval time of &amp;1 seconds not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A40 E</td>
<td align="left" valign="top">Interval time of &amp;1 seconds for IOP data not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A41 E</td>
<td align="left" valign="top">&amp;1 seconds for communications data not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A42 E</td>
<td align="left" valign="top">Collector ended abnormally.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A44 E</td>
<td align="left" valign="top">Collection not active for user.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A45 E</td>
<td align="left" valign="top">Cannot copy data to user space &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A46 E</td>
<td align="left" valign="top">Interval time of &amp;1 seconds for disk data not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0A47 E</td>
<td align="left" valign="top">User space &amp;1 in lib &amp;2 not large
enough.</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">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</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">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R3
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<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>