492 lines
15 KiB
HTML
492 lines
15 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>Set Low-Level Environment Window Mode (QsnSetEnvWinMod) 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>Set Low-Level Environment Window Mode (QsnSetEnvWinMod) API</h2>
|
||
|
|
||
|
<div class="box" style="width: 70%;">
|
||
|
<br>
|
||
|
Required Parameter:<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
<table width="100%">
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">1</td>
|
||
|
<td align="left" valign="top" width="50%">Enable window mode</td>
|
||
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
<td align="left" valign="top" width="20%">Char(1)</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
Omissible Parameter Group:<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
<table width="100%">
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">2</td>
|
||
|
<td align="left" valign="top" width="50%">Previous window mode setting</td>
|
||
|
<td align="left" valign="top" width="20%">Output</td>
|
||
|
<td align="left" valign="top" width="20%">Char(1)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">3</td>
|
||
|
<td align="left" valign="top">Window mode description</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Char(*)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">4</td>
|
||
|
<td align="left" valign="top">Length of window mode description</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">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">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>
|
||
|
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%">Return code</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 Set Low-Level Environment Window Mode (QsnSetEnvWinMod) API enables or
|
||
|
disables the window mode for the low-level environment. Use this API to affect
|
||
|
how row and cursor positions specified on low-level interface operations are
|
||
|
interpreted for operations to the given low-level environment. Additional
|
||
|
details regarding windows can be found in
|
||
|
<a href="dsm2.htm#HDRINTROWN">Window Services APIs</a>.</p>
|
||
|
|
||
|
<p>When window mode is enabled, screen locations and cursor positions specified
|
||
|
and retrieved in the low-level interface routines are interpreted relative to
|
||
|
the logical window area defined. The logical window area is treated as a
|
||
|
logical screen in terms of validity of cursor and data starting positions. If
|
||
|
an attempt is made to write data or define a field that starts outside of the
|
||
|
current window area, a CPFA31D error is issued for that particular API. If data
|
||
|
or a field is written to the window that exceeds the window boundary, no error
|
||
|
condition occurs and the data or field is truncated.</p>
|
||
|
|
||
|
<p>The size of the logical window area can be determined through the Retrieve
|
||
|
Low-Level Environment Window Mode (QsnRtvEnvWinMod) API. When window mode is
|
||
|
enabled, screen addresses must be explicitly specified for APIs such as the
|
||
|
QsnWrtDta API in order for the address to be interpreted relative to the window
|
||
|
area. If a screen address is not specified, the current display address will be
|
||
|
used as an absolute screen address irrespective of the current window mode.
|
||
|
This is because the current screen address is not tracked by DSM, but is
|
||
|
handled by the control unit.</p>
|
||
|
|
||
|
<p>When window mode is enabled, APIs where a cursor position is specified, such
|
||
|
as the QsnSetFld API, issue a CPFA307 error if the given cursor position is
|
||
|
outside the bounds of the current window area. For APIs that return a cursor
|
||
|
position, such as the Get Cursor Address (QsnGetCsrAdr) API, both the row and
|
||
|
column returned will be -1 if the cursor screen location is outside of the
|
||
|
current window area, 0 if the cursor is on the top or left border, or the
|
||
|
number of screen rows or columns plus 1 if the cursor is on the bottom or
|
||
|
center border of the window area, respectively. The following low-level APIs
|
||
|
are affected by the window mode:</p>
|
||
|
|
||
|
<blockquote>
|
||
|
QsnRtvReadAdr<br>
|
||
|
|
||
|
QsnRtvFldInf<br>
|
||
|
|
||
|
QsnGetCsrAdr<br>
|
||
|
|
||
|
QsnGetCsrAdrAID<br>
|
||
|
|
||
|
QsnSetOutAdr<br>
|
||
|
|
||
|
QsnWrtDta<br>
|
||
|
|
||
|
QsnWrtSFMaj<br>
|
||
|
|
||
|
QsnWrtTDta<br>
|
||
|
|
||
|
QsnWrtExtAtr<br>
|
||
|
|
||
|
QsnWrtPad<br>
|
||
|
|
||
|
QsnWrtPadAdr<br>
|
||
|
|
||
|
QsnSetFld<br>
|
||
|
|
||
|
QsnSetCsrAdr<br>
|
||
|
|
||
|
QsnInsCsr<br>
|
||
|
|
||
|
QsnSetErr<br>
|
||
|
</blockquote>
|
||
|
|
||
|
<p>The actual screen location used for a screen I/O operation is calculated
|
||
|
using the formula base+offset=actual, where base is the upper left row/column
|
||
|
location of the window border (0 for full screen) if offset is positive and the
|
||
|
lower center row/column location of the window border (screen height/width plus
|
||
|
1 for full screen), if offset is negative, offset is the row/column specified
|
||
|
on the API, and actual is the actual screen location. For example, if the
|
||
|
window area were defined to be from row 3, column 10 with 15 rows and 30
|
||
|
columns, as shown in <a href="#FIGSETWMD">Window Area</a>, then an attempt to
|
||
|
position the cursor through the QsnSetCsrAdr API at row 4, column 5 would
|
||
|
actually position the cursor on the screen at row 7, column 15, as indicated by
|
||
|
the letter a in <a href="#FIGSETWMD">Window Area</a>. Specifying row 9, column -7
|
||
|
would position the cursor on the screen at row 12, column 34 (b in <a href=
|
||
|
"#FIGSETWMD"> Window Area</a>). An attempt to position the cursor at error issue a
|
||
|
CPFA307 error row 16, column 5 would result error (Screen position
|
||
|
&1,&2 outside of display or window area). since this position is
|
||
|
outside the bounds of the current window area. Given the same window area
|
||
|
description, a call to the QsnRtvFldInf API specifying an input buffer
|
||
|
containing a field read from row 10, column 20 on the actual screen (the c in
|
||
|
<a href="#FIGSETWMD">Window Area</a>), would return a field row and column
|
||
|
location of 7 and 10 respectively. A call to the QsnGetCsrAdr API would return
|
||
|
-1,-1 if the cursor were located outside of the window area, such as in row 18
|
||
|
column 32.</p>
|
||
|
|
||
|
<p>Enabling or disabling the window mode does not affect any data currently
|
||
|
displayed on the screen or the behavior of any commands stored previously in a
|
||
|
command buffer. For example, if the window mode was enabled as described above
|
||
|
and the QsnSetCsrAdr API was called as an indirect operation specifying row 4
|
||
|
and column 5, the cursor position command stored in the command buffer would
|
||
|
reflect the current window mode. Whenever that command buffer is written out,
|
||
|
the cursor would always be set on the screen at row 6, column 14, regardless of
|
||
|
whether or not window mode was disabled or changed at the point when the
|
||
|
command buffer was written to the screen.</p>
|
||
|
|
||
|
<p><strong><a name="FIGSETWMD">Window Area</a></strong><br>
|
||
|
<img src="RBAFX646.gif" alt="WIndow Area"></p>
|
||
|
|
||
|
<br>
|
||
|
<h3>Authorities and Locks</h3>
|
||
|
|
||
|
<p>None</p>
|
||
|
|
||
|
<br>
|
||
|
<h3>Required Parameter</h3>
|
||
|
|
||
|
<dl>
|
||
|
<dt><strong>Window mode</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(1)
|
||
|
|
||
|
<p>Whether window mode should be enabled or disabled. The possible values
|
||
|
are:</p>
|
||
|
|
||
|
<table cellpadding="3">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td valign="top"><em>0</em></td>
|
||
|
<td valign="top">Disable window mode</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign="top"><em>1</em></td>
|
||
|
<td valign="top">Enable window mode</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p>Window mode is initially disabled.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
|
||
|
<br>
|
||
|
<h3>Omissible Parameter Group</h3>
|
||
|
|
||
|
<dl>
|
||
|
<dt><strong>Previous window mode setting</strong></dt>
|
||
|
|
||
|
<dd>OUTPUT; CHAR(1)
|
||
|
|
||
|
<p>Whether window mode was enabled or disabled prior to this API being called.
|
||
|
The possible values returned are:</p>
|
||
|
|
||
|
<table cellpadding="3">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td valign="top"><em>0</em></td>
|
||
|
<td valign="top">Window mode was disabled prior to this API being called</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign="top"><em>1</em></td>
|
||
|
<td valign="top">Window mode was enabled prior to this API being called</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Window mode description</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(*)
|
||
|
|
||
|
<p>The window mode description. If this parameter is omitted or the length
|
||
|
parameter is specified as 0, and window mode is to be enabled, the values from
|
||
|
the previous window mode setting will be used. If no such values exist, the
|
||
|
current screen size will be used. The window area described must fall within
|
||
|
the bounds of the current screen size. in a CPFA307 error (Screen position
|
||
|
&1,&2 outside of display or window area). The format of this field is
|
||
|
shown in <a href="#HDRSETWMDF">Format of the Window Mode Description</a>.</p>
|
||
|
|
||
|
<p>This parameter is ignored if window mode is to be disabled.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Length of window mode description</strong></dt>
|
||
|
|
||
|
<dd>INPUT; BINARY(4)
|
||
|
|
||
|
<p>The length of the window mode description parameter. If this parameter is
|
||
|
specified, it must be either 0, in which case the window mode description
|
||
|
parameter is ignored, or exactly 13 bytes in which case the window mode
|
||
|
description is required.</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>Return code</strong></dt>
|
||
|
|
||
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
||
|
<p>A return code indicating the result of the operation. The value returned
|
||
|
will be 0 if the operation was successful, or -1 otherwise.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
|
||
|
<br>
|
||
|
<h3><a name="HDRSETWMDF">Format of the Window Mode Description</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%">CHAR(1)</td>
|
||
|
<td align="left" valign="top" width="60%">Attribute column indication</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">1</td>
|
||
|
<td align="center" valign="top">1</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Upper left row of window area border</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">5</td>
|
||
|
<td align="center" valign="top">5</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Upper left column of window area border</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">9</td>
|
||
|
<td align="center" valign="top">9</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Number of rows in window area</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">13</td>
|
||
|
<td align="center" valign="top">D</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Number of columns in window area</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
<h3>Field Descriptions</h3>
|
||
|
|
||
|
<p><strong>Attribute column indication.</strong> Whether the column containing
|
||
|
the left border of the logical window is an attribute column. Operations such
|
||
|
as QsnWrtDta can specify column 1 for the data location and specify a leading
|
||
|
attribute. In this case the data will be written to the first column of the
|
||
|
window area and the attribute will be written to the column containing the
|
||
|
logical window border. If the attribute column is not specified for the window
|
||
|
area, such an operation would result in a CPFA31D error (Attempt to write
|
||
|
outside of window area.). This column would also be used to insert the leading
|
||
|
attribute when line wrapping occurs within the window.</p>
|
||
|
|
||
|
<p>The allowable values are:</p>
|
||
|
|
||
|
<table cellpadding="3">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td valign="top"><em>0</em></td>
|
||
|
<td valign="top">No attribute column</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign="top"><em>1</em></td>
|
||
|
<td valign="top">Attributes can be written to column containing left logical
|
||
|
window border</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Number of columns in window area.</strong> The number of columns in
|
||
|
the window area.</p>
|
||
|
|
||
|
<p><strong>Number of rows in window area.</strong> The number of rows in the
|
||
|
window area.</p>
|
||
|
|
||
|
<p><strong>Upper left column of window area border.</strong> The column
|
||
|
location of the leftmost column in the window area. This parameter must be a
|
||
|
value between 0 and the screen width inclusive.</p>
|
||
|
|
||
|
<p><strong>Upper left row of window border.</strong> The row location of the
|
||
|
upper border of the logical window area. This parameter must be a value between
|
||
|
0 and the screen height inclusive.</p>
|
||
|
|
||
|
<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">CPF3C1D E</td>
|
||
|
<td valign="top">Length specified in parameter &1 not valid.</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">CPFA31E E</td>
|
||
|
<td valign="top">Required parameter &1 omitted.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPFA324 E</td>
|
||
|
<td valign="top">Window area definition is incorrect.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPFA32A E</td>
|
||
|
<td valign="top">Window mode indicator must be '0' or '1'.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPFA334 E</td>
|
||
|
<td valign="top">Low level environment handle incorrect.</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>
|
||
|
|