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

723 lines
20 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>Set Writer Status (QSPSETWI) 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. -->
<!-- Print SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited by Kersten Oct 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>Set Writer Status (QSPSETWI) API</h2>
<div class="box" style="width: 65%;">
<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%">Status changes</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of status changes</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">Format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Writer handle</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(16)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Spooled file handle</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">6</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: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Set Writer Status (QSPSETWI) API is used by a driver exit program to
update information about a spooled file that a writer is processing. This
information is used on certain spooled file displays. For example, the Work
with Spooled File (WRKSPLF) command displays the correct status, current page,
and total copies information.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Output queue lock</em></dt>
<dd>*EXCLRD
<p>The lock is on the output queue on which the spooled file resides.</p>
</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Status changes</strong></dt>
<dd>INPUT; CHAR(*)
<p>The variable that contains the status information to be updated.</p>
</dd>
<dt><strong>Length of status changes</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the status information provided by the status changes
parameter. The amount of data specified can be smaller than the information in
the format. However, all the status information may not be set
appropriately.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the file status changes.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#HDRSETW100">SETW0100</a></em></td>
<td align="left" valign="top">Contains the information about the writer and the
spooled file status information to be changed.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Writer handle</strong></dt>
<dd>INPUT; CHAR(16)
<p>The handle to the writer job. This handle is provided to the driver program
on a writer call to the driver exit program during initialization.</p>
</dd>
<dt><strong>Spooled file handle</strong></dt>
<dd>INPUT; CHAR(10)
<p>The spooled file handle of the current file for which the information is
being set. This handle is provided to the driver program on a writer call to
the driver exit program (using the process file option).</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><a name="HDRSETW100">SETW0100 Format</a></h3>
<p>The following table shows the information specified in the SETW0100 format.
For more details about the fields in the following table see, <a href=
"#HDRFIELDS">Field Descriptions</a>.</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%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Change status</td>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="center" valign="top">1</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Change current page</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="center" valign="top">2</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Change convert page</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="center" valign="top">3</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Change copies</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Change accounting pages</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="center" valign="top">5</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Change accounting lines</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="center" valign="top">6</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Change accounting bytes</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="center" valign="top">7</td>
<td align="left" valign="top">CHAR(5)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Status</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Current page</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Convert page</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Copies</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of pages for accounting</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of lines for accounting</td>
</tr>
<tr>
<td align="center" valign="top">26</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">PACKED (15,0)</td>
<td align="left" valign="top">Number of bytes for accounting</td>
</tr>
</table>
<br>
<h3><a name="HDRFIELDS">Field Descriptions</a></h3>
<p><strong>Change accounting bytes.</strong> Change the number of bytes that
have been processed for accounting purposes.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not change the accounting bytes.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Change the number of bytes that have been
processed for accounting to the value specified in the number of bytes for
accounting field.</td>
</tr>
</table>
<br>
<p><strong>Change accounting lines.</strong> Change the number of lines that
have been processed for accounting purposes.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not change the accounting lines.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Change the number of lines that have been
processed for accounting to the value specified in the number of lines for
accounting field.</td>
</tr>
</table>
<br>
<p><strong>Change accounting pages.</strong> Change the number of pages that
have been processed for accounting purposes.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not change the accounting pages.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Change the number of pages that have been
processed for accounting to the value specified in the number of pages for
accounting field.</td>
</tr>
</table>
<br>
<p><strong>Change convert page.</strong> Change the number of pages that have
been converted.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not change the number of pages that have been
converted.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Change the number of pages that have been
converted to the value specified in the convert page field.</td>
</tr>
</table>
<br>
<p><strong>Change copies.</strong> Change the number of copies currently
printing.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not change the number of the copies being
printed.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Change the number of the copies being printed to
the value specified in the copies field.</td>
</tr>
</table>
<br>
<p><strong>Change current page.</strong> Change the current page that has just
printed.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not change the current page that has just
printed.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Change the current page that has just printed to
the value specified in the current page field.</td>
</tr>
</table>
<br>
<p><strong>Change status.</strong> Change the status of the spooled file being
processed by the writer.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not change the status of the spooled
file.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Change the status of the spooled file to the
value specified in the status field.</td>
</tr>
</table>
<br>
<p><strong>Copies.</strong> The current number of copies of the spooled file
that have been processed by the driver program. The driver program should call
this API with the current number of copies processed after the processing of
each copy of the spooled file.</p>
<p><strong>Convert page.</strong> The number of the pages that have been
converted.</p>
<p><strong>Current page.</strong> The number of the page that is being
printed.</p>
<p><strong>Number of bytes for accounting.</strong> The cumulative number of
bytes to be logged for accounting.</p>
<p><strong>Number of lines for accounting.</strong> The cumulative number of
lines to be logged for accounting.</p>
<p><strong>Number of pages for accounting.</strong> The cumulative number of
pages to be logged for accounting.</p>
<p><strong>Reserved.</strong> Field must be set to blank.</p>
<p><strong>Status.</strong> The new status of the spooled file.</p>
<p>Possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top">1 (pending)</td>
<td align="left" valign="top">The spooled file is being converted.</td>
</tr>
<tr>
<td align="left" valign="top">2 (writing)</td>
<td align="left" valign="top">The spooled file is being selected by the
writer.</td>
</tr>
<tr>
<td align="left" valign="top">3 (sending)</td>
<td align="left" valign="top">The spooled file is being sent to a remote
system.</td>
</tr>
<tr>
<td align="left" valign="top">4 (printing)</td>
<td align="left" valign="top">The spooled file is being printed.</td>
</tr>
<tr>
<td align="left" valign="top">5 (separator)</td>
<td align="left" valign="top">The writer is printing separator pages.</td>
</tr>
<tr>
<td align="left" valign="top">6 (suspend)</td>
<td align="left" valign="top">The driver is still processing the file.</td>
</tr>
<tr>
<td align="left" valign="top">7 (interrupt)</td>
<td align="left" valign="top">The driver is done processing the file.</td>
</tr>
<tr>
<td align="left" valign="top">8 (ready)</td>
<td align="left" valign="top">The spooled file is ready for processing.</td>
</tr>
<tr>
<td align="left" valign="top">9 (held)</td>
<td align="left" valign="top">The spooled file has been held by the
driver.</td>
</tr>
<tr>
<td align="left" valign="top">10 (sent)</td>
<td align="left" valign="top">The spooled file has been sent to a remote
system.</td>
</tr>
<tr>
<td align="left" valign="top">11 (finished)</td>
<td align="left" valign="top">The driver is finished with the spooled
file.</td>
</tr>
</table>
<p><strong>Notes:</strong></p>
<ul>
<li>The driver program should use 6 (suspend) when a Hold Writer (HLDWTR)
command with option *PAGEEND or *CNTRLD has occurred, and the driver program
wishes to continue processing the spooled file when the writer is released
(RLSWTR).</li>
<li>The driver program should use 7 (interrupt) when an interruption of the
driver program has occurred during the process file option (20) of the printer
driver exit, and the driver program wishes to no longer continue processing the
spooled file.</li>
</ul>
<p>An example scenario using the suspend status:</p>
<ul>
<li>The writer calls driver program with the process file (20) process
option.</li>
<li>While the driver program is processing the file, a Hold Writer (HLDWTR)
command is issued with option *PAGEEND or *CNTRLD. The driver program can
periodically check for the holding of the writer using the <a href=
"QSPEXTWI.htm">Extract Writer Information (QSPEXTWI) API</a>.</li>
<li>The driver program finishes processing the spooled file to the next end of
page for the *PAGEEND option of the Hold Writer (HLDWTR) command, and finishes
processing the current copy of the spooled file for the *CNTRLD option of the
Hold Writer (HLDWTR) command.</li>
<li>The driver program then returns to the writer with the error code field of
the option specific output information of the print driver exit set to 10.</li>
<li>The writer then calls the driver program with the hold writer (40) process
option.</li>
<li>The driver program at this time uses the Set Writer Information (QSPSETWI)
API to set the status of the spooled file to suspend. This indicates to the
writer that the driver program wishes to continue processing the spooled file
when the Release Writer (RLSWTR) command has been issued.</li>
<li>If a Release Writer (RLSWTR) command is issued, the writer will call the
driver program with the reprocess file (21) process option.</li>
<li>The driver program can use the <a href="QSPEXTWI.htm">Extract Writer
Information (QSPEXTWI) API</a> to determine where to continue processing of the
spooled file. At this time the driver program would update the status of the
spooled file from suspended to whatever is appropriate.</li>
<li>Processing would continue as normal.</li>
</ul>
<br>
<p>An example scenario using the interrupt status follows:</p>
<ul>
<li>The writer calls the driver program with the initialize (10) process
option.</li>
<li>The driver program performs whatever initialization and setup is needed
before processing of spooled files begins. At this time the driver program
decides to allow interrupts to occur while it is processing a spooled file. The
driver program does this by setting the allow interrupt field in the option
specific output information of the print driver exit interface to 1 before
returning to the writer.</li>
<li>The writer then will call the driver program with the process file (20)
process option when a spooled file becomes eligible for processing.</li>
<li>While the driver program is processing a spooled file, that spooled file is
deleted using the Delete Spooled File (DLTSPLF) command, held using the Hold
Spooled File (HLDSPLF) command, or a restart page is specified using the Change
Spooled File Attributes (CHGSPLFA) command. Since the driver program allowed
interrupts, the driver program loses control to the writer immediately.</li>
<li>The writer calls the driver program with the reprocess file (21) process
option.</li>
<li>The driver program uses the <a href="QSPEXTWI.htm">Extract Writer
Information (QSPEXTWI) API</a> to determine whether a delete, hold, or restart
page change has been executed.</li>
<li>The driver program, upon detecting that a hold or delete operation has
occurred, then uses the Set Writer Information (QSPSETWI) API to set the status
of the spooled file to interrupt and returns control back to the writer.</li>
<li>Processing would continue as normal.</li>
</ul>
<br>
<h3>Error Messages</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF24B4 E</td>
<td width="85%" valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C19 E</td>
<td align="left" valign="top">Error occurred with receiver variable
specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF33CC E</td>
<td align="left" valign="top">No writer found for specified handle &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF33CD E</td>
<td align="left" valign="top">No file found for specified handle &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF34CB E</td>
<td align="left" valign="top">Value not valid for field &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<hr>
API introduced: V3R7
<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=
"print1.htm">Print APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</body>
</html>