ibm-information-center/dist/eclipse/plugins/i5OS.ic.rzau8_5.4.0.1/hfsapitable.htm

345 lines
18 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<?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>