Sample Custom Function Routines for the 7524
--------------------------------------------
Table of Contents
-----------------
Introduction
CFR Usage
Compiling
Functions
WAIT FOR HOST TO SET USER VARIABLE
UNIQUE DATA CHECKING -- A ROLLING EXCLUSIVE VALIDATION
TIME AND DATE STAMP RETRIEVAL
DIGITAL COUNTERS
CLEAR/RESTORE POP-UP WINDOW
STRING COMPARE
INTEGER COMPARE
INTEGER ARITHMETIC
TRANSACTION MESSAGE CONTROL
ERROR Codes
Introduction
------------
The CFRSMP24.C source file contains a sample Custom Function Routine (CFR) for
use with the 7524 Data Collection Terminal. This same CFR can also run on any
terminal that is supported by the DCConnect Client (formerly 752x Emulator for
DOS).
Three versions of the sample 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 CFR operates in mode 1 (as extensions to the ETS command set), and
contains several (largely unrelated) routines callable by the 7524 transaction
program by specifying a sub-function name within the parameter string.
o Wait for a specified user variable to be set from the host, timing out if no
data is received within the designated time period
o Logical comparison of 2 integers passed in user variables
o Simple arithmetic for 2 integers passed in user variables
o Circular list (FIFO) function to check data for uniqueness among the last 10
(or more) reads.
o Logical string comparison for contents of 2 user variables
o Digital counters which can be incremented, decremented, sampled, and reset.
o Clear and restore a variable size pop-up window
o Get the current time and date and return them in user variables
o Turn off/on the "Good Transaction" message
CFR Usage
---------
Details of function and usage are described below, as are explanations of error
codes which the CFR may report back on the 7524's screen.
The CFR is called by placing a Call CFR command in the 7524 ETS transaction
program. Pop-up windows in DCC/2 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
---------
Make files for the IBM C/2 1.10 compiler and Borland Turbo C++ 3.0 for DOS
compiler are provided in this package. You can customize the source as needed
and rebuild the CFRs.
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.
WAIT FOR HOST TO SET USER VARIABLE
----------------------------------
Watches the specified terminal user variable and returns when the host has set
some data in that variable, or when the specified timeout period has elapsed.
This allows more flexibility than a simple TEST/GOTO loop in your transaction
program (such as loop will run forever if your host is down).
Format:
Parameters = WAIT_UV-VAR XX FOR YYY SECONDS
where
XX is the user variable whose contents will be
watched for host input
YYY the timeout period in seconds to wait.
Range is 001 to 999 seconds.
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.
UNIQUE DATA CHECKING -- A ROLLING EXCLUSIVE VALIDATION
------------------------------------------------------
Checks that the data in a user variable is not identical to 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.
Format:
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 DATE STAMP RETRIEVAL
-----------------------------
Obtain the current time and date in the user variables of your choice.
Format:
Parameters =
TM_DATE:yy HOUR TIME IN VAR(tt); zzzz DATE IN VAR(dd)
12 EURO
24 AMER
where yy is set to "12" or "24", indicated the time format
tt is the UV desired for the time string output (1-19)
zzzz is the date format; EURO==DD-MM-YY, AMER==MM/DD/YY
dd is the UV desired for the date string output (1-19)
DIGITAL 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 are changed only by calls from your transaction program. They are
non-volatile, so values are not lost during a power off/on cycle. Reloading
the CFR will wipe the out.
Format: To sample a counter and append to a user variable:
Parameters = DICOUNT:SAMPL CTR(cc) TO VAR(vv)
To reset a counter to 0:
Parameters = DICOUNT:RESET CTR(cc)
To increment a counter by 1:
Parameters = DICOUNT:INCRT CTR(cc)
To decrement a counter by 1:
Parameters = DICOUNT:DECRT CTR(cc)
where
cc is the counter to work with
00-31
vv 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
CLEAR/RESTORE POP-UP WINDOW
---------------------------
The window can be from 1 to 10 rows high, and is fixed at 22 chars wide. The
pop-up window function is useful for putting up instructions or warning
messages without having to worry about what is on the screen. The screen is
re-built for you when the window is cleared.
A box is automatically drawn around the window, adding another 2 lines and 2
columns used.
Upon return from a 'Clear' call, the transaction program may fill in the
desired text inside the window, starting at line 3, column 4.
When called to 'Refresh' a window, the original text and attributes are
restored, but not any pixel manipulations.
Calls to Refresh if no Clear has been called are rejected.
Format: To clear a pop-up panel:
For normal video panel:
Parameters = POPUPWN:CLEAR rr ROWS NORMAL
For reverse video panel:
Parameters = POPUPWN:CLEAR rr ROWS REVERSE
To restore the original text and attributes:
Parameters = POPUPWN:REFRESH
where
rr is the number of rows of text needed, 1-10
STRING COMPARE
--------------
Compare the strings in 2 user variables. Returns SKIP or NO_SKIP as desired
for a true condition. Test can be:
yy exactly equals (EQ) zz
yy not equal (NE) zz
yy greater than (GT) zz
yy less than (LT) zy
yy greater than or equal to (GE) zz
yy less than or equal to (LE) zz
Format:
Parameters = COMPARE:VAR(yy) cc VAR(zz) TRUE RC=rc
EQ NO_SKIP
NE SKIP
GT
LT
GE
LE
where
yy is the first user variable number holding
a string.
cc is the two-letter condition test code
zz 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:
yy exactly equals (EQ) zz
yy not equal (NE) zz
yy greater than (GT) zz
yy less than (LT) zy
yy greater than or equal to (GE) zz
yy less than or equal to (LE) zz
Format:
Parameters = INT_CMP:VAR(yy) cc VAR(zz) TRUE RC=rc
EQ NO_SKIP
NE SKIP
GT
LT
GE
LE
where
yy is the first user variable number holding
a string.
cc is the two-letter condition test code
zz 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.
Format:
Parameters = INTMATH-V(yy) o V(zz)
+
-
*
/
where
yy is the first user variable number holding
a string.
o is the operation letter (+, -, *, / )
zz is the second user variable holding a string
This function always returns NO_SKIP
TRANSACTION MESSAGE CONTROL
---------------------------
This CFR call is used to turn on and off the "Good Transaction" message shown
on the 7524 screen each time a transaction is "sent" to the host computer. As
a default, ETS clears the screen and shows this message each time the
transaction program does a SEND TO HOST or exits the transaction program with
AUTO set to ON. Sometimes this is disruptive to a information display, or
simply adds unwanted delay to the transaction cycle time
Format:
Parameters = TRANMSG:sss
YES
NO
where
sss is the word ON or OFF as desired
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 CCFR(xx)..." error message on the first line of the
7524'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 2 digits (e.g. type
"01", not "1").
Error codes are:
COMPARE
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; must be No_Skip or Skip
DICOUNTER
D1: Too few characters in parameter string of a DI counter call
D2: Invalid counter number, must be 00 to 31
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
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"
TRANSACTION MESSAGE CONTROL
F1: Too few chars in parm string of time/date stamp call
GENERAL
M1: CFR identifying name in parameter string was not recognized
POP-UP WINDOW
P1: Pop-up window call will not work on a Model 001, only a 002
P2: Too few characters in parameter string of a pop-up window clear
call
P3: Invalid number of rows requested in pop-up window
P4: Too few characters in parameter string of a pop-up window
refresh call
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
WAIT FOR USER VARIABLE TO BE SET
W2: Not enough characters in call to check uniqueness
W3: Invalid user variable