540 lines
20 KiB
HTML
540 lines
20 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>Collection Services Data Collection Exit Program</title>
|
|
<!-- 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. -->
|
|
<!-- Begin Header Records -->
|
|
<!-- Created for V5R2 -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>Collection Services Data
|
|
Collection Exit Program</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<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%">Collection request parameters</td>
|
|
<td align="left" valign="top" width="20%">I/O</td>
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Data buffer</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Work area</td>
|
|
<td align="left" valign="top">I/O</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Return code</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
QSYSINC member name: QPMDCPRM<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>A Collection Services Data Collection exit program is called by Collection
|
|
Services to collect performance data for a user-defined performance category.
|
|
The Collection Services collector will store this data in the management
|
|
collection object. For the exit program to be called by the collector, it must
|
|
first be registered using the <a href="qypsregcoll.htm">Register Collector Data
|
|
Category (QypsRegCollectorDataCategory) API</a>. User-defined performance data
|
|
that is stored in the management collection object can be read using the <a href=
|
|
"qpmreadmgtcoldata.htm">Read Management Collection Object Data
|
|
(QpmReadMgtcolData) API</a>.</p>
|
|
|
|
<p>At the time a user-defined category is registered, a single entry point is
|
|
specified for the data collection program. This entry point can be a program
|
|
object (*PGM) or an entry point in a service program (*SRVPGM).</p>
|
|
|
|
<p>Collection Services calls this entry point with parameters which specify the
|
|
type of request to perform and the control information necessary for the data
|
|
collection program to complete the request.</p>
|
|
|
|
<p>Collection Services provides a data buffer where the data collection program
|
|
will return collected data.</p>
|
|
|
|
<p>Collection Services also provides a work area which can be used by the data
|
|
collection program to save its state between the calls.</p>
|
|
|
|
<p>The parameter structure passed to the data collection program is mapped by
|
|
the QPMDCPRM header file shipped with the system in the QSYSINC library.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
|
|
<!-- Instead, use the commented out coding below to indicate NONE. -->
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<!-- Use this if there are no authorities and locks. -->
|
|
<p>None.</p>
|
|
|
|
<br>
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Collection request parameters</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>This is a structure in which Collection Services passes control information
|
|
about the data collection request to the data collection program. The data
|
|
collection program uses this structure to return information about actions
|
|
performed. The format of the data in this structure is determined by the
|
|
parameter format specified when the user-defined category was registered using
|
|
the Register Collector Data Category (QypsRegCollectorDataCategory) API.
|
|
Currently, PMDC0100 is the only format supported. The layout of this structure
|
|
is described in <a href="#HDRCOLREQ">Layout of Collection Request Structure</a>
|
|
below.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Data buffer</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>This is a data buffer in which the data collection program returns data to
|
|
be stored in the management collection object. Collection Services will store
|
|
this data in a record of the repository of the management collection
|
|
object.</p>
|
|
|
|
<p>For start collection and end collection requests, this is control data and
|
|
will be stored in a collection control record. For interval collection request,
|
|
this is collected performance data and will be stored in an interval
|
|
record.</p>
|
|
|
|
<p>The length of this buffer is defined in the data buffer bytes available
|
|
field of the collection request parameters structure. Writing to the data
|
|
buffer beyond this length will have unpredictable results.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Work area</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>The work area is a storage area created by Collection Services for the sole
|
|
use of the data collection program. Initially, the work area is set to zeroes.
|
|
The same work area is passed in every call to the data collection program. This
|
|
work area can be used by the data collection program to save some state
|
|
information between the calls. Collection Services will preserve the work area
|
|
contents between the calls. The length of the work area is set at category
|
|
registration time and is defined in the length of work area field of the
|
|
collection request.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Return code</strong></dt>
|
|
|
|
<dd>OUTPUT; BINARY(4)
|
|
|
|
<p>Return code set by the data collection program. Collection Services will
|
|
take an action based on the code returned from the data collection program. The
|
|
return code is ignored for the cleanup and terminate request. Possible return
|
|
codes and Collection Services actions:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Data collection request was performed
|
|
successfully.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>> 0</em></td>
|
|
<td align="left" valign="top">Data collection request encountered recoverable
|
|
errors. A non-zero return code will be logged in the job log. Action taken by
|
|
Collection Services depends on the collection request:
|
|
|
|
<ul>
|
|
<li>For start collection and end collection requests, Collection Services will
|
|
assume that no data can be collected for this category and data collection for
|
|
this category will be stopped.</li>
|
|
|
|
<li>For interval collection request, Collection Services will assume that
|
|
future requests may still be successful. No data will be stored for this
|
|
request. However, Collection Services will continue collecting data for this
|
|
category.</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>< 0</em></td>
|
|
<td align="left" valign="top">Data collection request encountered unrecoverable
|
|
errors. Collection Services will assume that no further data collection is
|
|
possible for this category and stop collecting data for this category. The data
|
|
collection program may use a negative return code to cause immediate
|
|
termination of data collection for the user-defined category.</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRCOLREQ">Layout of Collection Request Structure</a></h3>
|
|
|
|
<p>The layout of the collection request structure is determined by the
|
|
parameter format specified when the user-defined category was registered using
|
|
the Register Collector Data Category (QypsRegCollectorDataCategory) API.</p>
|
|
|
|
<p>Currently, PMDC0100 is the only format supported. The table below shows the
|
|
layout of the collection request structure for the PMDC0100 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">Input/Output</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="15%">INPUT</td>
|
|
<td align="left" valign="top" width="15%">CHAR(8)</td>
|
|
<td align="left" valign="top" width="50%">Format name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Category name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="center" valign="top">12</td>
|
|
<td align="left" valign="top">--</td>
|
|
<td align="left" valign="top">CHAR(2)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="center" valign="top">14</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Request type</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Request type modifier</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="center" valign="top">1C</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Data buffer bytes available</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Offset to category parameter string</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">36</td>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of category parameter string</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">40</td>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of work area</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">44</td>
|
|
<td align="center" valign="top">2C</td>
|
|
<td align="left" valign="top">--</td>
|
|
<td align="left" valign="top">CHAR(4)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">48</td>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">CHAR(8)</td>
|
|
<td align="left" valign="top">Interval key</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">56</td>
|
|
<td align="center" valign="top">38</td>
|
|
<td align="left" valign="top">INPUT</td>
|
|
<td align="left" valign="top">CHAR(8)</td>
|
|
<td align="left" valign="top">Interval time</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">64</td>
|
|
<td align="center" valign="top">40</td>
|
|
<td align="left" valign="top">OUTPUT</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Data buffer bytes provided</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">68</td>
|
|
<td align="center" valign="top">44</td>
|
|
<td align="left" valign="top">OUTPUT</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">More data indicator</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">72</td>
|
|
<td align="center" valign="top">48</td>
|
|
<td align="left" valign="top">--</td>
|
|
<td align="left" valign="top">CHAR(8)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRDESC">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Category name.</strong> Name of the user-defined category for which
|
|
data collection is performed. This name was registered previously uisng the
|
|
Register Collector Data Category (QypsRegCollectorDataCategory) API.</p>
|
|
|
|
<p><strong>Data buffer bytes available.</strong> Size of the data buffer passed
|
|
in the data buffer parameter.</p>
|
|
|
|
<p><strong>Data buffer bytes provided.</strong> The data collection program
|
|
indicates in this field how many bytes of data in the data buffer should be
|
|
stored by Collection Services in the repository of the management collection
|
|
object. If this field is set to 0 for start collection or end collection
|
|
requests, a collection control record will not be created. If this field is set
|
|
to 0 for an interval collection request, Collection Services will still create
|
|
an interval record but will not store any data in it. This field is set to zero
|
|
at entry to the data collection program.</p>
|
|
|
|
<p><strong>Format name.</strong> Name of the collection request structure
|
|
format passed to the data collection program. This is the parameter format
|
|
specified when the user-defined category was registered using the Register
|
|
Collector Data Category (QypsRegCollectorDataCategory) API. Currently, PMDC0100
|
|
is the only format supported.</p>
|
|
|
|
<p><strong>Interval key.</strong> Record key of the repository record about to
|
|
be written into the repository of the management collection object. 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 interval records, with the possible exception of the key of
|
|
the first interval record in a collection period, are normalized to the
|
|
collection interval boundary. For example, for a 15 minute collection interval,
|
|
valid record keys will be 00124500 or 00223000, but not 00131014.</p>
|
|
|
|
<p><strong>Interval time.</strong> Exact time in system timestamp format when
|
|
the Collection Services collector initiated a particular request. This time is
|
|
provided for reference only. Normally this time is close to the time implied by
|
|
the interval key field but, unlike the interval key, this time is not
|
|
normalized. See <a href="qwccvtdt.htm">Convert Date and Time Format (QWCCVTDT)
|
|
API</a> for details about time formats.</p>
|
|
|
|
<p><strong>Length of category parameter string.</strong> Length of the category
|
|
parameter string. If the parameter string was not registered for this category,
|
|
this field is set to 0.</p>
|
|
|
|
<p><strong>Length of work area.</strong> Length of the work area passed in the
|
|
work area parameter. The size of the work area is set during category
|
|
registration.</p>
|
|
|
|
<p><strong>More data indicator.</strong> By setting this field to a non-zero
|
|
value, the data collection program may indicate to Collection Services that it
|
|
has more data to store in the repository of the management collection object
|
|
for this request. When this field is returned with a non-zero value, Collection
|
|
Services will transfer the returned data to the current repository record then
|
|
will call the data collection program again with all parameters identical to
|
|
the previous call except that the request type modifier field will be set to
|
|
20. The data collection program may use the more data indicator field as many
|
|
times as needed to transfer all collected data to Collection Services. This
|
|
field is set to zero at entry to the data collection program.</p>
|
|
|
|
<p><strong>Offset to category parameter string.</strong> Offset in bytes to the
|
|
category parameter string starting from the beginning of the collection
|
|
request. This parameter string was specified when the user-defined category was
|
|
registered using the Register Collector Data Category
|
|
(QypsRegCollectorDataCategory) API. The parameter string can be used to pass
|
|
customization information to the data collection program. The length of this
|
|
string is defined in the length of category parameter string field. If a
|
|
parameter string was not registered for this category, this field is set to 0.
|
|
The parameter string is only passed when the request type is set to 10 - start
|
|
collection request.</p>
|
|
|
|
<p><strong>Request type.</strong> Type of action requested from the data
|
|
collection program. The data collection program must support the following
|
|
request types:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="10 90" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>10</em></td>
|
|
<td align="left" valign="top"><em>Start collection request.</em> This is the
|
|
first request that the data collection program will receive in a data
|
|
collection session. When receiving this request, the data collection program is
|
|
expected to initialize whatever interfaces it uses to collect the data.
|
|
Optionally, in the provided data buffer, the data collection program may return
|
|
collection control information to be stored in a collection control record in
|
|
the repository of the management collection object.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>20</em></td>
|
|
<td align="left" valign="top"><em>End collection request.</em> This is the last
|
|
request the data collection program will receive in a data collection session.
|
|
When receiving this request, the data collection program is expected to close
|
|
whatever interfaces it uses to collect the data, release resources, and so on.
|
|
Optionally, in the provided data buffer, the data collection program may return
|
|
collection control information to be stored in a collection control record in
|
|
the repository of the management collection object.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>30</em></td>
|
|
<td align="left" valign="top"><em>Interval collection request.</em> The data
|
|
collection program will receive a request of this type each time the interval
|
|
collection for this user-defined category is scheduled. The time between
|
|
interval collection requests is specified at category registration time. When
|
|
receiving this request, the data collection program is expected to perform its
|
|
regular collection of performance data and return collected data in the
|
|
provided data buffer. This data will be stored in an interval record in the
|
|
repository of the management collection object.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>40</em></td>
|
|
<td align="left" valign="top"><em>Cleanup and terminate (shutdown)
|
|
request.</em> This request is sent to the data collection program when
|
|
Collection Services cannot continue data collection. An example of such a
|
|
problem is the loss of contact with the Collection Services collector job. When
|
|
receiving this request, the data collection program is expected to perform
|
|
necessary cleanup, release resources, and so on. The data collection program cannot
|
|
return any data for this request. Any data placed in the data buffer will be
|
|
ignored.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Request type modifier.</strong> This field modifies the meaning of
|
|
the request type field. This field can have two values:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="10 90" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>10</em></td>
|
|
<td align="left" valign="top">Normal request to collect data.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>20</em></td>
|
|
<td align="left" valign="top">Continuation of the previous request. This value
|
|
is used to indicate to the data collection program that this is the
|
|
continuation of the same collection request. When the data collection program
|
|
returns with the more data indicator set to a non-zero value, Collection
|
|
Services will transfer the returned data to the current repository record then
|
|
will call the data collection program again with the same parameters except
|
|
that the request type modifier field will be set to 20. In this way, the data
|
|
collection program may store more collected data in the management collection
|
|
object than fits into the data buffer.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<hr>
|
|
API introduced: V5R2
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="qypscsca.htm">Top</a> | <a href=
|
|
"perfmgmt.htm">Performance Management APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|