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

546 lines
14 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>Build Separator Pages (QSPBSEPP) 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>Build Separator Pages (QSPBSEPP) 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%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</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 receiver variable</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">Printer device name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Printer data stream type</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">Type of separator page</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Qualified name of separator page program</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">8</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">9</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">10</td>
<td align="left" valign="top">Drawer for separator page</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">11</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 Build Separator Pages (QSPBSEPP) API builds the system separator page to
be printed for the spooled file. A user exit program is called to build the
separator page or the system default is used. The separator page is returned in
the receiver variable parameter. This data can then be sent to the printer.
This API is only valid when called from a program that was called by a printer
writer program. This API is not valid when called from a program that was
called by a remote writer program.</p>
<p>If Build Separator Pages (QSPBSEPP) API encounters a problem when running a
separator exit program, the default system separator will be returned. No error
will be signalled or returned in the error code parameter.</p>
<br>
<h3>Authorities and Locks</h3>
<p>If a qualified separator page program is specified or implied the user must
have *EXECUTE authority to the program and the library the program is stored
in.</p>
<p>The user must have *USE authority to the printer device description.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that receives the information requested. You can
specify the size of the area to be smaller than the format requested as long as
you specify the length parameter correctly. As a result, the API returns only
the data that the area can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable. The amount of data is truncated if the
receiver variable is too small. Anything less than 8 bytes is not valid.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the information returned in the receiver variable.</p>
<p>The valid format name is:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td valign="top"><em><a href="#HDRBSEP100">SEPP0100</a></em></td>
<td valign="top">The formatted separator page data.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Printer device name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the printer device description for the writer that was
started.</p>
</dd>
<dt><strong>Print data stream type</strong></dt>
<dd>INPUT; CHAR(10)
<p>The type of data stream recognized by the printer writer. This is used to
determine the type of data to generate for the separator page.</p>
<p>The valid special value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td valign="top"><em>*SCS</em></td>
<td valign="top">Systems Network Architecture (SNA) character string</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Type of separator</strong></dt>
<dd>INPUT; CHAR(10)
<p>The type of separator page to be built.</p>
<p>Valid values are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td valign="top"><em>*FILE</em></td>
<td valign="top">A file separator page is returned in the separator page data.
This separator is printed before each copy of a spooled file.</td>
</tr>
<tr>
<td valign="top"><em>*JOB</em></td>
<td valign="top">A job separator page is returned in the separator page data.
This separator is printed between spooled files created by different jobs.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Qualified name of separator page program</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the separator page exit program to use to build the separator
page. The first 10 characters contain the separator page program name and the
second 10 characters contain the name of the library in which the separator
page program is located.</p>
<p>The following special values are supported for the program name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>*SYSDFT</em></td>
<td valign="top">The system default separator page is generated.</td>
</tr>
<tr>
<td valign="top"><em>*DEVD</em></td>
<td valign="top">The separator program specified in the device description for
the printer is used.</td>
</tr>
</table>
<br>
<p>The following special values are supported for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>*LIBL</em></td>
<td valign="top">The library list of the writer job is used to locate the
message file.</td>
</tr>
<tr>
<td valign="top"><em>*CURLIB</em></td>
<td valign="top">The current library for the writer job is used to locate the
message file.</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 at initialization time (the
initialize option).</p>
</dd>
<dt><strong>Spooled file handle</strong></dt>
<dd>INPUT;CHAR(10)
<p>The spooled file handle to the current file that is being processed by the
writer. 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>Drawer for separator page</strong></dt>
<dd>INPUT; BINARY(4)
<p>The following values are allowed:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The separator drawer specified in the device
description for the printer device name is used.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1 - 255</em></td>
<td align="left" valign="top">The drawer from which the separator page is
printed.</td>
</tr>
</table>
<br>
</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="HDRBSEP100">SEPP0100 Format</a></h3>
<p>The following table shows the information returned for the SEPP0100 format.
For more details about the fields in the following table see, <a href=
"#HDRFIELDP">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%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to separator page data</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">Size of separator page data</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Separator page data</td>
</tr>
</table>
<br>
<h3><a name="HDRFIELDP">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The number of bytes of data available to
be returned. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Offset to separator page data.</strong> The byte offset to the
separator page data (from the beginning of the format).</p>
<p><strong>Separator page data.</strong> The separator page data, which
includes printer commands and the data to be printed.</p>
<p><strong>Size of separator page data.</strong> The size of the separator page
data, in bytes.</p>
<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">CPF2207 E</td>
<td width="85%" valign="top">Not authorized to use object &amp;1 in library
&amp;3 type *&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2702 E</td>
<td align="left" valign="top">Device description &amp;1 not found.</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">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">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C40 E</td>
<td align="left" valign="top">Spooled file &amp;4 not found.</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">CPF3309 E</td>
<td align="left" valign="top">No files named &amp;1 are active.</td>
</tr>
<tr>
<td align="left" valign="top">CPF334C E</td>
<td align="left" valign="top">Value &amp;1 not valid for print data stream
type.</td>
</tr>
<tr>
<td align="left" valign="top">CPF334D E</td>
<td align="left" valign="top">Value &amp;1 not valid for type of
separator.</td>
</tr>
<tr>
<td align="left" valign="top">CPF334E E</td>
<td align="left" valign="top">Value &amp;1 not valid for separator drawer.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3344 E</td>
<td align="left" valign="top">File &amp;1 number &amp;2 no longer in the
system.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9811 E</td>
<td align="left" valign="top">Program &amp;1 in library &amp;2 not found.</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>
<br>
<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>