529 lines
19 KiB
HTML
529 lines
19 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 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| : ===> __________________________ : |
|
|
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"> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"><em>2</em></td>
|
|
<td align="left" valign="top"> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"><em>3</em></td>
|
|
<td align="left" valign="top"> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"><em>4</em></td>
|
|
<td align="left" valign="top"> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"><em>5</em></td>
|
|
<td align="left" valign="top"> </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"> </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"> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"><em>13</em></td>
|
|
<td align="left" valign="top"> </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"> </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"> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"><em>23</em></td>
|
|
<td align="left" valign="top"> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"><em>24</em></td>
|
|
<td align="left" valign="top"> </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>
|
|
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>
|
|
|