344 lines
9.4 KiB
HTML
344 lines
9.4 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>Change File Pointer (QHFCHGFP) 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 -->
|
||
|
|
<!--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>Change File Pointer (QHFCHGFP) 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="40%">Open file handle</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="30%">Char(16)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Move information</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(6)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">Distance to move</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">New offset</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Binary(4) Unsigned</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>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: No<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Change File Pointer (QHFCHGFP) API moves the file pointer a specified
|
||
|
|
number of bytes forward or backward. (The <strong>file pointer</strong> is the
|
||
|
|
current read/write position in the file.) This file pointer is used by the Read
|
||
|
|
from Stream File (QHFRDSF) and Write to Stream File (QHFWRTSF) APIs. You can
|
||
|
|
also use the QHFCHGFP API to determine the size of a file by moving the pointer
|
||
|
|
to the end of the file.</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>Open file handle</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(16)
|
||
|
|
|
||
|
|
<p>The handle returned when the file was opened with the Open Stream File
|
||
|
|
(QHFOPNSF) API.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Move information</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(6)
|
||
|
|
|
||
|
|
<p>Additional information specifying the action to take. The 6 characters of
|
||
|
|
this parameter are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="10 90" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">The pointer's starting location. The pointer is moved the
|
||
|
|
distance you specify from this place. For example, specifying 0 here and 5 in
|
||
|
|
the distance to move parameter moves the pointer to a new position 5 bytes from
|
||
|
|
the start of the file. Valid values for the starting location are:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">The beginning of the file.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">The pointer's current location.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">The end of the file. If the distance to move is zero, the new
|
||
|
|
offset parameter returns the file's size.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top" nowrap><em>2-6</em></td>
|
||
|
|
<td valign="top">Reserved. These characters must be set to blanks.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Distance to move</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The distance to move the pointer from the starting location, in bytes. A
|
||
|
|
negative value parameter moves the pointer backward in the file. A positive
|
||
|
|
value moves it forward.</p>
|
||
|
|
|
||
|
|
<p>The file pointer can be set to any location that can be supported by a
|
||
|
|
4-byte unsigned value. An error is returned only if the application tries to
|
||
|
|
move the pointer to a negative position or an offset larger than the maximum
|
||
|
|
value that can be stored in a 4-byte unsigned binary number.</p>
|
||
|
|
|
||
|
|
<p>Setting the file pointer beyond the end of the file is allowed, but it does
|
||
|
|
not change the file's size. To change the file's size, see <a href="qhfsetsz.htm">Set
|
||
|
|
Stream File Size (QHFSETSZ) API</a> or <a href="qhfwrtsf.htm">Write to Stream File
|
||
|
|
(QHFWRTSF) API</a>.</p>
|
||
|
|
|
||
|
|
<p>For brief examples of how the move information and the distance to move work
|
||
|
|
together, see <a href="#HDRUXCHGFP">How to Move the File Pointer</a>.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>New offset</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; BINARY(4) UNSIGNED
|
||
|
|
|
||
|
|
<p>The new position of the pointer.</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="HDRUXCHGFP">How to Move the File Pointer</a></h3>
|
||
|
|
|
||
|
|
<p>The file pointer represents a position or offset within a file where the
|
||
|
|
next read or write is to take place. It does not actually point to a byte in
|
||
|
|
the file; rather, it points to the gap between bytes. The diagram below
|
||
|
|
represents a 10-byte file as a series of boxes. Each box represents a byte of
|
||
|
|
data in the file.</p>
|
||
|
|
|
||
|
|
<p><img src="RBAFX503.gif" alt="Example showing how to move the file pointer"></p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Examples</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>To move the file pointer to the beginning of the file, set the start
|
||
|
|
location in the move information parameter to zero (the beginning of the file).
|
||
|
|
Set the distance to move to zero, too.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>To move the file pointer to offset 3 (that is, pointing to the gap between
|
||
|
|
bytes 3 and 4), set the start location in the move information parameter to
|
||
|
|
zero (the beginning of the file). Set the distance to move to 3.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>To move the file pointer to the end of the file, set the start location in
|
||
|
|
the move information parameter to 2 (the end of the file). Set the distance to
|
||
|
|
move to zero. The new offset parameter returns the file's size.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top" nowrap>Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F2D E</td>
|
||
|
|
<td valign="top">File pointer position not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F2E E</td>
|
||
|
|
<td valign="top">Range of bytes in file in use.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F25 E</td>
|
||
|
|
<td valign="top">File handle not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F28 E</td>
|
||
|
|
<td valign="top">Damaged file.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F4E E</td>
|
||
|
|
<td valign="top">Move information value not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F4F E</td>
|
||
|
|
<td valign="top">Distance to move value not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F41 E</td>
|
||
|
|
<td valign="top">Severe error occurred while addressing parameter list.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F52 E</td>
|
||
|
|
<td valign="top">Error code not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F62 E</td>
|
||
|
|
<td valign="top">Requested function failed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F66 E</td>
|
||
|
|
<td valign="top">Storage needed exceeds maximum limit for user profile
|
||
|
|
&1.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F71 E</td>
|
||
|
|
<td valign="top">Exception specific to file system occurred.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F72 E</td>
|
||
|
|
<td valign="top">Internal file system error occurred.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F73 E</td>
|
||
|
|
<td valign="top">Not authorized to use command.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F74 E</td>
|
||
|
|
<td valign="top">Not authorized to object.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F82 E</td>
|
||
|
|
<td valign="top">Function not supported.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF1F87 E</td>
|
||
|
|
<td valign="top">Missing or damaged exit program &2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
||
|
|
<td valign="top">Literal value cannot be changed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
|
<td valign="top">Program or service program &1 in library &2 ended.
|
||
|
|
Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V2R1
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"hfs1.htm">Hierarchical File System APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|