7526 DCT Reference
A CFR is called automatically by the 7526 DCT upon its initial load (after
command CMD MD is issued by the terminal controller) and on each restart of
the 7526 DCT (power-on start or an Out of Service/In Service sequence. The
automatic call can be used to do initialization work for the CFR. The CFR
may then be called from any place within a transaction program by using the
;M operation code of the 7526 DCT (see ";M&mdash.Call CFR 0-9").
For users of Data
Collection Control/2 or Data Collector, the transaction programming
command CCFR;M
command and its arguments.
A CFR is called with 2 arguments supplied by the caller to the CFR
code (these arguments are passed much like command line arguments in a
personal computer program). The first argument is a single-digit integer
function number, with value between 0 and 9.
The second argument is a
variable length parameters
string of up to 101 characters.
The function number has 2 reserved values:
- Function set to 0 indicates an initialization call, and is made after
loading the CFR. The MD host command initiates the function 0
initialization call, however, the CFR is not called with this function code
until the 7526 DCT is placed in service (CMD A). When this function number
is received, the CFR code should switch to an area of code that processes
any initialization work (that is, setting counters to zero, reading in
validation files to extract data, and so forth).
- Function set to 2 indicates that the terminal has been restarted, usually
by being powered-off and on again or taken out of service and placed in
service again.
The parameter string may be used to transfer
up to 99 characters of string data to the CFR.
The meaning of the data is dependent on the code in the CFR.
Uses for this string may include encoding of sub-function
numbers, passing of input and output user variable numbers, and
passing of program flags.
The first 2 characters represent a number from 00 to 99, which should be set
to the number of characters remaining in the string. If there are no
additional parameters, then the first 2 characters of the string must be set
to 00. The CFR code which processes the parameter string should reference
the first 2 characters to obtain the string length (offsets 0 and 1), and
characters 3 and on for the rest of the data (offset 2 and on).
The 7526 operates under a non-preemptive multitasking operating system.
Each function of the terminal&mdash.keypad polling, host communications
handling, indicator operations, bar code and magnetic decoding, and other
operations&mdash.is performed by one or more tasks placed on the system's
task queue.
The Custom Function Routine is started as one of these tasks, and it
must yield periodically to the task dispatcher so that these other functions
may be serviced. If the CFR goes for long periods without yielding to the
other tasks, undesired results may occur such as:
- The system may reset due to the watchdog timer not being serviced.
- The host computer may not receive a reply to its commands or polls
in the required time period.
- The operator may notice that key strokes are ignored
- The speaker or an indicator LED or DO point may stay active for
longer than desired.
- A bar code or magnetic swipe may go un-decoded.
In general, it is recommended that a CFR not execute for more than
5 milliseconds without issuing an IdleManager API call
(or doing a return to the calling program). The IdleManager
routine allows the task manager to run once through each of the other
tasks which are waiting in the queue.
When a CFR is waiting in a loop for keypad input, a bar code or
magnetic stripe to be read, or for the host to set a user variable, it
is essential that the loop checking for this input have an IdleManager
call included in the code path. If not, no input can ever be received.
When the program execution calls for a delay period (for example, while
giving time for an operator to read a display screen), the IdleManager routine
provides a convenient way to wait for this delay time to elapse while
being a good multi-tasking entity at the same time. The argument to
IdleManager allows a delay of 0 to 65535 units of 5 milliseconds during
which the task manager allows all other tasks to run as often as possible
while the CFR "sleeps" (much like OS/2's DOSSLEEP function).
The 7526 DCT terminal's watchdog timer needs to be serviced at least once
every second to prevent the terminal from resetting. The CFR must service
the watchdog if its processes are
time consuming. The CFR is responsible for maintaining the terminal
watchdog through a call to the HitWatchdog API or any other API call. All
CFR APIs service the watchdog timer on entry, and again on exit.
The transaction record is initialized at the start of a transaction
program, and the transaction record is transmitted at the
end of the transaction program.
CFRs can add directly to the current transaction by
using the API call WriteToTrans, or it may pass its results
back in an appropriate user variable, from which the transaction program
may copy it to the transaction record.
A new, clear transaction record is created each time a transaction program
is started. When the CFR is called, the transaction record may contain
data acquired by the transaction program up to that point.
The CFR code may then:
- Add to the transaction record using the WriteToTrans function and
return to the transaction program for more data. Eventually, the
transaction program causes the transaction to be sent to the host processor
either by explicitly using the SendTransaction command or by
exiting the transaction program with automatic transaction building set to
On (Refer to the :A Automatic
Transaction command on page reference #6).
- Add to the transaction record using the WriteToTrans
function and send it to the host processor output queue using the
SendTransaction function. After SendTransaction transmits the
transaction record, the record space may be cleared using the
ClearUserVariable function. The CFR may return
control to the transaction program or it may execute more calls to
WriteToTrans and SendTransaction before returning.
On exit, the CFR returns a flag which determines the next action in a
transaction program. The return flags are:
- CONTINUE (0) = continue the next command
- SKIP (1) = continue execution after the next command
- ABORT (2) = abort the transaction.
The CFR is not required to return to the system after an invocation.
The CFR may, in effect, take over the terminal and provide it's own
personality to it's operation.