7524 Input Panel Driver CFR

7524 Input Panel Driver CFR
---------------------------

Table of Contents
-----------------
Forward
Introduction
Pre-Requisites
Usage Overview
HELP.VAL Structure
System Messages
Contextual Field Help
Input Screen Text
Range Designations
Inclusive Data Sets
Input Format Strings
SET_FIELD Flag Strings
CLEAR_PANEL Function
SET_HELP Function
SET_FIELD Function
Description
Mandatory Flags
Field Index
Input Modes
Field Length
Field Row
Field Start Column
Optional Field Flags
Input Length Mode
Data Required
Return Data User Variable
Pre-fill Data User Variable
Edit Pre-filled Data
Verification File Name
Verification Type
Help Screen Pointer
Screen Text Pointer
Data Identifier
Keep/Strip Data Identifier
Mandatory Data Identifier
EXEC_PANEL function
Description
Optional Flags
Input Time Limit
Time-Out Error Handling
Host Variable Return Data
Concatenate Fields for Validation
Completion/Error Return Handling
Laser Scanner Control
Clear Non-Pre-filled Fields on Re-Entry
Starting Field Index
Panel Termination Reason
Use Multi-Screen Input Mode
Keypad Usage in the Panel
Quick Reference
Run-Time Error Codes
Run-Time Error During EXEC_PANEL function
Run-Time Error During SET_FIELD function call
Source Code

Forward
-------
This documentation is for version 1.43 of the program.

Note: HELP.VAL files (or profiles by any other name) which were developed for
the 1.0 version of this program will need to be modified to include 4-digit
prefix numbers on each record (instead of 3). Simply add a leading or trailing
0 to each record number prefix.

New functions in version 1.42 are

o You can scan special bar code symbols to simulate pressing of the Enter, tab,
Cancel, and Clear keys on the DCT.

o The new REASON= flag allows you to find out whether the panel ended
successfully, timed-out, or was canceled by the operator.

New in 1.43 are:

o PASSWORD input type allows entry of a password without echoing characters to
the screen.

Introduction
------------
The PANELS Custom Function Routine for the 7524 Data Collection Terminal
provides an easy, efficient method to produce powerful, user-friendly data
input panels on the screen of a 7524 terminal or any terminal running the
DCConnect Client (formerly 752x Emulator for DOS). Any number of input panels
may be placed in-line with the regular data collection terminal transaction
program steps.

Three versions of the panel driver CFR are provided:
- A DOS version that is for use on 7524 terminals with 7524 ETS flash and for
use on terminals running one of the DOS versions of the DCConnect Client.
- A 32-bit Windows version for use on devices that are running the 32-bit
Windows version of DCConnect Client.
- A Windows CE version for use on Intermec 5020 terminals that are running
Windows CE version of DCConnect Client.

For simplicity, the remainder of this document will use 7524 to refer to the
terminal.

For actual 7524 terminals, the 7524 must be running the "7524 Extended Terminal
Services" flash for the CFR to be used. Other terminals must be running the
DCConnect Client.

The program product Data Collection Control/2 or "Data Collection Connection"
used in conjuncton with "7524 Interface Support" are offered to facilitate
configuring and loading of the 7524 with the CFR, and then to control the data
collection terminals. (7524 Interface Support is only needed if you are
actually using 7524 terminals on an RF network that is attached to the
data collection server via the serial port).

This program was developed as a sample to aid in the marketing and use of IBM
7524 terminals. It may be used and/or altered in any way, as long as credit to
IBM is retained in the code for the portions provided by IBM. As the program
is provided without charge, IBM assumes no warranty for its fitness for
purpose, and the program should not be re-sold unless accompanied by
substantial value-add (such as modifications and/or support).

Input panel functions provided include:

o From 1 to 20 independent input fields per screen panel (more can be provided
with a simple re-compile of the program)

o Input modes to be allowed in individual fields can be defined:

- Numeric keypad
- Alpha-numeric keypad
- Automatic Input (AI) sensors
- Combination of AI and numeric or alpha-numeric keypad
- Date or time input

o Tab and Enter keys allow forward and backward movement between fields

o Cursor left, right, and back-rub keys allow editing of data within a field

o Each input field can have its own screen, allowing paging between input
screens.

o Automatic, configurable input field checking for a variety of data types:

- Numeric range checking inclusive of specified high and low values

- Character string set checking (mini-validation files, such as a set of
completion codes of "G", "R", or "N" as used by MAPICS).

- Data input character format checking, where each character of the input
field is verified to be an element of the specified set of characters
(numeric, alpha, any character, a literal character)

- MAPICS badge checking (leading "0" and valid modulo 10 checksum)

- MAPICS turnaround number checking (leading turnaround type character(s)
and valid modulo 10 check digit)

- ETS file validation for inclusive or exclusive presence in a local or
remote file, including optional non-mandatory remote validation (in case
the host PC is down, the field can still be accepted)

- Presence of data in mandatory fields

- Completion of fields which require fixed-length input The operator is
prompted in pop-up windows to correct the data in fields which fail the
checking.

o Numeric input fields force the operator to input data in the desired fashion:

- Unsigned integer

- Signed integer

- Unsigned real

- Signed real - Signed numbers may only have one negative sign, located in
the first character position, and real numbers are forced to have a single
decimal point

o Real number input fields may be formated to a specific quantity of digits
after the decimal point

o User-defined, context-sensitive help is presented in a pop-up window by
pressing the PF1 key while the cursor is positioned on the desired field.

o Fields may be pre-filled for the operator, using the contents of a specified
user variable.

o Data from each field is concatenated to individually-specified user
variables

o Bar code/magnetic inputs are sorted into the proper field based on the data
identifier(**) optionally associated with the field

o Data identiers may either be retained with or be stripped off of the data
prior to insertion into the field

o The input time may be specified from 1 to 65,535 seconds, or for no time out.

o The CFR return code (SKIP, NO_SKIP, ABORT) for abnormal endings (e.g. Cancel
key, time-out) and normal endings can be specified.

Pre-Requisites
--------------
The CFR requires 54K of storage in the 7524

Usage Overview
--------------
Setting up the data collection system (DCC/2 or Data Collector or equivalent)
involves 3 basic steps:

1. Planning the content of each data input panel, including validation type,
help information, position, etc.

2. Creation of the HELP.VAL file which contains

o Pre-defined records for CFR system messages
o Help text for each field (optional)
o Range values and sets of values for fields which use this type of
validation (optional)
o Parameter flags and values used to define fields and execute panels
(optional)

3. Creation of the transaction programs which show the fixed text of the
screen and make calls to the CFR for clearing the panel, setting up the
fields and executing a panel.

The transaction program's general form is:

a. Call the CFR CLEAR_PANEL function

b. Call the CFR SET_HELP function to tell the CFR which validation file to
use for its parameter file. The default is "HELP.VAL".

c. Show the prompt identifying an input field

d. Call the CFR SET_FIELD function, referencing an argument string that
currently resides in a user variable or in a records of the HELP.VAL
file

e. Repeat steps 3c and 3d for as many fields as are desired in the panel

f. Call the CFR EXECUTE_PANEL function, referencing an argument string
which currently resides in either a user variable or in a record in the
HELP.VAL file

g. Process the data which is returned in the user variables specified when
the fields were set up

h. Either execute the panel again (with or without clearing non-prefilled
fields of their data), or goto back to step 3a.

HELP.VAL Structure
------------------
The HELP.VAL validation file is downloaded to the 7524 to provide a data base
of messages, configuration records, and sets of validation records. Each
record in the file starts with a 4-digit, zero-filled index number (followed by
a space) to force the DCC/2 Validation Editor to maintain their absolute
position in the file as they are sorted in numeric ascending order. The
HELP.VAL file may contain up to 10,000 records (0000 through 9999). The record
numbers used do not need to be consecutive (i.e. you may skip numbers for
clarity or to allow space for future addition of records).

Note: When using the Data Collector product, import or key-in the same data as
is in DCC/2's HELP.VAL file into Data Collector's verification file 1 for the
desired file version.

System Messages
---------------
The first 17 records are defined for specific prompts to the operator:

Record Message Context/Meaning
0 No contextual help is defined for this field
1 Shown during the field validation operation
2 Warning that an attempt to append too much data to a remote
validation string
3 The indicated field failed a presence/absence look-up in a file
4 The indicated field failed a range-check validation
5 The indicated field failed a MAPICS badge validation
6 The indicated field failed a MAPICS turnaround number validation
7 A mandatory remote validation could not be accomplished (PS/2 is
down)
8 The OK key has been pressed when the indicated field is empty and
data is required in the field
9 A field exit key (Enter, Tab, OK) has been pressed and the fixed-length field has not been fully
completed
10 An attempt has been made to key in data to a sensor-only field
11 The input time for the panel has been exceeded
12 The sensor input is not the correct length for the field
13 An attempt has been made to scan data to a keypad-only field
14 A bar code/magnetic mis-read has been detected
15 The bar code data does not have a data identifier which matches the
current field or any other field in the panel
16 Shown at the bottom of message pop-ups to indicate that the Enter key
must be pressed to clear the message
17 A date or time input field has an invalid number (e.g. invalid number
of days in the month, too many minutes, etc.).
18 The characters input do not match the format string required
19-24 Reserved for future use

Each of these system messages may be a single line of length. Adjust the
length based on the number of columns that the device's display has.

An example of the system message portion of HELP.VAL is shown below.

Note: The system messages must be numbered as shown.

0000 SORRY, NO HELP FOR THIS FIELD....
0001 VALIDATING -- PLEASE STANDBY
0002 REMOTE VALIDATION RECORD FULL
0003 INPUT DOES NOT MATCH REQUIRED DATA
0004 INPUT NOT IN REQUIRED RANGE OR SET
0005 INVALID MAPICS BADGE NUMBER
0006 INVALID MAPICS TURNAROUND NUMBER
0007 HOST NOT UP -- TRY AGAIN LATER
0008 AN EMPTY FIELD IS NOT ACCEPTED
0009 FIELD MUST BE COMPLETELY FILLED
0010 KEYPAD ENTRY NOT ALLOWED
0011 INPUT TIME EXCEEDED....
0012 INCORRECT INPUT LENGTH
0013 SCANNERS NOT ALLOWED IN THIS FIELD
0014 SCANNER DECODING ERROR
0015 DATA IDENTIFIER ON READ INCORRECT
0016 PRESS THE 'Enter' KEY TO CONTINUE
0017 INVALID DATE/TIME FORMAT
0018 INVALID CHARACTERS IN FORMAT
0019 RESERVED
0020 RESERVED
0021 RESERVED
0022 RESERVED
0023 RESERVED
0024 RESERVED

Contextual Field Help
---------------------
Help screen data may be located in blocks located anywhere after the System
Messages. The help data for each field must be contiguous. A flag in the
SET_FIELD call is used to register the beginning and ending record number of
the help for the field. For example, the flag for the HELP.VAL file fragment
shown below could be HELP=100,125.

0100 THIS IS HELP SCREEN NUMBER 1. IT
0105 IS USED TO TEST THE USE OF MULTI-
0110 LINE HELP INFORMATION PROVIDED BY
0120 PRESSING THE F1 KEY WHILE IN THE
0130 FIELD OF INTEREST

The length allowed depends on the number of columns that your device has.

Input Screen Text
-----------------
The complete text of an input screen (prompts, information, etc.) may be
located in the HELP.VAL file. This is mainly intended to facilitate production
of multi-field input panels on devices with smaller screens. When multiple
input screens mode is enabled, each input field is shown on its own screen.

Screen text data may be located in blocks located anywhere after the System
Messages. The screen data for each field must be contiguous. A flag in the
SET_FIELD call is used to register the beginning and ending record number of
the help for the field. For example, the flag for the HELP.VAL file fragment
shown below could be SCRN=31,32. The field definition flags shown in record 30
could be referenced in a SET_FIELD call (SET_FIELD FROM HELP=30) to set up the
entire two-line input screen for the third field in the panel.

0030 FI=3 INPUT=AIALPHA ROW=2 COL=13 LEN=10 SCRN=31,32 HELP=33,34
0031 Input the item number, using the wand or
0032 the keypad:
0033 When keying the item number, do not input
0034 the leading 'P' from the bar code tag.

Range Designations
------------------
Numeric validation ranges may be included as minimum and maximum values in
separate records (the range is inclusive if these values). These range limits
need not be in contiguous records. Only the first numeric value of the record
is used, and all subsequent data in the record is ignored. The value must
start in the first data position (immediately after the space separating it
from the index number). In the example below, the range is included in the
help data for the field. The flags in the SET_FIELD call would be ...
HELP=22,25 VERT=R 23,24 .

0022 A3 - Input must be in the range
0023 1.1 to
0024 25.98
0025 in order to be accepted

Inclusive Data Sets
-------------------
Sets of valid field values may be included in the HELP.VAL file in contiguous
blocks. These serve essentially as miniature presence-checking validation
files, and are useful for validating fields which have a limited number of
values which must have an exact match. An example that could be used to check
MAPICS completion codes is shown below. The SET_FIELD flag would be VERT=S
27,29.

0026 //Completion codes
0027 G
0028 R
0029 N

Input Format Strings
--------------------
Strings which define the format of input fields may be included in the HELP.VAL
file. Data which is input to a field which uses this verification type is
checked against this input format descriptor.

The format string consists of characters with special meanings as well as
characters which must literally match the input data. The input data and
format string are compared character-by-character until either string ends.
The format string need not be as long as the input data string if only the
leading characters require checking.

Note: If you want all of the format string to match the input data, you may
want to specifiy that the field input mode is FIXED length.

The format string characters can be:

Character Interpretation
a An alpha character, A-Z or a-z, must be in the position.
n A numeric character, 0-9, must be in the position.
? Any character is accepted in the position.
* Any character may be used in this position and in all subsequent
positions.
Others The character in this position of the input must match exactly the
character in the format string.

Examples are:

Format String Explanation
annnnn Input must start with one alpha character, followed by
five numeric digits.
nnBaa7 Input must start with two numeric digits, have a B in the
third position, then have two alpha characters, and
finally have a 7 as the last character.
KA???n Input must start with KA, and then can have any
characters in the next 3 positions, and finally have a
numeric digit.
D0* Input data must start with D0, and then can have any
characters for the remainder of the string.

SET_FIELD Flag Strings
----------------------
The SET_FIELD command may reference either a user variable, or a record in the
HELP.VAL file as the source of the flag string used in setting up the field.
For example, the field may be set with the CFR parameters SET_FIELD FROM
HELP=30, where the HELP.VAL record could look like:

0030 FI=1 INPUT=ALPHA LEN=1 ROW=5 COL=1 VERT=S 27,29

CLEAR_PANEL Function
--------------------
Use the CLEAR_PANEL CFR function to erase all current panel settings, in
preparation for registering the next panel to be presented.

CCFR Settings Values
Function 3
Parameters CLEAR_PANEL

SET_HELP Function
-----------------
Use the SET_HELP CFR function to specify which validation file on the 7524
should be used for input. The default is "HELP.VAL". In this document,
HELP.VAL is the name always used in refering to the CFR's input source, but the
name you specify will actually be used. This allows different clusters of
terminals on the DCC/2 or DC system to use different versions of a
HELP.VAL-type file.

CCFR Settings Values
Function 3
Parameters SET_HELP FILE=filename.ext
where the FILE= flag identifies the following text as the file name. An
extension does not need to be used. Do not use any path information in front
of the file name.

Description
-----------
The SET_FIELD function is used to register each field's characteristics into
the current panel definition. It may be called any number of times prior to
execution of the panel in order to create the maximum number of fields allowed
in a panel. It may also be called to change one or more fields within a panel
which has just been executed.

CCFR Settings Values
Function 3
Parameters SET_FIELD FROM VAR=X, or SET_FIELD FROM HELP=Y where X is
the user variable number or Y is the HELP.VAL record number
containing the field flag string.

Note: With the Data Collector product, the size of the
verification file (used as a data file) is limited to 40
characters. Thus, most SET_FIELD flag strings will not fit
in the verification file, and so user variables must be
used. Building up the user variable usually takes 2
"Append from message..." steps because messages are also
limited to 40 characters. To make sure there is a space
between flags where the 2 appends join, start the second
appended message with a space character.

CLRD user variable 1
APND to user variable 1 from message 200
APND to user variable 1 from message 201
SET_FIELD FROM VAR=1

where messages are
200 FI=1 INPUT=AI LEN=5 ROW=2 COL=1 HELP=30,31 DI=P KEEPDI=Y
201 VERT=I VERF=H_PARTNS

The field flag string which defines the characteristics of a field consists of
5 mandatory flags and values, and various optional flags. The flags may appear
in any order in the string, but must be typed exactly as shown (for example,
FI=1 is correct; FI = 1 and FI= 1 are incorrect). Numeric values, such as
references to HELP.VAL record numbers, do not need to be zero-filled (e.g.
"001" and "1" are acceptable and equivalent).

Mandatory Flags
---------------
The following flags must be included in each SET_FIELD call.

Field Index
-----------
Flag

FI=n

Purpose

Provides the Field Index number, where n is an integer from 1 to 20. The field
index number dictates the order in which tabbing moves the cursor between the
fields and the order in which field data is appended to return-data user
variables and to concatenated validation fields. Calls with the same field
number as was previously used in the panel will result in over-writing of the
field's previous settings.

Input Modes
-----------
Flag

INPUT=inputs
Purpose

Designates the keypad/input modes allowed for the field. The input value may
be:

Value Inputs Allowed
NUM Only the numeric keypad can be used to input a valid
numeric form, with the form dicatated by the LEN= flag
value.
AINUM Either the numeric keypad can be used to input a valid
numeric form, with the form dictated by the LEN= flag
value, or the sensor ports can be used to input automatic
identification data. The AI data is not checked for valid
numeric format.
ALPHA Any keypad data key (A-Z, 0-9, etc.) may be used to input
the data. AI sensors may not be used.
PASSWORD The same as ALPHA, but input is displayed as '*' characters
for security.
AIALPHA AI sensors or any keypad data key (A-Z, 0-9, etc.) may be
used to input the data.
AI Only AI sensors may be used. Keypad input of any form is
not allowed.
DATE_AMER Only the numeric keys may be used to input a valid date in
a MM-DD-YYYY form. The CFR forces a check of the format
without need for any verification type to be specified.
The length of this field must be 10. If the field is not
pre-filled, it is automatically filled with a "MM-DD-YYYY"
template. As the user keys in the data, the cursor skips
over the separators between the month, day, etc. If any of
the sub-fields in the date is left with the pre-fill
characters (e.g. MM, DD, or YYYY), it will be filled
automatically with the current date elements. Thus, the
operator can fill in the month and day, and the "YYYY"
section will automatically be set to the current year. The
operator can also simply leave the field with the pre-fill
data intact and have the entire date filled in
automatically. If the operator changes one or more
characters of any sub-field, the remaining M, D, or Y
characters will be set to zeroes.

All inputs are checked for validity, including the month
number, and number of days in that month (including leap
year), and a year number between 1992 and 2025.

DATE_EURO Only the numeric keys may be used to input a valid date in
a DD-MM-YYYY form. Refer to DATE_AMER above for further
description.

TIME_STD Only the numeric keys may be used to input a valid time in
a HH:MM:SS form. An input length of 8 must be specified
for the field. Refer to DATE_AMER above for a description
of how inputs are handled. The hours digits are checked
for the range 00 to 23, while minutes and seconds are
checked for the range 00 to 59. A 24-hour time format is
used for all automatic time input.

Field Length
------------
Flag

LEN=[-]l[.n]
Purpose

This flag specifies the length of the input field (either the maximum length
for a variable length field, or the required length for a fixed length field).
The input field is automatically underscored to this length upon entry to the
panel.

Data from the field is padded to this length prior to appending to the
return-data user variable.

The length l may be from 1 to 39 characters. It is the user's responsibility
to ensure that the field fits after the starting row and column position. At
least 1 character position should remain to the right of the field prior to the
edge of the display.

If the INPUT=NUM or INPUT=AINUM flag is used, an optional leading '-' sign on
the l parameter can be used to specify signed input is allowed, and a decimal
point and following digits can be used to specify that real number input is
allowed and the number of places after the decimal. If not present, the
default is non-signed (positive) integer input.

In numeric input fields, always allow the first character to be used by the
sign character, even if only non-signed input was allowed (i.e. for a 7 digit
numeric integer input, allow a field length of 8).

The decimal point may be either a "." or a "," symbol. The first use of a
decimal point in defining a real-number input field for the panel will
determine the style of decimal point used during input and numeric formating
for the entire panel.

If the decimal point is used to specify a real number, then some precision
value must follow the decimal point. The numeric field formatting will try to
get the desired level of precision, but will not sacrifice the whole part of
the number or the sign in doing so. Extra characters of precision which are
input will be truncated.

A precision of 0 may be used to specify real number input in a free-form style.
In this case, no formatting of the real number will be performed.

The whole number portion of a real number is formatted to its most compact form
(removing non-significant leading zeroes) as long as the whole part is in the
range �2,147,483,648. Outside of this range, the whole number will be kept as
input by the operator. The decimal portion may be of any precision up to 37
digits.

Field Row
---------
Flag

ROW=r
Purpose

The ROW= flag is used to define the row location of the field. Row 1 is the
top line of the display.

Field Start Column
------------------
Flag

COL=c
Purpose

The COL= flag is used to define the starting column position of the field.
Column 1 is at the left edge of the display.

Refer to Field Length for requirements of positioning the starting column
position based on the input field length.

Optional Field Flags
--------------------
The following field definition flags are optional. Each has a default value if
not specified in the string referenced by the SET_FIELD call.

Input Length Mode
-----------------
Flag

MODE=m
Purpose

The MODE=m flag specifies if the field is for fixed or variable length input.
The value of m may be either "FIXED" or "VARIABLE" (which may be abbreviated
down to simply "F" or "V"). Fixed length input fields require that all
characters of the field be filled by the keyed or scanned data before the data
will be accepted. This checking is done as the data is entered, without
waiting for the operator to press the OK key. Variable length data can be as
little as 1 character in a 39 character field. Variable length data is always
left-justified in the returned data, with the field padded on the right with
blanks for non-numeric data or on the left with zeros (after the sign
character) for numeric data, to the maximum length specified in the LEN=l
mandatory flag.

The default is VARIABLE length.

Data Required
-------------
Flag

REQ=r
Purpose

The data required flag specifies if the entry of data in a field is required in
order for the panel to be accepted. Value r may be either "YES" or "NO" (or
simply "Y" or "N"). If specified as NO, then an empty field will be accepted
(a field of blanks will be returned).

The default value is "YES".

Return Data User Variable
-------------------------
Flag

RUV=ruv
Purpose

The ruv value specifies which user variable should be used to return the data
to the transaction program. Valid values are 1 through 19. The user must
clear the user variable prior to calling the EXEC_PANEL function if the return
data is to start at the beginning of the user variable. If more than 1 field
specifies a particular user variable, then the data will be concatenated to the
user variable in the order specified by the field index number.

The default is user variable 1.

Pre-fill Data User Variable
---------------------------
Flag

PUV=puv
Purpose

The PUV=puv flag may be used to specify that the current contents of user
variable puv are to be used as pre-fill data for the field. The value must
already be in the user variable when the SET_FIELD call is made. It may then
be cleared prior to calling the EXEC_PANEL call. This data is automatically
placed in the desired field when the panel is presented. It may be accepted
unchanged by the operator, or optionally be edited (see Edit Pre-filled Data)
or cleared and overwritten. Valid values are 0 to 19 for pre-fill of data, or
-1 for no pre-fill.

The default is -1 (no pre-fill).

Edit Pre-filled Data
--------------------
Flag

EDIT=e
Purpose

This flag indicates whether pre-filled data may be edited (i.e. one or more
characters changed, while leaving others alone), or must be completely
overwritten. Valid values are "YES" or "NO". If EDIT=N, then the field will
automatically be cleared as soon as the operator presses a data entry key when
in the field.

The default is "YES".

Verification File Name
----------------------
Flag

VERF=f
Purpose

The VERF=f flag specifies the verification file name to be used for file-based
inclusive or exclusive validation of the field. The file name f is 1 to 8
characters long, representing the file name of the .VAL file when used with
DCC/2, or the file number ("1" to "6") for Data Collector. Do not include a
file extension; the extension ".VAL" is assumed.

Note: If you DCC/2 validation file name is a single-character name, then you
should specify it with an extension (i.e. X.VAL).

If you have large, terminal-based validation files which are pre-sorted into
ascending order, you may want to use the binary file search function of the CFR
to accelerate the searches. Normally, it takes the 7524 about 0.25 seconds per
1,000 records to perform the search; with the CFR's binary search, even the
largest file should be complete within 1 second. To enable its usage, simply
name your validation file with a leading B_.

With DCC/2, be sure to include a reference to the validation file name in some
regular transaction program in order to force DCC/2 to include the name when it
generates the ETS file e data. The refererence to the name in a VERIFY or READ
command in the transaction program does not ever need to be actually executed;
it may be hidden in a non-used transaction program that is bound to the "extra
keys" or a touch screen or DI point.

The default is to have no validation file for the field.

Verification Type
-----------------
Flag

VERT=t
Purpose

The VERT=t flag specifies the type of validation to be done on the field as the
OK key is pressed. Valid types for t are:

Type Description
I Mandatory inclusive validation in the file specified with the VERF=f
flag. If the validation cannot be completed (e.g. the host PS/2 is
not available for remote validation), the panel cannot be accepted.
i Desired inclusive validation in the file specified with the VERF=f
flag. If the validation cannot be completed (e.g. the host PS/2 is
not available for remote validation), the panel may still be
accepted.
E Mandatory exclusive validation in the file specified with the VERF=f
flag. If the validation cannot be completed (e.g. the host PS/2 is
not available for remote validation), the panel cannot be accepted.
e Desired exclusive validation in the file specified with the VERF=f
flag. If the validation cannot be completed (e.g. the host PS/2 is
not available for remote validation), the panel may still be
accepted.
0 No validation is required.
R Range-checking, where range value pointers (minimum and maximum) come
after the flag (e.g. VERT=R 101, 102). The pointers are directed to
record numbers in HELP.VAL which represent the inclusive range
allowed in the field. The values in the HELP.VAL file may be of
differing precisions from that defined for the field input.

See Range Designations for additional details.
S Data set checking (a set of allowed values), where set pointers
(starting record and ending record) come after the flag (e.g. VERT=S
103, 108). The pointers are directed to record numbers in HELP.VAL.

See Inclusive Data Sets for additional details.
F Field data format checking, where a format string pointer comes after
the flag (e.g. VERT=F 150). The pointers are directed to a record
number in HELP.VAL. See Input Format Strings for additional details.
B Specifies that the field must be a valid MAPICS badge number (e.g.
begins with a 0, and has an IBM modulo 10 check digit as the 7th digit).
T Specifies that the field must be a valid MAPICS turn-around number,
starting with a "1" to a "4" and having a valid IBM modulo 10 check
digit as the final character. An optional 1 or 2 digit number may
immediately follow the "T" to specifiy a unique turnaround number
prefix (e.g. T1, T11) instead of the "1" to "4" traditional
turnaround prefix.

MAPICS turnaround numbers must be less than 15 characters in length.

The fields are checked first for presence of data in data-required fields, and
then each field is checked (in field index-order) per the verification type
specified. Once a field passes verification, it will not be reverified during
the panel's execution unless the operator changes the field data in some way.
This prevents unnecessary usage of processing and communication resources if
the OK key must be pressed several times as the operator corrects errors
flagged in other fields.

The default value is I. Presence of VERT without VERF has no effect when I, i,
E, or e is specified.

Help Screen Pointer
-------------------
Flag

HELP=s,e
Purpose

This flag specifies the location of the help screen data for the field. The
locations index into the HELP.VAL file, where s is the starting message index
(1 to 999), and e is the ending message index (1 to 999). They may be the same
value.

See Contextual Field Help for additional details.

The default is for no help to be available.

Screen Text Pointer
-------------------
Flag

SCRN=s,e
Purpose

This flag specifies the location of the screen text data for the field. When
the panel is executed using the MULT=Y flag, each input field is presented on
its own screen, with the text indicated by the SCRN= flag being used to paint
the prompts to be presented to the operator.

The locations index into the HELP.VAL file, where s is the starting message
index (1 to 999), and e is the ending message index (1 to 999). They may be
the same value.

See Input Screen Text for additional details.

The default is for no screen to be defined.

Data Identifier
---------------
Flag

DI=d
Purpose

The DI=d flag specifies the data identifier required to be at the beginning of
any bar code or magnetic automatic identification data which is to be placed in
the field. The value d is a string of from 0 to 3 numeric characters followed
by a single alphabetic character.

Note: Defining a data identifier for a field implies that automatic
identification (AI) sensor input is allowed in the field. This will over-ride
the lack of an AI- specification in the INPUT= flag.

If data is keyed into a field which has a data identifier defined, the data
identifier will not be checked if it is included. If the KEEPDI flag has been
set equal to N (the default), then the operator most likely should not key in
the DI.

Note: In most cases, the DI is hidden on a bar code label; the data is
included in the symbol, but is usually not printed in the human-readable area
under the bar code.

The default is to have no data identifier.

The program follows the logic below when a bar code/magnetic stripe is read
with the cursor in a particular field:

// Try to attach data to a field with a Data Identifier,
// giving first preference to the current field, then
// looking at other fields in field-index order.
if a DI is defined for this field
if it matches the read data
if the length, after keeping/stripping the DI, fits
per the length and fixed/variable mode
then place the data in the field and return ENTER key
else show bad length error and return (no read)
else
search list of DIs of fields 1- 20 for a match
if it matches the read data
if the length, after keeping/stripping the DI, fits
per the length and fixed/variable mode
change the cursor position to the matching field
place the read data in the field and return ENTER key

// Could not sort by a DI, see if the original current field
// allows AI input
if sensor input not allowed in this field
show bad sensor input error and return

// If there is supposed to be a DI for this field, but none is
// found, show error
if a MANDATORY DI is defined for this field (read data has been proven to
not match any registered DI)
then return error that DI not matched

// No DI required for this field; if the data fits, use it for the
// field.
if the length fits
per the length and fixed/variable mode of the ORIGINAL FIELD
place the data in the field and return ENTER key
else show bad length error

If all the fields in a panel are defined with a data identifier, then the panel
is assumed to be complete when all fields are filled with data. The OK key is
presumed, and field validation commences.

Keep/Strip Data Identifier
--------------------------
Flag

KEEPDI=k
Purpose

This flag specifies whether any data identifier specified for the field should
be kept with the data when it is sent to the transaction program or if it
should be stripped off prior to sending. Values are "YES" or "NO" (or simply
"Y" or "N").

The default value is "NO".

Mandatory Data Identifier
-------------------------
Flag

MANDI=k
Purpose

This flag specifies whether any data identifier specified for the field is
absolutely required to be a header on the AI data input. Values are "YES" or
"NO" (or simply "Y" or "N"). If the DI is mandatory ("YES"), scanned data will
not be accepted for the field unless the DI is present in the first characters
of the data. If the DI is not mandatory ("NO"), then scanned data input while
the cursor is in the subject field does not need to have a DI. Length checking
and fixed/variable checking still applies. This allows the operator to be
responsible for scanning the proper label when a bar code is encountered which
does not utilize data identiers.

The default value is "YES".

Description
-----------
The EXEC_PANEL function is called to execute a panel which has been defined by
1 or more SET_FIELD calls. This CFR call will not return until the panel has
been successfully completed, the time-out period elapses, or the operator
presses the Cancel key. If the panel was successfully completed, then the user
variables specified in the SET_FIELD calls will have the field data appended to
them.

CCFR Settings Values
Function 3
Parameters EXEC_PANEL FROM VAR=X, or EXEC_PANEL FROM HELP=Y where X is
the user variable number or Y is the HELP.VAL record number
containing the panel flag string.

The panel flag string which defines the characteristics of a field consists of
various optional flags, each having a default value if not explicitly
specified. The flags may appear in any order in the string, but must be typed
exactly as shown. HELP.VAL record number references do not need to be
zero-filled (e.g. "001" and "1" are acceptable and equivalent).

Optional Flags
--------------
The following flags are optional when making a EXEC_PANEL call. If not
specified, a default value will be used.

Input Time Limit
----------------
Flag

T=t
Purpose

The T=t flag specifies the amount of idle time allowed in the panel before it
will execute the time-out error routine (see Time-Out Error Handling). The
time tmay be from 1 to 65535 seconds, or it may be set to 0 to indicate no
time-out.

Any activity by the operator will reset the timer. Activities include pressing
a data key, pressing a field movement key, scanning on a sensor port, exiting a
help panel, etc..

The default value is 0 (no time-out).

Time-Out Error Handling
-----------------------
Flag

TOE=a
Purpose

This flag determines what the effect of a input time-out error will be when
executing the panel. There are 4 choices for the flag value a:

Value Action
A Return an ABORT to the transaction program, which will cause ETS to
set the 7524 back to the idle screen.
N Return a NO_SKIP to the transaction program, which can then perform
what ever error recovery it desires.
S Return a SKIP to the transaction program, which can then perform
whatever error recovery it desires.
T Terminate the panel normally by simulating the press of the OK key.
If all fields pass their defined validations, then the panel will
exit and the data will be returned to the transaction program. If
any problem is detected with the panel fields, the operator will be
prompted to fix the first offending field. If the operator is not at
the station, then the terminal will cycle endlessly in a loop of
timing-out for input, failing the validations, and returning for
corrections to the input.

The default value is "N" for NO_SKIP.

See also Panel Termination Reason, which will provide information on the manner
in which the panel terminated.

Host Variable Return Data
-------------------------
Flag

HVR=h
Purpose

This flag allows you to specify which user variable will contain a pointer to a
block of messages in the HELP.VAL file for presentation to the operator when
the host fails the validation of a field. The pointers to the message block
are returned to the CFR by the host using the user variable h, The message text
can tell the operator exactly what is wrong with the field. Before the host
(PS/2) program gives the remote validation response to DCC/2, it can use
DccSetTermUserVariable to put the proper pointers into the user varialble h in
the form:

HELP=start, end

where HELP= is the key flag string, start is the starting message number in
HELP.VAL, and end is the ending message number. The data placed in the user
variable is only used once (for the field which was the subject of the remote
validation); it is then marked with the flag "USED" appended to the data in the
variable.

The value of h may be from 10 to 19, or may be 0 to indicate that a host
variable is not used. The default value is 0.

Concatenate Fields for Validation
---------------------------------
Flag

CON=c
Purpose

The CON=c flag allows the panel to be configured for concatenation of all field
data in the panel which share a validation file name into a single, larger
validation attempt. The field data is appended to the validation data in the
order defined by their field indexes. A ";" character is appended after each
field's data in the overall string. The verification type (i,I,e, or E) is
taken from the first field in the concatenated list.

This function is useful in 2 situations:

1. A remote program validation is done at the host PS/2, and it is desired to
get multiple fields of related data to this program simultaneously. This
also reduces the amount of network traffic required to get several fields
to this program.

2. A validation must be made of data which is a matched set. For example, one
field could be a worker's badge number and the second a personal
identification number (PIN) which is keyed in. The validation file may
consist of these two pieces of data already merged into a single record
which uniquely qualifies the worker. The panel program will automatically
put these 2 pieces of data together if both specify the same validation
file name.

The possible values for c are "YES" or "NO" ( or simply "Y" or "N").

The default value is "N".

Note: You may have an application which requires using concatenated
validation, but which also has several fields using a commond validation file
where you do not want concatenated validation. You can specify that these
fields require singlular validation by naming the common validation file with
the special prefix "S_". This tells the CFR to not consider any fields using a
validation file with such a prefix when it is performing the concatenated
validations.

Completion/Error Return Handling
--------------------------------
Flag

ERET=e
Purpose

This flag specifies the return code to be used when the panel exits normally or
is aborted by the operator pressing the Cancel key. There are 3 values
available for e:

Value Meaning
S Return SKIP on an error; NO_SKIP for successful completion
N Return NO_SKIP on an error; SKIP for successful completion
A Return ABORT on an error; NO_SKIP for successful completion

The default is "N".

See also Panel Termination Reason, which will provide information on the manner
in which the panel terminated.

//Laser Scanner Control
//---------------------
//Flag
//
//L=l
//Purpose
//
//This flag enables control of a wand-emulating laser scanner via the control
//lines on the 7527 sensor ports. DO1 (pin 7) is used to enable a specially
//configured scanner(**), and DO 2 (pin 9) is used to send an acknowledge to
//the scanner (which lights a green LED and sounds its beeper). This serves to
//synchonize the operator's actions with the input desired at the 7527
//terminal. Values for l are "YES" or "NO" (or simply "Y" or "N").
//
//The default is "NO".

Clear Non-Pre-filled Fields on Re-Entry
---------------------------------------
Flag

CNP=a
Purpose

This flag allows re-entry to a panel which has already been completed so that a
nearly duplicate panel can be edited and re-entered or so that some secondary
validation done after return from the initial EXEC_PANEL call can prompt for a
corrective action and then re-show the panel as it was left. Calling
EXEC_PANEL a second time with CNP=N and SF (see Starting Field Index) equal to
the field number in question will allow the cursor to be re-positioned at the
field to be corrected. Valid values for CNP= are "YES" or "NO" (or simply "Y"
or "N". If "Y" is used, all fields which were not pre-filled during the
SET_PANEL calls will be cleared of data as the panel is presented.

Note: The pre-filled fields will be re-shown with their final data from the
last panel exit, which is not necessarily the data they may have had upon the
initial panel entry.

The default value is "YES".

Starting Field Index
--------------------
Flag

SF=s
Purpose

This flag can be used to specify the starting field number for cursor
positioning upon entry to the panel. It is most often used in conjunction with
the CNP=NO flag for secondary field correction prompting. Normally, the panel
cursor starts at the first character of the field with the lowest index number.
Valid values for s are 1 through 20. If the index specified is not defined in
the panel, a run-time error will be presented and the cursor will go to the
lowest index numbered field.

The default value for s is 1.

Panel Termination Reason
------------------------
Flag

REASON=r
Purpose

This flag can be used to specify a user variable in which the panel driver will
return text describing why the panel was terminated. With this reason text,
your transaction program can determine if the panel ended due to an input
timeout, the operator pressing the Cancel key, or because all input fields were
successfully completed. The specified user variable will be cleared and one of
the following reason texts will be appended:

o OK

o CANCEL

o TIMEOUT

After the EXEC_PANEL CFR call, you could use the COMPARE CFR function to
determine which event ended the panel and then take appropriate action:

CMT //HELP.VAL RECORD 0100 CONTAINS FLAG 'REASON=1' TO PUT TERMINATE REASON
CMT //CODE IN USER VARIABLE 1, FLAG 'TOE=S', AND FLAG 'ERET=S'.
CCFR 3 EXEC_PANEL FROM HELP=100
CMT //PANEL WAS SUCCESSFULLY COMPLETED, RETURNING A 'NO_SKIP'
GOTO current transaction step 16
CMT //IF REASON RETURN WAS 'CANCEL', THEN GOTO STEP 57
(Step 5)
APND to variable 2 from "CANCEL"
CCFR 3 COMPARE:VAR(01) EQ VAR(02) TRUE RC=NO_SKIP
GOTO Current transaction step 57
CMT //WAS NOT CANCELLED; MUST HAVE BEEN A TIME OUT; HANDLE IN STEP 100
GOTO Current transaction step 100
(Step 16)
...
...
(Step 57)
CMT //ASK IF OPERATOR REALLY WANTS TO CANCEL; IF SO, TERMINATE (TERM), OTHERWISE
CMT //RE-SHOW THE INPUT PANEL WITHOUT CLEARING NON-PREFILLED FIELDS (USER GETS
CMT //HIS OLD DATA BACK)
SHOW message "Do you really want to Cancel this tranaction? (Y/N)"
READ Fixed length 1 from alpha keypad
CLRD variable 2
APND variable 2 from "Y"
CCFR 3 COMPARE:VAR(00) EQ VAR(02) TRUE RC=NO_SKIP
TERM
CMT //HELP.VAL RECORD 0101 CONTAINS SAME FLAGS AS RECORD 100, BUT ALSO
CMT //HAS FLAG 'CNP=N' TO RETAIN DATA IN PANEL FOR RE-EDITING
CCFR 3 EXEC_PANEL FROM HELP=101
CMT //PANEL RETURNS NO_SKIP IF DATA IS OK, SKIP IF TIMED OUT OR CANCELED
GOTO current transaction step 16
GOTO current transaction step 5

Valid values for r are 0 through 19, with 0 meaning that no reason return is
desired, and 1 through 19 being the terminal user variable numbers. The
default value for r is 0.

User Multi-Screen Input Mode
----------------------------
Flag

MULT=a

Purpose This flag specifies that each input field is to be presented on its own
screen, resulting in paging of the display as the fields are entered or the tab
keys are pressed. In all other ways, the fields are still elements of the same
input panel.

Valid values for MULT= are "YES" or "NO" (or simply "Y" or "N").

The default value is "NO".

Keypad Usage in the Panel
-------------------------
The panel CFR supports the following usage of cursor control and special keys:

Function Keys Used
Next field Left tab or Enter

The Left tab and Enter keys may be simulated by scanning
a bar code consisting of the text $LT$ and $ENT$,
respectively.

Note: The next field is the field with the next higher
index number, not necessarily the next field to the right
or down.
Previous Field Right tab

The Right tab key may be simulated by scanning a bar code
consisting of the text $RT$.

Note: The previous field is the field with the next
higher index number, not necessarily the next field to
the left or up.

Send/Accept OK The OK key may be simulated by scanning a bar code consisting of the text $OK$.
Cursor Left Shift - 1,4, or 7

Note: For a single character movement, the Shift key may
be released prior to pressing the numeric key. For
multiple character movements, hold the Shift key down
will repeatedly pressing the numeric key.

Cursor Right Shift - 3,6, or 9

Note: See note under Cursor Left.
Backward Rub-out back-space (rub-out)

Note: This key rubs-out the data immediately to the left
of the cursor, and moves all text past the cursor along
with it to the left.

Clear/Re-show Pressing the Clear key repeatedly toggles between
clearing the field of data and then re-showing the
previous data.

The Clear key may be simulated by scanning a bar code
consisting of the text $CLR$.

Cancel The Cancel key ends the panel without checking of the
data or return of the data in user variables. The CFR
completion code specified in the ERET= flag is returned
to the ETS program interpreter.

The Cancel key may be simulated by scanning a bar code
consisting of the text $CAN$.

Quick Reference
---------------
All CCFR calls use function number 3. Parameter strings are:

CLEAR_PANEL

SET_HELP FILE=filename.val

SET_FIELD FROM VAR=X, or SET_FIELD FROM HELP=Y

Mandatory Flags in referenced VAR or HELP record:

Optional Flags:
(Default is in bold)

MODE=FIXED|F|VAR|V
REQ=Y|N
RUV=r (r = 1 to 19)
PUV=p ([ = 1 to 19, or -1 for none)
EDIT=Y|N
VERF=f (f is filename without extension)
VERT=0|I|i|E|e|B|T[nn]|R s,e|S s,e|F s
HELP=s,e (none)
SCRN=s,e (none)
DI=d (none)
KEEPDI=N|Y
MANDI=N|Y

EXEC_PANEL FROM VAR=X, or EXEC_PANEL FROM HELP=Y

Optional Flags in referenced VAR or HELP record:
(Default is in bold)

Run-Time Error Codes
--------------------
When the CFR encounters an error as it interprets your field or panel
configuration flags or tries to execute a panel, an error code is shown on the
first line of the terminal's display:

BAD CCFR (EE): STRING

The EE code is replaced with one of the codes listed below, and the STRING is
replaced with the first 18 characters of the CCFR parameter string, or in some
cases, a value which can help you find the source of the error (REC=, FI=,
etc.).

Run-Time Error During EXEC_PANEL Function
-----------------------------------------
X1: No VAR= or HELP= flag on EXEC_PANEL call
X2: Invalid user variable/help record used on EXEC_PANEL CFR call
X3: Could not find value for TOE= flag
X4: Invalid TOE= value
X5: Could not find value for ERET= flag
X6: Invalid ERET= value
X7: Could not find value for CON= flag
X8: Invalid CON= value
X9: Could not find value for L= flag
XA: Invalid L= value
XB: Could not find value for CNP= flag
XC: Invalid CNP= value
XD: Could not find value for T= flag
XE: Invalid T= value
XF: Could not find value for SF= flag
XG: Invalid SF= value; Not in range or field not defined
XH: No fields defined for EXEC_PANEL call
XI: Return data will not fit in return user variable VAR
XJ: Return data user variable out of range
XK: Could not find DATA SET check record in HELP.VAL
XL: Could not find LOW range check record in HELP.VAL
XM: Could not find HIGH range check record in HELP.VAL
XN: Could not find help text record REC in HELP.VAL file during EXEC_PANEL
XO: Could not find value for HVR= flag
XP: Invalid HVR= value
XQ: HELP= start tag value for HVR not found in user variable data
XR: HELP= start tag value for HVR is out of range (from user variable data)
XS: HELP= end tag value for HVR not found in user variable data
XT: HELP= end tag value for HVR is out of range (from user variable data)
XU: Could not find FORMAT check record in HELP.VAL
XV: Could not find value for MULT= flag
XW: Invalid MULT= value
XX: Could not find value for REASON= flag
XY: Invalid REASON= value

Y1: Could not find help text record REC in HELP.VAL file
Y2: Could not find HELP.VAL file (system message)
Y3: MAPICS badge/turnaround fields must be less than 15 characters long

Run-Time Error During SET_FIELD Function Call
---------------------------------------------
Note: Most error messages in this section include the Field Index number for
reference, rather than the portion of the CCFR parameter string.

Z1: No VAR= or HELP= flag on SET_FIELD call
Z2: Invalid user variable used on SET_FIELD CFR call
Z3: SET_FIELD variable does not contain a FI tag
Z4: SET_FIELD FI tag value not found
Z5: SET_FIELD FI tag value FI is out of range
Z6: SET_FIELD variable for FI does not contain a INPUT= tag
Z7: SET_FIELD INPUT= tag value for FI not found
Z8: SET_FIELD INPUT= tag value for FI is out of range
Z9: SET_FIELD variable for FI does not contain a LEN= tag
ZA: SET_FIELD LEN= tag value for FI not found
ZB: SET_FIELD LEN= tag value for FI is out of range
ZC: SET_FIELD variable does not contain a ROW= tag
ZD: SET_FIELD ROW= tag value for FI not found
ZE: SET_FIELD ROW= tag value for FI is out of range
ZF: SET_FIELD variable does not contain a COL= tag
ZG: SET_FIELD COL= tag value for FI not found
ZH: SET_FIELD COL= tag value for FI is out of range
ZI: SET_FIELD VERT= tag value for FI not found
ZJ: SET_FIELD VERT=T turnaround prefix for FI is too long
ZK: SET_FIELD VERT=R/S/F first tag record value for FI not found
ZL: SET_FIELD VERT= range/set/format start tag value for FI is out of range
ZM: SET_FIELD VERT=R/S second tag record value for FI not found
ZN: SET_FIELD VERT= range/set end tag value for FI is out of range
ZO: SET_FIELD VERT= tag value for FI is out of range
ZP: SET_FIELD MODE= tag record value for FI not found
ZQ: SET_FIELD MODE= tag value for FI is out of range
ZR: SET_FIELD REQ= tag record value for FI not found
ZS: SET_FIELD REQ= tag value for FI is out of range
ZT: SET_FIELD KEEPDI= tag record value for FI not found
ZU: SET_FIELD KEEPDI= tag value for FI is out of range
ZV: SET_FIELD EDIT= tag record value for FI not found
ZW: SET_FIELD EDIT= tag value for FI is out of range
ZX: SET_FIELD RUV= tag record value for FI not found
ZY: SET_FIELD RUV= tag value for FI is out of range
ZZ: SET_FIELD PUV= tag record value for FI not found

Za: SET_FIELD PUV= tag value for FI is out of range
Zb: SET_FIELD VERF= tag record value for FI not found
Zc: SET_FIELD VERF= tag value for FI is too long
Zd: SET_FIELD HELP= start tag value for FI not found
Ze: SET_FIELD HELP= start tag value for FI is out of range
Zf: SET_FIELD HELP= end tag value for FI not found
Zg: SET_FIELD HELP= end tag value for FI is out of range
Zh: SET_FIELD DI= tag record value for FI not found
Zi: SET_FIELD DI= tag value for FI is too long
Zj: Could not find help text record REC in HELP.VAL file
Zk: File name not found on SET_HELP call
Zl: No FILE= flag found on SET_HELP call
Zm: SET_FIELD SCRN= start tag value for FI not found
Zn: SET_FIELD SCRN= start tag value for FI is out of range
Zo: SET_FIELD SCRN= end tag value for FI not found
Zp: SET_FIELD SCRN= end tag value for FI is out of range

Source Code
-----------
The source code for the CFR is in 4 files

1. CFRSMP24.C

This is the main program file. It interprets the CFR calling arguments and
directs control to other modules.

2. PANEL_CS.C

This module contains the routines called to Clear and Set the field
parameters.

3. PANEL_EX.C

This module contains the panel execution routines, including parsing of the
EXEC_PANEL flag string, handling of field tabbing, and validation of the
data read.

4. PANEL_MI.C

This module contains miscellaneous functions, including handling the keypad
and sensor ports during inputs and some validation routines.

The CFRSMP24.H file contains defines, function prototypes, and external data
delarations for the various C source files.

The CFRUTL24.H and CFRUTL24.LIB files are also required.