7526 Input Panel Driver CFR

7526 Input Panel Driver CFR
---------------------------
This documentation is for version 1.33 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.

The PANELS26 Custom Function Routine for the 7526 Data Collection Terminal
provides an easy, efficient method to produce powerful, user-friendly data
input panels on the screen of the 7526 model 200. Any number of input panels
may be placed in-line with the regular data collection terminal transaction
program steps.

This program was developed as a sample to aid in the marketing and use of IBM
7526 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 (shift 7(&) and 8(*)) and Enter keys allow forward and backward movement
between fields

o Cursor left, right, and back-rub keys (shoft 4($), 5(%), and 6(/),
respectively) 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)

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

Note: Remote validation requires a catcher program to be developed for
the PS/2 to receive transactions and send responses.

- 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 shift 1 (+) 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 41.6K of storage in the 7526.

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 which makes 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. If not using the Multiple Screen (MULT=Y) mode, 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 c and d 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.

Note: If host validation of a field is specified, the transaction
program should use the AKA (alias transaction key ID) command to set the
transaction ID back to the desired value. Otherwise, any transaction
sent will have the key ID of 40H, as used by the host validation
transaction.

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

HELP.VAL
--------
The HELP.VAL validation file is downloaded to the 7526 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 25 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 40 characters in length.
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,105.

0100 THIS IS HELP SCREEN LINE NUMBER 1.
0105 THIS IS HELP SCREEN LINE NUMBER 2.

Each of these help panel message blocks may be made up of 2 lines of 40
characters.

Contextual help is presented when the operator presses the shift 1 (+) key.
System message 16 is shown first for 1 second to tell him/her how to get out of
the help screen, which then follows.

Input Screen Help
-----------------
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 the small screen of the 7526. 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,23 VERT=R 23,24 .

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

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 Formal 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 7526
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. For connection to DCC/2 / DCConnect systems, use an
extension of ".VAL". An extension does not need to be used
for other systems. Do not use any path information in
front of the file name.

SET_FIELD Function
------------------
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).

The following field flags must be included in a 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 inputs 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 dicatated 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.

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.

Note: When Automatic Input (AI) input is detected (a bar code or magnetic
sensor was used to input the data), the cursor/screen will be located to the
next empty field; if there are no empty fields, then the cursor/screen will
be located at the next field.

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.

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. 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 the maximum user variable
number for pre-fill of data, or -1 for no pre-fill.

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

Note: The maximum varible number used is determined by the number of user
variables defined in the 7526's configuration record. For microcode level
1.01, this is always a maximum of 4.

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 automatically added to any
file name greater than 1 character in length.

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 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.

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 7526 about 1 second
per 1,000 records to perform the search (it would be faster, but DCC/2 and
Data Collector doe not tell it to use its built-in binary searching); 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_.

The CFR facilitates host-based validation of a field (or fields; see
Concatenate Fields for Validation) by sending an specially formatted
transaction to the PS/2 as it is checking the field inputs. If the
verification file name specified in the VERF= flag begins with the characters
"H_", a transaction in the format

(filename)(t)(transaction data)

will be sent to the host for each field or group of fields. The file name,
verification type t, and transaction data are each enclosed in parenthesis to
facilitate parsing in the host program. The verification type character will
be either an I for Inclusive, or a E for Exclusive. The transaction ID will
always be 40H (DI-7 initiated transaction). DCC/2's Transaction Data Export
configuration for the program which is used to catch the validation requests
may be setup to only receive transactions from DI point 7. This data export
program's task is to:

1. Read a transaction from DCC/2

2. Verify that the key-id is a 40H

Note: An additional, optional check might be that the transaction
timestamp is within X seconds of the current time -- if DCC/2 or the
communications link has been down for some period, there may be 'stale'
verification requests in the transaction log file for which the terminal
has long since timed-out waiting for the response.

3. Parse the transaction data to find the file name requested, the type
requested and the transaction data.

4. Perform the data checking (e.g. file search, DB query, S/370 transaction,
etc.).

5. Use the DccSetTermUserVariable API to send a response string to user
variable 3 on the 7526 which requested the data. The response string is
in a modified form of the Host Variable Return string (see Host Variable
Return Data; use of a host-based filename automatically implies that
HVR=3):

HELP=s,e r

where s is the starting record number in the HELP.VAL file for the answer
to be shown to the operator; e is the ending message record number, and r
is the result of the validation:

Code Meaning

0 Verfication failed

1 Verfication passed

2 Unknown file name specified

When the 7526 CFR senses that the response user variable (3) has been set
with the response, it will

o Show the text records from the HELP.VAL file for several seconds if the
verification failed, and then re-position the cursor to the field in
question

o Proceed with verifying the next fields and returning to the transaction
program if the verification passed

o Show CFR system message 7 (Host validation attempt failed) if a time-out
occurs while waiting for the host response. The time-out period is
obtained from the terminal configuration for Host Response Time-out in the
DCC/2 or DC general terminal parameters menus.

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.

Screem 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 then 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".

EXEC_PANEL Function
-------------------
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).

The following flags may optionally be specified on the EXEC_PANEL call.

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 force the
7526 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 (equivalent to CONTINUE).

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

HVR=h

Purpose:

This flag allows you to specify a block of messages in the HELP.VAL file
which is to be presented to the operator when the host fails the validation
of a field.

Note: This flag is included for use with future versions of the 7526
microcode which may support the command V host verification sequences. With
1.01 and 1.02 code levels, do not use this flag. A type of host verification
is allowed by specifying the verification file name to start with a "H_"
(refer to Verification File Name), which automatically uses a variation of
HVR=3.

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 1 to 999, or may be 0 to indicate that a host
variable is not used. The default value is 0.

Note: The maximum varible number used is determined by the number of user
variables defined in the 7526's configuration record. For microcode level
1.01, this is always a maximum of 4.

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 common 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 indices. 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" for NO_SKIP. This is equivalent to CONTINUE.

Note: 7526 micrcode levels 1.0x only supports ABORT for the error return
type.

Laser Scanner Control Flag
--------------------------

L=l

Purpose:

This flag enables control of a wand-emulating laser scanner via the control
lines on the 7526 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 7526
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.

Use 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 (shift-7(&)) or Enter

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 (shift-8(*))

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 Fill

Cursor Left Shift - 4

Cursor Right Shift - 5

Backward Rub-out Shift - 6

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/Cancel Pressing the Clear key (shift 0) clears the field the
first time it is pressed. If it is pressed again without
pressing any other keys (e.g. Tab, Enter, data key),
then it will be interpreted as a Cancel operation.

Cancel Press the Clear key twice in a row, without pressing any
other characters in between.

Note: The 7526 will only allow pressing of a single key at a time. To tab,
backspace, etc. multiple times, you will need to press shift (the green light
will start flashing), release shift, press and release the control key, and
repeat the process.

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 7526'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

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. PAN26_MA.C

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

2. PAN26_CS.C

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

3. PAN26_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. PAN26_MI.C

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

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

The CFRUTL26.H and CFRUTL26.LIB files are also required. Make sure you pick
the appropriate CFRUTL26.LIB based on the compiler that you are using (IBM C/2
1.10 or Borland Turbo C++ 3.0 for DOS). These are utility routines that can
be and have been used in many different CFRs.