379 lines
15 KiB
HTML
379 lines
15 KiB
HTML
<!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>Write to SNADS File Server Object (QZDWTFSO) 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>Write to SNADS File Server Object (QZDWTFSO) API</h2>
|
|
|
|
<div class="box" style="width: 75%;">
|
|
<br>
|
|
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">Error code</td>
|
|
<td align="LEFT" valign="TOP">I/O</td>
|
|
<td align="LEFT" valign="TOP">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Default Public Authority: *EXCLUDE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
|
|
</div>
|
|
|
|
<p>The Write to SNADS File Server Object (QZDWTFSO) API has four operations that can be used to write to an FSO. The first two operations, <strong>write</strong> and <strong>terminate write</strong>, are required to completely write to an FSO. The write operation copies the data from the caller's buffer into the file server object. This operation may be called multiple times to write all the data. The terminate write operation must be done after all the writes are completed. This operation closes the file server object and makes the FSO available to other processes to read it.</p>
|
|
|
|
<p>The two optional operations are <strong>suspend write</strong> and <strong>resume write</strong>, both of which are supported only by the SNADS general file server. These operations can be used to suspend the writing of a SNADS general FSO and then return to writing (resume) at a later time. These operations could be used in conjunction with the initiate read location operation.</p>
|
|
|
|
<p>An example of the usage of these operations follows. When data is being sent from one system to another, the sender on the source side is reading the file server object and the receiver is writing the data received into a new FSO on the target side. If the communications connection goes down during the middle of this data transmission, the receiver issues the suspend write operation. When the communications connection comes back up, the sender starts reading again using the initiate read location operation (part of the Read SNADS File Server Object (QZDRDFSO) API), and the receiver starts writing again using the resume write operation.</p>
|
|
|
|
<p>There are two types of file server objects that the QZDWTFSO 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. There are four SNADS general file server write operations and two DIA file server write operations provided by this API.</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. 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 only be 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 APIs. After a chain of FSOs is created, this chain is still referred to by <strong>one</strong> file server object handle.</p>
|
|
|
|
<p>The following paragraphs describe each of the SNADS general file server write operations.</p>
|
|
|
|
<p><strong>Write</strong></p>
|
|
|
|
<p>The write operation copies the contents of the caller's buffer to the file server object. If the data being written is greater than 16MB, the write operation automatically creates new file server object spaces and chains them together. The caller may call the write operation multiple times to write all the data.</p>
|
|
|
|
<p><strong>Terminate Write</strong></p>
|
|
|
|
<p>Once this operation is called, no other write operations can be done on the specific file server object. Also, the file server object cannot be read or have an access ID assigned to it until the terminate write operation completes.</p>
|
|
|
|
<p><strong>Suspend Write</strong></p>
|
|
|
|
<p>The suspend write operation allows the caller to temporarily suspend the writing of an object. This operation does not assign an access ID to the file server object, nor does it increment the objects usage count.</p>
|
|
|
|
<p><strong>Resume Write</strong></p>
|
|
|
|
<p>The resume write operation does the setup needed to resume writing into a file server object. It is similar to the create file server object API since it needs to be called only once before write operations can be done. The caller of this operation must pass in the starting position of where to continue writing in the file server object. This number is based on how many bytes were written when the suspend write operation was called.</p>
|
|
|
|
<p><strong>Note:</strong> The resume write operation also checks the system storage threshold to make sure there is enough room for the rest of the data to be written.</p>
|
|
|
|
<br>
|
|
<h3>DIA File Server</h3>
|
|
|
|
<p>The DIA file server provides a means for SNADS to save the data object portion of an OfficeVision distribution request. The DIA file server objects are of 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 only be 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 following sections describe each of the DIA file server write operations.</p>
|
|
|
|
<p><strong>Write</strong></p>
|
|
|
|
<p>The write operation copies the contents of the caller's buffer to the DIA document object. If the data being written is greater than 16MB, the write operation automatically creates new spaces and chains them together. The caller may call the write operation multiple times to write all the data.</p>
|
|
|
|
<p><strong>Terminate Write</strong></p>
|
|
|
|
<p>When the caller completes writing the entire document, the terminate write operation must be called to save the distribution tracking object. The DIA document will also be closed. The DTO and the document are not available to other processes until this operation is called. Once this operation is called, no other write operations can be done on the specific file server object. Also, the file server object cannot be read or have an access ID assigned to it until the terminate write operation completes.</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. The value of this parameter should be taken from the FSO 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 requested is used by the QZDWTFSO API to determine which operation, write, terminate write, suspend write, or resume write, the caller is requesting. Valid values for this parameter are as follows:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td valign="top"><em>Write</em></td>
|
|
<td valign="top">5</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Terminate write</em></td>
|
|
<td valign="top">6</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Suspend write</em></td>
|
|
<td valign="top">7</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Resume write</em></td>
|
|
<td valign="top">8</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 that has been written. This parameter is returned on the terminate write, suspend write, and resume write 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 resume write function is to resume writing in the FSO. This parameter is ignored on the write, terminate write, and suspend write functions. Valid values for this parameter are as follows:</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>The data that the caller wants to write into a file server object.</p></dd>
|
|
|
|
<dt><strong>Bytes provided in buffer area</strong></dt>
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The number of bytes of data in the buffer area that are to be written to the file server object. Valid values for this parameter are as follows:</p>
|
|
|
|
<p><em>1 byte through 16 megabytes</em></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">CPF3A0D E</td>
|
|
<td valign="top">Temporary server error.</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">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 &1 in library &2 ended. Reason code &3.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
<hr>
|
|
API Introduced: V3R6
|
|
|
|
<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>
|