friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qyperpex.htm

757 lines
20 KiB
HTML
Raw Permalink Normal View History

Add readme and dist folders
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 PEX Information (QYPERPEX) 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. -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- 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>Retrieve PEX Information (QYPERPEX, qypeRetrievePexInfo) API</h2>
<div class="box" style="width: 80%;">
<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">PEX session name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</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: QYPESVPG<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve PEX Information (QypeRetrievePexInformation) API retrieves information about a PEX session. It can be used to retrieve the following:</p>
<ul>
<li>Session name</li>
<li>Collection type</li>
<li>State</li>
<li>State qualifier</li>
<li>Event count</li>
<li>Filtered event count</li>
<li>Start complete time</li>
<li>Resume time</li>
<li>Storage used</li>
<li>Qualified job name of the job that created the session</li>
<li>Definition name</li>
<li>Filter name</li>
<li>Sampling interval</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<p>None</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The variable that is to receive the information requested. The minimum size
for this area is 8 bytes. You can specify the size of this area to be smaller
than the format requested if you specify the length of receiver variable
parameter correctly. As a result, the API returns only the data that the area
can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable. If this value is larger than the actual
size of the receiver variable, the results may not be predictable. The minimum
value is 8.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information returned for the PEX session.</p>
<p>The possible format names are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em><a href="#PEXI0100">PEXI0100</a></em></td>
<td align="left" valign="top">Basic information about the PEX session.</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#PEXI0200">PEXI0200</a></em></td>
<td align="left" valign="top">Detailed information about the PEX session.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>PEX session name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of a PEX session. Special values supported:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ALL</em></td>
<td align="left" valign="top">All PEX sessions.</td>
</tr>
</table>
<br>
</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="XXXX">Header section</a></h3>
For detailed descriptions of the fields in this table, see
<a href="#PEXFLDS">Field Descriptions</a>
<br><br>
<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(4)</td>
<td align="left" valign="top">Offset to first entry</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of entries returned</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">Size of each entry</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 entries available</td>
</tr>
</table>
<br>
<h3><a name="PEXI0100">PEXI0100 Format</a></h3>
<p>The following information is returned for one entry with the PEXI0100 format. For detailed
descriptions of the fields in the table, see <a href="#PEXFLDS">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%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Session name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Collection type</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">State</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">State qualifier</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">Event count</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Filtered event count</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Start complete time</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Resume time</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Storage used</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Job name of the job that created the session</td>
</tr>
<tr>
<td align="center" valign="top">62</td>
<td align="center" valign="top">3E</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User name of the job that created the session</td>
</tr>
<tr>
<td align="center" valign="top">72</td>
<td align="center" valign="top">48</td>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Job number of the job that created the session</td>
</tr>
</table>
<h3><a name="PEXI0200">PEXI0200 Format</a></h3>
<p>The following information is returned for one entry with the PEXI0200 format. For detailed
descriptions of the fields in the table, see <a href="#PEXFLDS">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%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Session name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Collection type</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">State</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">State qualifier</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">Event count</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Filtered event count</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Start complete time</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Resume time</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Storage used</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Job name of the job that created the session</td>
</tr>
<tr>
<td align="center" valign="top">62</td>
<td align="center" valign="top">3E</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User name of the job that created the session</td>
</tr>
<tr>
<td align="center" valign="top">72</td>
<td align="center" valign="top">48</td>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Job number of the job that created the session</td>
</tr>
<tr>
<td align="center" valign="top">82</td>
<td align="center" valign="top">52</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Definition name</td>
</tr>
<tr>
<td align="center" valign="top">92</td>
<td align="center" valign="top">5C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Filter name</td>
</tr>
<tr>
<td align="center" valign="top">102</td>
<td align="center" valign="top">5C</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">104</td>
<td align="center" valign="top">5E</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Sampling interval</td>
</tr>
</table>
<br>
<br>
<h3><a name="#PEXFLDS">Field Descriptions</a></h3>
<p><strong>Bytes available. </strong>Number of bytes available to be returned by the API.
If this value is larger than the bytes returned it means that the API had more information to return than the receiver variable could hold.
</p>
<p><strong>Bytes returned. </strong> Number of bytes returned by the API and placed in the receiver variable.
If this value is smaller than the bytes available, it means that the API had more information to return than the receiver variable could hold.
</p>
<p><strong>Collection type.</strong> Indicates type of data being collected in the PEX session.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Trace.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Stats.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Stats hierarchical.</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">Profile.</td>
</tr>
</table>
<p><strong>Definition name. </strong>Name of definition used by the session.
</p>
<p><strong>Event count. </strong> Number of events in the session.</p>
<p><strong>Filter name. </strong>Name of filter used by the session. This field will contain a value if a valid filter name was specified with the FTR keyword of the STRPEX command. If no filter name was specified in STRPEX, this field will be all blanks.
</p>
<p><strong>Filtered event count. </strong>Number of filtered events in the session. A filtered event is one that is not collected. It is filtered out based on specifications supplied in the Add Pex Filter (ADDPEXFTR) command. </p>
<p><strong>Job name of the job that created the session. </strong>
The name of the job that did the STRPEX command to start the session.
</p>
<p><strong>Job number of the job that created the session. </strong>
The system-assigned number of the job that did the STRPEX command to start the session.
</p>
<p><strong>Number of entries available. </strong> Number of fixed-length entries that were available to be returned to the caller of the API, given sufficient space in the receiver variable. If this value is larger than the number of entries returned, it means that the API had more information to return than the receiver variable could hold.
</p>
<p><strong>Number of entries returned. </strong>The number of fixed-length entries following the header section. If this value is smaller than the number of entries available, it means that the API had more information to return than the receiver variable could hold.
</p>
<p><strong>Offset to first entry. </strong>The offset, in bytes, from the start of the header section to the beginning of the actual data returned by the API.
</p>
<p><strong>Reserved. </strong>An ignored field.
</p>
<p><strong>Resume time. </strong>
Time (in 8 byte time of day format) that the session was resumed, if STRPEX OPTION(*RESUME) was used. If STRPEX (*RESUME) was not used, this field will be set to x'00' (nulls).
</p>
<p><strong>Sampling interval. </strong>Size of sampling interval in milliseconds. This field will contain a value if a sampling interval was specified with the INTERVAL keyword of the ADDPEXDFN command for the PEX definition used by this session.
</p>
<p><strong>Session name. </strong>The name of the PEX session. </p>
<p><strong>Size of each entry. </strong>The size in bytes of each fixed-length entry following the header section.
</p>
<p><strong>Start complete time. </strong>
Time (in 8 byte time of day format) that the session completed its start activity.
</p>
<p><strong>State. </strong> Specifies the internal state of the session.
</p>
<p>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">Created</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Active</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Suspended</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Deleted</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Stopped</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td align="left" valign="top">Stopping (stop pending)</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">Starting</td>
</tr>
</table>
<p><strong>State qualifier. </strong> Specifies additional details about the state of the session.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Normal(normal)</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Wrapped (normal)</td>
</tr>
<tr>
<td align="left" valign="top"><em>4096</em></td>
<td align="left" valign="top">Storage limit reached (limit)</td>
</tr>
<tr>
<td align="left" valign="top"><em>4098</em></td>
<td align="left" valign="top">ASP storage limit reached (limit)</td>
</tr>
<tr>
<td align="left" valign="top"><em>4099</em></td>
<td align="left" valign="top">User profile storage limit reached (limit)</td>
</tr>
<tr>
<td align="left" valign="top"><em>4100</em></td>
<td align="left" valign="top">Byte stream file storage limit reached (limit) </td>
</tr>
<tr>
<td align="left" valign="top"><em>8193</em></td>
<td align="left" valign="top">Internal error (error)</td>
</tr>
<tr>
<td align="left" valign="top"><em>8194</em></td>
<td align="left" valign="top">Damage encountered (error)</td>
</tr>
</table>
<p><strong>Storage used. </strong>Number of bytes of storage used by the session.
</p>
<p><strong>User name of the job that created the session. </strong>
The user name of the job that did the STRPEX command to start the session.
</p>
<h3>Error messages:</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPFAF04 E</td>
<td align="left" valign="top">Session &amp;1 is not active.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1E E</td>
<td align="left" valign="top">Required parameter &amp;1 omitted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3C E</td>
<td align="left" valign="top">Value for parameter &amp;1 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>
</table>
<br>
<hr>
API introduced: V5R3
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="qyperpex.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>
Reference in New Issue Copy Permalink