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

529 lines
19 KiB
HTML
Raw 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>Using Session 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 -->
<!-- File created for V5R2 -->
<!-- 030718 KYLEG :LF EBCDIC character not documented -->
<!-- and update DBCS and UCS2 -->
<!-- considerations for DSM D99394. -->
<!-- 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 Session Services APIs</h2>
<h3><a name="Header_594">Session Details</a></h3>
<p>The following figure shows the default attributes provided by
the DSM session description for a session.</p>
<p><strong><a name="FIGSESS1">Session Attributes</a></strong></p>
<table border>
<tr>
<td>
<pre>
... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ... ... 8
*-------------------------------------------------------------------------------*
1| |
2| .................................... |
3| : *------------------------------* : |
4| : | | : |
5| : | | : |
6| : | | : |
7| : | SCROLLER | : |
8| : | | : |
9| : | | : |
10| : *------------------------------* : |
11| : : |
12| : ===&gt; __________________________ : |
13| : ________________________________ : |
14| : : |
15| : F3=Exit F6=Print F9=Retrieve : |
16| : F14=Move F15=Resize F22=Switch : |
17| : : |
18| :..................................: |
19| |
20| |
21| |
22| |
23| |
24| |
.-------------------------------------------------------------------------------.
</pre>
</td>
</tr>
</table>
<p>The main component of a session is the scrollable area, or <strong>
scroller</strong>, where output data can be displayed for the session. A
session may or may not have a data input line, depending on the application. A
session that uses the default attributes has an input line underneath the
scroller. You can allow the size and location of the session attributes to
default based on the window size, or you can specify these explicitly. Up to
two lines of command key descriptions can appear below the scroller and can be
managed by a session. For details on the session description see <a href=
"QsnCrtSsn.htm">Create a Session (QsnCrtSsn) API</a>.</p>
<p>When a window containing a session is moved or resized, the scroller and any
automatically defined fields are redrawn to reflect the new window positions
and size. If any additional items have been added to the session through the
low-level interface APIs, you must supply an exit program that will reposition
such items explicitly. See <a href="QsnCrtSsn.htm">Create a Session (QsnCrtSsn)
API</a> for details on the exit program.</p>
<br>
<h3><a name="Header_595">Line Mode and Character Mode I/O</a></h3>
<p>Session I/O can be performed in a line mode or a character mode basis. In
line mode, each call to the line-specific interfaces operates on a complete
line, either on input or output. In character mode, I/O is performed a
character at a time. This means that multiple I/O operations can be issued to
operate on the current line. For example, an output operation could output
several characters. Then a backspace operation could be followed by input from
the current cursor position. (All input operations are still performed in block
mode, where the input is not available until an AID-generating key has been
pressed.)</p>
<p>Line mode output is performed using the Write Line to Scroller
(QsnWrtSclLin) API. This API writes a line of data to the next session line and
sets the active position (see <a href="#HDRACTPOS">Active Position</a>) to the
start of the next line after the added line. For character output, the Write
Characters to Scroller (QsnWrtSclChr) API is used. This API outputs a string of
characters starting at the active position. After this operation completes, the
active position is one position past the last character written, or it is the
position specified by a control character sequence if this appears at the end
of the data.</p>
<br>
<h3><a name="HDRCMDKEY">Command Key Action Routines</a></h3>
<p>Part of the session description is an array of command key actions. Each
action is an exit routine that is specified as a function pointer. When a
command key is pressed during a QsnReadSsnDta operation, if an action has been
specified, the appropriate exit routine is called. Otherwise, an <samp>Invalid
key pressed</samp> error message will be issued. DSM provides a group of
functions that can be called, or user-defined exit-routines can be specified.
The action routines are specified as an array of 24 function pointers in the
session description. (See <a href="QsnCrtSsn.htm">Create a Session (QsnCrtSsn)
API</a> for details.) The default values for the action routines DSM calls
are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left">Cmd Key</th>
<th align="left">Action Routine</th>
</tr>
<tr>
<td align="center" valign="top"><em>1</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>2</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>3</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>4</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>5</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>6</em></td>
<td align="left" valign="top">Print Scroller Data (QsnPrtScl)</td>
</tr>
<tr>
<td align="center" valign="top"><em>7</em></td>
<td align="left" valign="top">Roll Scroller Down (QsnRollSclDown)</td>
</tr>
<tr>
<td align="center" valign="top"><em>8</em></td>
<td align="left" valign="top">Roll Scroller Up (QsnRollSclUp)</td>
</tr>
<tr>
<td align="center" valign="top"><em>9</em></td>
<td align="left" valign="top">Retrieve Session Input Line to Input Line (QsnRtvSsnLin)</td>
</tr>
<tr>
<td align="center" valign="top"><em>10</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>11</em></td>
<td align="left" valign="top">Toggle Line Wrap/Truncate Mode (QsnTglSclWrp)</td>
</tr>
<tr>
<td align="center" valign="top"><em>12</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>13</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>14</em></td>
<td align="left" valign="top">Move Window by User (QsnMovWinUsr)</td>
</tr>
<tr>
<td align="center" valign="top"><em>15</em></td>
<td align="left" valign="top">Resize Window by User (QsnRszWinUsr)</td>
</tr>
<tr>
<td align="center" valign="top"><em>16</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>17</em></td>
<td align="left" valign="top">Display Scroller Top (QsnDspSclT)</td>
</tr>
<tr>
<td align="center" valign="top"><em>18</em></td>
<td align="left" valign="top">Display Scroller Bottom (QsnDspSclB)</td>
</tr>
<tr>
<td align="center" valign="top"><em>19</em></td>
<td align="left" valign="top">Shift Scroller Left (QsnShfSclL)</td>
</tr>
<tr>
<td align="center" valign="top"><em>20</em></td>
<td align="left" valign="top">Shift Scroller Right (QsnShfSclR)</td>
</tr>
<tr>
<td align="center" valign="top"><em>21</em></td>
<td align="left" valign="top">Display Command Line Window (direct mapping to QUSCMDLN API)</td>
</tr>
<tr>
<td align="center" valign="top"><em>22</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>23</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top"><em>24</em></td>
<td align="left" valign="top">&nbsp;</td>
</tr>
</table>
<p>The default action routines for command keys 7, 8, 19, and 20
(QsnRollSclDown, QsnRollSclUp, QsnShfSclL, and QsnShfSclR, respectively) will
pass any numeric input to the API when the command key is pressed. For example,
to shift the scroller to the right by 10 columns, the value 10 could be entered
at the input line prior to pressing command key 20. Non-numeric input is
ignored.</p>
<p>When a user-defined action routine is called, it is passed the following
information:</p>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Information Passed to the Action Routine<br>
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Session handle</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
<td></td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Input buffer</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
<td></td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Returned action</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(1)</td>
</tr>
</table>
<br>
</div>
<p>When the specified command key is pressed, the action routine for the
command key is called. If you change the default values to have a command key
call a different DSM API, you cannot specify the API directly because the
action routine is passed specific parameters. You must define an action routine
that can accept the action routine parameters and then call the desired DSM API
with the appropriate parameters. You can define a generic action routine that
is specified for each key you want to define, and in that action routine query
the input buffer to determine the command key pressed and the appropriate
action to take.</p>
<p>When an action routine is called, any data on the input line will remain.
You can use the QsnWTD API to clear the line. However, if you write to the
session or perform any action that causes the session to be redrawn in the
action routine, the data on the input line will be lost.</p>
<p>If an exception occurs during the processing of an action routine, it is
ignored and processing continues. A CPFA3D9 will be issued as an exception from
the QsnReadSsnDta API when control returns from the action routine. You can
handle exceptions explicitly by adding an exception handler to the action
routine.</p>
<br>
<h3><a name="Header_597">Action Routine Parameters</a></h3>
<dl>
<dt><strong>Session handle</strong></dt>
<dd>INPUT; BINARY(4)
<p>The session currently active. If the action routine causes the active
session to change, this variable will be changed to reflect the new
session.</p>
</dd>
<dt><strong>Input buffer</strong></dt>
<dd>INPUT; BINARY(4)
<p>The input buffer containing the results of the input operations that caused
this exit routine to be called. The input buffer can be queried using the
low-level interface routines. This is the buffer that was passed to
QsnReadSsnDta.</p>
</dd>
<dt><strong>Returned action</strong></dt>
<dd>OUTPUT; CHAR(1)
<p>The variable containing the flag indicating if, following a successful
return from this exit routine, control returns to the caller of the Read Data
from Session (QsnReadSsnDta) API or if QsnReadSsnDta handles the next input
operation. If an error occurs in the exit routine, control always returns to
the caller. The possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">QsnReadSsnDta continues to handle the next input operation.
Control does not return to the caller.</td>
</tr>
<tr>
<td valign="top"><em>1</em></td>
<td valign="top">QsnReadSsnDta returns control to the caller. The output
parameters for QsnReadSsnDta are filled in appropriately.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3><a name="HDRACTPOS">Active Position</a></h3>
<p>The active position in the scroller is the point at which data will be
written for character mode operations. The active position is affected by
output operations to the scroller, including the writing of data that contains
EBCDIC display control character sequences.</p>
<p>
DSM does not allow the application to partially overwrite data of one type, with
another type of data. Instead, it removes the mismatched data and all data that
follows it from the scroller line, so that the new data may be inserted in its place.
</p>
<p>
A single scroller line can contain a mixture of data types, including EBCDIC, DBCS and
CCSID-based data. The QsnSclBS and QsnSclCR APIs change the active position of
the scroller line. Subsequent calls to the QsnWrtSclChr or QsnWrtSclChrCC APIs
will cause
existing data in the line to be overwritten, starting at the active position. If
the new data is the same type or CCSID of the existing data, the new data will
replace the existing data. However, if the existing data is not the same type
or CCSID as the new data, DSM will remove the subset of mismatched existing
data from the line. Any data in the line that follows the mismatched data will
also be removed.
</p>
<p>
For example, the scroller line contains some EBCDIC data followed by DBCS data.
The QsnSclBS API is called such that the active position is moved within the
DBCS data. If QsnWrtSclChr is called to write EBCDIC data to
the active position, the DBCS data is removed from the line and the new EBCDIC
data is written. The result is a line that contains the original EBCDIC data
with the new EBCDIC data appended to it.
</p>
<p>
Consider the same scroller line that contains EBCDIC followed by DBCS data.
QsnSclBS is called such that the active position is before the last byte
of EBCDIC data. If QsnWrtSclChr is called to write two bytes of EBCDIC data,
the last byte of existing EBCDIC data is replaced. However, the second byte of the
new data would overwrite the shift out character of the existing DBCS data.
DSM will remove the DBCS data from the line, and write the last byte of the
new EBCDIC data to the line. The result is a line that contains all but the
last byte of the original EBCDIC data with the new EBCDIC data appended to it.
</p>
<p>
In both examples, if other combinations of EBCDIC, DBCS or CCSID-based data
were present in the line after the DBCS data, all of that data would have
also been removed with the DBCS data. If other combinations of data
types or CCSIDs in the line would have preceded the EBCDIC data, all of the
preceding data would be unchanged.
</p>
<br>
<h3><a name="HDREBCDICC">EBCDIC Display Control Characters</a></h3>
<p>The data written to the scroller may contain display control characters
consisting of single byte EBCDIC values. If specified on the session
description (see <a href="QsnCrtSsn.htm">Create a Session (QsnCrtSsn) API</a>),
the APIs for writing data to the scroller will check for and interpret such
control characters. Each control character recognized in the output data is
replaced by a call to a DSM API or internal routine that will perform the
appropriate function. The following table shows the control characters that
are recognized and the APIs that are called, where applicable.</p>
<p><strong><a name="TBLEBCDICC">EBCDIC Display Control Characters</a></strong></p>
<table border width="60%">
<tr>
<th align="left" valign="top">Character</th>
<th align="left" valign="top">Hex Value</th>
<th align="left" valign="top">Interpretation</th>
</tr>
<tr>
<td align="left" valign="top" width="30%">HT</td>
<td align="left" valign="top" width="30%">05</td>
<td align="left" valign="top" width="40%">QsnSclTab</td>
</tr>
<tr>
<td align="left" valign="top">VT</td>
<td align="left" valign="top">0B</td>
<td align="left" valign="top">QsnSclLF</td>
</tr>
<tr>
<td align="left" valign="top">FF</td>
<td align="left" valign="top">0C</td>
<td align="left" valign="top">QsnSclFF</td>
</tr>
<tr>
<td align="left" valign="top">CR</td>
<td align="left" valign="top">0D</td>
<td align="left" valign="top">QsnSclCR</td>
</tr>
<tr>
<td align="left" valign="top">NL</td>
<td align="left" valign="top">15</td>
<td align="left" valign="top">QsnSclNL</td>
</tr>
<tr>
<td align="left" valign="top">LF</td>
<td align="left" valign="top">25</td>
<td align="left" valign="top">QsnSclNL</td>
</tr>
<tr>
<td align="left" valign="top">BS</td>
<td align="left" valign="top">16</td>
<td align="left" valign="top">QsnSclBS</td>
</tr>
<tr>
<td align="left" valign="top">BEL</td>
<td align="left" valign="top">2F</td>
<td align="left" valign="top">QsnBeep</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRSSDBCS">DBCS Considerations</a></h3>
<p>If the low-level environment description (see <a href=
"QsnCrtEnv.htm#HDRLLDESC">Format of the Low-Level Environment Description</a>)
for the session specifies DBCS support, the session services will check for and
handle DBCS data. DBCS data must be enclosed by shift control (SO/SI)
characters. The DBCS support field determines the type of the input field
defined for the session, but does not affect the checking done for session
output data other than to indicate that DBCS data may be present. The scroller
does not display data using extended NLS attributes, regardless of the
underlying display device support.</p>
<br>
<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>