222 lines
9.5 KiB
HTML
222 lines
9.5 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>Using Low-Level Screen I/O Services APIs</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 -->
|
|
<!-- DSMMST1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
|
<!-- at RCHVMW2 on 29 Jan 1999 at 16:05:09 -->
|
|
<!-- File Edited November 2001 -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<!-- Java sync-link -->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
|
|
|
|
<h2>Using Low-Level Screen I/O Services APIs</h2>
|
|
|
|
<h3><a name="HDR5250ERR">DSM Error Handling</a></h3>
|
|
|
|
<p>Calls to most of the interfaces can result in a direct I/O operation, or in
|
|
the storing of commands in a command buffer. The command buffer provides a way
|
|
of saving the commands so that multiple operations can be specified and
|
|
performed in a single I/O operation. DSM performs error handling as much as
|
|
possible prior to issuing an I/O operation. For example, if a request is made
|
|
to place the screen in wide mode, and the display does not support this mode,
|
|
DSM detects and reports the error condition before performing an I/O operation.
|
|
This way of handling errors is particularly useful in the case where multiple
|
|
commands have been saved in a buffer. Otherwise, there is no obvious way to
|
|
determine which command was in error when the I/O operation fails.</p>
|
|
|
|
<p>The errors that can occur for each operation are listed with the operation.
|
|
If an error message indicates that the error is issued for a negative response
|
|
code, this means that the error was not detected by DSM and occurred on the I/O
|
|
operation.</p>
|
|
|
|
<p><strong>Note:</strong> When you are using the i5/OS<SUP>(TM)</SUP> TELNET display station
|
|
emulation, an unsuccessful I/O operation may be undetected initially, but will
|
|
be reported on the next operation.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRDEVSUPP">Device Support</a></h3>
|
|
|
|
<p>The 5250 Query command is used to determine the valid commands for a
|
|
particular device. This command is issued for the current device at the start
|
|
of each DSM session and the information is saved for subsequent queries. If the
|
|
5250 Query command is not supported, the base data stream support as documented
|
|
in the 5250 Functions Reference is assumed, with color and wide support being
|
|
determined by the device type.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRLGLSCR">Operating Environments</a></h3>
|
|
|
|
<p>The low-level interfaces operate within an environment that can be defined
|
|
using the Create Low-Level Environment (QsnCrtEnv) API. The low-level
|
|
environment defines the operating modes, such as DBCS support and the window
|
|
mode. The environment is passed as a parameter to most of the low-level
|
|
services APIs. There is no need to define a low-level environment unless you
|
|
need a specific operating environment that is different from the default. The
|
|
default low-level environment is indicated on the low-level service APIs by
|
|
specifying the environment handle as zero.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRDIRECT">Direct and Indirect Operations</a></h3>
|
|
|
|
<p>Many of the low-level APIs accept an optional command buffer as a parameter.
|
|
For such APIs, the command buffer can be used to store and accumulate a group
|
|
of requested operations. The accumulated operations can then be written to the
|
|
screen in a single I/O operation. Better performance can be achieved because a
|
|
group of repetitive operations can be issued to the screen without having to
|
|
recall the sequence of individual APIs for each repeated operation.</p>
|
|
|
|
<p>A <strong>direct operation</strong> is one that omits the command buffer.
|
|
The requested operation takes place immediately. For most APIs, specifying the
|
|
command buffer results in an <strong>indirect operation</strong>. No I/O
|
|
operation takes place and the operation is simply stored in the command buffer.
|
|
Several of the screen input APIs, however, do perform a direct operation when
|
|
the command buffer is specified. This semantic is discussed in
|
|
<a href="QsnReadInp.htm">Read Input Fields (QsnReadInp) API</a>.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRDBCS">DBCS Considerations</a></h3>
|
|
|
|
<p>You can write DBCS data enclosed with SO/SI to the screen, and when the
|
|
underlying display supports it, graphic DBCS using the Write Data (QsnWrtDta)
|
|
API to specify the data stream Write Extended Attribute order. (See the 5250
|
|
data stream documentation for further details.) You can define fields as being
|
|
DBCS through the Set Field (QsnSetFld) API using the appropriate field control
|
|
word. DBCS data can be written to such fields as described above. If you
|
|
specify DBCS support on the low-level environment description,
|
|
(see <a href="QsnCrtEnv.htm#HDRLLDESC">Format of the Low-Level Environment Description</a>),
|
|
the APIs will handle the parsing of DBCS data and fields appropriately.</p>
|
|
|
|
|
|
|
|
<p>The APIs do not provide any special processing of DBCS data, such as adding
|
|
SO/SI to DBCS graphic data when graphic data is not supported by the display.
|
|
For example, if you want to define a field as graphic DBCS and write graphic
|
|
DBCS data to it, code the QsnSetFld API specifying a control word of
|
|
QSN_FCS_DBCS_PURE (x'8220') and then write the graphic data to a command buffer
|
|
using the QsnWrtDta API. Precede and follow this data with Write Extended
|
|
Attribute orders to add the extended NLS SO/SI attributes. If you want to write
|
|
a graphic data value to a non-graphic DBCS field, you must enclose the graphic
|
|
DBCS data with SO/SI prior to calling the QsnWrtDta API.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRLLPERF">Performance Considerations</a></h3>
|
|
|
|
<p>The following operations can incur overhead and adversely affect the
|
|
performance of your application:</p>
|
|
|
|
<ul>
|
|
<li><strong>QsnCrtEnv</strong><br>
|
|
<br>
|
|
|
|
|
|
<p>Specifying translation of x'3f' to x'1f' can incur overhead because all
|
|
outgoing data must be checked for this value. This option should be specified
|
|
only if CDRA is on and translation between the code pages will result in a
|
|
x'3f' occurrence in data to be displayed.</p>
|
|
</li>
|
|
|
|
<li><strong>QsnSavScr</strong><br>
|
|
<br>
|
|
|
|
|
|
<p>This operation results in the entire contents of the screen being read,
|
|
which can adversely affect response time. This is typically about 3KB, but
|
|
could be up to 28KB.</p>
|
|
</li>
|
|
|
|
<li><strong>QsnRstScr</strong><br>
|
|
<br>
|
|
|
|
|
|
<p>This operation writes the result of a save screen back to the device, which
|
|
can adversely affect response time.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>If you have GUI support, you can put additional commands after the QsnSavScr
|
|
or QsnRstScr APIs to reduce I/O operations and improve performance.</p>
|
|
|
|
<p>Deleting structures associated with handles, such as command buffers, prior
|
|
to exiting a program will improve performance for the programs that use APIs
|
|
that create handles.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRLLLIMIT">Limitations and Restrictions</a></h3>
|
|
|
|
<p>The following limitations or restrictions apply to the low-level
|
|
interfaces:</p>
|
|
|
|
<ul>
|
|
<li>Certain functions are supported by control units that do not support the
|
|
5250 Query command. If the Query command is not supported, it is assumed that
|
|
the particular function is not supported either. These functions are
|
|
transparent data support and move cursor order support. Device attributes such
|
|
as wide mode and color support are determined based on the device type if the
|
|
5250 Query command is not supported.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>For the Retrieve Display Mode (QsnRtvMod) operation to correctly report the
|
|
current state of the display, all commands that affect this state (such as a
|
|
Clear Unit or Clear Unit Alternate) must occur as the first command in any
|
|
command stream written to the display. This is because the work station control
|
|
unit inspects the first command in the stream to determine if a state change is
|
|
taking place. Most iSeries<SUP>(TM)</SUP> programs, including the DSM APIs, send these
|
|
commands only at the beginning of a stream. If you write a stream in which such
|
|
commands do not appear at the beginning of the stream, the results of the
|
|
Retrieve Display Mode (QsnRtvMod) operation may not be accurate.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>When conversions are performed, they are performed only after a Read Input
|
|
Fields (QsnReadInp), Read Modified Fields (QsnReadMDT), Read Modified Alternate
|
|
(QsnReadMDTAlt), Read Immediate (QsnReadImm), or Read Modified Immediate
|
|
Alternate (QsnReadMDTImmAlt) operation. They are performed on all incoming
|
|
field data, including transparent and numeric data. You must turn conversion on
|
|
and off. To prevent certain data from being converted, you explicitly set the
|
|
conversion options on the QsnCrtEnv and QsnChgEnv APIs. The conversions that
|
|
are affected by this are CDRA conversion based on the job CCSID and conversions
|
|
of X'1F' in the incoming data stream to X'3F'.</li>
|
|
</ul>
|
|
|
|
<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>
|
|
|