267 lines
14 KiB
HTML
267 lines
14 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="Control file system functions" />
|
||
|
|
<meta name="abstract" content="Optical support provides Control File System (QHFCTLFS) functions to perform unique operations for the optical file system." />
|
||
|
|
<meta name="description" content="Optical support provides Control File System (QHFCTLFS) functions to perform unique operations for the optical file system." />
|
||
|
|
<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="cfsfunctions" />
|
||
|
|
<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>Control file system functions</title>
|
||
|
|
</head>
|
||
|
|
<body id="cfsfunctions"><a name="cfsfunctions"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Control file system functions</h1>
|
||
|
|
<div><p>Optical support provides Control File System (QHFCTLFS) functions
|
||
|
|
to perform unique operations for the optical file system.</p>
|
||
|
|
<div class="section"><p>The functions described below are optical specific functions that
|
||
|
|
are not otherwise available through the HFS APIs. Different functions are
|
||
|
|
available for directly attached and LAN-attached optical devices. </p>
|
||
|
|
<div class="p">The
|
||
|
|
following control file system functions are available for directly attached
|
||
|
|
media libraries:<ul><li><strong>SAV</strong>. Saves a held optical file.</li>
|
||
|
|
<li><strong>RLS</strong>. Releases a held optical file.</li>
|
||
|
|
<li><strong>SRD/VOL</strong>. Performs a sector read to an optical volume.</li>
|
||
|
|
<li><strong>SRD/DEV</strong>. Performs a sector read to an optical device.</li>
|
||
|
|
<li><strong>RTV/VOL</strong>. Returns volume-specific information.</li>
|
||
|
|
<li><strong>GET</strong>. Reads file data directly from the media with minimal caching.</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle"><span class="wintitle">Control File System functions for directly attached
|
||
|
|
optical devices</span></h4><p>The following functions are available
|
||
|
|
for directly attached optical devices.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Save held optical file function</h4><p>Use the Control
|
||
|
|
File System program to save a held optical file. A process must be allowed
|
||
|
|
read access to a held optical file to save it.</p>
|
||
|
|
<p>The following is the
|
||
|
|
syntax for the input buffer for the QHFCTLFS program: </p>
|
||
|
|
<p><samp class="codeph">'SAV'
|
||
|
|
+ '/' + held-file-path + '//' + destination-file-path</samp></p>
|
||
|
|
<div class="p">For example: <ul><li>Input data buffer: <samp class="codeph"> SAV/VOLUME1/DIRECTORY1/FILE1//VOLUME2/DIRECTORY2/FILE2 </samp></li>
|
||
|
|
<li>Input data buffer length: <samp class="codeph">54</samp></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<p>This function is also available using an option on the Work with
|
||
|
|
Held Optical File (WRKHLDOPTF) display. However, unlike the save option on
|
||
|
|
the Work with Held Optical File (WRKHLDOPTF) display, the save held optical
|
||
|
|
file function of the control file system API does not automatically release
|
||
|
|
a held file after it is saved. Therefore, an explicit release held optical
|
||
|
|
file request is needed afterward. </p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Release held optical file function</h4><p>Use the Control
|
||
|
|
File System program to clear the held status of a file and release the optical
|
||
|
|
file system from its obligation to write to the optical disk. A process must
|
||
|
|
be allowed read and write access to a held file in order to release it; this
|
||
|
|
means that no locks may currently be imposed on the file by other active jobs.</p>
|
||
|
|
<div class="p">The
|
||
|
|
following is the syntax for the input buffer for the QHFCTLFS program: <pre>'RLS' + '/' + held-file-path</pre>
|
||
|
|
</div>
|
||
|
|
<div class="p">For
|
||
|
|
example: <ul><li>Input data buffer: <samp class="codeph">RLS/VOLUME1/DIRECTORY1/FILE1</samp></li>
|
||
|
|
<li>Input data buffer length: <samp class="codeph">28</samp></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<p>This function is also available using an option on the Work Held
|
||
|
|
Optical File (WRKHLDOPTF) display. </p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Sector read function</h4><p>The Control file system program
|
||
|
|
can be used to do a sector reading of optical media. The sector read function
|
||
|
|
is useful if the application knows precisely where data is stored on optical
|
||
|
|
media. Sector read functions can be accomplished without opening and closing
|
||
|
|
files and independently of all HFS APIs. Multiple sectors may be read at one
|
||
|
|
time.</p>
|
||
|
|
<div class="p">There are two variations of the input buffer for issuing the Control
|
||
|
|
File System sector read function: <pre>SRD/VOL/volume_name/starting sector/number of sectors</pre>
|
||
|
|
<pre>SRD/DEV/device_name/starting sector/number of sectors</pre>
|
||
|
|
</div>
|
||
|
|
<p>Both return the range of sectors requested by the user. Sectors can
|
||
|
|
be requested from an optical volume or optical device. For example, if an
|
||
|
|
application wanted to read five sectors of optical volume <samp class="codeph">VOL01</samp> beginning
|
||
|
|
at sector 1000, the following is requested: <samp class="codeph">SRD/VOL/VOL01/1000/5</samp></p>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> DEV
|
||
|
|
is valid for stand-alone CD and DVD devices.</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Retrieve volume information function</h4><p>Use the Control
|
||
|
|
File System program to retrieve information about a particular volume.</p>
|
||
|
|
<div class="p">The
|
||
|
|
following is the input buffer format for the QHFCTLFS program: <pre>RTV/VOL/volume_name</pre>
|
||
|
|
</div>
|
||
|
|
<p>The
|
||
|
|
format of the information returned in the output buffer is identical to the
|
||
|
|
output file structure for volume attributes (QAMODVA). </p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Get file data</h4><p>You can use the Control File System
|
||
|
|
(QHFCTLFS) HFS API to read a block of data from a file directly into your
|
||
|
|
output buffer. This function improves performance when reading an entire file
|
||
|
|
sequentially or when reading large blocks of data. The optical file system
|
||
|
|
will not copy or cache the data as it does through normal Open, Read, and
|
||
|
|
Close Stream File HFS APIs. When doing random read operations to a file, the
|
||
|
|
Open, Read, and Close Steam File option may still provide the best performance.</p>
|
||
|
|
<div class="p">The
|
||
|
|
following restrictions apply when using this API:<ul><li>Align output buffer on a 512-byte boundary.</li>
|
||
|
|
<li>File offset must be 0 or a multiple of 4096.</li>
|
||
|
|
<li>Maximum-read size is 16␠384␠000 bytes.</li>
|
||
|
|
<li>The HFS API requires Shared No Update (*SHRNUP) access to the file.</li>
|
||
|
|
<li>Calling program must be in user (not system) state.</li>
|
||
|
|
<li>The HFS API requires *USE authority to the volume.</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="p">Here is the syntax for the input buffer for the QHFCTLFS program: <pre>'GET' + '/' + entire path + '//' + bytes to read + '/' + file offset</pre>
|
||
|
|
</div>
|
||
|
|
<div class="p"> The following example will read 15 MB from FILE.XXX, starting at
|
||
|
|
the beginning of the file with (offset=0):<ul><li>Input data buffer: GET/VOL1/DIR1/SUBDIR1/FILE.XXX//15728640/0</li>
|
||
|
|
<li>Input data buffer length: 42</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<p>The number of bytes read is returned in the Length of data returned
|
||
|
|
parameter. In the above example if FILE.XXX is only 50 KB in size, 51200 will
|
||
|
|
be returned in the field. Therefore, it is not necessary to know the file
|
||
|
|
size prior to issuing this request. Likewise, if 15728640 is returned in the
|
||
|
|
Length of data returned parameter, the file is at least 15 MB in size. More
|
||
|
|
read operations may be necessary to retrieve all the data.</p>
|
||
|
|
<p>It is not
|
||
|
|
required that the number of bytes to read be a multiple of 4096. However,
|
||
|
|
if the number is not a multiple of 4096, data may be read into the output
|
||
|
|
buffer beyond the number of bytes requested. This is because the device does
|
||
|
|
I/O in blocks of 4096 bytes. Therefore, reading data in multiples of 4096
|
||
|
|
bytes is advised in order to avoid this problem.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Errors from control file system (GET)</h4><p>The following
|
||
|
|
table shows some common application errors that may occur using this API.</p>
|
||
|
|
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><caption>Table 1. Common errors for the GET API</caption><thead align="left"><tr><th valign="top" id="d0e172">Message</th>
|
||
|
|
<th valign="top" id="d0e174">Error</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td valign="top" headers="d0e172 ">OPT1812 with 6030 as unexpected return code</td>
|
||
|
|
<td valign="top" headers="d0e174 ">File offset is beyond the end of file.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" headers="d0e172 ">OPT1812 with A950 as unexpected return code</td>
|
||
|
|
<td valign="top" headers="d0e174 ">Output buffer is not 512-byte aligned.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" headers="d0e172 ">OPT1860</td>
|
||
|
|
<td valign="top" headers="d0e174 ">Bytes to read is greater than the buffer size.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" headers="d0e172 ">OPT1812 with C060 as unexpected return code</td>
|
||
|
|
<td valign="top" headers="d0e174 ">Attempted to read more than 16␠384␠000 bytes.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" headers="d0e172 ">OPT1812 with C061 as unexpected return code</td>
|
||
|
|
<td valign="top" headers="d0e174 ">File offset is not a 4096 multiple.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" headers="d0e172 ">CPF1F48</td>
|
||
|
|
<td valign="top" headers="d0e174 ">Input buffer is not valid. Verify the syntax.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle"><span class="wintitle">Control file system functions for LAN-attached optical
|
||
|
|
devices</span></h4><div class="p">The following control file system functions are
|
||
|
|
available for LAN-attached media libraries.<ul><li>UPD/LAN - performs a dynamic refresh of the LAN volume lists.</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>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Update volume information</h4><p>Use the Control File System
|
||
|
|
program to retrieve information about a particular volume or to update the
|
||
|
|
internal list of available volumes on a LAN.</p>
|
||
|
|
<div class="p"> The following is the input
|
||
|
|
buffer format for the QHFCTLFS program: <pre>UPD/VOL/volume_name</pre>
|
||
|
|
</div>
|
||
|
|
<div class="p">It
|
||
|
|
performs the following: <ul><li>UPD/VOL/volume-name: Using this input buffer format returns the amount
|
||
|
|
of free space on a volume, total user space, media type, and opposite-side
|
||
|
|
volume ID. The format is shown here: <ul><li>Bytes (1-32): Opposite-side volume ID.</li>
|
||
|
|
<li>Bytes (33): Reserved.</li>
|
||
|
|
<li>Bytes (34-37): User free space on the volume. This is a 4-byte binary
|
||
|
|
field.</li>
|
||
|
|
<li>Bytes (38-41): Total free space on the volume. This consists of the user
|
||
|
|
free space on the volume plus the reserved space on the volume. The reserved
|
||
|
|
space on the volume is determined when setting the volume-full threshold for
|
||
|
|
the volume. This is a 4-byte binary field.</li>
|
||
|
|
<li>Bytes (42): Media type. This is a 1-byte binary field that can have
|
||
|
|
the following values. <ul><li>0 = Nonvalid Media or 3431 Standalone Drive</li>
|
||
|
|
<li>1 = Write Once Read Many (WORM) media</li>
|
||
|
|
<li>2 = Rewriteable media</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>Bytes (43): Magnitude of free space on the volume. This is a 1-byte binary
|
||
|
|
field that can have the following values: <ul><li>0 = Space field is in number of bytes.</li>
|
||
|
|
<li>1 = Space field is in number of kilobytes (1024).</li>
|
||
|
|
<li>2 = Space field is in number of megabytes (1048576).</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>Bytes (44): Magnitude of Total Space on the Volume. This is a 1-byte
|
||
|
|
binary field that can have the following values: <ul><li>0 = Space field is in number of bytes.</li>
|
||
|
|
<li>1 = Space field is in number of kilobytes (1024).</li>
|
||
|
|
<li>2 = Space field is in number of megabytes (1048576).</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>UPD/LAN: Using this input buffer format updates an internal list of available
|
||
|
|
volumes on all activated servers. You can perform this function after adding
|
||
|
|
or removing cartridges from data servers.</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Retrieve volume information function</h4><p>Use the Control
|
||
|
|
File System program to retrieve information about a particular volume.</p>
|
||
|
|
<div class="p">The
|
||
|
|
following is the input buffer format for the QHFCTLFS program:<pre>RTV/VOL/volume_name</pre>
|
||
|
|
</div>
|
||
|
|
<p>The
|
||
|
|
format of the information returned in the output buffer is identical to the
|
||
|
|
output file structure for volume attributes (QAMODVA). </p>
|
||
|
|
<p>The system uses
|
||
|
|
format QAMODVA for volumes in all optical device types. While the format is
|
||
|
|
the same, not all fields contain a value for LAN volumes. </p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Retrieve directory information function</h4><p>Use the
|
||
|
|
Control File System program to retrieve a list of files and subdirectories
|
||
|
|
for a particular directory.</p>
|
||
|
|
<div class="p">The following is the input buffer for the
|
||
|
|
QHFCTLFS program:<pre>RTV/DIR/volume_name/directory_name</pre>
|
||
|
|
</div>
|
||
|
|
<div class="p">The
|
||
|
|
directory information is returned in the output buffer in the following format: <ul><li>CBdirectoryBCBdirectoryBCBfilenameBCBfilenameBB, whereas the following
|
||
|
|
are: <ul><li>C <ul><li>D = Directory entry</li>
|
||
|
|
<li>F = File name entry</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>B = EBCDIC blank</li>
|
||
|
|
<li>BB = Double EBCDIC blanks to indicate end of string</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<p>The output buffer must be at least 31 KB long.</p>
|
||
|
|
</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>
|