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

1603 lines
46 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>Retrieve Program Variable (QTERTVPV) 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. -->
<!-- DEBUG1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 29 Jan 1999 at 16:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited November 2001 -->
<!--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 Program Variable (QTERTVPV) API</h2>
<div class="box" style="width: 85%;">
<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">Program variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(132)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Basing pointer</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array(5) of Char(132)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Starting position</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Length of string</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Output format</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Program</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Recursion level</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">10</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: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Program Variable (QTERTVPV) API retrieves the current value of one program variable in a program that is being debugged. The information is returned to the calling program in a receiver variable. The amount of returned information is limited to the size of the receiver variable. This information is similar to the information returned using the Display Program Variable (DSPPGMVAR) command.</p>
<br>
<h3>Restriction</h3>
<p>This API is valid only in debug mode and supports original program model (OPM) programs only. It cannot be used if the user is servicing another job and that job is on a job queue, or is held, suspended, or ended.</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>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. If the size of this area is smaller than the available information, the API returns only the data that the area can hold.</p>
<p>See <a href="#HDRLATE">Format of Receiver Variable</a> for details about the format.</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 storage allocated for the receiver variable, the results are not predictable. The minimum length is 8 bytes.</p>
</dd>
<dt><strong>Program variable</strong></dt>
<dd>INPUT; CHAR(132)
<p>The name of the program variable whose value is to be retrieved. Possible values follow:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td width="15%" valign="top"><em>*CHAR</em></td>
<td width="85%" valign="top">This special value is specified instead of a variable name if a basing pointer is also specified. This special value returns a character view of the area addressed by a pointer.</td>
</tr>
<tr>
<td valign="top"><em>Program variable name</em></td>
<td valign="top">The name of the program variable. For information about program variables, see the topic on program-variable description in the <a href="../rbam6/rbam6clmain.htm">Control Language (CL)</a> information.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Basing pointer</strong></dt>
<dd>INPUT; ARRAY(5) of CHAR(132)
<p>In languages where a program variable may be based on a pointer variable, you can specify the basing pointers for the variable to be retrieved. Up to five basing pointers may be specified. If the basing pointer is an element in an array, the subscript representing an element in the array must be specified. Up to 132 characters can be specified for one basing pointer name. If no basing pointer is specified, then the structure must be initialized to blanks. If one or more basing pointers are specified, then the subsequent array entries must be initialized to blanks. For more information on basing pointers, refer to the topic on basing-pointer description in the <a href="../rbam6/rbam6clmain.htm">Control Language (CL)</a> information in the iSeries Information center.</p>
</dd>
<dt><strong>Starting position</strong></dt>
<dd>INPUT; BINARY(4)
<p>For string variables only, the starting position in the string from which its value is being retrieved. For a bit string, the value is the starting bit position. For a character string, the value is the starting character position.</p>
<p>This parameter is ignored on nonstring variables but must be initialized to any number greater than 0.</p>
</dd>
<dt><strong>Length of string</strong></dt>
<dd>INPUT; BINARY(4)
<p>For string variables only, the length of the string retrieved, starting at the position specified by the start parameter. For a bit string, this value is the number of bits to retrieve. For a character string, this value is the number of characters to retrieve.</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The value of the string variable is retrieved to the end of the string or retrieved for 200 bytes, whichever is less. If the string variable has a maximum length of zero, only 0 is allowed.</td>
</tr>
<tr>
<td valign="top"><em>Retrieve length</em></td>
<td valign="top">The length of data to retrieve.
<p>This parameter is ignored on nonstring variables but must be initialized to any number 0 or greater.</p>
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Output format</strong></dt>
<dd>INPUT; CHAR(10)
<p>The format in which the value is to be returned.</p>
<table cellpadding="3">
<!-- cols="10 90" -->
<tr>
<td valign="top"><em>*CHAR</em></td>
<td valign="top">The value of the program variable is returned in character form.</td>
</tr>
<tr>
<td valign="top"><em>*HEX</em></td>
<td valign="top">The value of the program variable is returned in hexadecimal form.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Program</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the program that contains the program variable to be retrieved.</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>*DFTPGM</em></td>
<td valign="top">The program currently specified as the default program will be used.</td>
</tr>
<tr>
<td valign="top"><em>Program name</em></td>
<td valign="top">The name of the program whose program variable is retrieved.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Recursion level</strong></dt>
<dd>INPUT; BINARY(4)
<p>The recursion level of the program that contains the program variable.</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The last (most recent) call of the program is the one from which the automatic program variable is retrieved.</td>
</tr>
<tr>
<td valign="top"><em>n</em></td>
<td valign="top">The number of the recursion level of the program from which the automatic program variable is retrieved.</td>
</tr>
</table>
<p>This parameter is ignored on static variables but must be initialized to any number 0 or greater.</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="HDRLATE">Format of Receiver Variable</a></h3>
<p>The following table shows the information supplied in the receiver variable parameter. For more information on each field, see <a href="#HDRFDES">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%">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">Variable type</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">Data error</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">POINTER</td>
<td align="left" valign="top">Pointer to variable</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Bit position</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Variable length</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Variable precision</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of array dimensions</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">Number of array elements returned</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">ARRAY(15) of BINARY(4)</td>
<td align="left" valign="top">Subscript bounds</td>
</tr>
<tr>
<td align="center" valign="top">172</td>
<td align="center" valign="top">AC</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Element length</td>
</tr>
<tr>
<td align="center" valign="top">176</td>
<td align="center" valign="top">B0</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Character string length</td>
</tr>
<tr>
<td align="center" valign="top">180</td>
<td align="center" valign="top">B4</td>
<td align="left" valign="top">CHAR(64)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">244</td>
<td align="center" valign="top">F4</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Data retrieved</td>
</tr>
</table>
<p>The following tables show the information supplied in the data retrieved field. The variable type field, which is enclosed in parentheses, indicates which table is used.</p>
<br>
<h3>Data for Binary Numeric (1)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable value</td>
</tr>
</table>
<br><br>
<h3>Data for Floating Point (2)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable value</td>
</tr>
</table>
<br><br>
<h3>Data for Zoned Decimal (3)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable value</td>
</tr>
</table>
<br><br>
<h3>Data for Packed Decimal (4)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable value</td>
</tr>
</table>
<br><br>
<h3>Data for Fixed Character (5)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable value</td>
</tr>
</table>
<br><br>
<h3>Data for Varying Character (6)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Varying character length</td>
</tr>
<tr>
<td align="center" valign="top">256</td>
<td align="center" valign="top">100</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable value</td>
</tr>
</table>
<br><br>
<h3>Data for Fixed Bit (7)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable value</td>
</tr>
</table>
<br><br>
<h3>Data for Unsigned Binary (8)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable value</td>
</tr>
</table>
<br><br>
<h3>Data for Space Pointer (9)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Hexadecimal offset</td>
</tr>
<tr>
<td align="center" valign="top">260</td>
<td align="center" valign="top">104</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">268</td>
<td align="center" valign="top">10C</td>
<td align="left" valign="top">CHAR(30)</td>
<td align="left" valign="top">Object addressed by pointer</td>
</tr>
<tr>
<td align="center" valign="top">298</td>
<td align="center" valign="top">12A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Library name</td>
</tr>
<tr>
<td align="center" valign="top">308</td>
<td align="center" valign="top">134</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Object type</td>
</tr>
</table>
<br><br>
<h3>Data for Data Pointer (10)</h3>
<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 valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FA</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Hexadecimal offset</td>
</tr>
<tr>
<td align="center" valign="top">260</td>
<td align="center" valign="top">104</td>
<td align="left" valign="top">CHAR(30)</td>
<td align="left" valign="top">Object addressed by pointer</td>
</tr>
<tr>
<td align="center" valign="top">290</td>
<td align="center" valign="top">122</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Library name</td>
</tr>
<tr>
<td align="center" valign="top">300</td>
<td align="center" valign="top">12C</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Object type</td>
</tr>
<tr>
<td align="center" valign="top">308</td>
<td align="center" valign="top">134</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Data type</td>
</tr>
<tr>
<td align="center" valign="top">312</td>
<td align="center" valign="top">138</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Data length</td>
</tr>
<tr>
<td align="center" valign="top">316</td>
<td align="center" valign="top">13C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Data precision</td>
</tr>
<tr>
<td align="center" valign="top">320</td>
<td align="center" valign="top">140</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Data string length</td>
</tr>
<tr>
<td align="center" valign="top">324</td>
<td align="center" valign="top">144</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Element length</td>
</tr>
<tr>
<td align="center" valign="top">328</td>
<td align="center" valign="top">148</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Data</td>
</tr>
</table>
<br><br>
<h3>Data for Instruction Definition List (11)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Instruction number</td>
</tr>
<tr>
<td align="center" valign="top">260</td>
<td align="center" valign="top">104</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">268</td>
<td align="center" valign="top">10C</td>
<td align="left" valign="top">CHAR(30)</td>
<td align="left" valign="top">Object addressed by pointer</td>
</tr>
<tr>
<td align="center" valign="top">298</td>
<td align="center" valign="top">12A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Library name</td>
</tr>
<tr>
<td align="center" valign="top">308</td>
<td align="center" valign="top">134</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Object type</td>
</tr>
</table>
<br><br>
<h3>Data for System Pointer (12)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Authorization</td>
</tr>
<tr>
<td align="center" valign="top">268</td>
<td align="center" valign="top">10C</td>
<td align="left" valign="top">CHAR(30)</td>
<td align="left" valign="top">Object addressed by pointer</td>
</tr>
<tr>
<td align="center" valign="top">298</td>
<td align="center" valign="top">12A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Library name</td>
</tr>
<tr>
<td align="center" valign="top">308</td>
<td align="center" valign="top">134</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Object type</td>
</tr>
</table>
<br><br>
<h3>Data for Machine Space Pointer (13)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Hexadecimal offset</td>
</tr>
<tr>
<td align="center" valign="top">260</td>
<td align="center" valign="top">104</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">268</td>
<td align="center" valign="top">10C</td>
<td align="left" valign="top">CHAR(30)</td>
<td align="left" valign="top">Object addressed by pointer</td>
</tr>
<tr>
<td align="center" valign="top">298</td>
<td align="center" valign="top">12A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Library name</td>
</tr>
<tr>
<td align="center" valign="top">308</td>
<td align="center" valign="top">134</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Object type</td>
</tr>
</table>
<br><br>
<h3>Data for Exception Description (14)</h3>
<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%">244</td>
<td align="center" valign="top" width="10%">F4</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message ID</td>
</tr>
<tr>
<td align="center" valign="top">251</td>
<td align="center" valign="top">FB</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">252</td>
<td align="center" valign="top">FC</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Control</td>
</tr>
<tr>
<td align="center" valign="top">253</td>
<td align="center" valign="top">FD</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Handler type</td>
</tr>
<tr>
<td align="center" valign="top">254</td>
<td align="center" valign="top">FE</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Instruction number</td>
</tr>
<tr>
<td align="center" valign="top">262</td>
<td align="center" valign="top">106</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Program name</td>
</tr>
<tr>
<td align="center" valign="top">272</td>
<td align="center" valign="top">110</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Library name</td>
</tr>
<tr>
<td align="center" valign="top">282</td>
<td align="center" valign="top">11A</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">284</td>
<td align="center" valign="top">11C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Compare string length</td>
</tr>
<tr>
<td align="center" valign="top">288</td>
<td align="center" valign="top">120</td>
<td align="left" valign="top">CHAR(28)</td>
<td align="left" valign="top">Compare string</td>
</tr>
<tr>
<td align="center" valign="top">316</td>
<td align="center" valign="top">13C</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Job log</td>
</tr>
<tr>
<td align="center" valign="top">317</td>
<td align="center" valign="top">13D</td>
<td align="left" valign="top">CHAR(3)</td>
<td align="left" valign="top">Message type</td>
</tr>
<tr>
<td align="center" valign="top">320</td>
<td align="center" valign="top">140</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of message IDs</td>
</tr>
<tr>
<td align="center" valign="top">324</td>
<td align="center" valign="top">144</td>
<td align="left" valign="top">ARRAY(*) of CHAR(7)</td>
<td align="left" valign="top">Array of messages</td>
</tr>
</table>
<br><br>
<h3><a name="HDRFDES">Field Descriptions</a></h3>
<p><strong>Array of messages.</strong> An array of the number of message IDs is returned.</p>
<p><strong>Authorization.</strong> Pointer authorization.</p>
<p><strong>Bit position.</strong> The starting bit position, 1-8, for bit strings returned in *HEX format. The least significant bit is 1 and 8 the most significant bit. This field will be initialized to 0 for any other variable type.</p>
<p><strong>Bytes available.</strong> The number of bytes of data available to be returned. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Character string length.</strong> For output format *CHAR, this value is the length of the returned character string. For output format *HEX, this value is initialized to 0. For fixed character, varying character, and fixed bit variables this field contains the actual length of the data returned for *CHAR and *HEX output formats. For pointers and exception monitors this field is 0.</p>
<p><strong>Comparison string.</strong> The specified comparison string.</p>
<p><strong>Comparison string length.</strong> The length of the comparison string. This value is 0 if a value is not specified.</p>
<p><strong>Control.</strong> Exception monitor control action. The following values may be returned:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>X'00'</em></td>
<td valign="top">Default</td>
</tr>
<tr>
<td valign="top"><em>X'01'</em></td>
<td valign="top">Off</td>
</tr>
<tr>
<td valign="top"><em>X'02'</em></td>
<td valign="top">Resignal</td>
</tr>
<tr>
<td valign="top"><em>X'04'</em></td>
<td valign="top">Defer</td>
</tr>
<tr>
<td valign="top"><em>X'05'</em></td>
<td valign="top">Handle</td>
</tr>
</table>
<p><strong>Data.</strong> The data addressed by the pointer. This field is returned in the corresponding output format for the variable type (data type).</p>
<p><strong>Data error.</strong> Whether an error was returned when returning a variable.</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">No errors were returned with the variable data.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">One or more errors were returned with the variable data.</td>
</tr>
</table>
<p><strong>Data length.</strong> The length of the data addressed by the pointer. This is the same value as in the variable length field in the header.</p>
<p><strong>Data precision.</strong> The precision of the data addressed by the pointer. This is the same value as in the variable precision field in the header.</p>
<p><strong>Data retrieved.</strong> If an error is encountered while retrieving the data, CPD messages may be returned instead of the variable data. The structure of this parameter is dependent on the object type. The format of the data depends on the variable type field.</p>
<p><strong>Data string length.</strong> The string length of the data addressed by the pointer. This is the same value as in the variable string length field in the header.</p>
<p><strong>Data type.</strong> The type of data addressed by the pointer. This is the same value as in the variable type field in the header.</p>
<p><strong>Element length.</strong> The length of the data element returned. If this field is 0, each element can be a different length and the user must go to the element to get the element length.</p>
<p><strong>Handler type.</strong> Exception monitor handler type.</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>'00'X</em></td>
<td valign="top">External handler</td>
</tr>
<tr>
<td valign="top"><em>'01'X</em></td>
<td valign="top">Call internal handler</td>
</tr>
<tr>
<td valign="top"><em>'02'X</em></td>
<td valign="top">Branch point handler</td>
</tr>
</table>
<p><strong>Hexadecimal offset.</strong> Hexadecimal offset of the space pointed to by the space or machine space pointer.</p>
<p><strong>Instruction number.</strong> The exception handler instruction number for a monitor with an internal handler or X'0' for an external handler.</p>
<p><strong>Job log.</strong> Put messages on job log.</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">No</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">Yes</td>
</tr>
</table>
<p><strong>Library name.</strong> The library containing the object addressed by the pointer, *LIBL, or X'0' for internal monitors.</p>
<p><strong>Message ID.</strong> If an error was received with the variable data, this field contains the diagnostic message ID. If no error was received with the variable's data, this field contains blanks.</p>
<p><strong>Message type.</strong> Message types being monitored.</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>100</em></td>
<td valign="top">Escape</td>
</tr>
<tr>
<td valign="top"><em>010</em></td>
<td valign="top">Notify</td>
</tr>
<tr>
<td valign="top"><em>001</em></td>
<td valign="top">Status</td>
</tr>
</table>
<p>More than one message type can be monitored at a time. If the first and third characters are 1's, then escape and status messages are being monitored.</p>
<p><strong>Number of array dimensions.</strong> If the variable is an array or an element of an array, this field is the number of array dimensions. Otherwise, this field is initialized to 0.</p>
<p><strong>Number of array elements returned.</strong> If the variable is an array, this field is the number of array elements returned. Otherwise, this field is initialized to 0.</p>
<p><strong>Number of message IDs.</strong> The number of message identifiers being monitored.</p>
<p><strong>Object addressed by pointer.</strong> The fully qualified name of the object addressed by the pointer.</p>
<p><strong>Object type.</strong> The Machine Interface (MI) type of the object addressed by the pointer.</p>
<p><strong>Pointer to variable.</strong> Pointer to variable, if applicable. For example, a pointer is not returned to a variable of type machine space pointer or for an exception description. For system security reasons a pointer is not returned if the security level is 50 and if the job using the API is servicing and debugging another job.</p>
<p><strong>Program name.</strong> External handler program name or X'0' for an internal monitor.</p>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>Subscript bounds.</strong> The subscript lower bounds and subscript upper bounds for each array dimension. If the variable is not an element of an array, or the dimension is not used, the subscript lower and upper bounds are initialized to 0.</p>
<p><strong>Varying character length.</strong> The actual length of the varying character string.</p>
<p><strong>Variable length.</strong> The length of the variable value. For bit strings, this value is the number of bits. For packed and zoned variables, this value is the number of digits. For pointers and exception monitors this field is 0. For all other variable types, this value is the number of bytes.</p>
<p><strong>Variable precision.</strong> The number of decimal digits or fractional digits for zoned and packed variables. For any other variable type, this field will be initialized to 0.</p>
<p><strong>Variable type.</strong> The following are the possible variable types:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">Binary numeric</td>
</tr>
<tr>
<td valign="top"><em>2</em></td>
<td valign="top">Floating point</td>
</tr>
<tr>
<td valign="top"><em>3</em></td>
<td valign="top">Zoned decimal</td>
</tr>
<tr>
<td valign="top"><em>4</em></td>
<td valign="top">Packed decimal</td>
</tr>
<tr>
<td valign="top"><em>5</em></td>
<td valign="top">Fixed character</td>
</tr>
<tr>
<td valign="top"><em>6</em></td>
<td valign="top">Varying character</td>
</tr>
<tr>
<td valign="top"><em>7</em></td>
<td valign="top">Fixed bit</td>
</tr>
<tr>
<td valign="top"><em>8</em></td>
<td valign="top">Unsigned binary</td>
</tr>
<tr>
<td valign="top"><em>9</em></td>
<td valign="top">Space pointer</td>
</tr>
<tr>
<td valign="top"><em>10</em></td>
<td valign="top">Data pointer</td>
</tr>
<tr>
<td valign="top"><em>11</em></td>
<td valign="top">Instruction definition list</td>
</tr>
<tr>
<td valign="top"><em>12</em></td>
<td valign="top">System pointer</td>
</tr>
<tr>
<td valign="top"><em>13</em></td>
<td valign="top">Machine space pointer</td>
</tr>
<tr>
<td valign="top"><em>14</em></td>
<td valign="top">Exception description</td>
</tr>
</table>
<p><strong>Variable value.</strong> The value of the variable being retrieved.</p>
<p>The following messages may be returned in this field:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>CPD1901</em></td>
<td valign="top">Variable contains invalid decimal data.</td>
</tr>
<tr>
<td valign="top"><em>CPD1902</em></td>
<td valign="top">Pointer to be displayed not set to any address.</td>
</tr>
<tr>
<td valign="top"><em>CPD1903</em></td>
<td valign="top">Floating-point value displayed is not exact.</td>
</tr>
<tr>
<td valign="top"><em>CPD1904</em></td>
<td valign="top">Object not found for system pointer with initial value.</td>
</tr>
<tr>
<td valign="top"><em>CPD1905</em></td>
<td valign="top">Variable not found for data pointer with initial value.</td>
</tr>
<tr>
<td valign="top"><em>CPD1906</em></td>
<td valign="top">Variable to be displayed contained in deleted object.</td>
</tr>
<tr>
<td valign="top"><em>CPD1907</em></td>
<td valign="top">Variable refers to object with freed storage.</td>
</tr>
<tr>
<td valign="top"><em>CPD1908</em></td>
<td valign="top">Space addressing error for variable.</td>
</tr>
<tr>
<td valign="top"><em>CPD1909</em></td>
<td valign="top">Pointer alignment error. Pointer not on 16-byte boundary.</td>
</tr>
<tr>
<td valign="top"><em>CPD1910</em></td>
<td valign="top">High-level language (HLL) pointer invalid.</td>
</tr>
<tr>
<td valign="top"><em>CPD1911</em></td>
<td valign="top">START plus LEN values exceed length of string.</td>
</tr>
<tr>
<td valign="top"><em>CPD1913</em></td>
<td valign="top">Space addressing error for variable.</td>
</tr>
<tr>
<td valign="top"><em>CPD1914</em></td>
<td valign="top">Pointer addresses a deleted object.</td>
</tr>
</table>
<br><br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="3">
<!-- 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">CPF1902 E</td>
<td valign="top">No default program exists.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1903 E</td>
<td valign="top">Program &amp;1 not in debug mode.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1905 E</td>
<td valign="top">Starting position parameter is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1906 E</td>
<td valign="top">Command is not valid. No programs in debug mode.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1915 E</td>
<td valign="top">Length parameter is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1919 E</td>
<td valign="top">Recursion level parameter is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1927 E</td>
<td valign="top">Output format name not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1938 E</td>
<td valign="top">Command is not allowed while serviced job is not active.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1939 E</td>
<td valign="top">Time-out occurred waiting for a reply from the serviced job.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1941 E</td>
<td valign="top">Serviced job has completed. Debug commands are not allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C19 E</td>
<td valign="top">Error occurred with receiver variable specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td valign="top">Length of the receiver variable is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF7133 E</td>
<td valign="top">Variable or basing pointer name missing.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9549 E</td>
<td valign="top">Error addressing API parameter.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td 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>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center">
<a href="#top_Of_Page">Top</a> |
<a href="debug1.htm">Debugger APIs</a> |
<a href="aplist.htm">APIs by category</a>
</td>
</tr>
</table>
</center>
<br>
</body>
</html>