friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QsnStrWin.htm

441 lines
13 KiB
HTML
Raw Blame History

<!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>Start a Window (QsnStrWin) 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 November 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>Start a Window (QsnStrWin) API</h2>
<div class="box" style="width: 65%;">
<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%">Window handle</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</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%">Save screen</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">3</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 Start a Window (QsnStrWin) API starts a window created with the Create a
Window (QsnCrtWin) API. This causes the window to be displayed on the screen
and added to the active window list. If specified, the Draw Window exit routine
is called immediately before the window is drawn.</p>
<br>
<h3>Authorities and Locks</h3>
<p>None</p>
<br>
<h3>Required Parameter</h3>
<dl>
<dt><strong>Window handle</strong></dt>
<dd>INPUT; BINARY(4)
<p>A handle for the window to be started.</p>
</dd>
</dl>
<br>
<h3>Omissible Parameter Group</h3>
<dl>
<dt><strong>Save screen</strong></dt>
<dd>INPUT; CHAR(1)
<p>Indicates if the underlying display image should be saved prior to drawing
the window. This option should be used only if the window will not be moved or
resized over an existing display image. Performance can be improved by not
saving the display image. However, doing this limits the overlapping nature of
the window. If an attempt is made to move or resize a window for which the
display image was not saved, the screen is cleared and all windows are redrawn
prior to moving the window.</p>
<p>The possible values for this parameter are:</p>
<table cellpadding="3">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">Do not save the underlying display image when the window is
started.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">Save the underlying display image when the window is started.
This is the default.</td>
</tr>
</table>
<br>
</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>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 align="left" 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 &amp;amp;1 API.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA318 E</td>
<td valign="top">Error calling exit routine.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA31E E</td>
<td valign="top">Required parameter &amp;amp;1 omitted.</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 &amp;amp;2 in library &amp;amp;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>
<tr>
<td align="left" valign="top">CPFA3AA E</td>
<td valign="top">Window handle incorrect.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA3AB E</td>
<td valign="top">The value for &amp;amp;1 must be '0' or '1'.</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRWNPERF">Performance Considerations</a></h3>
<p>You can improve the performance of window operations by doing the
following:</p>
<ul>
<li>Do not save or restore the underlying screen image when a window is started
or ended with the Start a Window (QsnStrWin) or End a Window (QsnEndWin) API,
respectively. See pages <a href="QsnStrWin.htm">Start a Window (QsnStrWin)
API</a> and <a href="QsnEndWin.htm">End a Window (QsnEndWin) API</a>.</li>
<li>For non-GUI windows, use the same color for current and noncurrent
boundaries.</li>
<li>Use a display station attached to a control unit that supports an enhanced
interface for a nonprogrammable work station, even if you are not using GUI
windows.</li>
<li>Use GUI window support when the underlying control unit supports this.</li>
</ul>
<br>
<br>
<h3><a name="HDRWNEX">Creating/Manipulating Windows Example</a></h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The sample program in <a href="#FIGWNEX1">Creating and Manipulating
Windows</a> shows how to create and manipulate several windows with exit
routines. The program creates three windows- Window 1, Window 2, and Window 3.
Each time Enter is pressed, the next window is made current; in which case, the
Draw Window exit routine for that window is called. If the user presses F4=Move
or F5=Resize, the current window is moved or resized and the Draw Window exit
routine is called again. The resulting screen output is shown in <a href=
"#FIGWNEX1A">Display Screen</a>.</p>
<p><strong><a name="FIGWNEX1">Creating and Manipulating
Windows</a></strong></p>
<div class="box" style="width: 85%;">
<pre>
#include &lt;stddef.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;stdio.h&gt;
#include "qsnapi.h"
void GenericDraw(const Qsn_Cmd_Buf_T *cbuf, const Qsn_Win_T *win)
{
char *msg1 = "F3: quit F4: move F5: resize";
char *msg2 = "text no attribute";
QsnWrtDta(msg2, strlen(msg2), 0, 2, 1, QSN_NO_SA, QSN_NO_SA,
QSN_NO_SA, QSN_NO_SA, *cbuf, *win, NULL);
QsnWrtDta(msg1, strlen(msg1), 0, -1, 1, QSN_SA_HI, QSN_SA_NORM,
QSN_SA_RED, QSN_SA_NORM, *cbuf, *win, NULL);
}
void Draw1(const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf)
{
char *txt = "window 1 (ul/blue)";
GenericDraw(cbuf, win);
QsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_UL, QSN_SA_NORM,
QSN_SA_BLU, QSN_SA_NORM, *cbuf, *win, NULL);
}
void Draw2(const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf)
{
char *txt = "window 2 (ul/red)";
GenericDraw(cbuf, win);
QsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_UL, QSN_SA_NORM,
QSN_SA_RED, QSN_SA_NORM, *cbuf, *win, NULL);
}
void Draw3(const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf)
{
char *txt = "window 3 (ul/pink)";
GenericDraw(cbuf, win);
QsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_UL, QSN_SA_NORM,
QSN_SA_PNK, QSN_SA_NORM, *cbuf, *win, NULL);
}
int main (void) {
int i;
char text[100];
Qsn_Win_T win1, win2, win3, cur;
Qsn_Win_Desc_T win_desc;
Qsn_Win_Ext_Inf_T ext = { NULL, NULL, NULL, NULL, NULL, NULL };
Q_Bin4 win_desc_length = sizeof(win_desc);
char aid;
QsnInzWinD(&amp;win_desc, win_desc_length, NULL);
win_desc.GUI_support = '0';
/* define and start window 1 */
win_desc.top_row = 3;
win_desc.left_col = 5;
win_desc.num_rows = 13;
win_desc.num_cols = 40;
ext.draw_fp = Draw1;
win1 = QsnCrtWin(&amp;win_desc, win_desc_length, &amp;ext, sizeof(ext),
'1', NULL, 0, NULL, NULL);
QsnGetAID(NULL, 0, NULL);
/* define and start window 2 */
win_desc.top_row = 10;
win_desc.left_col = 10;
win_desc.num_rows = 10;
win_desc.num_cols = 30;
ext.draw_fp = Draw2;
win2 = QsnCrtWin(&amp;win_desc, win_desc_length, &amp;ext, sizeof(ext),
'1', NULL, 0, NULL, NULL);
QsnGetAID(NULL, 0, NULL);
/* define and start window 3 */
win_desc.top_row = 5;
win_desc.left_col = 20;
win_desc.num_rows = 15;
win_desc.num_cols = 50;
ext.draw_fp = Draw3;
win3 = QsnCrtWin(&amp;win_desc, win_desc_length, &amp;ext, sizeof(ext),
'1', NULL, 0, NULL, NULL);
cur = win3;
for ( ;; ) {
if (( (aid=QsnGetAID(NULL, 0, NULL)) == QSN_F3))
break;
else if (aid == QSN_F4)
QsnMovWinUsr(cur, NULL);
else if (aid == QSN_F5)
QsnRszWinUsr(cur, NULL);
else {
/* switch current window to next window */
if (cur == win1) {
QsnSetCurWin(win2, NULL);
cur = win2;
} else if (cur == win2) {
QsnSetCurWin(win3, NULL);
cur = win3;
} else {
QsnSetCurWin(win1, NULL);
cur = win1;
}
}
}
}
</pre>
</div>
<br>
<br>
<p><strong><a name="FIGWNEX1A">Display Screen</a></strong></p>
<div class="box" style="width: 85%;">
<pre>
+--------------------------------------------------------------------------------+
Command Entry RCHASD0I
Request level: 1
Pr ............................................
: :
: text no attr ......................................................
: : :
: : text no attribute :
: window 1 : :
: : :
: ......... : window 3 (ul/pink) :
: : : :
: : text no : :
: : : :
: : : :
: F3 : win : :
: : : : ottom
Ty :... : : :
===&gt; ca : : :
: F3: qui : F3: quit F4: move F5: resize :
: : :
:........ :....................................................:
F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages
F11=Display full F12=Cancel F13=Information Assistant F24=More keys
+--------------------------------------------------------------------------------+
</pre>
</div>
<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>
Reference in New Issue View Git Blame Copy Permalink