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

499 lines
16 KiB
HTML
Raw 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>Read SNADS File Server Object (QZDRDFSO) 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. -->
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
<!--File Edited October 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>Read SNADS File Server Object (QZDRDFSO) API</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;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="50%">File server object handle</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(32)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="LEFT" valign="TOP">Operation requested</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="LEFT" valign="TOP">File server object data length</td>
<td align="LEFT" valign="TOP">Output</td>
<td align="LEFT" valign="TOP">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="LEFT" valign="TOP">File server name structure</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Char(68)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="LEFT" valign="TOP">Resume position</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="LEFT" valign="TOP">Buffer area</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="LEFT" valign="TOP">Bytes provided in buffer area</td>
<td align="LEFT" valign="TOP">Input</td>
<td align="LEFT" valign="TOP">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="LEFT" valign="TOP">Bytes available in buffer area</td>
<td align="LEFT" valign="TOP">Output</td>
<td align="LEFT" valign="TOP">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">9</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>
&nbsp;&nbsp;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Read SNADS File Server Object (QZDRDFSO) API has four operations that
can be used to read an FSO. The three required operations are <strong>initiate
read</strong>, <strong>read</strong>, and <strong>terminate read</strong>. The
initiate read operation opens up an existing file server object that is based
on the information given to it by the caller. Once this operation is called,
the read operation can be used to read the data contained in the file server
object. The read operation can be called multiple times to read all the data.
After all read operations are completed, the terminate read operation must be
issued to close the file server object.</p>
<p>The optional operation provided on the QZDRDFSO API is <strong>initiate read
location</strong>. This operation can be used to start reading the file server
object at a specific location.</p>
<p>The QZDRDFSO API operates on SNADS general file server objects and DIA file
server objects. The interface to both of these types of objects is essentially
the same.</p>
<br>
<h3>SNADS General File Server</h3>
<p>The SNADS general file server provides a means for SNADS support to save the
data object portion of a distribution request. The general file server stores
objects in a byte stream format. No transformations are done to the data when
it is written into or read out of a general file server object. The SNADS
general file server objects are owned by QSNADS and are stored in the QUSRSYS
library.</p>
<p>The SNADS general file server can support objects up to 4 gigabytes. Each
file server object space can be only 16MB large, but the SNADS general file
server has the capability of chaining file server objects together. If the
amount of data is greater than 16MB, the SNADS general file server creates as
many file server object spaces as necessary and then chains them together. This
function is transparent to the caller of the SNADS general file server
routines.</p>
<p>The SNADS general file server read operations are as follows:</p>
<p><strong>Initiate Read</strong></p>
<p>The initiate read operation does the setup necessary to read the general
file server object. This includes finding the object specified by the object
handle in the input parameters. This operation must be the first called before
any of the other read operations can be used for the specific file server
object. The initiate read operation only needs to be called once in the
sequence of read operations.</p>
<p><strong>Read</strong></p>
<p>The caller of the read operation must specify what object is to be read,
where to put the data that is read, and how much data is to be read. If the
amount of actual data is less than the size of the caller's buffer space (that
is, where the data will be read in), the read operation reads as much data as
it can and then returns. Because a space can be a maximum of 16MB, the caller's
buffer space should be no more than 16MB, and the caller should not request
more data than 16MB to be read. If the object being read is larger than 16MB,
the caller must call the read operation more than once to read all the data. If
more than one read is done, the SNADS general file server read operation keeps
a marker in the data (offset inside the object) so that on subsequent read
operations, the read operation knows where to start reading.</p>
<p><strong>Terminate Read</strong></p>
<p>The terminate read operation does the cleanup processing after you have
completed reading the data in the file server object. After this operation is
called, the file server object may still exist, but an initiate read operation
must be done to read the file server object again.</p>
<p><strong>Initiate Read Location</strong></p>
<p>The initiate read location operation is similar to the initiate read
operation, but allows a caller to set up a general file server object to begin
reading at a specified location rather than at the beginning of the object.
This operation also needs to be called only once in the sequence of read
operations. The caller of this operation must pass in the resume position of
where to continue reading the file server object. This number is based on how
many bytes were read when the terminate read operation was called.</p>
<br>
<h3>DIA File Server</h3>
<p>The DIA file server provides a means for SNADS support to save the data
object portion of an OfficeVision distribution request. The DIA file server
objects are of the type *DTO (distribution tracking object), are owned by the
QDOC user profile, and are stored in the QUSRSYS library.</p>
<p>The DIA file server can support objects up to 2 gigabytes. Each file server
object space can be only 16MB large, but the DIA file server has the capability
of chaining file server objects together. If the amount of data is greater than
16MB, the DIA file server creates as many file server object spaces as
necessary and then chains them together. This function is transparent to the
caller of the DIA file server routines.</p>
<p>The DIA file server read operations are as follows:</p>
<p><strong>Initiate Read</strong></p>
<p>The initiate read operation does the setup necessary to read the DIA
distribution tracking object. This includes finding the object specified by the
object handle in the input parameters. This operation must be the first
operation called before any of the other read operations can be used for the
specific file server object.</p>
<p><strong>Read</strong></p>
<p>The caller of the read operation must specify what document object is to be
read, where to put the data that is read, and how much data is to be read. If
the amount of actual data is less than the size of the caller's buffer space
(that is, where the data will be read in), the read operation reads as much
data as it can and then returns.</p>
<p>Because a space can be a maximum of 16MB, the caller's buffer space should
be no more than 16MB, and the caller should not request more data than 16MB to
be read. If the document object being read is larger than 16MB, the caller must
call the read operation more than once to read all the data. If more than one
read operation is done, the DIA file server read operation keeps a marker in
the data (offset inside the object) so that on subsequent read operations, the
read operation knows where to start reading.</p>
<p><strong>Terminate Read</strong></p>
<p>The terminate read operation should be called when you have completed
reading the document. This operation closes the document object.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*EXCLUDE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>File server object handle</strong></dt>
<dd>INPUT; CHAR(32)
<p>The necessary linkage to the file server object is contained in this
parameter. This parameter must be specified on all file server read operations.
The value of this parameter should be taken from the file server object handle
that was returned on the call to the Create SNADS File Server Object (QZDCRFSO)
API.</p>
</dd>
<dt><strong>Operation requested</strong></dt>
<dd>INPUT; BINARY(4)
<p>The operation the caller is requesting. Valid values for this parameter are
as follows:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>Initiate read</em></td>
<td valign="top">1</td>
</tr>
<tr>
<td valign="top"><em>Read</em></td>
<td valign="top">2</td>
</tr>
<tr>
<td valign="top"><em>Terminate read</em></td>
<td valign="top">3</td>
</tr>
<tr>
<td valign="top"><em>Initiate read location</em></td>
<td valign="top">9</td>
</tr>
</table>
<br>
</dd>
<dt><strong>File server object data length</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The total length of the file server object being read. This parameter is
returned on the initiate read and the initiate read location functions.</p>
</dd>
<dt><strong>File server name structure</strong></dt>
<dd>INPUT; CHAR(68)
<p>The file server name (either DIA or SNADS) and the server name length.</p>
<table border width="80%">
<tr>
<th align="CENTER" valign="BOTTOM" colspan="2">Offset</th>
<th align="LEFT" valign="BOTTOM" rowspan="2">Type</th>
<th align="LEFT" valign="BOTTOM" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Length of file server name</td>
</tr>
<tr>
<td align="CENTER" valign="TOP">4</td>
<td align="CENTER" valign="TOP">4</td>
<td align="LEFT" valign="TOP">CHAR(64)</td>
<td align="LEFT" valign="TOP">File server name</td>
</tr>
</table>
<p>The length of the file server name is the number of bytes in the file server
name defined by the SNADS architecture. Valid values for length of the file
server name are as follows:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>4</em></td>
<td valign="top">SNADS general file-server name</td>
</tr>
<tr>
<td valign="top"><em>4</em></td>
<td valign="top">DIA file-server name</td>
</tr>
</table>
<p>The file server name is the name value defined by the SNADS architecture for
the file server that is to be used. The only file servers available with this
API are the SNADS general file server and the DIA file server. Valid values for
file server name:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>'21F0F0F6'X</em></td>
<td valign="top">SNADS general file-server name</td>
</tr>
<tr>
<td valign="top"><em>'20F0F0F1'X</em></td>
<td valign="top">DIA file-server name</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Resume position</strong></dt>
<dd>INPUT; BINARY(4)
<p>The place where the initiate read location operation is to resume reading in
the FSO. This parameter is ignored on the initiate read, read, and terminate
read operations. Valid values for this parameter follow:</p>
<p><em>1 through the current file server object data length</em></p>
</dd>
<dt><strong>Buffer area</strong></dt>
<dd>INPUT; CHAR(*)
<p>A buffer area defined by the caller. It is used by the read operation to
store the data that is being read.</p>
</dd>
<dt><strong>Bytes provided in buffer area</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of bytes of data that can be read into the buffer area. Valid
values for this parameter are as follows:</p>
<p><em>1 byte through 16 megabytes</em></p>
</dd>
<dt><strong>Bytes available in buffer area</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The number of actual bytes of data that was read into the buffer area.</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">CPF24B4 E</td>
<td valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3A09 E</td>
<td valign="top">System error.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3A1A E</td>
<td valign="top">Location in file server object not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3A1B E</td>
<td valign="top">File server object operation not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3A1C E</td>
<td valign="top">File server object request not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3A1D E</td>
<td valign="top">Limit of number of open file server objects exceeded.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3A1E E</td>
<td valign="top">End of data reached in file server object.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3A15 E</td>
<td valign="top">File server object not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3A17 E</td>
<td valign="top">Permanent server error.</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">CPF3CF1 E</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
<p>API Introduced: V3R6</p>
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"off1a.htm">Office APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</body>
</html>