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

492 lines
15 KiB
HTML
Raw Permalink 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>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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Service Program: QSNAPI<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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
&amp;1,&amp;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
&amp;1,&amp;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 &amp;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 &amp;1 API.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA31E E</td>
<td valign="top">Required parameter &amp;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>