547 lines
16 KiB
HTML
547 lines
16 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>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>
|
|
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>
|
|
Default Public Authority: *EXCLUDE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
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 &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF0A38 E</td>
|
|
<td align="left" valign="top">Resource type &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF0A39 E</td>
|
|
<td align="left" valign="top">Interval time of &1 seconds not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF0A40 E</td>
|
|
<td align="left" valign="top">Interval time of &1 seconds for IOP data not
|
|
valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF0A41 E</td>
|
|
<td align="left" valign="top">&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 &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF0A46 E</td>
|
|
<td align="left" valign="top">Interval time of &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 &1 in lib &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 &1 in library
|
|
&2 ended. Reason code &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>
|
|
|