145 lines
9.4 KiB
HTML
145 lines
9.4 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="security" content="public" />
|
||
|
|
<meta name="Robots" content="index,follow" />
|
||
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
|
<meta name="DC.Type" content="concept" />
|
||
|
|
<meta name="DC.Title" content="Collection program recommendations and requirements" />
|
||
|
|
<meta name="abstract" content="Collection Services calls the data collection program once during the start of a collection cycle, once for each collection interval, and again at the end of the collection cycle." />
|
||
|
|
<meta name="description" content="Collection Services calls the data collection program once during the start of a collection cycle, once for each collection interval, and again at the end of the collection cycle." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rzahxcollservuserdef.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rzahxcolluserdefexdatacoll.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="rzahxcolluserdefprog" />
|
||
|
|
<meta name="DC.Language" content="en-us" />
|
||
|
|
<!-- 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. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>Collection program recommendations and requirements</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzahxcolluserdefprog"><a name="rzahxcolluserdefprog"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Collection program recommendations and requirements</h1>
|
||
|
|
<div><p>Collection Services calls the data collection program once during
|
||
|
|
the start of a collection cycle, once for each collection interval, and again
|
||
|
|
at the end of the collection cycle.</p>
|
||
|
|
<p>The data collection program must perform any data collection and return
|
||
|
|
that data to a data buffer provided by Collection Services. In addition to
|
||
|
|
providing a data buffer, Collection Services also provides a work area, which
|
||
|
|
allows the data collection program to maintain some state information between
|
||
|
|
collection intervals.</p>
|
||
|
|
<p>The data collection program should collect data as quickly as possible
|
||
|
|
and should perform minimal formatting. The program should not perform any
|
||
|
|
data processing or sorting. Although data from the user-defined category is
|
||
|
|
not converted into database files, Collection Services may run the <span class="cmdname">Create
|
||
|
|
Performance Data (CRTPFRDTA)</span> command automatically and add the data
|
||
|
|
from the collection object to database files at the end of each collection
|
||
|
|
interval. If the data collection program cannot complete its tasks within
|
||
|
|
the collection interval, the CRTPFRDTA command does not run properly.</p>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> By using the code examples, you agree to the terms of the <a href="codedisclaimer.htm">Code license and disclaimer information</a>.</div>
|
||
|
|
<p>You may create the data collection program in several environments:</p>
|
||
|
|
<ul><li>*PGM for OPM languages. This environment may not be used to query the
|
||
|
|
collection object and may result in poor performance. However, it is supported
|
||
|
|
for older programming languages.</li>
|
||
|
|
<li>*SRVPGM, an entry point in a service program. This is for ILE languages.</li>
|
||
|
|
<li>*JVAPGM, the required Java™ classes are included in ColSrv.jar.
|
||
|
|
This file is included in the IFS at QIBM/ProdData/OS400/CollectionServices/lib.
|
||
|
|
Download the <a href="javadoc.zip">javadocs.zip</a> file
|
||
|
|
and open index.html for a description of the Java implementations of the APIs.</li>
|
||
|
|
</ul>
|
||
|
|
<p>Collection Services sends the following requests to the data collection
|
||
|
|
program:</p>
|
||
|
|
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><thead align="left"><tr><th valign="top" width="20%" id="d0e53">Request</th>
|
||
|
|
<th valign="top" width="80%" id="d0e55">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td valign="top" width="20%" headers="d0e53 ">Start collection</td>
|
||
|
|
<td valign="top" width="80%" headers="d0e55 ">The data collection program should initialize any interfaces or resources
|
||
|
|
used during data collection. Optionally, it may also initialize a work area,
|
||
|
|
provided by Collection Services, that preserves state information between
|
||
|
|
collection intervals. If you want to include a control record prior to the
|
||
|
|
collected data, the data collection program may also write a small amount
|
||
|
|
of data to the data buffer. Typically, this control record would be used during
|
||
|
|
data processing to help interpret the data.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="20%" headers="d0e53 ">Collection interval</td>
|
||
|
|
<td valign="top" width="80%" headers="d0e55 ">Collection Services sends an interval request for each collection interval.
|
||
|
|
The data collection program should collect data and return it in the data
|
||
|
|
buffer. Collection Services then writes that data to the interval record in
|
||
|
|
the collection object. If the amount of data is too large for the data buffer,
|
||
|
|
the data collection program should set a "More data" flag. This action causes
|
||
|
|
Collection Services to send another interval request with a modifier indicating
|
||
|
|
that it is a continuation. Collection Services resets the more data flag before
|
||
|
|
each call. This process is repeated until all the data is moved into the collection
|
||
|
|
object.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="20%" headers="d0e53 ">End of collection</td>
|
||
|
|
<td valign="top" width="80%" headers="d0e55 ">When the collection for the category containing the data collection
|
||
|
|
program ends, Collection Services sends this request. The data collection
|
||
|
|
program should perform any cleanup and can optionally return a collection
|
||
|
|
control record. The data collection program should also send a return code
|
||
|
|
that indicates the result of the collection.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="20%" headers="d0e53 ">Clean up and terminate (Shutdown)</td>
|
||
|
|
<td valign="top" width="80%" headers="d0e55 ">Collection Services sends this request if an abnormal termination is
|
||
|
|
necessary. Operating system resources are freed automatically when the data
|
||
|
|
collection program job ends, but any other shutdown operations should be performed
|
||
|
|
by the data collection program. The data collection program can receive this
|
||
|
|
request at any time.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<p>For a detailed description of these parameters, the work area, data buffer,
|
||
|
|
and return codes, refer to the header file QPMDCPRM, which is located in QSYSINC.</p>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Data storage in collection objects</h4><p>Collection objects
|
||
|
|
have a repository for each data collection category. This repository gets
|
||
|
|
created by Collection Services when collections for that category are started.
|
||
|
|
Each repository consists of the following records:</p>
|
||
|
|
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><thead align="left"><tr><th valign="top" width="20%" id="d0e91">Record</th>
|
||
|
|
<th valign="top" width="80%" id="d0e93">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td valign="top" width="20%" headers="d0e91 ">Control</td>
|
||
|
|
<td valign="top" width="80%" headers="d0e93 ">This optional record can be the first or last record that results from
|
||
|
|
the data collection program, and may occur in both positions. Typically, it
|
||
|
|
should contain any information needed to interpret the record data.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="20%" headers="d0e91 ">Interval</td>
|
||
|
|
<td valign="top" width="80%" headers="d0e93 ">Each collection interval creates an interval record, even if it is
|
||
|
|
empty. The interval record contains the data written to the data buffer during
|
||
|
|
the collection interval. It must not exceed 4 GB in size.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="20%" headers="d0e91 ">Stop</td>
|
||
|
|
<td valign="top" width="80%" headers="d0e93 ">Collection Services automatically creates this record to indicate the
|
||
|
|
end of a data collection session. If the collections for the user-defined
|
||
|
|
category were restarted without ending or cycling Collection Services, you
|
||
|
|
can optionally include a control record followed by additional interval records
|
||
|
|
after the stop record.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzahxcollservuserdef.htm" title="The user-defined categories function in Collection Services enables applications to integrate performance data collection into Collection Services.">User-defined categories in Collection Services</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relref"><strong>Related reference</strong><br />
|
||
|
|
<div><a href="rzahxcolluserdefexdatacoll.htm" title="This program example collects some test data and stores it in a data buffer, which Collection Services copy to the collection object.">Example: data collection program</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|