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

531 lines
16 KiB
HTML
Raw Permalink 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>HFS Directory Entry Attributes</title>
<!-- 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited November 2001 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body><!--End Header Records -->
<!--Java sync-link-->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>HFS Directory Entry Attributes</h2>
<p>Every file and directory in a file system has a corresponding directory
entry. The <strong>directory entry</strong> is created automatically by the
file system when the stream file is opened or the directory is created. It is
stored in the directory in which the file or directory is located and contains
descriptive information, such as the item's creation date and whether it is a
file or directory. The items of information are called <strong>directory entry
attributes</strong> or simply <strong>attributes.</strong> Each attribute has a
name and a value.</p>
<br>
<h3>Standard HFS Directory Entry Attributes</h3>
<p>Some directory entry attributes are created automatically when the directory
entry is created. These attributes are called <strong>standard
attributes.</strong> Their names start with the letter Q so you can identify
them easily. Each file system determines which standard attributes you can
specify when working with directory entries.</p>
<p>The standard attributes for directory entries are:</p>
<dl>
<dt><strong>QNAME</strong></dt>
<dd>CHAR(*)
<p>The current name of a file or directory.</p>
<p>Do not specify this attribute in the attribute information table or
attribute selection table used with some APIs. The name is either already
specified or disallowed, as follows:</p>
<ul>
<li>When you create a directory (or open a stream file) and when you retrieve
directory entry attributes, the object's name is already specified in the API's
path name parameter.</li>
<li>The Read Directory Entries (QHFRDDR) API always returns the QNAME attribute
to identify the name of the directory entry.</li>
<li>You cannot use the Change Directory Entry Attributes (QHFCHGAT) AP I to
change this attribute and rename the object. You must use the Rename Directory
(QHFRNMDR) or Rename Stream File (QHFRNMSF) API to rename the object.</li>
</ul>
<br>
</dd>
<dt><strong>QFILSIZE</strong></dt>
<dd>BINARY(4) UNSIGNED
<p>The size of a file's data, in bytes.</p>
<p>This attribute applies only to files. Thus, for directories, it has a value
of zero. If you specify it for a directory, it is ignored.</p>
</dd>
<dt><strong>QALCSIZE</strong></dt>
<dd>BINARY(4) UNSIGNED
<p>For a file, the allocated size of the file in bytes. The allocated size is
the amount of space the file system actually uses to store the file.</p>
<p>This attribute applies only to files. Thus, for directories, it has a value
of zero. If you specify it for a directory, it is ignored.</p>
</dd>
<dt><strong>QCRTDTTM</strong></dt>
<dd>CHAR(13)
<p>The date and time of day the file or directory was created, in CYYMMDDHHMMSS
format.</p>
<p>You cannot specify this attribute when creating a directory or file.
However, you can specify it on calls to the Retrieve Directory Entry Attributes
(QHFRTVAT) and Change Directory Entry Attributes (QHFCHGAT) APIs.</p>
</dd>
<dt><strong>QACCDTTM</strong></dt>
<dd>CHAR(13)
<p>The date and time of day the file or directory was last accessed, in
CYYMMDDHHMMSS format.</p>
<p>You can specify this attribute on any API call, but your file system might
ignore it in some APIs.</p>
</dd>
<dt><strong>QWRTDTTM</strong></dt>
<dd>CHAR(13)
<p>The date and time of day the file or directory was last written to, in
CYYMMDDHHMMSS format.</p>
<p>Changes to this attribute may not be supported by all file systems. Refer to
the file system's documentation for any restrictions.</p>
</dd>
<dt><strong>QFILATTR</strong></dt>
<dd>CHAR(10)
<p>The type of item the directory entry is for. You can specify this attribute
on any API call, except as noted in the following list of character
descriptions.</p>
<p>Each character in the QFILATTR attribute has a specific meaning. Characters
6-10 must be set to blanks. Characters 1-5 must have a value of either 0 or
1:</p>
<table cellpadding="3">
<!-- cols="10 90" -->
<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>The characters and their meanings are:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">Read-only file. This applies only to files; it is ignored for
directories. You can change it only by using the Change Directory Entry
Attributes (QHFCHGAT) API.
<p>When a file has this attribute, the file cannot be accessed in write mode.
It cannot be opened with write or read/write access, it cannot be the target
file in a copy stream file operation, and it cannot be deleted.</p>
</td>
</tr>
<tr>
<td valign="top"><em>2</em></td>
<td valign="top">Hidden file or directory. You can change this attribute by
using the Change Directory Entry Attributes (QHFCHGAT) API.</td>
</tr>
<tr>
<td valign="top"><em>3</em></td>
<td valign="top">System file or directory. You can change this attribute by
using the Change Directory Entry Attributes (QHFCHGAT) API.</td>
</tr>
<tr>
<td valign="top"><em>4</em></td>
<td valign="top">Entry is a directory (not a file). You cannot change this
attribute. If you specify it on the Change Directory Entry Attributes
(QHFCHGAT) API, it is ignored.</td>
</tr>
<tr>
<td valign="top"><em>5</em></td>
<td valign="top">Changed file. This applies only to files. It indicates that
the file has been changed and is usually used to determine when a file needs to
be moved to safe, permanent storage. It is set to Yes when the file is created
or written to. You can set it to No only by using the Change Directory Entry
Attributes (QHFCHGAT) API.</td>
</tr>
<tr>
<td valign="top"><em>6-10</em></td>
<td valign="top">Reserved. Must be set to blanks.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>QERROR</strong></dt>
<dd>CHAR(7)
<p>A special attribute that can be returned in the attribute data buffer by the
Read Directory (QHFRDDR) API when it encounters an error in retrieving the
attributes of a directory entry. These values can be returned:</p>
<table 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">CPF1F06</td>
<td valign="top">Directory in use.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1F06</td>
<td valign="top">Directory in use.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1F08</td>
<td valign="top">Damaged directory.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1F26</td>
<td valign="top">File in use.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1F28</td>
<td valign="top">Damaged file.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1F62</td>
<td valign="top">Requested function failed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1F71</td>
<td valign="top">File system unique exception occurred.</td>
</tr>
</table>
<p>For details about calling the QHFRDDR API from an application, see the <a
href="qhfrddr.htm">Read Directory Entries (QHFRDDR) API</a>. For details about
the interface between the QHFRDDR API and a new file system, see the <a href=
"xhfrddr.htm">Exit Program for Read Directory Entries (QHFRDDR) API</a>.</p>
</dd>
</dl>
<br>
<h3><a name="HDRHOTATT">Other HFS Directory Entry Attributes</a></h3>
<p>File systems can define their own unique attributes for files and
directories in addition to the standard ones. The file system's documentation
defines the attributes' names and values, and explains how to access and use
them.</p>
<p>An application can also define its own directory entry attributes. These
attributes are sometimes called <strong>extended attributes.</strong> They
resemble the extended attributes in the IBM<SUP>(R)</SUP> OS/2<SUP>(R)</SUP> file system and supply
additional information relevant to the application. The application must define
the names and values of these attributes.</p>
<br>
<h3><a name="HDRATTTAB">HFS Attribute Information Table</a></h3>
<p>The HFS APIs use a common attribute information table to pass all types of
directory entry attributes between the application and the file system. Thus,
the information is returned in the same format regardless of which file system
the application is using. Different file systems can use different attributes,
so the contents of the table can vary from one file system to another.</p>
<p>The file system must use the attribute information table when communicating
with the application. It must accept and return attributes in that format. For
its own use, however, the file system can store the attribute information in
whatever format is most convenient.</p>
<p>The table consists of zero or more attributes and varies in length.</p>
<p>The attribute information table is used by these HFS APIs:</p>
<dl>
<dd>Create Directory (QHFCRTDR)</dd>
<dd>Retrieve Directory Entry Attributes (QHFRTVAT)</dd>
<dd>Change Directory Entry Attributes (QHFCHGAT)</dd>
<dd>Read Directory Entries (QHFRDDR)</dd>
<dd>Open Stream File (QHFOPNSF)</dd>
</dl>
<p>The attribute information table has three logical parts:</p>
<ol>
<li>The first field specifies the number of attributes defined in the
table.</li>
<li>The next fields give the offsets to the attributes defined in the table.
There is one offset field for each attribute.</li>
<li>Next are groups of fields describing the attributes being defined or
retrieved. There is one group of descriptive fields for each attribute.</li>
</ol>
<p>The format of the attribute information table is:</p>
<table border width="80%">
<tr>
<th align="left" valign="top">Type</th>
<th align="left" valign="top">Field</th>
</tr>
<tr>
<td align="left" valign="top" width="30%">BINARY(4)</td>
<td align="left" valign="top" width="70%">The number of attributes defined in
the table. This is the number of attributes being defined for or retrieved from
the directory entry.</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2"><em>Offsets:</em></td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">The offset to the first attribute</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">The offset to the next attribute, if more than
one is being defined or retrieved. This field is repeated to list the offset to
each attribute being defined or retrieved.</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2"><em>Description of the first
attribute:</em></td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of attribute name</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of attribute value</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Reserved; currently set to zero</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Attribute name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Attribute value<sup>1</sup></td>
</tr>
<tr>
<td align="left" valign="top" colspan="2"><em>Description of the next attribute
(repeated for each attribute after the first):</em></td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of attribute name</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of attribute value</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Reserved; currently set to zero</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Attribute name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Attribute value<sup>1</sup></td>
</tr>
<tr>
<td align="left" valign="top" colspan="2"><br>
<strong>Note:</strong><br>
<br>
<sup>1</sup>The attribute value is either a character or the character
representation of a binary field.<br>
<br>
</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRATTSEL">HFS Attribute Selection Table</a></h3>
<p>The HFS APIs use a common attribute selection table to choose which
directory entry attributes to retrieve or to make available for reading. The
attribute selection table specifies which attributes the file system should
return to the application. The file system must read the table, determine which
attributes have been selected, and return those attributes to the application
in the attribute information table.</p>
<p>The attribute selection table varies in length.</p>
<p>The attribute selection table is used by these HFS APIs:</p>
<dl>
<dd>Open Directory (QHFOPNDR)</dd>
<dd>Retrieve Directory Entry Attributes (QHFRTVAT)</dd>
</dl>
<p>The attribute selection table contains an entry for every attribute the
application selects. If a selected attribute does not exist for the directory
entry, no error is signaled. The attribute name is returned, and the length of
the attribute value is zero.</p>
<p>The attribute selection table has three logical parts:</p>
<ol>
<li>The first field specifies the number of attributes specified in the
table.</li>
<li>The next fields give the offsets to the attributes specified in the table.
There is one offset field for each attribute.</li>
<li>Next are pairs of fields describing the attributes specified. There is one
pair of descriptive fields for each attribute.</li>
</ol>
<p>The format of the attribute selection table is:</p>
<table border width="80%">
<tr>
<th align="left" valign="top">Type</th>
<th align="left" valign="top">Field</th>
</tr>
<tr>
<td align="left" valign="top" width="30%">BINARY(4)</td>
<td align="left" valign="top" width="70%">The number of attributes specified in
this table</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2"><em>Offsets:</em></td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">The offset to the first attribute</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">The offset to the next attribute, if more than
one is specified. This field is repeated for each attribute.</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2"><em>Description of the first
attribute:</em></td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of attribute name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Attribute name</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2"><em>Description of the next attribute
(repeated for each attribute specified):</em></td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of attribute name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Attribute name</td>
</tr>
</table>
<br>
<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>
<br>
</body>
</html>