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

633 lines
18 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>Retrieve Output Information (QWSRTVOI) 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- File cleanup completed by v2cdijab -->
<!--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>Retrieve Output Information (QWSRTVOI) 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%">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">Qualified job name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(26)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Internal job identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(16)</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 Retrieve Output Information (QWSRTVOI) API gives the caller information
on either the last active record format involved in an output operation to the
requester device for the specified job or all the active record formats
currently displayed on the requester device for the specified job.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Job Authority</em></dt>
<dd>*JOBCTL if the job for which information is retrieved has a different user
profile from that of the job that calls the QWSRTVOI API.<br>
<br>
</dd>
<dt><em>Device Authority</em></dt>
<dd>*READ authority to the display device that the interactive job is using as
the *REQUESTER device.<br>
<br>
</dd>
<dt><em>File Authority</em></dt>
<dd>*READ authority to the display file that is active currently.</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p> The variable that is to receive the information requested. You can specify
the size of this area to be smaller than the format requested if you specify
the length of receiver variable 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. If this value is larger than the
actual size of the receiver variable, the result may not be predictable. The
minimum length is 8 bytes.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p> The content and format of the information returned for the job. The
following format names can be specified:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>OINF0100</em></td>
<td align="left" valign="top">Display file and last record format name involved
in an output operation.</td>
</tr>
<tr>
<td align="left" valign="top"><em>OINF0200</em></td>
<td align="left" valign="top">Display file and a list of active records
currently on the display.</td>
</tr>
</table>
<p> For more information, see <a href="#HDROINF1">OINF0100 Format</a> or
<a href="#HDROINF2">OINF0200 Format</a>.</p>
</dd>
<dt><strong>Qualified job name</strong></dt>
<dd>INPUT; CHAR(26)
<p> The name of the job for which information is to be returned. The qualified
job name has three parts:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>Job name</em></td>
<td align="left" valign="top">CHAR(10). A specific job name or one of the
following special values:
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>*</em></td>
<td align="left" valign="top">The job in which this program is running. The
rest of the qualified job name parameter must be blank.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INT</em></td>
<td align="left" valign="top">The internal job identifier locates the job. The
user name and job number must be blank.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>User name</em></td>
<td align="left" valign="top">CHAR(10). A specific user profile name, or blanks
when the job name is a special value or *INT.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>Job number</em></td>
<td align="left" valign="top">CHAR(6). A specific job number, or blanks when
the job name specified is a special value or *INT.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Internal job identifier</strong></dt>
<dd>INPUT; CHAR(16)
<p> The internal identifier for the job. The List Job (QUSLJOB) API creates
this identifier. If you do not specify *INT for the job name parameter, this
parameter must contain blanks. With this parameter, the system can locate the
job more quickly than with a job name.</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="HDROINF1">OINF0100 Format</a></h3>
<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">CHAR(10)</td>
<td align="left" valign="top">Display file name</td>
</tr>
<tr>
<td align="center" valign="top">18</td>
<td align="center" valign="top">12</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Display file library name</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Display file record format name</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDROINF2">OINF0200 Format</a></h3>
<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 the list of active record formats</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">Number of active record formats</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">Size of an active record format entry</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Display file name</td>
</tr>
<tr>
<td align="center" valign="top">30</td>
<td align="center" valign="top">1E</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Display file library name</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="7" colspan="2">These fields repeat in
the order listed for the number of active record formats</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Active record format name</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Record format type</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Start row</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">End row</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Window start column</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Window end column</td>
</tr>
</table>
<br>
<br>
<h3>Field Descriptions</h3>
<strong>Active record format name.</strong> The name of an active record format
for the active file on the requester device for the specified interactive job.
An active record format is a record format that is currently displayed on the
requester device.
<p>The following internal record names may be returned:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ERRSFL</em></td>
<td align="left" valign="top">The name for an internal sub-file created when
the ERRSFL keyword is used at the file level in the DDS. The start and end row
values both indicate the message line. If the MSGLOC keyword is used in the
DDS, the values indicate that line. Otherwise, they indicate the default
message line.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*ERRCTL</em></td>
<td align="left" valign="top">The name of an internal sub-file control record
created for the ERRSFL keyword.</td>
</tr>
</table>
<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>Display file library name.</strong> The name of the library that
contains the display file.</p>
<p><strong>Display file name.</strong> The name of the display file. The user
interface manager (UIM) panel groups generate a user-defined data stream
through a display file. The name of the display file (such as QDUI80 or
QDUI132) is returned, not the panel group. If format OINF0200 is being used,
the record format type for a UIM panel is <strong>*USRDFN</strong>.</p>
<p><strong>Display file record format name.</strong> The name of the record
format used from the display file.</p>
<p><strong>End row.</strong> Ending row of the record format.</p>
<p><strong>Number of active record formats.</strong> The number of currently
active record formats for the given file. This number is used to determine the
size of the list of active record formats array. The maximum number of active
records is 25.</p>
<p><strong>Offset to the list of active record formats.</strong> An offset from
the beginning of format OINF0200 to the list of active record formats.</p>
<p><strong>Record format type.</strong> The type of the record format. Blanks
are returned in this field if the record format has no special type. Otherwise,
one of the following is returned:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*SFL</em></td>
<td align="left" valign="top">Subfile record</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SFLCTL</em></td>
<td align="left" valign="top">Subfile control record</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SFLMSGRCD</em></td>
<td align="left" valign="top">Subfile message record</td>
</tr>
<tr>
<td align="left" valign="top"><em>*MNUBAR</em></td>
<td align="left" valign="top">Menubar record</td>
</tr>
<tr>
<td align="left" valign="top"><em>*PULLDOWN</em></td>
<td align="left" valign="top">Pulldown record</td>
</tr>
<tr>
<td align="left" valign="top"><em>*USRDFN</em></td>
<td align="left" valign="top">The record is a user defined data stream.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*WINDOW</em></td>
<td align="left" valign="top">Window definition record.</td>
</tr>
</table>
<p>If a window is active on the display, any previously written records are
inactive. The window definition record is active, as are any records written
&quot;in&quot; the window. Non-window definition records active in the window
are records with the WINDOW keyword with a parameter that names the window
definition record format; these are window reference records. Reported for
an active window are:</p>
<ul>
<li>An entry that names the window definition record and for which the the
start row, end row, start column and end column define the positions of the
window's borders on the display. This is the only entry which has a format type
of &quot;*WINDOW&quot;.<br><br>
</li>
<li>Another entry with the same record name, if the window definition record
contains fields. Only the start row and end row are non-zero in this entry. The
start row and end row are the actual rows on the display that the record's
fields occupy.<br><br>
</li>
<li>Any additional records that are active in the window, with their actual
start row and end row positions.</li>
</ul>
<p>If a window is active, the sub-file for the ERRSFL keyword (if present in
the DDS) is not active.</p>
<p><strong>Size of an active record format entry.</strong> The size of one of
the repeating entries in the active records format information.</p>
<p><strong>Start row.</strong> Starting row of the record format.</p>
<p><strong>Window end column.</strong> If the record format type is *WINDOW,
this is the ending column of the window record. For all other record format
types, this field is zero.</p>
<p><strong>Window start column.</strong> If the record format type is *WINDOW,
this is the starting column of the window record. For all other record format
types, this field is zero.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<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" width="15%">CPF2207 E</td>
<td align="left" valign="top" width="85%">Not authorized to requester device or
display file.</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">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">CPF3C51 E</td>
<td align="left" valign="top">Internal job identifier not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C52 E</td>
<td align="left" valign="top">Internal job identifier no longer valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C53 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C55 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 does not exist.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C57 E</td>
<td align="left" valign="top">Not authorized to retrieve job information.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C58 E</td>
<td align="left" valign="top">Job name specified is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C59 E</td>
<td align="left" valign="top">Internal identifier is not blanks and job name is
not *INT.</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">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF919F E</td>
<td align="left" valign="top">Job is not interactive.</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: V3R6
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center">
<a href="#Top">Top</a> |
<a href="wss1.htm">Work Station Support APIs</a> |
<a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>