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/QsnSetFld.htm

1141 lines
39 KiB
HTML
Raw Normal View History

Add readme and dist folders
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 Field (QsnSetFld) 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 Field (QsnSetFld) API</h2>
<div class="box" style="width: 75%;">
<br>
&nbsp;&nbsp;Omissible 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%">Field ID</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Field length</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Row</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Column</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">Field format word (FFW)</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(2)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Field control words (FCW)</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Number of field control words</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Monochrome attribute</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Color attribute</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Command buffer handle</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">11</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">12</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 Field (QsnSetFld) API defines an input field on the screen at the
given row and column. The following occurs when this command is issued to the
control unit as a direct operation or when the buffer containing the command is
written out:</p>
<ul>
<li>Any outstanding AID requests are cleared.<br>
<br>
</li>
<li>The keyboard is locked.<br>
<br>
</li>
<li>If there is an entry in the format table whose starting address is equal to
the address for this field, then that entry is modified. The FFW of the
existing entry is replaced by the new FFW and the previous screen starting
attribute is overlaid with the new screen starting attribute. The ending screen
attribute is not rewritten. All FCWs and the length parameter are ignored. See
the 5250 data stream documentation for details.<br>
<br>
</li>
<li>If no entry can be found in the table for the field being defined, a new
entry will be added to the end of the table. However, the address must be
greater than the ending address of the field currently defined last in the
format table or an error will occur. If the new entry is valid, it will contain
the field's FFW, the optional FCWs, and the field's starting and ending
address. An error will occur if an attempt is made to define too many fields on
the screen (see the 5250 data stream documentation for details).</li>
</ul>
<p>The display address after this operation will be the starting field address
minus 1 if row and column are specified as valid positive integers or if this
is the first field specified within the current WTD command. Otherwise, the
display address will be one position past the ending screen attribute.</p>
<p>This command corresponds indirectly to the 5250 Write to Display (WTD)
command with a Set Buffer Address order and a Start of Field order if the row
and column parameters are specified. (For an indirect operation, a WTD is
placed in the command buffer only if one does not already exist in that
buffer.)</p>
<br>
<h3>Authorities and Locks</h3>
<p>None</p>
<br>
<h3>Restrictions</h3>
<p>The same restrictions apply as for the Write Data (QsnWrtDta) API, with the
exception that the trailing field attribute can be written past the end of the
screen. (It will be suppressed by the control unit.)</p>
<br>
<h3>Omissible Parameter Group</h3>
<dl>
<dt><strong>Field ID</strong></dt>
<dd>INPUT; BINARY(4)
<p>The field ID to be associated with this field. The value specified can be
any nonzero integer value. For APIs that accept a field ID parameter, this
value can be subsequently used instead of the row and column parameter to
specify a screen address. If the given ID is already defined, this operation
will redefine that field ID with the values specified. To remove a field ID
definition, use the QsnDltFldId API.</p>
<p>If a previously defined field ID is supplied and some or all of the
parameters are omitted, the field is defined using the current field definition
values for those omitted parameters.</p>
<p>If this field is omitted or specified with a value of zero, then no field ID
is associated with this field description.</p>
</dd>
<dt><strong>Field length</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the field being defined. If no field ID is specified, the
length must be a positive integer value greater than 1 for signed numeric
fields and greater than 0 for all other field types. The entire field must fit
on the display. If a field ID is specified with a nonzero value, the length may
be 0, in which case a field will not be defined on the screen; however, this
will associate the field definition with the specified field ID.</p>
</dd>
<dt><strong>Row</strong></dt>
<dd>INPUT; BINARY(4)
<p>The row at which to define the field. The row parameter must refer to a row
no greater than the current screen or window mode height (if window mode is
enabled). The actual screen row used for a screen I/O operation is calculated
using the formula base+offset=actual. The base is the row location of the top
window border (0 for full screen) if offset is positive, or the row location of
the bottom window border (screen height plus 1 for full screen) if offset is
negative. The offset is the row parameter value specified, and actual is the
actual screen row to be used. A CPFA307 error occurs if an incorrect row value
is specified.</p>
<p>The starting field address will be the row and column locations given if
both parameters are specified. Otherwise, it will be the current display
address plus 1. If this is the case and the command is a direct operation, or
the buffer specified does not contain a preceding output operation that sets
the display address, the current display address is set to row 1, column 1,
prior to writing the initial screen attribute and the field definition. The
ending field address for this field is the starting field address plus the
field length.</p>
<p>If a field ID is supplied along with a row and column, the row and column
parameters will be stored as specified. These parameters will be used as
relative or actual screen positions on a subsequent operation, depending upon
the window mode setting for the environment supplied with that operation.</p>
<p>If a previously undefined field ID is supplied with this operation, the row
and column parameters must be specified. Also, the row and column parameters
must both be specified or omitted; one cannot be specified if the other is
omitted. A CPFA307 error occurs if an incorrect cursor position is specified.
On some devices, row and column can both be specified as 1, which will cause
the field to be defined at row 1, column 1, with a screen attribute of normal
(X'20'). If this is the case, then any initial screen attribute parameters
specified are ignored. This is only supported by certain devices. Whether or
not this is supported can be determined by the Query 5250 (QsnQry5250) API.</p>
</dd>
<dt><strong>Column</strong></dt>
<dd>INPUT; BINARY(4)
<p>The column at which to write the data. The column parameter must refer to a
column no greater than the current screen or window mode width (if window mode
is on). The actual screen column used for a screen I/O operation is calculated
using the formula base+offset=actual. The base is the column location of the
left window border (0 for full screen) if offset is positive, or the column
location of the center window border (screen width plus 1 for full screen) if
offset is negative. The offset is the column parameter value specified, and
actual is the actual screen column to be used. A CPFA307 error occurs if an
incorrect column value is specified.</p>
</dd>
<dt><strong>Field format word (FFW)</strong></dt>
<dd>INPUT; CHAR(2)
<p>The field format word is a 2-byte value that controls the type of the field
being defined. <a href="#TBLFFW">Table 6</a> shows the field types, and the
corresponding bit to be set for each type. To omit this parameter, specify
X'00' in both characters of the parameter. You must specify this parameter to
define an input field, and it is required if a field control word is
specified.</p>
</dd>
<dt><strong>Field control words (FCW)</strong></dt>
<dd>INPUT; CHAR(*)
<p>An array of 2-byte field control words. The field control words are 2-byte
values that request certain functions to be performed. <a href="#TBLFCW">Table
7</a> shows the valid field control word values, their function, and mnemonics
for those values.</p>
<p>The 5250 CCSID-based I/O specific FCWs are not allowed (<a href=
"QsnSetFldCC.htm">QsnSetFldCC</a> must be used to create CCSID-capable fields).
If the CCSID-based I/O CCSID or Maximum data length FCWs are given here, a
CPFA332 will result. FCWs will not be exhaustivly checked to see if they are
formatted correctly or to see if the function requested is valid for the
current device. However, some FCWs are checked against the support provided by
the device and a CPFA306 signaled if an incompatibility is found. <a href=
"#TBLDEVFCW">Table 8</a> shows the display capablility and FCW combinations
that are valid.</p>
<p>Errors not found here may be detected and reported when the FCW is required
during subsequent command and keystroke processing. See the 5250 data stream
documentation for further details about the meaning and use of these
functions.</p>
</dd>
<dt><strong>Number of field control words</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of control words in the field control word array. Omitting this
parameter or specifying it with a value of 0 indicates that no field control
words are specified with the FCW parameter. If this parameter is specified with
a nonzero value, the FCW parameter is required; if the FCW parameter is
omitted, a CPFA31E error is issued.</p>
</dd>
<dt><strong>Monochrome attribute</strong></dt>
<dd>INPUT; CHAR(1)
<p>The initial screen attribute for monochrome displays. A screen attribute is
required for defining a field on the screen; if this parameter is omitted and
monochrome attributes are to be used, X'20' is assumed. The initial screen
attribute is written one position to the left of the starting field address.
The ending screen attribute (X'20') is supplied by the controller and written
at the end-of-field address plus 1.</p>
<p>The monochrome attribute and color attribute parameters consist of 1 byte
that will be used as the screen attribute for a monochrome or a color display,
respectively. One of these parameters will be selected based on the underlying
display type, and the other will be discarded. See <a href=
"dsm1e.htm#HDRSCRATTR">Screen Attribute Characters</a> for a description of
the screen attribute values.</p>
</dd>
<dt><strong>Color attribute</strong></dt>
<dd>INPUT; CHAR(1)
<p>The initial screen attribute for color displays. A screen attribute is
required for defining a field on the screen; if this parameter is omitted and
color attributes are to be used, X'20' is assumed. See <a href=
"dsm1e.htm#HDRSCRATTR">Screen Attribute Characters</a> for a description of
the screen attribute values.</p>
</dd>
<dt><strong>Command buffer handle</strong></dt>
<dd>INPUT; BINARY(4)
<p>A handle for the command buffer in which to store the command. If this
parameter is omitted or specified as 0, this is a direct operation and the
starting field address will be the supplied location. Otherwise, this is an
indirect operation and the command is stored in the command buffer without an
I/O operation taking place.</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="HDRFFW">Format of the Field Format Word</a></h3>
<p>The following table shows the field types and the bits to set for each type
for the field format word (FFW).</p>
<p><strong><a name="TBLFFW">Table 6. Field Format Words</a></strong></p>
<table border width="100%">
<tr>
<th align="center" valign="top"><strong>Field Type</strong></th>
<th align="center" valign="top"><strong>Bit To Set</strong></th>
<th align="center" valign="top"><strong>Mnemonic</strong></th>
<th align="center" valign="top"><strong>Description</strong></th>
</tr>
<tr>
<td align="left" valign="top" width="15%">&nbsp;</td>
<td align="center" valign="top" width="10%">0-15</td>
<td align="center" valign="top" width="30%">QSN_NO_FFW</td>
<td align="left" valign="top" width="45%">If bits 0 to 15 are set to 0, then no
FFW is used. The field will be defined as an output field and its contents will
not be returned by operations such as the Read Input Fields (QsnReadInp)
API.</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;</td>
<td align="center" valign="top">0-1</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">The first two bits of a field format word must be
01. The mnemonic for every other field type includes this setting.</td>
</tr>
<tr>
<td align="center" valign="top">Bypass</td>
<td align="center" valign="top">2</td>
<td align="center" valign="top">QSN_FFW_BYPASS</td>
<td align="left" valign="top">If this bit is set, this is a bypass field and
entries are not allowed in it. If the operator tries to enter something in this
field, an error results.</td>
</tr>
<tr>
<td align="center" valign="top">Dup Enable</td>
<td align="center" valign="top">3</td>
<td align="center" valign="top">QSN_FFW_DUP</td>
<td align="left" valign="top">If this bit is set, duplication is allowed in the
field. The controller repeats X'1C' from the cursor position to the end of the
field when the operator presses the Dup key; this shows on the display as an
overstruck asterisk.</td>
</tr>
<tr>
<td align="center" valign="top">Modified data tag (MDT)</td>
<td align="center" valign="top">4</td>
<td align="center" valign="top">QSN_FFW_MDT</td>
<td align="left" valign="top">Setting this bit sets the modified data tag for
this field. The field will then be read with the Read Modified Fields
(QsnReadMDT) API (see <a href="QsnReadMDT.htm">Read Modified Fields
(QsnReadMDT) API</a>) as if the operator had modified it.</td>
</tr>
<tr>
<td align="center" valign="top"><strong>Field Shift/ Edit
Specification</strong></td>
<td align="center" valign="top"><strong>Bits 5-7</strong></td>
<td align="center" valign="top"><strong>Mnemonic</strong></td>
<td align="center" valign="top"><strong>Description</strong></td>
</tr>
<tr>
<td align="center" valign="top">Alphabetic shift</td>
<td align="center" valign="top">000</td>
<td align="center" valign="top">QSN_FFW_ALPHA_SHIFT</td>
<td align="left" valign="top">The field accepts all characters. The shift keys
are acknowledged. The characters on the lower symbol of each key are
valid.</td>
</tr>
<tr>
<td align="center" valign="top">Alphabetic only</td>
<td align="center" valign="top">001</td>
<td align="center" valign="top">QSN_FFW_ALPHA_ONLY</td>
<td align="left" valign="top">The field accepts only characters A-Z (both
uppercase and lowercase) plus the comma (,), period (.), minus (-), space, and
DUP (if the DUP-enable bit is on in the associated Field Format Word (FFW)).
Other characters cause operator errors. Some special characters
are also acceptable (see the 5250 data stream documentation).</td>
</tr>
<tr>
<td align="center" valign="top">Numeric shift</td>
<td align="center" valign="top">010</td>
<td align="center" valign="top">QSN_FFW_NUM_SHIFT</td>
<td align="left" valign="top">The field accepts all characters from all
keys.</td>
</tr>
<tr>
<td align="center" valign="top">Numeric only</td>
<td align="center" valign="top">011</td>
<td align="center" valign="top">QSN_FFW_NUM_ONLY</td>
<td align="left" valign="top">The field accepts only characters 0-9 and the
comma (,), period (.), minus (-), plus (+), space, and DUP (if the DUP-enable
bit is on in the associated Field Format Word (FFW)). Other characters cause
operator errors.
<p>The unit position of this field will carry the sign digit for the field. If
the field is exited with the Field - key, the last character in the field will
be 'D' zoned, unless the last character in the field is a '+', '-', ',', '.',
or space, in which case an error will be posted. In a center-adjusted field,
the field will be center-adjusted before any 'D' zoning or testing of the sign
character is performed. When a negative field (from the Field - key) is
returned, the units digit will have a 'D' zone.</p>
</td>
</tr>
<tr>
<td align="center" valign="top">Katakana shift</td>
<td align="center" valign="top">100</td>
<td align="center" valign="top">QSN_FFW_KATA</td>
<td align="left" valign="top">This is the same as the alphabetic shift except
that the keyboard is placed in the Katakana shift on the Japan Katakana data
entry, typewriter, and G keyboards. This reverses the order of the cursor
direction with respect to the screen. If the display is in bidirectional mode,
this changes the cursor direction to left to center; otherwise, it changes the
cursor direction to center to left.</td>
</tr>
<tr>
<td align="center" valign="top">Digits only</td>
<td align="center" valign="top">101</td>
<td align="center" valign="top">QSN_FFW_DIGIT_ONLY</td>
<td align="left" valign="top">The field allows keys 0-9 and DUP (if the
DUP-enable bit is on in the associated Field Format Word (FFW)).</td>
</tr>
<tr>
<td align="center" valign="top">I/O</td>
<td align="center" valign="top">110</td>
<td align="center" valign="top">QSN_FFW_IO</td>
<td align="left" valign="top">This field will not accept any data keys from the
keyboard. An operator error is posted if keystrokes are entered in this field.
The operator may move the cursor into and out of this field similar to
operation in any non-bypass input field (that is, Field Advance will position
the cursor to the start of the field).
<p>This field can be used for input from feature devices such as a magnetic
stripe reader of selector light pen while data input from the keyboard is
excluded.</p>
<p>The Field +, Field Exit, and Dup keys are valid for this field and
performance is the same as that for any non-bypass input field.</p>
</td>
</tr>
<tr>
<td align="center" valign="top">Signed Numeric</td>
<td align="center" valign="top">111</td>
<td align="center" valign="top">QSN_FFW_SIGNED_NUMERIC</td>
<td align="left" valign="top">The field allows keys 0-9 and DUP (if the
DUP-enable bit is on in the associated Field Format Word (FFW)). Typing any
other character will cause an operator error display.
<p>This field reserves the center-hand position for a sign display (- for
negative and null for positive); therefore, the largest number of characters
that can be entered into this field is one less than the field length. A signed
numeric field less than 2 characters long will cause an error to be
flagged.</p>
<p>No digit may be keyed into the centermost position; however, the cursor can
be positioned there by using the cursor movement keys and then followed by the
F+ or F- key. This allows changing the sign without affecting the rest of the
field.</p>
</td>
</tr>
<tr>
<td align="center" valign="top">Signed Numeric (continued)</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">If this field is not a mandatory fill or
center-adjust field, it is still handled as if it were specified as a
center-adjust blank fill field. If the Field - key is used to exit this field,
the field will be center-adjusted and a negative sign placed in the centermost
position of the field. The Field Exit or Field + key will insert a blank in the
centermost position and center-adjust this field.
<p>Before this field is returned on an input operation, it is changed as
follows:</p>
<ul>
<li>If the centermost character is a negative sign, the zone of the low order
digit is set to a X'D'.</li>
<li>If the centermost character is not a negative sign, the low order digit is
not changed.</li>
</ul>
<p>In either case, the centermost sign position is not sent to the host.</p>
</td>
</tr>
<tr>
<td align="center" valign="top"><strong>Field Type</strong></td>
<td align="center" valign="top"><strong>Bit to Set</strong></td>
<td align="center" valign="top"><strong>Mnemonic</strong></td>
<td align="center" valign="top"><strong>Description</strong></td>
</tr>
<tr>
<td align="center" valign="top">Auto Enter</td>
<td align="center" valign="top">8</td>
<td align="center" valign="top">QSN_FFW_AUTO_ENTER</td>
<td align="left" valign="top">If this bit is set, this is an auto enter field.
The auto enter function occurs only for valid Field Exit/Field +, Field -, and
Dup exit keys, or if the last data character position is typed into the auto
enter field. After any required center-adjust, mandatory fill, data
duplicating, or check digit operations are successfully performed, the auto
enter function causes the panel to be sent to the host as if the Enter key had
been pressed.</td>
</tr>
<tr>
<td align="center" valign="top">Field Exit Required</td>
<td align="center" valign="top">9</td>
<td align="center" valign="top">QSN_FFW_AUTO_FER</td>
<td align="left" valign="top">If this bit is set, a nondata key must be typed
to leave the field. When the last data character is typed into the last
position of the field, the cursor will remain under the character and blink,
signifying the controller is waiting for an exit key. Any nondata key will
satisfy the exit requirement (including cursor movement or function keys).</td>
</tr>
<tr>
<td align="center" valign="top">Monocase</td>
<td align="center" valign="top">10</td>
<td align="center" valign="top">QSN_FFW_AUTO_MONOCASE</td>
<td align="left" valign="top">If this bit is set, then regardless of the shift
state of the typewriter keyboard, only the uppercase A-Z is entered into the
field being typed (that is, if a lowercase a is typed, the uppercase A is
entered). All other characters are unaffected. Certain characters on some
typewriter keyboards also will be translated to uppercase (see the 5250
data stream documentation).</td>
</tr>
<tr>
<td align="center" valign="top">Reserved</td>
<td align="center" valign="top">11</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top">Mandatory Enter</td>
<td align="center" valign="top">12</td>
<td align="center" valign="top">QSN_FFW_ME</td>
<td align="left" valign="top">If this bit is set, the operator must enter
something in the field before the controller allows the Enter key to be active.
The controller recognizes the state of these fields by checking the MDT bit for
the field. If the operator tries to bypass the field using a Field +, Field -,
or Field Exit key, an error occurs.</td>
</tr>
<tr>
<td align="center" valign="top"><strong>Center-Adjust/ Mandatory
Fill</strong></td>
<td align="center" valign="top"><strong>Bits 13-15</strong></td>
<td align="center" valign="top"><strong>Mnemonic</strong></td>
<td align="center" valign="top"><strong>Description</strong></td>
</tr>
<tr>
<td align="center" valign="top">No adjust specified</td>
<td align="center" valign="top">000</td>
<td align="center" valign="top">QSN_FFW_NOADJUST</td>
<td align="left" valign="top">No field adjustment occurs.</td>
</tr>
<tr>
<td align="center" valign="top">Reserved</td>
<td align="center" valign="top">001</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top">Reserved</td>
<td align="center" valign="top">010</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top">Reserved</td>
<td align="center" valign="top">011</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top">Reserved</td>
<td align="center" valign="top">100</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="center" valign="top">Center-adjust, zero fill</td>
<td align="center" valign="top">101</td>
<td align="left" valign="top">QSN_FFW_RA_ZERO</td>
<td align="left" valign="top">All leftmost unoccupied positions of a field are
filled with zero. Characters are center-adjusted and spaces are zero-filled.
The fill character will appear on the display.
<p>center-adjust is only activated by keying the Field Exit, Field +, or Field
- keys. The field is center-adjusted from the first non-null character to the
left of the cursor when one of these keys is depressed. If a center-adjust
field is left through cursor movement keys, the field will remain as is (not
center-adjusted). center-adjust fields longer than 15 characters might cause a
slow response that would result in a keyboard overrun. A center-adjust
specified field has an implied field exit required function.</p>
<p>The Dup key will fill a center-adjust field from the cursor to the end of
the field with the Dup character (X'1C'), but the field will not be
center-adjusted. After typing the first character into a center adjust field,
but prior to exiting the field (using cursor movement or exit keys), the Enter
key will cause an operator error to be posted; that is, Enter is invalid from
an active center-adjust field.</p>
</td>
</tr>
<tr>
<td align="center" valign="top">Center-adjust, blank fill</td>
<td align="center" valign="top">110</td>
<td align="left" valign="top">QSN_FFW_RA_BLANK</td>
<td align="left" valign="top">The field behavior is the same as for
center-adjust, zero fill, but the fill character is blank instead of zero.</td>
</tr>
<tr>
<td align="center" valign="top">Mandatory fill</td>
<td align="center" valign="top">111</td>
<td align="left" valign="top">QSN_FFW_MF</td>
<td align="left" valign="top">Once any data has been entered into the field,
the field must be completely filled before exiting it. Any attempt to leave an
unfilled field causes an error. The cursor may pass into and out of a mandatory
fill field as a result of cursor movement keys without fill-checking or error
posting by the controller, as long as no data is entered into the field.
<p>The Dup key will fill the field from the cursor to the end of field with the
Dup characters X'2C', and then the entire field will be checked for any nulls
(an error is posted if a null is found). A mandatory fill field with nulls can
be returned under the following conditions:</p>
<ol>
<li>The field was initialized with nulls and with the MDT bit on.</li>
<li>The Erase Input, Field Exit, or Field + key is used from the first position
of the field. The field is filled with nulls and the MDT bit is set on.</li>
</ol>
<p>The above fields, with no further entry, can be returned with all data as
blanks on a Read Input Fields (QsnReadInp) operation or as a null field on a
Read Modified Fields (QsnReadMDT) operation.</p>
</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRFCW">Format of the Field Control Word</a></h3>
<p>The following table explains the valid field control words (FCW) for use
with the QsnSetFld API.</p>
<p><strong><a name="TBLFCW">Table 7. Field Control Words</a></strong></p>
<table border width="100%">
<tr>
<th align="left" valign="top">FCW Value</th>
<th align="left" valign="top">Mnemonic</th>
<th align="left" valign="top">Description</th>
</tr>
<tr>
<td align="left" valign="top" width="15%">X'80nn'</td>
<td align="left" valign="top" width="30%">QSN_FCW_RESEQ</td>
<td align="left" valign="top" width="55%">Entry field resequencing (used in the
Read Input Fields (QsnReadInp) and Read Modified Fields (QsnReadMDT) APIs, and
so forth). The <em>nn</em> specifies the next entry field in the sequence
(<em>nn</em> can be X'00' to X'80'). See <a href="dsm1e.htm#HDRRESEQ">
Resequencing</a>.</td>
</tr>
<tr>
<td align="left" valign="top">X'8101'</td>
<td align="left" valign="top">QSN_FCW_MSR</td>
<td align="left" valign="top">Magnetic stripe reader entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'8102'</td>
<td align="left" valign="top">QSN_FCW_SLP</td>
<td align="left" valign="top">Selector light pen entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'8103'</td>
<td align="left" valign="top">QSN_FCW_MSR_SLP</td>
<td align="left" valign="top">Magnetic stripe reader and selector light pen
entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'8106'</td>
<td align="left" valign="top">QSN_FCW_SLP_SA</td>
<td align="left" valign="top">Selector light pen and selectable attention entry
field.</td>
</tr>
<tr>
<td align="left" valign="top">X'8200'</td>
<td align="left" valign="top">QSN_FCW_DBCS_ONLY</td>
<td align="left" valign="top">DBCS only entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'8220'</td>
<td align="left" valign="top">QSN_FCW_DBCS_PURE</td>
<td align="left" valign="top">DBCS Graphic DBCS entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'8240'</td>
<td align="left" valign="top">QSN_FCW_DBCS_EITHER</td>
<td align="left" valign="top">DBCS Either entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'8280' or X'82C0'</td>
<td align="left" valign="top">QSN_FCW_DBCS_OPEN or QSN_FCW_DBCS_OPEN_C0</td>
<td align="left" valign="top">DBCS open entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'84??'</td>
<td align="left" valign="top">QSN_FCW_TRANSPARENT</td>
<td align="left" valign="top">Transparency entry field (used in the Read Input
Fields (QsnReadInp) and Read Modified Fields (QsnReadMDT) APIs, and so forth).
The <em>??</em> indicates that these values are ignored.</td>
</tr>
<tr>
<td align="left" valign="top">X'8501'</td>
<td align="left" valign="top">QSN_FCW_FET</td>
<td align="left" valign="top">Forward edge trigger entry field. This provides
the same function as Auto Enter specified in the FFW, except a unique AID is
returned to the host when the field is exited. The state on the Auto Enter flag
in the FFW is ignored.</td>
</tr>
<tr>
<td align="left" valign="top">X'8601'</td>
<td align="left" valign="top">QSN_FCW_CONT_FIRST</td>
<td align="left" valign="top">Continued entry field first segment.</td>
</tr>
<tr>
<td align="left" valign="top">X'8602'</td>
<td align="left" valign="top">QSN_FCW_CONT_LAST</td>
<td align="left" valign="top">Continued entry field last segment.</td>
</tr>
<tr>
<td align="left" valign="top">X'8603'</td>
<td align="left" valign="top">QSN_FCW_CONT_MIDDLE</td>
<td align="left" valign="top">Continued entry field middle segment.</td>
</tr>
<tr>
<td align="left" valign="top">X'88nn'</td>
<td align="left" valign="top">QSN_FCW_CP</td>
<td align="left" valign="top">Cursor progression entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'89nn'</td>
<td align="left" valign="top">QSN_FCW_HL</td>
<td align="left" valign="top">Highlighted entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'8Ann'</td>
<td align="left" valign="top">QSN_FCW_PDS</td>
<td align="left" valign="top">Pointer device selection entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'B140'</td>
<td align="left" valign="top">QSN_FCW_MOD11</td>
<td align="left" valign="top">Self Check Modulus 11 entry field.</td>
</tr>
<tr>
<td align="left" valign="top">X'B1A0'</td>
<td align="left" valign="top">QSN_FCW_MOD10</td>
<td align="left" valign="top">Self Check Modulus 10 entry field.</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRDEVFCW">Valid Field Control Word and Device Capability
Combinations</a></h3>
<p>The following table explains the field control words (FCW) available for
certain capabilities of the device. If one of the FCW values listed is given to
QsnSetFld and the corresponding device capability is not supported, a CPFA306
will result. QsnSetFld, however, does not detect all invalid FCW combinations.
See the Field control words (FCW) parameter for more information.</p>
<p>See the <a href="QsnQry5250.htm">QsnQry5250 API</a> to determine the
capablilities supported by the current device.</p>
<p><strong><a name="TBLDEVFCW">Table 8. Valid Field Control Word and Device
Capability Combinations</a></strong></p>
<table border width="60%">
<tr>
<th>FCW Values</th>
<th>Display capablility required for FCW to be valid</th>
</tr>
<tr>
<td align="left" valign="top" width="15%">QSN_FCW_CONT_FIRST,<br>
QSN_FCW_CONT_MIDDLE,<br>
QSN_FCW_CONT_LAST,<br>
QSN_FCW_CP,<br>
QSN_FCW_HL,<br>
QSN_FCW_PDS<br>
</td>
<td align="left" valign="top" width="15%">ENPTUI</td>
</tr>
<tr>
<td>QSN_FCW_DBCS_ONLY,<br>
QSN_FCW_DBCS_EITHER,<br>
QSN_FCW_DBCS_OPEN,<br>
QSN_FCW_DBCS_OPEN_C0</td>
<td>DBCS</td>
</tr>
<tr>
<td>QSN_FCW_DBCS_PURE</td>
<td>Pure DBCS</td>
</tr>
<tr>
<td>QSN_FCW_TRANSPARENT</td>
<td>Transparent Data</td>
</tr>
</table>
<br>
<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">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">CPFA301 E</td>
<td valign="top">Command buffer is full.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA304 E</td>
<td valign="top">Data-stream error &amp;1 reported for screen I/O
operation.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA305 E</td>
<td valign="top">Cannot add operation to command buffer.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA306 E</td>
<td valign="top">Command not supported by current device.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA307 E</td>
<td valign="top">Screen position &amp;1, &amp;2 outside of display or window
area.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA308 E</td>
<td valign="top">Attempt to write data past end of display.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA30A E</td>
<td valign="top">Field length &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA30B E</td>
<td valign="top">Invalid starting address for field.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA30C E</td>
<td valign="top">Maximum allowable number of fields exceeded.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA30D E</td>
<td valign="top">Invalid screen attribute.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA30E E</td>
<td valign="top">Invalid field format word.</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">CPFA31D E</td>
<td valign="top">Attempt to write outside of window area.</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">CPFA331 E</td>
<td valign="top">Buffer handle incorrect.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA332 E</td>
<td valign="top">Incorrect field control word.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA333 E</td>
<td valign="top">Parameter &amp;1 not positive integer value.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA334 E</td>
<td valign="top">Low level environment handle incorrect.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA335 E</td>
<td valign="top">Screen address parameter error.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA33D E</td>
<td valign="top">Invalid screen attribute.</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;2 in library &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>
</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>
Reference in New Issue Copy Permalink