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

594 lines
17 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>Open Print Application (QUIOPNPA) 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. -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--Edited by Kersten Nov 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Open Print Application (QUIOPNPA) API</h2>
<div class="box" style="width: 80%;">
<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%">Application handle</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Qualified panel group name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Application scope</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Exit parameter interface</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Qualified name of printer device file</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Alternative file name</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">Share open data path</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">User data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</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;Optional Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">10</td>
<td align="left" valign="top" width="50%">Open data receiver</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">11</td>
<td align="left" valign="top">Length of open data receiver</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">Length of available open data</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</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 Open Print Application (QUIOPNPA) API initiates a UIM print application
by opening the panel group that the application program specifies. The QUIOPNPA
API and the Close Application (QUICLOA) API must be used in pairs to open and
close each UIM print application.</p>
<p>Multiple applications can be opened at the same time. Each open application
contains a complete set of dialog variables and active lists, and is
independent of other open applications. The same panel group can be opened more
than once per job, but each call of the QUIOPNPA API initiates a new UIM print
application and returns a unique application handle.<br>
</p>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Library Authority</em></dt>
<dd>*READ</dd>
<dt><em>Panel Group Authority</em></dt>
<dd>*USE</dd>
<dt><em>Panel Group Lock</em></dt>
<dd>*SHRRD</dd>
<dt><em>Printer Device File Authority</em></dt>
<dd>*USE</dd>
<dt><em>Printer Device File Lock</em></dt>
<dd>*SHRNUP</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Application handle</strong></dt>
<dd>OUTPUT; CHAR(8)
<p> The application handle for the open application. The Open Display
Application (QUIOPNDA) API returns a unique handle for each application opened.
This handle must be provided as a parameter to every other UIM API that
operates on the application, including the QUICLOA API, which must be used to
close the application.</p>
</dd>
<dt><strong>Qualified panel group name</strong></dt>
<dd>INPUT; CHAR(20)
<p> The name of the *PNLGRP object opened for this UIM application. The first
10 characters contain the name of the *PNLGRP object, and the second 10
characters contain the name of the library in which the panel group resides.
These special values can be used for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Application scope</strong></dt>
<dd>INPUT; BINARY(4)
<p> The scope of the resources for the application. The UIM uses the scope to
determine whether or not to automatically close the application when reclaim
resource processing is performed through the Reclaim Resource (RCLRSC) command,
the Reclaim Activation Group (RCLACTGRP) command, or the End Request (ENDRQS)
command. During reclaim resource processing, the UIM closes all applications
whose scope is no longer active.</p>
<p> One of the following values must be used:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top" nowrap><em>-1</em></td>
<td align="left" valign="top">The calling program is the scope for the
application. If the calling program is an original program model (OPM) program
and the application program is no longer active, the UIM will automatically
close the application during reclaim resource processing. If the calling
program is an Integrated Language Environment (ILE) program and the activation
group mark is no longer active, the UIM will automatically close the
application during reclaim resource processing.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The job is the scope for the application. The
application is not automatically closed by the UIM until the job is ended.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Exit parameter interface</strong></dt>
<dd>INPUT; BINARY(4)
<p> The type of parameter interface used with exit programs and programs called
as a result of the CALL dialog command for the UIM application being
opened.</p>
<p> All exit and CALL programs receive a single parameter or multiple
parameters, which are space pointers to information describing the state of the
UIM application.</p>
<p> One of the following values must be used:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Used by programs written in languages that can
efficiently process structures.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Used by programs written in languages that cannot
efficiently process structures. This value indicates that all application
programs called as exits or as a result of the CALL dialog command accept the
parameter lists described for interface level 1.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Used by programs written in languages that cannot
efficiently process structures. This value indicates that all application
programs called as exits or as a result of the CALL dialog command accept the
parameter lists described for interface level 2.</td>
</tr>
</table>
<p> For a detailed description of the exit parameter lists, and for a
description of the type of structure passed for each type of exit and CALL
program, see <a href="uim1.htm">User Interface Manager Exit Programs</a>.</p>
</dd>
<dt><strong>Qualified name of printer device file</strong></dt>
<dd>INPUT; CHAR(20)
<p> The name of the printer device file used in print operations. The first 10
characters contain the *FILE object name, and the second 10 characters contain
the name of the library in which the printer device file resides. These special
values can be used for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Alternative file name</strong></dt>
<dd>INPUT; CHAR(10)
<p> An alternative name for the spooled file. The following special value can
be used:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*NONE</em></td>
<td align="left" valign="top">There is no alternative name for the spooled
file. The name of the spooled file is the name of the printer device file.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Share open data path</strong></dt>
<dd>INPUT; CHAR(1)
<p> Determines whether or not the printer device file's open data path (ODP) is
shared. Sharing the ODP allows multiple UIM applications to print to the same
spooled file. One of the following values must be used:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">The ODP is shared.</td>
</tr>
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">The ODP is not shared.</td>
</tr>
<tr>
<td align="left" valign="top"><em>F</em></td>
<td align="left" valign="top">Use the share value of the print file.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>User data</strong></dt>
<dd>INPUT; CHAR(10)
<p> User data associated with the spooled file. This data becomes an attribute
of the spooled file. The following special values can be used:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*FILE</em></td>
<td align="left" valign="top">The user data of the spooled file will be set to
the user data value of the printer file being opened.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NONE</em></td>
<td align="left" valign="top">There is no user data associated with the spooled
file. The user data value of the printer file being opened will be set to
blanks.</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>Optional Parameter Group</h3>
<dl>
<dt><strong>Open data receiver</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that is to receive the open data information
requested. For the format of the open data receiver variable, see <a href=
"#HDRFMTDT3">Format of Data Returned</a>.</p>
</dd>
<dt><strong>Length of open data receiver</strong></dt>
<dd>INPUT; BINARY(4)
<p>The amount of data the application program is prepared to receive. If the
length specified is larger than the amount of data available, the receiver is
not changed beyond the amount of data available. If the length specified is
greater than the actual length of the open data receiver parameter,
unpredictable results may occur.</p>
</dd>
<dt><strong>Length of available open data</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The length of all open data available. All available open data is returned
if enough space is provided.</p>
</dd>
</dl>
<br>
<h3><a name="HDRFMTDT3">Format of Data Returned</a></h3>
<p>The format of the data available, returned in the open data receiver
parameter, is as follows:</p>
<p>One of the following values is returned:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>CHAR(1)</em></td>
<td align="left" valign="top">Whether or not an error occurred while attempting
to obtain the conversion tables needed to process the panel group. The
conversion tables are needed when the CHRID attribute of the panel group is not
equal to the CHRID attribute of the device, or when the CHRID attribute of the
panel group is *JOBCCSID and the job CCSID is not equal to the device CHRID. A
CPD6A2A diagnostic message will be logged in the job log for each conversion
table that is not found.
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">No error occurred while obtaining the conversion
tables or the conversion tables were not necessary.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">An error occurred while obtaining the conversion
tables.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>CHAR(1)</em></td>
<td align="left" valign="top">Whether or not the conversion of data from the
job to the device and from the device to the job will result in loss of
fidelity of the data. Conversion will be done when the CHRID attribute of the
panel group is not equal to the CHRID attribute of the device, or when the
CHRID attribute of the panel group is *JOBCCSID and the job CCSID is not equal
to the device CHRID.
<p>One of the following values is returned:</p>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">No loss of fidelity will occur.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">Loss of fidelity may occur on the
conversions.</td>
</tr>
</table>
</td>
</tr>
</table>
<br>
<h3>Error Messages</h3>
<table width="100%" 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 valign="top">CPF3C90 E</td>
<td valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A1C E</td>
<td valign="top" align="left">Unable to add print function.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A1E E</td>
<td valign="top" align="left">Object cannot be used with this device or print
file.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A11 E</td>
<td valign="top" align="left">Value is not correct. Reason code is &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A12 E</td>
<td valign="top" align="left">Unable to open panel group.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A17 E</td>
<td valign="top" align="left">Panel group &amp;1 in library &amp;2 is not at
the current release level.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A2A E</td>
<td valign="top" align="left">Value for Application Scope parameter not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A2E E</td>
<td valign="top" align="left">Value for Exit Parameter Interface parameter not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A24 E</td>
<td valign="top" align="left">Parameter &amp;1 not passed correctly.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A25 E</td>
<td valign="top" align="left">Return code length of &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A26 E</td>
<td valign="top" align="left">Resources not available to open application.</td>
</tr>
<tr>
<td align="left" valign="top">CPF6A3A E</td>
<td valign="top" align="left">Value for Open Data Receiver is not valid. Reason
code &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9850 E</td>
<td valign="top" align="left">Override of printer file &amp;1 not allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td valign="top" align="left">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R2
<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=
"uim1.htm">User Interface Manager (UIM) APIs</a> | <a href="aplist.htm">APIs by
category</a> </td>
</tr>
</table>
</body>
</html>