476 lines
13 KiB
HTML
476 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 Modified Fields (QsnReadMDT) 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 Modified Fields (QsnReadMDT) 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%">Field count</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%">Field count</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Service Program: QSNAPI<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Read Modified Fields (QsnReadMDT) API reads the contents of all modified
|
|
fields on the screen 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>. See <a
|
|
href="dsm1e.htm#HDRCC">Control Characters</a> for a description of the control
|
|
character values. The format of the data returned is:</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" valign="top">
|
|
Cursor
|
|
Row/Column<br>
|
|
2 bytes
|
|
</td>
|
|
<td align="center" valign="top">
|
|
AID Code<br>
|
|
1 byte
|
|
</td>
|
|
<td align="center" valign="top">
|
|
SBA<br>
|
|
X'11'
|
|
</td>
|
|
<td align="center" valign="top">
|
|
Field
|
|
Row/Column<br>
|
|
2 bytes
|
|
</td>
|
|
<td align="center" valign="top">Field Data</td>
|
|
<td align="center" valign="top">
|
|
SBA<br>
|
|
X'11'
|
|
</td>
|
|
<td align="center" valign="top">
|
|
Field
|
|
Row/Column<br>
|
|
2 bytes
|
|
</td>
|
|
<td align="center" valign="top">Field Data</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The field data returned for transparent fields and CCSID-capable fields
|
|
(created with <a href="QsnSetFldCC.htm">QsnSetFldCC</a>) includes an additional
|
|
order and a length:</p>
|
|
|
|
<table>
|
|
<tr>
|
|
|
|
<td align="center" valign="top" colspan="3">Field Data </td>
|
|
|
|
|
|
<td align="center" valign="top">
|
|
Inbound
|
|
Transparent
|
|
Data order<br>
|
|
X'10'
|
|
</td>
|
|
<td align="center" valign="top">
|
|
Length of
|
|
the following
|
|
data<br>
|
|
2 bytes
|
|
</td>
|
|
<td align="center" valign="top">
|
|
Transparent
|
|
data
|
|
or data in
|
|
Field CCSID
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The information returned depends on the state of the MDT bit for each field
|
|
(see <a href="dsm1e.htm#HDRMDT">Modified Data Tag (MDT) Bit</a>) and the
|
|
AID-generating key used. If no bits are set, the input returned consists of the
|
|
cursor address and an AID code only. If at least one bit is set, the input may
|
|
also include field data. In each 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.</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>An unmasked command function key</p>
|
|
</blockquote>
|
|
|
|
<p>The field data, when returned, consists of the row and column address and
|
|
the contents of each field that has an MDT bit on as they appear on the
|
|
display, unless resequencing has been specified. (See <a href=
|
|
"dsm1e.htm#HDRRESEQ">Resequencing</a>.) The input buffer query routines <a
|
|
href="QsnRtvFldCnt.htm">Retrieve Number of Fields Read (QsnRtvFldCnt) API</a>
|
|
and <a href="QsnRtvFldInf.htm">Retrieve Field Information (QsnRtvFldInf)
|
|
API</a> can be used to retrieve the value for each field. (To interpret the
|
|
data directly, QsnRtvDta can be used to obtain a pointer for the data portion
|
|
of the input buffer. The first data byte will be the SBA order for the first
|
|
field as defined in the 5250 data stream documentation.)</p>
|
|
|
|
<p>Data for nontransparent fields is formatted as follows:</p>
|
|
|
|
<ul>
|
|
<li>Leading and embedded nulls within the field are translated to blanks, and
|
|
trailing nulls are stripped off. Only the field's address is returned for
|
|
fields whose MDT bit is on but which consist entirely of nulls.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If the specified field is a signed numeric field:<br>
|
|
<br>
|
|
|
|
|
|
<ul>
|
|
<li>The last character of the field is stripped off unless it was previously
|
|
stripped because it was null.<br>
|
|
<br>
|
|
</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>If the field is a transparent or CCSID-capable field, no formatting is
|
|
performed.</p>
|
|
|
|
<p>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 MDT Fields command.</p>
|
|
|
|
<br>
|
|
<h3>Restrictions</h3>
|
|
|
|
<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> or 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>Field count</strong></dt>
|
|
|
|
<dd>OUTPUT; BINARY(4)
|
|
|
|
<p>The variable that contains the number of input fields read after the
|
|
QsnReadMDT 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>Field count</strong></dt>
|
|
|
|
<dd>OUTPUT; BINARY(4)
|
|
|
|
<p>This API returns the value for the field count 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">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>
|
|
|