326 lines
9.9 KiB
HTML
326 lines
9.9 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>Lock and Unlock Range in Stream File (QHFLULSF) 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>Lock and Unlock Range in Stream File (QHFLULSF) 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">Lock 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">File offset where lock begins</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4) Unsigned</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Bytes to lock</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4) Unsigned</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">File offset where unlock begins</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4) Unsigned</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="left" valign="top">Bytes to unlock</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4) Unsigned</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>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Lock and Unlock Range in Stream File (QHFLULSF) API locks or unlocks a range of bytes in an open stream file. An application can lock part of a file instead of the entire file to temporarily keep other open instances from accessing that part.</p>
|
|
|
|
<p>An open instance is the state of a file having been opened and assigned an open file handle. The same job can open a file more than once. At each open operation, the file is assigned a unique open file handle, and the system treats the resulting state of being open as unique. Locks obtained during one open instance are honored by other open instances, even when the later open instances occur during the same job.</p>
|
|
|
|
<p>A locked range can be located anywhere in a file, and locking beyond the end of the file is allowed. Locks on a range are independent of the lock mode specified when the file is opened with the Open Stream File (QHFOPNSF) API.</p>
|
|
|
|
<p>Once a lock is obtained, the specified access is denied to all other requests to access that range in the file. The specified access is denied until the range is explicitly unlocked, the file is explicitly closed by the job, or the file is implicitly closed when the job ends. Closing a file releases all locks on the file.</p>
|
|
|
|
<p>If both unlocking and locking are specified on the request, the range is unlocked first. When unlocking is complete, the range is locked. This allows one open instance to keep other open instances from using a range that must be unlocked and relocked.</p>
|
|
|
|
<p>Your application should keep track of the ranges it locks. The QHFLULSF API does not track them, and HFS does not provide an API that lists locks.</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 file handle returned when the file was opened with the QHFOPNSF API.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Lock information</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(6)
|
|
|
|
<p>Additional information specifying the action to take. Valid values for the 6 characters in this parameter are:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td valign="top"><em>1</em></td>
|
|
<td valign="top">The lock mode, indicating what access other open instances can have to this range of the file. Valid values are:<br><br>
|
|
|
|
<table cellpadding="3">
|
|
<tr>
|
|
<td valign="top"><em>0</em></td>
|
|
<td valign="top">No lock. Use this when requesting an unlock operation only.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>2</em></td>
|
|
<td valign="top">Deny write. Other open instances have read-only access to the locked range. The range can overlap or include other ranges locked in deny write mode, but it cannot overlap or include other ranges locked in deny read/write mode.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>4</em></td>
|
|
<td valign="top">Deny read/write. This is an exclusive lock mode that denies other open instances all access to the locked range. The range cannot overlap or include any other locked range.</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>2-6</em></td>
|
|
<td valign="top">Reserved. These characters must be blank.</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>File offset where lock begins</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4) UNSIGNED
|
|
|
|
<p>The number of bytes from the beginning of the file where the range to lock begins.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Bytes to lock</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4) UNSIGNED
|
|
|
|
<p>The number of bytes to lock. If this is an unlock operation only, use zero for this parameter.</p>
|
|
</dd>
|
|
|
|
<dt><strong>File offset where unlock begins</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4) UNSIGNED
|
|
|
|
<p>The number of bytes from the beginning of the file where the range to unlock begins.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Bytes to unlock</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4) UNSIGNED
|
|
|
|
<p>The number of bytes to unlock. If this is a lock operation only, use zero for this parameter.</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>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">CPF1F2E E</td>
|
|
<td valign="top">Range of bytes in file in use.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F2F E</td>
|
|
<td valign="top">Unlock range of bytes in file failed.</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">CPF1F32 E</td>
|
|
<td valign="top">Number of locks on file exceeds limit.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F4B E</td>
|
|
<td valign="top">Value for number of bytes not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F4C E</td>
|
|
<td valign="top">Lock information value not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF1F4D E</td>
|
|
<td valign="top">File offset 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>
|