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

585 lines
17 KiB
HTML
Raw Normal View History

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 View File (QteRetrieveViewFile) 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 View File (QteRetrieveViewFile) API</h2>
<div class="box" style="width: 70%;">
<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%">Text descriptor 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 text descriptor 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">File name receiver variable</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Length of file name 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">5</td>
<td align="left" valign="top">Format of file name receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">View ID</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">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: QTEDBGS<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve View File (QteRetrieveViewFile) API is used to retrieve all the
files and text information necessary to construct the text for the entire view
specified by the view ID parameter. A list of text descriptors is returned.
Each text descriptor describes where a piece of text for the view comes from,
either from a file specified in the file name receiver variable or from
supplied text that may be obtained using the Retrieve View Text API.</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>Text descriptor receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The output variable containing the list of text descriptors, which describe
how the specified view is constructed. For more information, see <a href=
"#HDRVDRV">Format of Text Descriptor Receiver Variable</a>.</p>
</dd>
<dt><strong>Length of text descriptor receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length in bytes of the text descriptor receiver variable
parameter. The minimum length is 8 bytes.</p>
</dd>
<dt><strong>File name receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The output variable containing the list of files referenced by the text
descriptor receiver variable.</p>
</dd>
<dt><strong>Length of file name receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length in bytes of the file name receiver variable. The minimum length
is 8 bytes.</p>
</dd>
<dt><strong>Format of file name receiver variable</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information to be supplied by the API in the
file name receiver variable. The only valid value is:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>RVFN0100</em></td>
<td align="left" valign="top">Format of file name receiver variable</td>
</tr>
</table>
<p>For more information, see <a href="#HDRFRRV">Format of File Name Receiver
Variable</a>.</p>
</dd>
<dt><strong>View ID</strong></dt>
<dd>INPUT; BINARY(4)
<p>The identifier of a previously registered view obtained by using the
Register Debug View API.</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="HDRVDRV">Format of Text Descriptor Receiver Variable</a></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%">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">Number of text descriptor entries</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> The following
three fields are repeated the number of times specified in the number of text
descriptor entries field.</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">File name index</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Line number</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of lines</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRFRRV">Format of File Name Receiver Variable</a></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%">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">Number of file name entries</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> The following
eight fields are repeated the number of times specified on the number of file
name entries field.</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset of file name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of file name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">File format name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">External or i5/OS IFS file flag</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">CCSID of file name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Country or region ID of file name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(3)</td>
<td align="left" valign="top">Language ID of file name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(3)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> The file names
buffer follows all file name entries.</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">File names buffer</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRTVVFFD">Field Descriptions</a></h3>
<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>CCSID of file name.</strong> The CCSID the file name is in. The
value of this field is only valid for file format name RTVF0200.</p>
<p><strong>Country or region ID of file name.</strong> The country or region ID
of the file name. The value of this field is valid for file format name
RTVF0200 only.</p>
<p><strong>External or IFS file flag.</strong> Whether the file is an i5/OS
integrated file system file or an external file. A value of 0 means external
file; a value of 1 means i5/OS integrated file system file. The value of this
field is valid only for file format name RTVF0200.</p>
<p><strong>File names buffer.</strong> A list of file names from which text
should be retrieved.</p>
<p><strong>File name index.</strong> An index into the file name receiver
variable array. 0 is the first file entry in the file name receiver variable.
If the index is -1, the text comes from supplied text.</p>
<p><strong>File format name.</strong> The format of a file in the file names
buffer. Possible formats are:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>RTVF0100</em></td>
<td align="left" valign="top">i5/OS file (see <a href="#HDRRTVF100">RTVF0100
Format</a>)</td>
</tr>
<tr>
<td align="left" valign="top"><em>RTVF0200</em></td>
<td align="left" valign="top">External or i5/OS HFS file (see <a href="#HDRRTVF200">
RTVF0200 Format</a>)</td>
</tr>
</table>
<p><strong>Language ID of file name.</strong> The language ID of the file name.
The value of this field is valid only for file format name RTVF0200.</p>
<p><strong>Length of file name.</strong> The length in bytes of a file name in
the file names buffer.</p>
<p><strong>Line number.</strong> The line number in the file that is referenced
by the file name index to start reading text from. If the file name index is
-1, this specifies the line number in the view where the supplied text can be
retrieved using the QteRetrieveViewText API.</p>
<p><strong>Number of file name entries.</strong> The number of entries returned
in the file name receiver variable.</p>
<p><strong>Number of lines.</strong> The number of lines of text described by
the text descriptor. The number of lines to read from the file, which is the
number of lines of supplied text to be retrieved using the QteRetrieveViewText
API.</p>
<p><strong>Number of text descriptor entries.</strong> The number of entries
returned in the receiver variable. The file name index, line number, and number
of lines fields are repeated this number of times.</p>
<p><strong>Offset of file name.</strong> From the start of the file names
buffer, the start of a file name.</p>
<br>
<h3>Formats of File Format Name</h3>
<p><strong><a name="HDRRTVF100">RTVF0100 Format</a></strong></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%">i5/OS file name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">i5/OS library</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">i5/OS member name</td>
</tr>
</table>
<br>
<br>
<h3>Field Descriptions</h3>
<p><strong>i5/OS file name.</strong> The name of an i5/OS file from which
text should be retrieved. It is an i5/OS object name, left-justified, and
padded with blanks.</p>
<p><strong>i5/OS library.</strong> The name of a library that contains the
file from which text should be retrieved. It is an i5/OS object name,
left-justified, and padded with blanks.</p>
<p><strong>i5/OS member name.</strong> The name of the member of the file from
which text should be retrieved. It is an i5/OS object name, left-justified,
and padded with blanks.</p>
<br>
<p><strong><a name="HDRRTVF200">RTVF0200 Format</a></strong></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(*)</td>
<td align="left" valign="top" width="60%">External file or i5/OS integrated
file system file name</td>
</tr>
</table>
<br>
<br>
<h3>Field Description</h3>
<p><strong>External file or i5/OS integrated file system file name.</strong>
The name of an external file or i5/OS integrated file system file from which
text should be retrieved. The value of this field is valid only for file format
name RTVF0200.</p>
<br>
<h3>Error Messages</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is 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>
<tr>
<td align="left" valign="top">CPF9541 E</td>
<td align="left" valign="top">Not in debug mode.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9542 E</td>
<td align="left" valign="top">View not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9549 E</td>
<td align="left" valign="top">Error addressing API parameter.</td>
</tr>
<tr>
<td align="left" valign="top">CPF954A E</td>
<td align="left" valign="top">No source text available.</td>
</tr>
</table>
<br>
<hr>
API Introduced: V3R1
<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>
</body>
</html>