435 lines
13 KiB
HTML
435 lines
13 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>Read Input Fields (QsnReadInp) 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. -->
|
|
<!-- DSMMST1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
|
<!-- at RCHVMW2 on 29 Jan 1999 at 16:05:09 -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!--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>Read Input Fields (QsnReadInp) API</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<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%">Control character byte 1</td>
|
|
<td align="left" valign="top" width="20%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(1)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Control character byte 2</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(1)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Omissible Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">3</td>
|
|
<td align="left" valign="top" width="50%">Number of field data bytes read</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Input buffer handle</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">Command buffer handle</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">Low-level environment handle</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">7</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>
|
|
Returned Value:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="top" width="10%"></td>
|
|
<td align="left" valign="top" width="50%">Number of field data bytes read</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Public Default Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Service Program: QSNAPI<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Read Input Fields (QsnReadInp) API reads the contents of all input
|
|
fields on the display while requiring an AID-generating key to be pressed. The
|
|
command buffer handle or input buffer handle parameter must be specified as
|
|
described in <a href="QsnPutInpCmd.htm">Put Input Command (QsnPutInpCmd)
|
|
API</a>. The format of the data returned is:</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<td align="center" valign="top" width="20%">
|
|
<pre>
|
|
Cursor
|
|
Address in
|
|
Row/Column
|
|
FMT
|
|
2 bytes
|
|
</pre>
|
|
</td>
|
|
<td align="center" valign="top" width="20%">
|
|
<pre>
|
|
AID Code
|
|
1 byte
|
|
</pre>
|
|
</td>
|
|
<td align="center" valign="top" width="20%">Field Data</td>
|
|
<td align="center" valign="top" width="20%">Field Data</td>
|
|
<td align="center" valign="top" width="20%">Field Data</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The information returned depends on the condition of the master MDT bit (see
|
|
<a href="dsm1e.htm#HDRMDT">Modified Data Tag (MDT) Bit</a>) and the
|
|
AID-generating key pressed. If the bit is not set, the input returned consists
|
|
of the cursor address and an AID code only. If the bit is set, the input
|
|
returned also includes the field data in the data portion of the input buffer.
|
|
In either case, the returned cursor address indicates the location of the
|
|
cursor when the AID-generating key was pressed and the AID code for the
|
|
AID-generating key the operator used. See <a href="dsm1e.htm#HDRAID">
|
|
AID-Generating Keys</a> for a description of the AID-generating character
|
|
values.</p>
|
|
|
|
<p>Field data is returned only when one of the following AID-generating keys is
|
|
used:</p>
|
|
|
|
<blockquote>
|
|
<p>Roll Up</p>
|
|
|
|
<p>Roll Down</p>
|
|
|
|
<p>Enter/Auto Record Advance</p>
|
|
|
|
<p>Auto Enter</p>
|
|
|
|
<p>An unmasked command function key</p>
|
|
</blockquote>
|
|
|
|
<p>The field data, when returned, consists of the contents of all input fields
|
|
as they appear on the display, unless resequencing has been specified. (See <a
|
|
href="dsm1e.htm#HDRRESEQ">Resequencing</a>.) Any attributes contained in a
|
|
field are treated as data and returned as such. The attributes that start and
|
|
end a field are not returned. These are considered to be outside the boundaries
|
|
of the field. No field delimiters are added; data from each field is followed
|
|
directly by the data from the next field. Data for nontransparent fields is
|
|
formatted as follows:</p>
|
|
|
|
<ul>
|
|
<li>All nulls (leading, embedded, or trailing) are converted to blanks.</li>
|
|
|
|
<li>If the specified field is a signed numeric field:
|
|
|
|
<ul>
|
|
<li>The last character of the field is stripped off.</li>
|
|
|
|
<li>The last location of the field is checked for a negative sign. If detected,
|
|
the zone portion of the second to last character of the field is changed to a
|
|
X'D'.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The data returned for transparent or CCSID-capable fields is not edited. A
|
|
transparent field is defined with a transparency field control word X'84yy'
|
|
(see <a href="QsnSetFld.htm">Set Field (QsnSetFld) API</a>.) The <a href=
|
|
"QsnSetFldCC.htm">QsnSetFldCC</a> API creates CCSID-capable fields. Each field
|
|
read is returned unedited with no intervening control information. If a field
|
|
is both transparent and signed numeric, unpredictable results can occur in the
|
|
field data. CDRA conversion may be peformed upon this data, see <a href=
|
|
"dsm1e.htm#HDRLLLIMIT">Limitations and Restrictions</a> for further
|
|
details.</p>
|
|
|
|
<p>This command corresponds directly to the 5250 Read Input Fields command.</p>
|
|
|
|
<br>
|
|
<h3>Restrictions</h3>
|
|
|
|
<p>This command cannot be issued if the control unit supports ideographic data
|
|
types. A CPFA306 error will occur if an attempt is made to issue this command
|
|
to a control unit that supports ideographic data types.</p>
|
|
|
|
<p>Some control units, like those emulated by the Client Access program, do not
|
|
support a control character associated with input commands. For such units, the
|
|
control character specified would be ignored. A program could cause further
|
|
actions to be suspended if, for example, the control character byte 2 specified
|
|
to unlock the keyboard and this action was not specified elsewhere in the data
|
|
stream. If the underlying control unit does not support a control character
|
|
with input commands, you must specify the action to perform using the QsnWTD
|
|
API.</p>
|
|
|
|
<br>
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<p>None</p>
|
|
|
|
<br>
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Control character byte 1</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1)
|
|
|
|
<p>The operation for the display to perform after the read operation has been
|
|
serviced. See <a href="dsm1e.htm#HDRCC">Control Characters</a> for a
|
|
description of the control character values.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Control character byte 2</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1)
|
|
|
|
<p>The operation for the display to perform after the read operation and
|
|
control character byte 1 have been serviced. See <a href="dsm1e.htm#HDRCC">
|
|
Control Characters</a> for a description of the control character values.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Omissible Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Number of field data bytes read</strong></dt>
|
|
|
|
<dd>OUTPUT; BINARY(4)
|
|
|
|
<p>The variable that contains the number of field data bytes returned after the
|
|
QsnReadInp API has completed if a direct operation is specified. The parameter
|
|
is not modified for an indirect operation and the value remains unchanged from
|
|
whatever was passed.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Input buffer handle</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>A handle for the input buffer that receives the result of the input
|
|
operation if a direct operation is specified. The result can be queried using
|
|
the input buffer query operations. See <a href="QsnRtvFldDta.htm"> Retrieve
|
|
Pointer to Field Data (QsnRtvFldDta) API</a> and <a href="QsnRtvFldDtaLen.htm">
|
|
Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) API</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Command buffer handle</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>A handle for the command buffer in which to store the command.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Low-level environment handle</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The low-level environment that the operation applies to. If this parameter
|
|
is omitted or given with a value of zero, the default low-level environment is
|
|
used.</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>. If this
|
|
parameter is omitted, diagnostic and escape messages are issued to the
|
|
application.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Returned Value</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Number of field data bytes read</strong></dt>
|
|
|
|
<dd>OUTPUT; BINARY(4)
|
|
|
|
<p>This API returns the value for the number of field data bytes read parameter
|
|
if a direct operation was specified, or -1 if an error occurs during
|
|
processing. If this is an indirect operation, this API returns zero if
|
|
successful, or -1 otherwise.</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">CPF3CF1 E</td>
|
|
<td valign="top">Error code parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
|
<td valign="top">Error(s) occurred during running of &1 API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA301 E</td>
|
|
<td valign="top">Command buffer is full.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA302 E</td>
|
|
<td valign="top">Command buffer or input buffer parameters required.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA303 E</td>
|
|
<td valign="top">Error occurred for screen I/O operation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA304 E</td>
|
|
<td valign="top">Data-stream error &1 reported for screen I/O
|
|
operation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA305 E</td>
|
|
<td valign="top">Cannot add operation to command buffer.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA309 E</td>
|
|
<td valign="top">Invalid cursor position in command buffer.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA313 E</td>
|
|
<td valign="top">Command buffer already contains an input operation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA31C E</td>
|
|
<td valign="top">Incorrect value for control character byte &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA31E E</td>
|
|
<td valign="top">Required parameter &1 omitted.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA326 E</td>
|
|
<td valign="top">Screen must be redrawn.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA331 E</td>
|
|
<td valign="top">Buffer handle incorrect.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA334 E</td>
|
|
<td valign="top">Low level environment handle incorrect.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA343 E</td>
|
|
<td valign="top">Output operation not done.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA344 E</td>
|
|
<td valign="top">The file &2 in library &3 is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA345 E</td>
|
|
<td valign="top">The invite active flag is not valid.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V2R3
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"dsm.htm">Dynamic Screen Manager APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|