<!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> 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> Service Program: QTEDBGS<br> <!-- iddvc RMBR --> <br> 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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </td> <td align="left" valign="top">BINARY(4)</td> <td align="left" valign="top">Line number</td> </tr> <tr> <td align="center" valign="top"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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"> </td> <td align="center" valign="top"> </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 &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 &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>