345 lines
18 KiB
HTML
345 lines
18 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
<!DOCTYPE html
|
||
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
<html lang="en-us" xml:lang="en-us">
|
||
|
<head>
|
||
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
<meta name="security" content="public" />
|
||
|
<meta name="Robots" content="index,follow" />
|
||
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
<meta name="DC.Type" content="reference" />
|
||
|
<meta name="DC.Title" content="Hierarchical file system APIs" />
|
||
|
<meta name="abstract" content="This topic describes how the use of HFS APIs is different for the optical file system, as compared to general API use." />
|
||
|
<meta name="description" content="This topic describes how the use of HFS APIs is different for the optical file system, as compared to general API use." />
|
||
|
<meta name="DC.Relation" scheme="URI" content="hfs.htm" />
|
||
|
<meta name="copyright" content="(C) Copyright IBM Corporation 2000, 2006" />
|
||
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2000, 2006" />
|
||
|
<meta name="DC.Format" content="XHTML" />
|
||
|
<meta name="DC.Identifier" content="hfsapitable" />
|
||
|
<meta name="DC.Language" content="en-us" />
|
||
|
<!-- 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. -->
|
||
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
<title>Hierarchical file system APIs</title>
|
||
|
</head>
|
||
|
<body id="hfsapitable"><a name="hfsapitable"><!-- --></a>
|
||
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
<h1 class="topictitle1">Hierarchical file system APIs</h1>
|
||
|
<div><p>This topic describes how the use of HFS APIs is different for the
|
||
|
optical file system, as compared to general API use. </p>
|
||
|
<div class="section"><p>Although the APIs that HFS supports are common to all file systems,
|
||
|
each file system has different interpretations or restrictions regarding those
|
||
|
APIs. The following table summarizes the optical interpretation of each HFS
|
||
|
API. LAN-attached optical devices and directly attached optical devices have
|
||
|
different restrictions for several of the APIs. Some examples of directly
|
||
|
attached optical devices are CDs, DVDs, and SCSI attached optical libraries.
|
||
|
Some examples of LAN-attached optical devices are Ethernet or token ring attached
|
||
|
optical libraries.</p>
|
||
|
</div>
|
||
|
|
||
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><caption>Table 1. Optical HFS API restrictions</caption><tbody><tr><th valign="top" class="firstcol" id="d0e24"><strong>HFS APIs</strong></th>
|
||
|
<td valign="top" headers="d0e24 "><strong>Directly attached usage notes</strong></td>
|
||
|
<td valign="top" headers="d0e24 "><strong>LAN-attached usage notes</strong></td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e34">Change File Pointer (QHFCHGFP)</th>
|
||
|
<td valign="top" headers="d0e34 ">None.</td>
|
||
|
<td valign="top" headers="d0e34 ">None.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e41">Close Stream File (QHFCLOSF)</th>
|
||
|
<td valign="top" headers="d0e41 ">None.</td>
|
||
|
<td valign="top" headers="d0e41 ">None.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e48">Control File System (QHFCTLFS)</th>
|
||
|
<td valign="top" headers="d0e48 ">Supports the following requests: <ul><li>SAV saves a held optical file.</li>
|
||
|
<li>RLS releases a held optical file.</li>
|
||
|
<li>SRD/VOL returns a sector read from an optical volume.</li>
|
||
|
<li>SRD/DEV returns a sector read from an optical device.</li>
|
||
|
<li>RTV/VOL returns volume-specific information.</li>
|
||
|
<li>GET reads file data directly from the media with minimal data caching.
|
||
|
For UDF formatted volumes, GET requires *X authority to each directory in
|
||
|
the path preceding the file and *R authority to the file. </li>
|
||
|
</ul>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e48 ">Supports the following requests: <ul><li>UPD/LAN performs a dynamic index refresh of the list of LAN volumes.</li>
|
||
|
<li>UPD/VOL returns volume-specific information.</li>
|
||
|
<li>RTV/VOL returns volume-specific information.</li>
|
||
|
<li>RTV/DIR returns subdirectory and file entries for a specified directory.</li>
|
||
|
</ul>
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e77">Copy Stream File (QHFCPYSF)</th>
|
||
|
<td valign="top" headers="d0e77 ">If the source file is in the QOPT file system, *USE
|
||
|
authority is required to the source optical volume. <p>If the target file
|
||
|
is in the QOPT file system, *CHANGE authority is required to the target optical
|
||
|
volume. Copy information parameter, byte 1, option 2 is not supported (Copy
|
||
|
Append). If specified, CPF1F62 will be returned.</p>
|
||
|
<p>When the operation
|
||
|
is complete, QCRTDTTM, QACCDTTM, and QWRTDTTM are set to the current date.</p>
|
||
|
<p>When
|
||
|
copying between the QOPT and QDLS file systems, file attributes are optionally
|
||
|
copied depending on global optical attribute CPYATR. This attribute can be
|
||
|
displayed or changed utilizing the CHGOPTA command.</p>
|
||
|
<p>When copying between
|
||
|
the QOPT and QDLS file systems, file permissions are not copied. If permissions
|
||
|
need to be preserved between these file systems use the copy (CPY) CL command.</p>
|
||
|
<p>If
|
||
|
the source file is on a UDF formatted volume, *X authority is required to
|
||
|
each directory in the path preceding the file. *R authority is required to
|
||
|
the file. </p>
|
||
|
<p> If the target file is on a UDF formatted volume, *WX authority
|
||
|
is required to the parent directory and *X authority is required to each directory
|
||
|
in the path preceding the parent directory.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e77 ">If the source file is in the QOPT file system, *USE
|
||
|
authority is required to the source optical volume. <p>If the target file
|
||
|
is in the QOPT file system, *CHANGE authority is required to the target optical
|
||
|
volume. Copy information parameter, Byte 1, Option 2 is not supported (Copy
|
||
|
Append).</p>
|
||
|
<p>Copying from a volume in a directly attached library to a volume
|
||
|
in a LAN-attached optical device is not supported.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e100">Create Directory (QHFCRTDR)</th>
|
||
|
<td valign="top" headers="d0e100 ">When the operation is complete, QCRTDTTM, QACCDTTM,
|
||
|
QWRTDTTM are set to the current date. <p>When the operation is complete, QFILSIZE
|
||
|
and QALCSIZE are set to 0.</p>
|
||
|
<p>Requires *CHANGE authority to the optical
|
||
|
volume.</p>
|
||
|
<p>Creating the optical root directory is not supported.</p>
|
||
|
<p>Creating
|
||
|
the volume portion of the directory is not supported.</p>
|
||
|
<p>Attributes passed
|
||
|
in the attribute information table are not supported, and will result in a
|
||
|
CPF1F71 error message. The length of the attribute information table parameter
|
||
|
must be 0.</p>
|
||
|
<p> Optical attribute OPT.CHGATDTTM, which indicates the last
|
||
|
time that the directory attributes were changed, is created. This date is
|
||
|
set to the current date. If a user specifies an attribute, it is ignored.</p>
|
||
|
<p>For
|
||
|
UDF formatted volumes, *WX authority is required to the parent directory.
|
||
|
*X authority is required to each directory in the path preceding the parent
|
||
|
directory. The owner of the directory will be the user creating the directory
|
||
|
and the owner data authorities will be set to *RWX. The primary group and
|
||
|
primary group data authorities will be the same as the parent directory. The
|
||
|
*PUBLIC data authorities will be the same as the parent directory.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e100 ">When the operation is complete, QCRTDTTM, QACCDTTM,
|
||
|
QWRTDTTM are set to the current date. <p>When the operation is complete, QFILSIZE
|
||
|
and QALCSIZE are set to 0.</p>
|
||
|
<p>Requires *CHANGE authority to the optical
|
||
|
volume.</p>
|
||
|
<p>Creating the optical root directory is not supported.</p>
|
||
|
<p>Creating
|
||
|
a volume portion of a directory is not supported.</p>
|
||
|
<p>All standard attributes
|
||
|
are ignored. </p>
|
||
|
<p>The length of attribute information table parameter must
|
||
|
be set to 0.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e133">Delete Directory (QHFDLTDR)</th>
|
||
|
<td valign="top" headers="d0e133 ">Deleting the optical root directory is not supported. <p>Deleting
|
||
|
the volume portion of a path is not supported.</p>
|
||
|
<p>Requires *CHANGE authority
|
||
|
to the optical volume.</p>
|
||
|
<p>For UDF formatted volumes, *WX authority is required
|
||
|
to the parent directory and *X authority is required to each directory in
|
||
|
the path preceding the parent directory. *W authority is required to the directory
|
||
|
being deleted.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e133 ">Deleting the optical root directory is not supported. <p>Deleting
|
||
|
the volume portion of a path is not supported.</p>
|
||
|
<p>Requires *CHANGE authority
|
||
|
to the optical volume.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e150">Delete Stream File (QHFDLTSF)</th>
|
||
|
<td valign="top" headers="d0e150 ">Requires *CHANGE authority to the optical volume.<p>For
|
||
|
UDF formatted volumes, *WX authority is required to the parent directory.
|
||
|
*X authority is required to each directory in the path preceding the parent
|
||
|
directory. *W authority is required to the file being deleted.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e150 ">Requires *CHANGE authority to the optical volume.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e159">Get File Size (QHFGETSZ)</th>
|
||
|
<td valign="top" headers="d0e159 ">None</td>
|
||
|
<td valign="top" headers="d0e159 ">None</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e166">Set File Size (QHFSETSZ)</th>
|
||
|
<td valign="top" headers="d0e166 ">None</td>
|
||
|
<td valign="top" headers="d0e166 ">Not Supported</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e173">Open Stream File (QHFOPNSF)</th>
|
||
|
<td valign="top" headers="d0e173 ">Parameter open information: <ul><li>Opening with an access mode (byte 6) of write only or read/write requires
|
||
|
*CHANGE authority to the volume.</li>
|
||
|
<li>Opening with an access mode (byte 6) of read only requires *USE authority
|
||
|
to the volume.</li>
|
||
|
<li>Lock Modes (byte 5) are enforced across different open instances. If the
|
||
|
same job opens a file multiple times, these open locks can conflict.</li>
|
||
|
</ul>
|
||
|
<p>If QALCSIZE was specified on an open request for the write operation,
|
||
|
optical media will be checked to see if enough space is available. If not,
|
||
|
error message CPF1F62 is returned.</p>
|
||
|
<p>All standard attributes except QALCSIZE
|
||
|
are ignored.</p>
|
||
|
<p>If a file is being created, QCRTDTTM, QACCDTTM, and QWRTDTTM
|
||
|
are set to the current date. If a file is being updated, QWRTDTTM is set to
|
||
|
the current date. If a file is being read, no time stamps are changed. QACCDTTM
|
||
|
is never changed after a file is created. It will always equal QCRTDTTM.</p>
|
||
|
<div class="p"> The
|
||
|
following authorization rules apply only for UDF formatted volumes.<ul><li>If opening a file for READ, *X authority is required to each directory
|
||
|
in the path preceding the file and *R authority is required to the file.</li>
|
||
|
<li>If opening an existing file for WRITE, *X authority is required to each
|
||
|
directory in the path name preceding the file and *W authority is required
|
||
|
to the file.</li>
|
||
|
<li>If opening an existing file for READ/WRITE, *X authority is required to
|
||
|
each directory in the path name preceding the file and *RW authority is required
|
||
|
to the file.</li>
|
||
|
<li>If creating the file, *WX authority is required to the parent directory. </li>
|
||
|
<li>If creating the file, the owner of the file will be the user creating
|
||
|
the file and the owner data authorities will be set to *RWX. The primary group
|
||
|
and primary group data authorities will be the same as the parent directory.
|
||
|
The *PUBLIC data authorities will be the same as the parent directory.</li>
|
||
|
</ul>
|
||
|
</div>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e173 ">Parameter Open information: <ul><li>Byte 3 (write-through flag), is not supported.</li>
|
||
|
<li>Byte 7 (type of open operation to perform), is not supported.</li>
|
||
|
<li>Opening with an access mode (byte 6) of read-only requires *USE authority
|
||
|
to the volume.</li>
|
||
|
</ul>
|
||
|
<p>Unless the file open attempt is for read-only access, attributes are
|
||
|
not tolerated and result in error message CPF1F71. The length of the attribute
|
||
|
information table parameter must be 0.</p>
|
||
|
<p>If a file open attempt is for
|
||
|
read-only access, attributes are tolerated but ignored.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e217">Read Stream File (QHFRDSF)</th>
|
||
|
<td valign="top" headers="d0e217 ">None.</td>
|
||
|
<td valign="top" headers="d0e217 ">None.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e224">Retrieve Directory Entry Attributes (QHFRTVAT)</th>
|
||
|
<td valign="top" headers="d0e224 ">Requires *USE authority to an optical volume.<p>For
|
||
|
UDF formatted volumes, *X authority is required to each directory in the path
|
||
|
name preceding the file and *R authority is required to the file or directory
|
||
|
being read.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e224 ">The user can retrieve only LAN-standard attributes:
|
||
|
QFILSIZE, QCRTDTTM, and QWRTDTTM. <p> Requires *USE authority to an optical
|
||
|
volume.</p>
|
||
|
<p>The length of attribute information table parameter must be
|
||
|
set to 0.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e237">Write Stream File (QHFWRTSF)</th>
|
||
|
<td valign="top" headers="d0e237 ">None.</td>
|
||
|
<td valign="top" headers="d0e237 ">None.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e244">Change Directory Entry Attributes (QHFCHGAT)</th>
|
||
|
<td valign="top" headers="d0e244 ">QFILATTR is the only standard attribute that can be
|
||
|
changed. All others that are specified are ignored. <p>Read only flag, byte
|
||
|
1 of the QFILATTR attribute, can only be set for a file, not a directory.
|
||
|
If specified for a directory, it is ignored.</p>
|
||
|
<p>Changed flag, byte 5 of
|
||
|
the QFILATTR attribute, can be set to either 0 or 1. It is automatically set
|
||
|
on (1) whenever a file is created or written to.</p>
|
||
|
<p>If OPT.CHGATDTTM is
|
||
|
specified, it is ignored.</p>
|
||
|
<p> Requires *CHANGE authority to an optical
|
||
|
volume.</p>
|
||
|
<p>For UDF formatted volumes, *X authority is required to each
|
||
|
directory in the path name preceding the file and *W authority is required
|
||
|
to the file.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e244 ">API not supported.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e261">Close Directory (QHFCLODR)</th>
|
||
|
<td valign="top" headers="d0e261 ">None.</td>
|
||
|
<td valign="top" headers="d0e261 ">API not supported.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e268">Force Buffered Data (QHFFRCSF)</th>
|
||
|
<td valign="top" headers="d0e268 ">If the volume media format is *UDF, then data is forced
|
||
|
to optical media.<p> If the volume media format is not *UDF, then data is
|
||
|
forced to internal disk storage, not to optical media.</p>
|
||
|
<p>For a file opened
|
||
|
for read-only access, this API has no effect.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e268 ">API not supported.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e279">Lock and Unlock Range in Stream File (QHFLULSF)</th>
|
||
|
<td valign="top" headers="d0e279 ">None.</td>
|
||
|
<td valign="top" headers="d0e279 ">API not supported.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e286">Move Stream File (QHFMOVSF)</th>
|
||
|
<td valign="top" headers="d0e286 ">If the source file is in the QOPT file system, *CHANGE
|
||
|
authority is required to the optical source volume. <p>If the target file
|
||
|
is in the QOPT file system, *CHANGE authority is required to the optical target
|
||
|
volume.</p>
|
||
|
<p>When moving between the QOPT and QDLS file systems, file attributes
|
||
|
are optionally copied depending on the global optical attribute CPYATR. This
|
||
|
attribute can be displayed or changed using the CHGOPTA command.</p>
|
||
|
<p>If
|
||
|
the source file is on a UDF formatted volume, *WX authority is required to
|
||
|
the parent directory and *X authority is required to each directory in the
|
||
|
path name preceding the parent directory. *RW authority is required to the
|
||
|
file. </p>
|
||
|
<p>If the target file is on a UDF formatted volume, *WX authority
|
||
|
is required to the parent directory and *X authority is required to each directory
|
||
|
in the path name preceding the file.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e286 ">API not supported.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e301">Open Directory (QHFOPNDR)</th>
|
||
|
<td valign="top" headers="d0e301 ">Opening the file system root (/QOPT) will allow both
|
||
|
directly attached and LAN-attached volumes to be returned on Read Directory
|
||
|
Entries.<p>Lock mode is ignored when opening the file system root.</p>
|
||
|
<p>Lock
|
||
|
mode of no lock is not supported. If requested, a lock mode of deny none is
|
||
|
substituted.</p>
|
||
|
<p>Requires *USE authority to the optical volume.</p>
|
||
|
<p>For
|
||
|
UDF formatted volumes, *X authority is required to each directory in the path
|
||
|
name preceding the directory being opened and *R authority is required to
|
||
|
the directory being opened.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e301 ">API not supported.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e316">Read Directory Entries (QHFRDDR)</th>
|
||
|
<td valign="top" headers="d0e316 ">QNAME is returned without the QOPT file system name.<p>QNAME
|
||
|
is the only field that is set for a LAN-attached volume.</p>
|
||
|
<p>QWRTDTTM will
|
||
|
always equal QCRTDTTM. </p>
|
||
|
<p>For files and directories, QACCDTTM will always
|
||
|
equal QCRTDTTM.</p>
|
||
|
<p> For volumes, QACCDTTM will equal the last volume reference
|
||
|
date.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e316 ">API not supported.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e331">Rename Stream File (QHFRNMSF)</th>
|
||
|
<td valign="top" headers="d0e331 ">Requires *CHANGE authority to the optical volume.<p>For
|
||
|
UDF formatted volumes, *WX authority is required to the parent directory and
|
||
|
*X authority is required to each directory in the path name preceding the
|
||
|
parent directory. *W authority is required to the file being renamed.</p>
|
||
|
</td>
|
||
|
<td valign="top" headers="d0e331 ">API not supported.</td>
|
||
|
</tr>
|
||
|
<tr><th valign="top" class="firstcol" id="d0e340">Rename Directory (QHFRNMDR)</th>
|
||
|
<td valign="top" headers="d0e340 ">API not supported.</td>
|
||
|
<td valign="top" headers="d0e340 ">API not supported.</td>
|
||
|
</tr>
|
||
|
</tbody>
|
||
|
</table>
|
||
|
</div>
|
||
|
</div>
|
||
|
<div>
|
||
|
<div class="familylinks">
|
||
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="hfs.htm" title="Read this topic collection to learn how to program with the hierarchical file system (HFS).">Hierarchical file system (HFS) programming</a></div>
|
||
|
</div>
|
||
|
</div>
|
||
|
</body>
|
||
|
</html>
|