7526 Sample CFR
---------------
The CFRSMP26.C source file contains a sample Custom Function Routine (CFR) for
use with the 7526 Data Collection Terminal. The program products Data
Collection Control/2 and Data Collection Connection are offered to facilitate
configuring and loading of the 7526 with the CFR, and then to control the data
collection terminals.
This CFR operates in mode 1 (as extensions to the 7526 transaction programming
command set), and contains several (largely unrelated) routines callable by the
7526 transaction program by specifying a sub-function name within the parameter
string.
o Set baud rate, parity, etc. for optional Serial 1 & 2 ports. See Initialize
an RS-232 Port.
o Read from optional serial 1 & 2 ports. See Read From an RS-232 Port.
o Send to optional serial 1 & 2 ports. See Send to an RS-232 Port.
o Print on parallel printer with spooling and error recovery. See Print to the
Parallel Printer Port.
o Logical string comparison for contents of 2 user variables. See String
Compare.
o Logical integer comparison for contents of 2 user variables. See Integer
Compare.
o Integer add/subtract/divide/multiply of 2 user variables. See Integer
Arithmetic.
o Digital input point counter sampling and reseting, increment and decrement
by one. See Digital Input Point Counters.
o Digital input point count rate measurement. See Digital Input Rate
Measurement.
o Clear and restore a pop-up window. See Clear and Restore Pop-Up Window.
o Get the current time and date and return them in user variables. See Time
and Date Stamp Retrieval.
o Handle both sensors ports independently as Time/Attendance clocks. See
Dual Sensor Port Handle for 2 Controlled Doors/Gates.
o Allow variable delay time of 5 mS to 5 minutes, in 5 mS increments. See
Variable Program Delay with Fine Granularity.
o Checking of data for uniqueness among a sliding list of the last X number of
reads. This is useful for counting scanned items when the operator may
accidentally re-scan an item already done. See Unique Data Checking -- A
Rolling Exclusive Validation.
o Send a remote validation request to DCC/2 1.02 or later. See Send Remote
Validation Request to DCC.
o Wait for a specified duration for a user variable to be set by the host
application. See Wait for Host to Set a User Variable.
o General-purpose keypad and scanner input routine with input format rules and
cursor control. See Advanced Read Function.
CFR Usage
--------
Details of function and usage are described below, as are explanations of error
codes which the CFR may report back on the 7526's screen.
The CFR is called by placing a Call CFR command in the 7526 transaction
program. Pop-up windows in DCC/2/DCConnect guide you through this procedure.
In the CCFR (Call CFR) pop-up window, always set the funtion number to '3', and
the parameter string exactly as shown in the description of the functions
below.
Compiling and Linking
---------------------
Several compiled versions of the sample CFR are included in this package. You
can also use the compile/link information in the source file header to
customize it further.
The size and function of the executable can easily be manipulated by
commenting-out the associated "#define", which then is used by the "#if
defined" logic to skip that section during compiling.
The CFRUTL26.LIB and CFRUTL26.H files are required to build the sample CFR.
This sample library of functions (with source code) can be obtained from the
7526 web page:
ftp://ftp.software.ibm.com/software/dcconnect/hardware/7526/7526stuf.htm
Of course you also need CFRAPI26.H and CFRAPI26.LIB - also available from this
web page.
Sample make files are provided for building with the IBM C/2 1.10 compiler
(IBM_SAMP.MAK) and with the Borland Turbo C++ 3.0 for DOS compiler
(BOR_SAMP.MAK). Be sure to pick the proper version of CFRAPI26.LIB and
CFRUTL26.LIB based on the compiler being used.
Read From and RS-232 Port
-------------------------
Read characters which have been recieved or are in process of being received on
an optional RS-232 port and append them to a target terminal user variable.
Data will be read until any of the specified conditions becomes true:
o A timeout occurs while waiting for characters to arrive. Each character
which arrives resets the timer. The default is 10 seconds. Use 000 for no
time limit.
o A stop character is reached. Specify the decimal value of the ASCII
character (i.e. Carriage return is 013). The default is a null-character
(000). The stop character is returned as the last character in the target
user variable.
o A maximum length of data has been received. The default is 100.
This function requires 7526 microcode 3.0 or later and an
Ethernet-Serial-Parallel or Serial-Parallel communications adapter.
Note: While the parameter string for this function may have a variable number
of elements and does not require precise character column alignments, it
does require exact spelling for the setting items. Any mis-spelled
items will be ignored.
CCFR Format:
Function 3
Parameters:
READ SERIAL_n TARGET VAR(nnn) [TO CHAR(XXX)] [TIMEOUT(ttt)]
[TO LENGTH(lll)]
where n is 1 or 2 for SERIAL 1 port or SERIAL 2 port,
nnn is the target user variable number for the incoming data.
XXX is the decimal value of an optional end-of-data character
lll is the optional maximum length to read
ttt is the optional timeout for incoming characters (seconds).
Use 000 for no time limit.
Returns: NO_SKIP when data received without timeout
SKIP when a timeout occurs or when the operator
presses the shift-Clear key sequence during the
receiving process.
Errors: S1 Invalid SERIAL_n specified
S2 Invalid user variable specified
S3 No user variable source or target specified
S4 No serial-parallel comm adapter found, or not 3.0
microcode on 7526 machine.
S5: Target user variable filled with incoming data
Send to an RS-232 Port
----------------------
Send the contents of a terminal user variable to an attached device via one of
the 2 optional RS-232 serial ports. The function returns when all data has
been moved to the serial port transmit buffer.
This function requires 7526 microcode 3.0 or later and an
Ethernet-Serial-Parallel or Serial-Parallel communications adapter.
Note: While the parameter string for this function may have a variable number
of elements and does not require precise character column alignments, it
does require exact spelling for the setting items. Any mis-spelled
items will be ignored.
CCFR Format:
Function 3
Parameters:
SEND SERIAL_n SOURCE VAR(nnn)
where n is 1 or 2 for SERIAL 1 port or SERIAL 2 port, and
nnn is the user variable number containing the data to be sent.
Special characters may be encoded in the user variable data as
strings of "/xnn" where 'nn' is the hexidecimal value of the
desired character (for example, "/x00" would send a NULL to the
serial port; "/x0D" would send a linefeed character).
Returns: NO_SKIP always
Errors: S1 Invalid SERIAL_n specified
S2 Invalid user variable specified
S3 No user variable source or target specified
S4 No serial-parallel comm adapter found, or not 3.0
microcode on 7526 machine.
Initialize an RS-232 Port
-------------------------
Set the asynchronous communications parameters for an optional RS-232 serial
port. If any parameters are being changed from the current port setting, this
will result in automatic purging of any non-read characters in the receive
buffer and of any non-sent characters in the transmit buffer. If no parameters
are different from the current port settings, then this function will return
without doing any work (thus preserving the data in the buffers). You can also
request that the data be purged regardless of the port settings (this is useful
for getting rid of any old incoming data which you don't want any more).
This function requires 7526 microcode 3.0 or later and an
Ethernet-Serial-Parallel or Serial-Parallel communications adapter.
Note: While the parameter string for this function may have a variable number
of elements and does not require precise character column alignments, it
does require exact spelling for the setting items. Any mis-spelled
items will be ignored.
CCFR Format:
Function 3
Parameters:
1) To set and always clear (purge) the buffers:
Parameters =
SET PURGE SERIAL_n BAUD_nnnn PARITY_nnnn STOP_BITS_n DATA_BITS_n
2) To set only if SERIAL_n parameters are being changed from their
current vlaue (this method avoids purging the RX/TX buffers
so it may be called whenever in doubt about the port settings):
Parameters =
SET SERIAL_n BAUD_nnnn PARITY_nnnn STOP_BITS_n DATA_BITS_n
SERIAL_n may be either SERIAL_1 or SERIAL_2, as marked on the card ports.
Choices for nnnn in BAUD_nnnn include 110, 150, 300, 1200, 2400, 4800
9600 and 19200; Parity choices include PARITY_NONE, PARITY_ODD, and
PARITY_EVEN; Stop bit choices include STOP_BITS_1 and STOP_BITS_2;
Data bits choices include DATA_BITS_6, DATA_BITS_7, and DATA_BITS_8.
You need not set all values during a SET SERIAL_n call.
Values which have not explicitly set since start-up of the 7526
will default to 9600 baud, No parity, 1 stop bit, and 8 data bits,
respectively.
Returns: NO_SKIP always
Errors: S1 Invalid SERIAL_n specified
S4 No serial-parallel comm adapter found, or not 3.0
microcode on 7526 machine.
Print to the Parallel Printer Port
----------------------------------
Send the contents of a terminal user variable to an attached parallel printer
via the parallel port. If no Ethernet-Serial-Parallel or Serial-Parallel card
is installed the standard processor board port is used, otherwise the port on
the optional card is always used. The function returns when all data has been
moved to the parallel port transmit buffer.
This CFR-based function will be prefered by some users as it will spool the
print data to the printer over time as the printer accepts the data, and it
exercises more error recovery than the basic transaction program SEND TO
PRINTER function.
This function requires 7526 microcode 2.0 or later and a printer-capable
processor card(**). An Ethernet-Serial-Parallel or Serial-Parallel
communications adapter is optional.
This function will wait up to 15 seconds for the printer to accept additional
characters to its input buffer. It will detect various printer error
conditions, and display an error message on the 7526 if you have set it in
COMPLAIN mode.
CCFR Format:
Function 3
Parameters:
PRINT FROM VAR(nnn) [COMPLAIN]
where nnn is the user variable number
COMPLAIN is an optional flag which say you want printer errors to be
shown on a pop-up screen.
Returns: NO_SKIP is always returned
Errors: P1 No source user variable (FROM VAR) specified
P2 Invalid user variable specified
Send Remote Validation Request to DCC
-------------------------------------
This function requires 7526 microcode 2.0 or later PLUS DCC/2 version 1.02 or
later.
Because DCC/2 1.02 does not allow you to specify that a validation file is NOT
to be downloaded to the terminal after it is referenced in a transaction
program, you cannot get remote validation from a 7526 to work WHEN YOU WANT
DCC/2 TO DO THE FILE SEARCH. (If you have a program-based validation which
does DccReadValidation.. calls, then you can specify the validation in the
.PGM file instead of using this function).
This CFR function is used in place of a VRFY transaction program call.
CCFR Format:
Function 3
Parameters =
VERIFY- VAR(XXX) IN FILE name.ext
where XXX is the user variable number in which to find the
data to be checked. Pad on the left with 0's.(e.g. 003)
where name.ext is the file name which you want DCC/2 to
search and respond to.
Advanced Read Function
----------------------
This function tailors a keypad and / or sensor port read to your exact
requirements .
CCFR Format :
Function 3
Parameters =
READ CHAR LEN=LL FROM KS AT RR, CC TIME=TTT VAR=YYY
INTE KY
REAL NK
EURO SR
AMER NS
TIME
Returns: ABORT if timed out waiting for input
NO_SKIP if data input OK
ABORT if user pressed CLEAR or terminal received
off-line command.
where CHAR is character data
INTE is integer data
REAL is real number data (decimal point)
EURO is a European-format date: DD-MM-YY
AMER is a North American-formated date: DD-MM-YY
TIME is a standard time format of HH:SS
LL is the data length (1-39)
KS allows keypad or sensor port input
KY allows keypad only
NK allows numeric keypad only
SR allows sensor only
NS allows numeric keypad or sensor
RR is the input field row
CC is the input field starting column
TTT is the input time limit (seconds, specify 000 for no limit
YYY is the user variable to return data in.
Any data in the variable when the function is called is used
as pre-fill data for the field
Unique Data Checking - A Rolling Exlusive Validation
----------------------------------------------------
This function checks that the data in a user variable is not identical to one
of the last X inputs checked. X is set to 10, but may be easily changed in the
defines section of the code. Data checked may be up to 25 characters long.
There are 2 lists kept (again, this may be easily changed to more/less in the
#defines section). The list tracks the last X unique reads -- reading the same
item X times will NOT result in the list being full of the same data. A call
can be used to reset the list to empty.
CCFR Format:
Function 3
Parameters = CHKUNIQ-VAR XX IN LIST Y
CHKUNIQ-REFRESH LIST Y
where
XX is the user variable whose contents will be
checked
Y is the list to use (1, 2, etc)
If the data is unique, returns SKIP, else returns NO_SKIP
Time and Data Stamp Retrieval
-----------------------------
Obtain the current time and date in the user variables of your choice.
CCFR Format:
Function 3
Parameters =
TM_DATE-yy HR V(ttt) zzzz DATE V(ddd)
24 EURO
12 AMER
where yy is set to "12" or "24", indicated the time format
ttt is the UV desired for the time string output
(001 to 998)
zzzz is the date format; EURO==DD-MM-YY, AMER==MM/DD/YY
ddd is the UV desired for the date string output
(001 to 998)
ttt and ddd may be the same variable number. In that
case, the time comes first, followed by a space and
then the date.
Digital Input Point Counters
----------------------------
Sample or reset one of the 32 long-integer(**) counters and return (appended to
a user variable) a character representation of its value.
The counters all operate in the background, even when the terminal is offline.
They are non-volatile, so values are not lost during a power off/on cycle.
Reloading the CFR will wipe them out.
The counters require a minimum pulse width of 25 mS for program-debounced
counters in order to detect a change of state. This means the maximum count
rate is 20 cycles per second (25 mS high, 25 mS low equals 50mS cycle time).
The 7526 also does high-speed counting of changes in input state, with the
assumption that an electronic input is being used which does not exhibit signal
bouncing characteristics. These counters may run at up to 1000 cycles per
second when only a single point is active.
CCFR Format:
Function 3
1) To sample a counter and append to a user variable:
Parameters = DICOUNT-SAMPL CTR(ccc) TO VAR(vvv)
2) To reset a counter to 0:
Parameters = DICOUNT-.RESET CTR(ccc)
3) To increment a counter by 1:
Parameters = DICOUNT-INCRT CTR(ccc)
4) To decrement a counter by 1:
Parameters = DICOUNT-DECRT CTR(ccc)
where
ccc is the counter to work with:
000-007 for code-debounced, low speed counters
100-107 for high speed, externally-debounced
counters.
for DI points 0 through 7, respectively.
Both high speed and low speed counters are always
maitained for all DI points. The change of state
(e.g. high to low, or low to high) which causes the
count to increment is set in the terminal
configuration parameters for the parallel port.
vvv is the user variable to return the number in as
as a string (01-19) and is not required if a
Reset call is being made
Returns: NO_SKIP
Digital Input Rate Measurement
------------------------------
Sample the incoming pulse rate on a DI point, or put a value in the sampling
time base for the next and subsequent samples to use. The time base determines
how long the sample will take, and is specified in units of 5 mS. Thus, the
default value of 200 will cause a 1 second program delay as the counter is
allowed to accumulate for 1 second (200 * .005 = 1 second).
CCFR Format:
Function 3
1) To sample the rate of counter inputs to a user variable:
Parameters = DI_RATE-SAMP CTR(ccc) TO VAR(vvv)
2) To put the sample time base equal to the numeric value
now contained in a user variable string:
Parameters = DI_RATE-PUT TIME BASE TO VAR(vvv)
where
ccc is the counter to work with (000 - 007 ,
100 - 107, as described in Digital Input Point Counters).
vvv is the user variable to return the number in as
as a string (001-998) and is not required if a
Reset call is being made
Returns: CONTINUE
Clear and Restore Pop-up Window
-------------------------------
This function is useful for providing error or information messages to the
terminal operator.
On the first call to this function, it copies all characters from the current
display into a storage area and then clears the display to create a pop-up
window. Your transaction program can then present a message or prompt for some
time or until the operator takes an action. On the second call to this
function, the screen is re-cleared and the original text is re-displayed.
The window encompasses the full display size of the 7526.
Upon return from a 'Clear' call, the transaction program may fill in the
desired text inside the window, starting at line 1, column 1.
When called to 'Restore' a window, the original text is restored.
Calls to Refresh if no Clear has been called are rejected.
CCFR Format:
Function 3
1) To clear a pop-up panel:
Parameters = POPUPWN-CLEAR
2) To restore the original text and attributes:
Parameters = POPUPWN-RESTORE
String Compare
--------------
Compare the strings in 2 user variables. Returns SKIP or NO_SKIP as desired
for a true condition. Test can be:
yyy exactly equals (EQ) zzz
yyy not equal (NE) zz
yyy greater than (GT) zzz
yyy less than (LT) zzz
yyy greater than or equal to (GE) zzz
yyy less than or equal to (LE) zzz
CCFR Format:
Function 3
Parameters = COMPARE-V(yyy) cc V(zzz) TRUE RC=rc
EQ NO_SKIP
NE SKIP
GT
LT
GE
LE
where
yyy is the first user variable number holding
a string.
cc is the two-letter condition test code
zzz is the second user variable holding a string
rc is the return code desired if the condition is
true.
Returns: NO_SKIP or SKIP based on rc setting
Integer Compare
---------------
Compare the integers in 2 user variables. Returns SKIP or NO_SKIP as desired
for a true condition. Test can be:
yyy exactly equals (EQ) zzz
yyy not equal (NE) zz
yyy greater than (GT) zzz
yyy less than (LT) zzz
yyy greater than or equal to (GE) zzz
yyy less than or equal to (LE) zzz
CCFR Format:
Function 3
Parameters = CMP_INT-V(yyy) cc V(zzz) TRUE RC=rc
EQ NO_SKIP
NE SKIP
GT
LT
GE
LE
where
yyy is the first user variable number holding
a string.
cc is the two-letter condition test code
zzz is the second user variable holding a string
rc is the return code desired if the condition is
true.
Returns: NO_SKIP or SKIP based on rc setting
Integer Arithmetic
------------------
Perform simple math on 2 user variables. Result is string appended to user
variable 1.
CCFR Format:
Function 3
Parameters = INTMATH-V(yyy) o V(zzz)
+
-
*
/
where
yyy is the first user variable number holding
a string.
o is the operation letter (+, -, *, / )
zzz is the second user variable holding a string
This function always returns NO_SKIP
Wait for Host to Set a User Variable
------------------------------------
This function allows better control when using user variables as data transfer
or flag areas between the host application and the terminal. The usual
transaction program construct of TEST and GOTO will keep trying forever or
until the operator presses CANCEL. This CFR function allows you to set a time
limit on how long the terminal will wait for the host, and gives return codes
indicating whether the host data was received, the time out was reached, or the
operator pressed Cancel.
CCFR Format:
Function 3
Parameters:
WAIT_UV-VAR XXX FOR YYY SECONDS
where XXX is the terminal user variable to check/wait on
YYY is the number of seconds to wait for host data
Returns: NO_SKIP If timed out waiting for host
SKIP if host data received OK
ABORT if user pressed CANCEL or terminal received
off-line command.
Example:
Wait for user variable 10 for 15 seconds
Function: 3
Parameters: WAIT_UV-VAR 003 FOR 015 SECONDS
Variable Program Delay with Fine Granularity
--------------------------------------------
This function allows programmable delay periods in a transaction program with
delays as short as 5 milliseconds, or as long as 5.46 minutes, with granularity
of 5 milliseconds.
The delay time is specified as a quantity of 5 millisecond delays, from 1 to
65,535 units. Examples are:
1/10 second: V_DELAY 20 ( 0.1/.005 = 20 )
1/2 second: V_DELAY 100
3/4 second: V_DELAY 150
CCFR Format:
Function 3
Parameters:
V_DELAY xxxxx
where
xxxxx is the variable-length quantity of
5 mS intervals to be delayed. This number
may be from 1 to 5 digits in length.
Dual Sensor Port Handle for 2 Controlled Doors/Gates
----------------------------------------------------
This function handles Handles 2 independent bar code readers, allowing separate
validation files and digital output control points. For optimum performance,
install the HIGH PERFORMANCE BAR CODE READING COPROCESSOR to provide 2
independent bar code decoding systems. This will give simultaneous decoding on
both ports, coupled with pseudo-simultaneous processing of the decoded data.
The CFR controls 6 of the digital output points on the terminal:
Door strike ('Go') for port A (Validation passed): DO 0
'Go' light for port A (Validation passed): DO 1
'Stop' light for port A (Validation failed): DO 2
Door strike ('Go') for port B (Validation passed): DO 3
'Go' light for port B (Validation passed): DO 4
'Stop' light for port B (Validation failed): DO 5
Depending on how the program was compiled, the CFR will either use the default
Validation API (resulting usually in a sequential search), or it will use the
binary validation method found in the CFRUTL26 sample library. See the BINARY
#define for setting the compile option.
The CFR function expects to find the first bar code input in user variable 0.
This may be set up either by establishing a badge-initiated transaction which
calls the CFR as its only required instruction step, or using another
transactions program which performs an input step to get the badge data.
Format:
Function 3
Parameters:
2_DOORS "filept_A.ext" "filept_B.ext"
where
filept_A.ext is the verification file to be used for
the reads from port A. Enclose in " marks.
Valid names are "2" through "7" or any
regular DOS filename.extension-type name.
If no validation is required, then use
a filename of "0".
filept_B.ext is like above, but for port B. May repeat
using the same file name as for port A.
To change the default door strike activation duration from 1 second to some
other value, call the function using the parameters below. For simplicity, use
this function before all calls which do a badge validation.
2_DOORS DURATION=X
where X is the number of seconds (1-9) for the duration.v
Error Codes
-----------
If the simple parser for the command parameter strings does not find exactly
what it expects in certain character positions, or finds parameters out of
range, it will show a "Bad CFR xx:..." error message on the first line of the
7526's display. The "xx" is filled with an error code, and then the first few
character of the actual parameter string used in the CCFR call are shown.
To avoid getting parsing errors, you must strictly observe the spelling spaces,
and padding of user variable or counter numbers to 3 digits (e.g. type "001",
not "1").
Error codes are:
COMPARE / CMP_INT / INTMATH
---------------------------
C1: Too few characters in parameter string for COMPARE call
C2: Invalid user variable number in "yy" text
C3: Invalid user variable number in "zz" text
C4: Invalid True return code type specified
C5: Invalid logical compare operator or arithmetic operator
DICOUNTER / DI RATE COUNTER
---------------------------
D1: Too few characters in parameter string of a DI counter call
D2: Invalid counter number, must be 00 to 07
D3: Too few characters in parameter string of a DI counter SAMPLE
call.
D4: Invalid user variable in DI counter sample call
D5: Invalid usage of DI counter function: Not SAMPLE or RESET
DA: Too few characters in parameter string of a DI counter rate call
DB: Invalid counter number, must be 00 to 07 OR 100 to 107
DC: Bad user variable number in Sample rate counter call
DD: Bad user variable number in Put rate time base call
DE: Not a recognized call of Sample or Put
TIME/DATE STAMP
---------------
E1: Too few chars in parm string of time/date stamp call
E2: Invalid UV for time stamp output
E3: Invalid UV for date stamp output
E4: Invalid time format -- must be 12 or 24
E5: Invalid date format -- must be "AMER" or "EURO"
GENERAL
-------
M1: CFR identifying name in parameter string was not recognized
M2: CFR call could not fit desired output into specified user var
PRINTER PORT
------------
P1: No source user variable (FROM VAR) specified
P2: Invalid user variable specified
POP-UP WINDOW
-------------
P3: Too few characters in parameter string of a pop-up window clear
call
REMOTE VALIDATION / READ
------------------------
R1: Too few characters in the calling parameter string.
R2: Invalid user variable used in calling string.
SERIAL PORT FUNCTIONS
---------------------
S1: No valid serial port name used (e.g. SERIAL_1, SERIAL_2)
S2: Invalid user variable specified
S3: No user variable source or target specified
S4: No serial-parallel comm adapter found, or not 3.0
microcode on 7526 machine.
S5: Target user variable filled with incoming data
UNIQUE DATA CHECKING
--------------------
U2: Not enough characters in call to check uniqueness
U3: Invalid user variable
U4: Invalid list number
U5: Not enough characters in call to refresh
VARIABLE DELAY
--------------
V1: Too many characters in delay quantity, or delay quantity
text starts too far after the V_DELAY identifier.
WAIT FOR USER VARIABLE TO BE SET
--------------------------------
W2: Not enough characters in call to check uniqueness
W3: Invalid user variable
TWO BADGE READER HANDLER
------------------------
21: No validation file names found
22: Second validation file name not found
23: Too many characters in parameter string
25: Validation file name invalid, or validation data too long
26: Not enough room on tranaction record to append data