806 lines
25 KiB
HTML
806 lines
25 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>Create Low-Level Environment (QsnCrtEnv) 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>Create Low-Level Environment (QsnCrtEnv) API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 75%;">
|
||
|
|
<br>
|
||
|
|
Required Parameter Group:<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
<table width="100%">
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">1</td>
|
||
|
|
<td align="left" valign="top" width="50%">Low-level environment
|
||
|
|
description</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Length of low-level environment description</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Omissible Parameter Group:<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
<table width="100%">
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">3</td>
|
||
|
|
<td align="left" valign="top" width="50%">User Extension Information</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">Length of user extension information</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">Output</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%">Low-level environment handle</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 Create Low-Level Environment (QsnCrtEnv) API creates an operating
|
||
|
|
environment for low-level interface routines.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>Display file authority</em></dt>
|
||
|
|
|
||
|
|
<dd>*USE</dd>
|
||
|
|
|
||
|
|
<dt><em>Display file library authority</em></dt>
|
||
|
|
|
||
|
|
<dd>*USE</dd>
|
||
|
|
|
||
|
|
<dt><em>Exit routine authority</em></dt>
|
||
|
|
|
||
|
|
<dd>*EXECUTE</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Low-level environment description</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The environment description for the low-level interfaces. The format of this
|
||
|
|
parameter is shown in <a href="#HDRLLDESC">Format of the Low-Level Environment
|
||
|
|
Description</a>.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of low-level environment description</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; Binary(4)
|
||
|
|
|
||
|
|
<p>The length of the low-level environment description parameter. The value
|
||
|
|
specified must be 16, 36, or 38.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Omissible Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>User extension information</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The user extension information is used to associate data and exit routines
|
||
|
|
with the low-level environment. This essentially enables the object-oriented
|
||
|
|
programming concept of inheritance, allowing the low-level environment to be
|
||
|
|
extended in a natural way. The user extension information cannot be changed
|
||
|
|
once the environment has been created. The format of this parameter is shown in
|
||
|
|
<a href="#HDRLLEXT">Format of the Low-Level User Environment Extension
|
||
|
|
Information</a>.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>User extension information length</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length of the user extension information parameter. If this parameter is
|
||
|
|
specified with a zero value, the user extension information parameter is
|
||
|
|
ignored. If a non-zero value is specified, it must be 48 and the user extension
|
||
|
|
parameter is required.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Low-level environment handle</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The low-level environment that is created as a result of this operation.
|
||
|
|
This handle can be used across activation groups if the activation group in
|
||
|
|
which the handle was created is still active.</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>Low-level environment handle</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The value for parameter 5 is returned. If an error occurs during processing,
|
||
|
|
returns -1.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRLLDESC">Format of the Low-Level Environment
|
||
|
|
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%">Color support</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">1</td>
|
||
|
|
<td align="center" valign="top">1</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Character conversion</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">CDRA conversions to 0x3F</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">DBCS support</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Coexistence</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">5</td>
|
||
|
|
<td align="center" valign="top">5</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Alternative help key support</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="left" valign="top">CHAR(10)</td>
|
||
|
|
<td align="left" valign="top">Target device</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">16</td>
|
||
|
|
<td align="center" valign="top">10</td>
|
||
|
|
<td align="left" valign="top">CHAR(20)</td>
|
||
|
|
<td align="left" valign="top">Display file</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">36</td>
|
||
|
|
<td align="center" valign="top">24</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Invite active</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">37</td>
|
||
|
|
<td align="center" valign="top">25</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Prevent override</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRLLEXT">Format of the Low-Level User Environment Extension
|
||
|
|
Information</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%">PTR(SPP)</td>
|
||
|
|
<td align="left" valign="top" width="60%">User data associated with the environment</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">16</td>
|
||
|
|
<td align="center" valign="top">10</td>
|
||
|
|
<td align="left" valign="top">PTR(PP)</td>
|
||
|
|
<td align="left" valign="top">Exit routine to call when the low-level
|
||
|
|
environment is changed</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">32</td>
|
||
|
|
<td align="center" valign="top">20</td>
|
||
|
|
<td align="left" valign="top">PTR(PP)</td>
|
||
|
|
<td align="left" valign="top">Exit routine to call when the low-level
|
||
|
|
environment is deleted</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3>Field Descriptions</h3>
|
||
|
|
|
||
|
|
<p>In the following descriptions, specifying the value <em>Same</em> indicates
|
||
|
|
the current value when using the Change Low-Level Environment (QsnChgEnv) API.
|
||
|
|
The default value refers to the value set by the Initialize Low-Level
|
||
|
|
Environment Description (QsnInzEnvD) API.</p>
|
||
|
|
|
||
|
|
<p><strong>Alternative help key support.</strong> Specifies if the alternative
|
||
|
|
help key is used. The default is no alternative help key support.</p>
|
||
|
|
|
||
|
|
<p>The possible values for this field are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">Same: Keep the current setting.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">None: No alternative help key support is used.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>QSN_F1 through QSN_F24</em></td>
|
||
|
|
<td valign="top">The specified key is the alternative help key. See <a href=
|
||
|
|
"dsm1e.htm#TBLAID">Table 1</a> for the values that correspond to these
|
||
|
|
mnemonics. When this key is pressed, the AID code for the Help key will be
|
||
|
|
returned.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>CDRA conversions to X'3F'.</strong> When CDRA conversion takes
|
||
|
|
place, all characters not supported in the target CCSID are converted to X'3F'.
|
||
|
|
Sending data containing X'3F' to the display causes adverse effects.</p>
|
||
|
|
|
||
|
|
<p>This field specifies whether the DSM low-level routines are to check for
|
||
|
|
X'3F' in the data to be displayed and perform any conversions if necessary.
|
||
|
|
Conversion will be performed for both direct and indirect operations on data
|
||
|
|
output through the QsnWrtDta and QsnWrtTDta APIs, and input through the
|
||
|
|
QsnReadInp, QsnReadMDT, QsnReadMDTAlt, QsnReadMDTAlt, QsnReadImm, and
|
||
|
|
QsnReadMDTImmAlt APIs.</p>
|
||
|
|
|
||
|
|
<p>The default is convert if character conversion (see below) is specified as
|
||
|
|
convert. Otherwise, the default is standard. (See <a href=
|
||
|
|
"dsm1e.htm#HDRLLLIMIT">Limitations and Restrictions</a> for further
|
||
|
|
details.)</p>
|
||
|
|
|
||
|
|
<p>The possible values for this field are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">Same: Keep the current setting.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">Standard: Always display data as standard data with no
|
||
|
|
replacement.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">Convert: Always check for X'3F' in data and convert to X'1F'
|
||
|
|
before displaying the data and convert X'1F' in incoming data to X'3F'.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Character conversion.</strong> This field specifies whether CDRA
|
||
|
|
conversion takes place on the data when the job CCSID does not match that of
|
||
|
|
the display device. Conversion will be performed for both direct and indirect
|
||
|
|
operations on data output through the QsnWrtDta and QsnWrtTDta APIs, and input
|
||
|
|
through the QsnReadInp, QsnReadMDT, QsnReadMDTAlt, QsnReadMDTAlt, QsnReadImm,
|
||
|
|
and QsnReadMDTImmAlt APIs.</p>
|
||
|
|
|
||
|
|
<p>The CCSID for the display device is determined from the CHRID of the device.
|
||
|
|
The default is convert if the job CCSID does not match that of the underlying
|
||
|
|
device; otherwise, standard is the default.</p>
|
||
|
|
|
||
|
|
<p>The possible values for this field are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">Same: Keep the current setting.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">Standard: Do not perform conversion.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">Convert: If the job CCSID does not match that of the display
|
||
|
|
device and neither has the value 65535, perform the appropriate conversion on
|
||
|
|
outgoing and incoming data. (See <a href="dsm1e.htm#HDRLLLIMIT">Limitations
|
||
|
|
and Restrictions</a> for further details.)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Coexistence.</strong> Whether DSM coexists with other screen I/O
|
||
|
|
methods, such as DDS- or UIM-coded interfaces, during the course of this
|
||
|
|
application. Better performance can be achieved if coexistence is not required;
|
||
|
|
the DSM APIs can assume the state of the device, for example, wide or normal
|
||
|
|
mode.</p>
|
||
|
|
|
||
|
|
<p>The default is 1.</p>
|
||
|
|
|
||
|
|
<p>The possible values for this field are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">Same: Keep the current setting.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">Coexist: Other screen I/O methods are used in conjunction with
|
||
|
|
DSM.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">Only: DSM is the only screen I/O method being used.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Color support.</strong> This field determines the color selection
|
||
|
|
used when both a monochrome and a color display attribute are supplied. The
|
||
|
|
default is select.</p>
|
||
|
|
|
||
|
|
<p>The possible values for this field are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">Same: Keep the current setting.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">Mono: Always use the monochrome attributes specified
|
||
|
|
regardless of the underlying device type.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">Always use the color attributes specified regardless of the
|
||
|
|
underlying device type.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>3</em></td>
|
||
|
|
<td valign="top">Select: Select the appropriate attribute based on the
|
||
|
|
underlying display type.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>DBCS support.</strong> This field specifies whether the data being
|
||
|
|
sent to the display contains DBCS data. This field affects, for example, how
|
||
|
|
data is handled within sessions. For devices that do not support DBCS data, the
|
||
|
|
default is standard; for DBCS-capable devices, it is mixed. If a value other
|
||
|
|
than standard is specified for a device that does not support DBCS data, a
|
||
|
|
CPFA306 error will occur.</p>
|
||
|
|
|
||
|
|
<p>The possible values for this field are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">Same: Keep the current setting.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">Standard: Always handle data as single-byte characters.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">Only: Data contains double-byte characters only. SO/SI control
|
||
|
|
characters must enclose the data; these are not implicitly added.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>3</em></td>
|
||
|
|
<td valign="top">Either: Data contains either double-byte or single-byte
|
||
|
|
characters, but not both. SO/SI control characters must enclose the DBCS part
|
||
|
|
of the data, unless a graphic DBCS value is passed. In this case, extended
|
||
|
|
ideographic attributes must enclose the data, which can be written using the
|
||
|
|
QsnWrtDta API (see <a href="QsnWrtDta.htm">Write Data (QsnWrtDta)
|
||
|
|
API</a>).</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>4</em></td>
|
||
|
|
<td valign="top">Mixed: Data may contain both single- and double-byte
|
||
|
|
characters. All double-byte character strings within the data must be enclosed
|
||
|
|
by SO/SI control characters. Graphic DBCS data must be enclosed by extended
|
||
|
|
ideographic attributes as described for the preceding value.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Display file.</strong> The name of the display file to be used. The
|
||
|
|
first 10 characters contain the file name, and the last 10 characters contain
|
||
|
|
the library name. By specifying a display file, you can, for example, direct
|
||
|
|
the input/output of different DSM environments to different devices, and you
|
||
|
|
can specify the restore display parameter on the display file at creation time.
|
||
|
|
The default for this field is blanks, which indicate that the system-supplied
|
||
|
|
display file should be used.</p>
|
||
|
|
|
||
|
|
<p>If a file name is specified, the file must contain a record named USRRCD.
|
||
|
|
This record must have the USRDFN keyword specified.</p>
|
||
|
|
|
||
|
|
<p><strong>Exit routine to call when low-level environment changed.</strong>
|
||
|
|
Exit routine to call when the low-level environment is changed through the
|
||
|
|
QsnChgEnv or QsnSetEnvWinMod API. For a description of the parameters passed to
|
||
|
|
this routine, see <a href="#HDRLLCHGX">Change Low-Level Environment Exit
|
||
|
|
Routine</a>. Specify NULL for this field if no exit routine is required.</p>
|
||
|
|
|
||
|
|
<p><strong>Exit routine to call when low-level environment deleted.</strong>
|
||
|
|
Exit routine to call when the low-level environment is deleted through the
|
||
|
|
QsnDltEnv API. The exit routine will be called before the environment itself is
|
||
|
|
deleted. For a description of the parameters passed to this routine, see <a
|
||
|
|
href="#HDRLLDLTX">Delete Low-Level Environment Exit Routine</a>. Specify NULL
|
||
|
|
for this field if no exit routine is required.</p>
|
||
|
|
|
||
|
|
<p><strong>Invite active.</strong> This field determines whether each write
|
||
|
|
that is sent out causes the device to be invited. After the device is invited,
|
||
|
|
the user is able to enter data, but the application can continue processing
|
||
|
|
instead of waiting for input. When the application is ready for the input, it
|
||
|
|
can call QsnReadInvited, which will issue a read from invited device
|
||
|
|
operation.</p>
|
||
|
|
|
||
|
|
<p>The invite active flag is ignored by the read APIs, like QsnReadMDT. If the
|
||
|
|
operation is indirect, then the read command will be added to the command
|
||
|
|
buffer. This command buffer can be passed into the QsnReadInvited API, where it
|
||
|
|
will be sent out before the read from invited device is done. If the operation
|
||
|
|
is direct, then the read command will be sent in a data stream to the device.
|
||
|
|
The new data stream will cause the invite to be retracted. A read with wait
|
||
|
|
will be performed.</p>
|
||
|
|
|
||
|
|
<p>If the display file value is specified for the environment, the INVITE
|
||
|
|
keyword must be specified on the USRRCD record of the specified display
|
||
|
|
file.</p>
|
||
|
|
|
||
|
|
<p>The timeout value for the read from invited device operation can be
|
||
|
|
controlled, by supplying a display file for the environment. The WAITRCD
|
||
|
|
parameter on the CRTDSPF command can be set to the desired timeout value. See
|
||
|
|
the return value for the QsnReadInvited API to determine the return value if
|
||
|
|
the read from invited device operation times out.</p>
|
||
|
|
|
||
|
|
<p>The possible values for this field are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">Same: Keep the current setting.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">Not active: The INVITE keyword, if specified in the display
|
||
|
|
file, will be ignored. A normal read of the device will be performed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">Active: Any request to get data from the display will result
|
||
|
|
in a read from invited device being issued.
|
||
|
|
|
||
|
|
<p>For more information on invite processing, see the <a href=
|
||
|
|
"../books/sc415715.pdf" target="_blank">Application Display
|
||
|
|
Programming</a><img src="wbpdf.gif" alt="Link to PDF"> book.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Prevent override.</strong> This field determines whether the display
|
||
|
|
file used by DSM can be overridden or not. This value is ignored if the display
|
||
|
|
file value is not specified.</p>
|
||
|
|
|
||
|
|
<p>The possible values for this field are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>0</em></td>
|
||
|
|
<td valign="top">Same: Keep the current setting.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>1</em></td>
|
||
|
|
<td valign="top">Do not prevent override: When opened, the display file will
|
||
|
|
allow overrides. For create and initialize operations, this is the
|
||
|
|
default.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><em>2</em></td>
|
||
|
|
<td valign="top">Prevent overrides: When the display file is opened, the flag
|
||
|
|
to block overrides will be set.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>User data associated with the environment.</strong> A pointer to any
|
||
|
|
data the user wants to associate with this environment. This field can be used
|
||
|
|
by the programmer to attach information to the low-level environment that can
|
||
|
|
be of any format. For example, if multiple environments are being used, a list
|
||
|
|
of the fields currently defined in an environment could be associated with the
|
||
|
|
environment through this pointer. Specify NULL for this field if you do not
|
||
|
|
have any user data.</p>
|
||
|
|
|
||
|
|
<p><strong>Target device.</strong> The program device name of the target
|
||
|
|
display device for the environment. This parameter must be specified with a
|
||
|
|
value of *REQUESTER, which is the default.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRDSMXT9">Exit Routine Error Handling</a></h3>
|
||
|
|
|
||
|
|
<p>If an exception occurs during the processing of an exit routine, the
|
||
|
|
exception is ignored and processing continues. A CPFA318 will be issued as a
|
||
|
|
diagnostic message only. You can explicitly handle errors in an exit routine by
|
||
|
|
adding an exception handler to the routine.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRLLCHGX">Change Low-Level Environment Exit Routine</a></h3>
|
||
|
|
|
||
|
|
<p>This exit routine, if specified on the user extension information, is called
|
||
|
|
after the environment is changed through the QsnChgEnv or QsnSetEnvWinMod API.
|
||
|
|
The following parameter is passed to the exit routine:</p>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
<table width="100%">
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">1</td>
|
||
|
|
<td align="left" valign="top" width="50%">Low-level environment handle</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p><strong>Change Low-Level Environment Exit Routine Parameter</strong></p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Low-level environment handle</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>A handle for the environment that was changed.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRLLDLTX">Delete Low-Level Environment Exit Routine</a></h3>
|
||
|
|
|
||
|
|
<p>This exit routine, if specified on the user extension information, is called
|
||
|
|
before the environment is deleted. The following parameter is passed to the
|
||
|
|
exit routine:</p>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
<table width="100%">
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">1</td>
|
||
|
|
<td align="left" valign="top" width="50%">Low-level environment handle</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p><strong>Delete Low-Level Environment Exit Routine Parameter</strong></p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Low-level environment handle</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>A handle for the environment that was deleted.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDREDERR">Error Messages</a></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">CPFA314 E</td>
|
||
|
|
<td valign="top">Memory allocation error.</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">CPFA327 E</td>
|
||
|
|
<td valign="top">Low level environment description value incorrect.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFA344 E</td>
|
||
|
|
<td valign="top">The file &2 in library &3 is not valid.</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>
|
||
|
|
|