Data Collection Transaction Program Builder

Data Collection Transaction Program Builder
-------------------------------------------

This readme file describes the components of the IBM Data Collection Transaction
Program Builder (DCTPB). In addition, it covers version 3.0.8f (May 2013)
and later of the DCConnect Client because the Client now supports direct
compile of the same script files that DCTPB compiles.

Notices
-------

References in this document to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which
IBM operates. Any reference to an IBM product, program or service is not
intended to state or imply that only IBM's product, program, or service
may be used. Any functionally equivalent product, program, or service that
does not infringe any of IBM's intellectual property rights may be used
instead of the IBM product, program or service. Evaluation and verification
of operation in conjunction with other products, except those expressly
designated by IBM, is the user's responsibility.

IBM may have patents or pending patent applications covering subject matter
in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to
the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY
10577.

Trademarks and Service Marks
----------------------------

The following terms are trademarks of the IBM Corporation in the United
States or other countries or both:

IBM

Other company, product, and service names may be trademarks or service
marks of others.

Table of Contents
-----------------

Overview
DCConnect Client Direct Compile of Scripts
History and Naming of the Product
Hardware Requirements
Software Requirements
Installation Instructions
Running BPTCD32
Running DCTPB32
Running IMBEDSCR
Overview of the Script File Format
Spacing and Punctuation
Comments
Legacy DCTPB Commands
Messages
Multiple Language Support
Global User Variables, Local Variables, Parameters
Rules for Variable and Parameter Names
Subroutines
Return Code User Variable
CFR Access To Variables and Parameters
Imbedding Files
Transaction Program Control Using If/Else Commands
Using AND, OR and NOT operators in If Commands
Configuration Commands for DCConnect Client Text Downloads
BUFFERING_MODE Command
CFR_FILE Command
COMMUNICATIONS_TIMEOUT
DATE_SEPARATOR
ERROR_LOGGING
FAST_CLOCK_INTERVAL
IDLE_DATE_FORMAT
IDLE_PROMPT_FORMAT
IDLE_TIME_FORMAT
INPUT_TIMEOUT
LOCAL_VALIDATION Command
NON_PROMPT_TIMEOUT
NUMERIC_DELIMITER
RS232_BACK_STRIP_LENGTH
RS232_BAUD_RATE
RS232_DATA_BITS
RS232_FRONT_STRIP_LENGTH
RS232_HEADER_STRING
RS232_PARITY
RS232_RETRY_COUNT
RS232_STOP_BITS
RS232_TIMEOUT
RS232_TRAILER_STRING
RS232_XON_XOFF
SYSTEM_MESSAGE Command
TIME_SEPARATOR
VALIDATION_TIMEOUT
Special Programming Commands
MAKEPGM Command
MESSAGE Command
PROGRAM Command
ENDPROGRAM Command
IMBED Command
TERMTYPE Command
KEY Command
ENDKEY Command
NAME_UV Command
SUB Command
ENDSUB Command
Start_Language Command
End_Language Command
Transaction Programming Commands
AK Command
AKA Command
APND Command
APNDSTR Command
AUTO Command
Block Commands { and }
BNAV Command
BOX Command
BRAUV Command
CALL Command
CCFR Command
CLRD Command
CLRP Command
CLRS Command
CMPUV Command
CURS Command
DB Command
DBI Command
DECLARE Command
DLAY Command
ELSE Command
ELSEIF Command
ENAV Command
ENCRYPT Command
FB Command
FRMT Command
GOSUB Command
GOTO Command
HF Command
IF Commands
INAV Command
KB Command
LABEL Command
LED Command
LF Command
MATH Command
MODE Command
MSG Command
NAV Command
NAVZONE Command
NK Command
NOOP Command
ONKEY Command
ONSUB Command
QUERY Command
RDDI Command
READ Command
RETURN Command
SEND Command
SET Command
SETSTR Command
Set_Language Command
SF Command
SHOW Command
TERM Command
TEST Command
VB Command
VERSION Command
VRFY Command
WRDO Command
WTDI Command
Command/Key Relationships

Overview
--------
The Data Collection Transaction Program Builder provides one utility program,
DCTPB32.EXE, which is an alternative to the DCConnect Toolkit for building
transaction program (.PGM) files for IBM 7524, 7525, 7526 and 7527 data
collection terminals as well as for any 3rd party terminal that is supported
by the DCConnect Client (formerly 752x Emulator for DOS). When writing
programs for terminals running the DCConnect Client, they should considered
the same type as the IBM 7524 terminal (DCT7524).

Note: This document uses 7524/Client throughout to indicate a particular
feature applies both to the IBM 7524 terminal and to terminals running
the DCConnect Client.

This utility gives experienced DCC/2 or DCConnect users a method for quickly
generating complex transaction programs using their favorite text editor.
After using the editor to create or modify the transaction program(s), these
text program files are 'compiled' by DCTPB32.EXE resulting in a .PGM file
that can be used with the DCConnect Server product.

The generated .PGM file(s) can be copied to the DCConnect .\job subdirectory
and then the DCConnect User Interface can be started so that the transaction
programs can be bound to one or more terminals and ultimately downloaded to
those terminals.

A second utility, BPTCD32.EXE, is also provided for converting 32-bit transaction
program files (.PGM) to the text file format used as input for the program builder.
With this second utility, it is possible to quickly generate DCTPB32 source files
for any of your existing transaction programs. Note that in June 2004 when
version 2.10 of the DCConnect Client was created introducing the new commands such
as SET, SETSTR, MATH, SUB / ENDSUB, RETURN as well as the use of local variables,
parameters and other related variable usage enhancements, the BPTCD32 utility was
NOT updated to reverse compile these commands. So this tool can only be used
for .PGM files that were created for the 7525 / 7526 / 7527 terminals or DCConnect
Client programs that do not include any commands that were introduced after June 2004.

New with fix pack D is another utility program, IMBEDSCR.EXE, which is useful if
your transaction programs are stored in several different files and you use the
IMBED command to link them altogether. IMBEDSCR.EXE allows you to generate a
single listing file that includes all of the imbedded files. The output can
either be a 'runnable' file that DCTPB32 can compile or it can be a listing shows
the line number from each imbedded file along with a letter indicating the
imbed level of that file (A for the top level, B for the next level, ...)

Versions of all utilities are provided for OS/2 3.0 or later and
Windows NT/2000/XP/7/Server or later.

DCConnect Client Direct Compile of Scripts
------------------------------------------
With version 3.0.8f of the DCConnect Client, the script processing functionality
of DCTPB has been replicated in the Client, eliminating the need to do a separate
compile step. The Client now accepts the SCRIPT_NAME parameter in its EMULATOR.INI
file (or -s command line parameter). It also has the "-o=compile_only" command line
option to indicate that only syntax checking of the scripts should be performed. Any
errors or warnings from the compile are written to etspt.msg (instead of dctpb.err).

Without the "compile only" switch in effect, the Client will process the script
file(s) and then establish communication with the DCConnect Server and be ready
for the user to run transactions without having to first receive a download from
the Server. But there is a new VERSION command that can be included in the
scripts which both the Client and Server will look at to determine if the Client
has the current set of scripts. Only if there is a difference in versions will
a download of the current scripts be sent to the Client from the Server. In addition
a manual download request of any or all devices can be made from the DCConnect
User Interface or other application.

The script processing functionality was added in version 3.0.9 of the DCConnect Server.
In this version, the Terminal Settings notebook includes a new option called
"Settings Source" which defaults to <Use Settings Notebook> but which can be
set to a script file name instead. The dropdown list for this option will show
all files in the \dcconn\job directory that have the extension .COD, .TOP and .TXT.
You pick only one file for a terminal or function group, but that file may use the
IMBED command to include other files. These other files can be located anywhere on the
DCConnect Server.

When the Settings Source is a specific script file rather than <Use Settings Notebook>
then all of the terminal resident configuration parameters in the Settings Notebook are
ignored - including CFR Name, Validation at Terminal, Program Bindings, Idle Menu and
System Messages. The only parameters in the Terminal Settings notebook that are used
in this case, are those that define the terminal rather than what is loaded to it:

- General tab, Page 1
- Terminal Name
- Terminal Address
- Terminal Model
- Settings Source
- General tab, Page 2
- Start Up State - In Service
- Start Up State - Polled
- Time tab, Page 3
- Terminal's Time Zone relative to the Server

All of the other parameters can now be set in your text-based script files using new commands
such as CFR_FILE, SYSTEM_MESSAGE, LOCAL_VALIDATION, DATE_SEPARATOR, NON_PROMPT_TIMEOUT and many
more. For more info, please see Configuration Commands for DCConnect Client Text Downloads.

When the DCConnect Server does download text scripts to the Client, in order to minimize
the download size and time, all imbedded files are combined into one file, all comments
are removed as well as any extra spaces. The result is a single file called SCRIPTS.TXT
when it is received at the Client. Note that on the server, in order to prevent name
conflict with terminals that are being downloaded simultaneously, the stripped down
text file is given the name of the format ttttttt.$TP where 'ttttttt' is the terminal name.

During a text file download, the first file that is downloaded is actually an .INI file
called MASTER.INI that includes two commands as illustrated here:

TERM_SUB_MODEL=Win32
SCRIPT_NAME=SCRIPTS.TXT

The TERM_SUB_MODEL command tells the Client what model is configured for this terminal in
the DCConnect configuration (General tab, Page 1, Terminal Model). The primary use for
this is to choose the correct CFR_FILE command, when there are multiple such commands
in the scripts, each specifying a different CFR executable for different terminal models.
The SCRIPT_NAME parameter tells the client what script file to load. This is always
SCRIPTS.TXT.

Starting With version 3.0.8f, the DCConnect Client looks for both MASTER.INI and EMULATOR.INI
when it starts up and after text files are downloaded to it. If any setting is found in
both files, the one in MASTER.INI takes precedence.

History and Naming of the Product
---------------------------------
The Data Collection Transaction Building Tool has existed in the past as a
tool for generating 16-bit .PGM, .CFG and .TDF files. Despite its official
name, this tool has come to be known as DCTPB - Data Collection Transaction
Program Builder. In fact its executable has that name.

Due to the history of that name, we will continue to use it for the tool
used to convert the text file to a .PGM file. However, the current version
of the product generates only 32-bit .PGM files directly; it does not
generate .JOB files. The rest of the terminal configuration can be set up
using the DCConnect terminal notebooks.

The second utility, for converting from .PGM files to text files, is called
BPTCD32 (BPTCD is the reverse of DCTPB which stands for Binary Program To
Command Decoder).

Hardware Requirements
---------------------
None

Software Requirements
---------------------
IBM OS/2 Version 3.0 or later

- or -

Microsoft Windows NT/2000/XP/7/Server later

Installation Instructions
-------------------------
The CD for this product includes versions to be used on OS/2 and Windows NT/2000/XP/7/Server.
In addition online documentation for this and other ERPBridge and DCConnect
products are provided in the \MANUALS directory of the CD. To view the
list of online documentation, enter the following URL in your browser:

file:///d:\manuals\index.htm

where d: is the drive letter for your CD-ROM drive. A page will be displayed
from which you can click on the book you want to read. There is also a link
to the ERPBridge / DCConnect home page.

To install this product on Windows NT/2000/XP/7/Server, run the following from the root
directory of the CD:

setup

To install this product on OS/2, run the following from the root directory
of the CD:

setupos2

The installation program will step you through the rest of the process.

Running BPTCD32
---------------
Note that in June 2004 when version 2.10 of the DCConnect Client was created introducing
the new commands such as SET, SETSTR, MATH, SUB / ENDSUB, RETURN as well as the use of
local variables, parameters and other related variable usage enhancements, the BPTCD32
utility was NOT updated to reverse compile these commands. So this tool can only be used
for .PGM files that were created for the 7525 / 7526 / 7527 terminals or DCConnect
Client programs that do not include any commands that were introduced after June 2004.

In order to run the BPTCD32 utility to convert a DCConnect (or 32-bit DCC/2)
.PGM files to a DCTPB32 source text file, issue the following command:

bptcd32 filename.PGM [messages_in_line]

where 'filename.PGM' is the name of the 32-bit .PGM file.

'messages_in_line' is an optional parameter indicating that message
text should be included directly in MSG, SHOW,
APND and SHOW commands. If this parameter is not
specified, MESSAGE commands are put at the start
of the output for all messages that are used and
the MSG, SHOW, APND and SHOW commands use a message
number instead of the actual text.

The output file generated by the BPTCD32 utility will match the name of the
.PGM file that is being processed but will have the extension .COD. The .COD
file is a valid source file for use as input to the DCTPB32 utility. If
processed by the DCTPB32 utility it would yield a .PGM file equivalent to the
one you started with.

Running DCTPB32
---------------
In order to run the DCTPB32 utility to convert a text script file to a
DCConnect (or 32-bit DCC/2) .PGM file, issue the following command:

dctpb32 source_file [INCLUDE_COMMENTS] [SHOW_STEPS]

where 'source_file' is the name of the source text file to be converted to
a .PGM file. Typically this file will have the extension
.COD, but that is not required.

INCLUDE_COMMENTS is an optional parameter which specifies that
comments denoted by double slash are to be included in
the .PGM file that is generated. If this parameter is
used, do not include the square brackets shown above.

As of fix pack D, February 2001, double-slash comments
are no longer included in the .PGM file automatically;
You must now use the INCLUDE_COMMENTS parameter if you
want them.

You may want to use the INCLUDE_COMMENTS parameter if
you want them to show up when the program is viewed
using, for example, the DCConnect Toolkit. However,
comments that are included in the .PGM file result in a
larger download to 7524/Client and 7527 terminals
(2 extra bytes per comment).

SHOW_STEPS is optional parameter that tells DCTPB to show the program
number and step number of each command as it is compiling.
You could then redirect the screen output of the compile
to a file in order to capture this information.

This information can be useful when trying to cross
reference your DCTPB source code with DCConnect Client
generated messages or error transactions which reference
a step number or steps numbers shown while STEPPING
mode is in effect in the DCConnect Client.

When this parameter is in effect, all MESSAGE commands
are also shown in the output so that you can cross
reference them with the message numbers or names used in
the transaction program commands.

This option was new as of May 16, 2005.

By default the output file name will be PGMFILE.PGM. However, the MakePGM
command can be used in the source file to specify a different output file name.

Read below for more information about the format of the input script file for
DCTPB32.

Running IMBEDSCR
----------------
To generate a single listing file which includes all imbedded files in the
listing, issue the following command:

imbedscr source_file

where 'source_file' is the same name that you would use when running
DCTPB32.EXE. Typically this file will have the extension .COD, but that
is not required.

The output file will have the same 'file name' (before the period) as the
input file, but the extension of the output file will be .LST - unless the
extension of the input file is already .LST in which case the extension of
the output file will be .OUT.

Initially this tool generated a listing file that could not actually be compiled
by DCTPB32. But the latest version generates a 'runnable' output file. This
might be useful if the set of scripts need to be sent to a colleague to illustrate
something or if the set of scripts need to be sent to IBM so that a problem can
be replicated.

If you prefer to get a listing with line numbers, then you can add a second
parameter, 'listing', to the command line. For example:

imbedscr source.cod listing

The listing shows the line number from each imbedded file along with a letter
indicating the imbed level of that file (A for the top level, B for the next
level, ...).

Overview of the Script File Format
----------------------------------
A single input script file can contain definitions for more than one
transaction program. Each program starts with the PROGRAM command, specifying
the name and type. Each program ends with the ENDPROGRAM command. In between
are the commands that make up the transaction program.

At the start of the file you would typically have a MakePGM command which is
used to specify the name of the output .PGM file. To illustrate:

MakePgm(TIME_ATT.PGM)

PROGRAM(CLOCK_IN, DCT7526_200)
/* Commands for CLOCK_IN program here */
/* Commands for CLOCK_IN program here */
/* Commands for CLOCK_IN program here */
ENDPROGRAM()

PROGRAM(CLOCK_OUT, DCT7526_200)
/* Commands for CLOCK_OUT program here */
/* Commands for CLOCK_OUT program here */
/* Commands for CLOCK_OUT program here */
ENDPROGRAM()

Note: The commands TERMTYPE/KEY/ENDKEY commands can be used in place of
PROGRAM/ENDPROGRAM to specifies the start and end of programs as
well as their terminal types. However, these alternate commands
should only be used if all programs in the file are for the same
terminal type and the binding information from the KEY command will
be used. See the TERMTYPE command below for more details.

For text scripts that are to be loaded directly by the DCConnect Client,
the Key / EndKey commands must be used instead of Program / EndProgram
so that each program is properly associated with a key. In addition, the
MakePgm command is not used - and will be ignored if encountered.

Spacing and Punctuation
-----------------------
Spaces before commands and between parameters can be used as desired. DCTPB32
looks for specific keywords and delimiters, ignoring preceding and intervening
spaces.

Commas must be used to separate parameters. An opening parenthesis
must precede the first parameter of a particular command and a closing
parenthesis must follow the last parameter. An optional semicolon may be
added after the closing parenthesis. If a comma or parenthesis is part of
inline message text of the text of any parameter, that parameter's text should
be enclosed in double quotes. If a string that is enclosed in double quotes
must contain one or more double quotes within it, use a pair of double quotes
to represent each one. For example, to show the message:

Dean said "Time to go home!" and he did.

you would set up the MSG command as follows:

MSG("Dean said ""Time to go home!"" and he did.");

Blank lines can be interspersed throughout the text as desired.

A single command may be split across multiple lines.

The maximum total command length is 4000 after leading and trailing spaces and
trailing comments are removed.

Comments
--------
The DCTPB32 script may contain comments for describing what your programs are
doing. There are two ways comments can be entered into the script:

1) Preceded by slash-star and ending with star-slash. For example:

/* The following code prompts the user for the userid and password */

Comments of this type are NOT included in the .PGM file and thus result
in a smaller download to 7527 and 7524/Client terminals.

2) Preceding the comment using double slashes. For example:

// The following code prompts the user for the userid and password

As of fix pack D, February 2001, these comments are no longer included
in the .PGM file unless a second command line parameter, INCLUDE_COMMENTS,
is specified when DCTPB32.EXE is run.

You may want to use the INCLUDE_COMMENTS parameter if you want them to
show up when the program is viewed using, for example, the DCConnect
Toolkit. However, comments that are included in the .PGM file result
in a larger download to 7524/Client and 7527 terminals (2 extra bytes
per comment).

If a line starts with a comment, the entire line is ignored. For example, the
command on the following line is NOT processed:

/* Unlock door for 5 seconds */ WRDO (0, SET_DO_POINT, 5, DO_SYNCH)

However, comments may follow a complete command on the same line. For
example, the following WRDO command is processed:

WRDO (0, SET_DO_POINT, 5, DO_SYNCH) /* Unlock door for 5 seconds */

For commands that are split across multiple lines, it is legal for each
line in the split command to have a comment at the end of the line. For
example, the following If command is split over two lines but each line
has a comment at the end:

if ((uvRow #< 1) || (uvRow #> 16) || // Row must be 1-16
(uvCol #< 1) || (uvCol #> 20)) // Column must be 1-20
Goto (THIS_PROGRAM, INVALID_DIMENSIONS)

Legacy DCTPB Commands
---------------------
Throughout the history of DCTPB other commands have been allowed which may
not be documented here. These old commands, which related to the generation
of the old DCC/2 terminal configuration files (.CFG, .TDF) - such as
TXBUFFERSIZE, ALIAS or FASTCLOCKTIME, are also still accepted without error.
However, these have no real effect because the current DCTPB32 only generates
program files. This does allow any old DCTPB script to be used to generate
program files for DCConnect - even if those scripts included the entire
terminal configuration.

Messages
--------
For commands that can have message text as a parameter (MSG, APND, SEND and
SHOW), there are three ways you can set up the message text:

1) Put the message text directly into the command enclosed in double
quotes. For example:

SHOW(SRC_MESSAGE_FILE, "Enter badge:", 1, 1, NORMAL);

Messages designated this way are referred to as "inline".

2) Set up a message number for the message text using the MESSAGE command and
then use that message number in the command instead of the text:

MESSAGE( 300, "Enter badge:", 0);

...

SHOW(SRC_MESSAGE_FILE, 300, 1, 1, NORMAL);

3) Set up a message name for the message text using the MESSAGE command and
then use that message name in the command instead of the text:

MESSAGE( MSG_ENTER_BADGE, "Enter badge:", 0);

...

SHOW(SRC_MESSAGE_FILE, MSG_ENTER_BADGE, 1, 1, NORMAL);

Use of inline messages has the following advantages:

You see the text of the message directly in the command and do not have to look for it elsewhere in
the program. This improves the readability of the program.
It is easier to merge programs developed for different project (i.e. no need to re-number messages).

When using the inline method, DCTPB32 save space by detecting messages that are the same and will set up the .PGM file
so that the text is stored only once and referenced multiple times.

Advantages to the numbered method are:

You need only change the message text in one place (e.g. a separately imbedded message file) if a single message
is used in more than one place. Of course the Find/Replace function of your editor could also be used to
accomplish that when using the inline method.
You can write the code once and compile using different language translations of the messages file
It is easier to keep your message file organized as you add new functions

The use of named messages combines the advantages of inline and numbered messages, assuming you use meaningful names
that reflect the message text. The message name can be up to 64 characters in length.

If using MESSAGE commands, they should be defined before they are referenced.

If using message numbers it is not necessary for the numbers to be consecutive; message numbers
can be skipped as desired. For 7524/Client, 7525 and 7527 transaction
programs, the first message number used should be 10 or above; for 7526
transaction programs start with 11 or above.

As of the May 2000 release of the product, it is now possible to mix inline
messages along with messages defined using the MESSAGE command. In addition,
the message numbers in MESSAGE commands no longer need to be sequential -
although for maintenance purposes it is a good idea to organize them that way.

New in version 2.1.0 is the option to eliminate the SRC_MESSAGE_FILE
parameter from the APND, SEND and SHOW commands. So the three show commands
above could instead be entered as:

SHOW("Enter badge:", 1, 1, NORMAL);

SHOW(300, 1, 1, NORMAL);

SHOW(MSG_ENTER_BADGE, 1, 1, NORMAL);

When DCTPB compiles named messages into a .PGM file, the message names are handled strictly during the
DCTPB compile; the names are not seen by the DCConnect Server or the terminals; The DCTPB compile
converts the names to numbers when the .PGM file is generated.

And when the DCConnect Client is reading the text script files directly, the messages names are also
not visible anywhere, just the actual message text.

The ability to define multiple languages and switch which one is active is a feature that
is only available in version 3.0.8f of the DCConnct Client and later; it is not available when
using DCTPB to compile scripts. See the following commands in the rest of this document for
more details:

Start_Language
End_Language
Set_Language

Multiple Language Support
-------------------------
When text based scripts are being used - supported with version 3.0.8f and later - you can
define messages in multiple languages using Start_Langage, End_Language blocks and the
'named message' method for defining messages using the Message command. The System_Message
command can also be included in Start_Language / End_Language blocks.

The following example shows how language blocks are set up.

Start_Language ( English )

Message ( MSG_THANK_YOU, "Thank you" )
Message ( MSG_YOURE_WELCOME, "You're welcome" )
...

End_Language()

Start_Language ( Spanish )

Message ( MSG_THANK_YOU, "Gracias" )
Message ( MSG_YOURE_WELCOME, "De nada" )
...

End_Language()

Within any one Start/End_Language block, each message name must be unique. (In the example
above, the message names are MSG_THANK_YOU and MSG_YOURE_WELCOME). But each language block
should include the exact same set of message names. When the script file is processed by
the Client, an error will be given if duplication is found within a block or if the set of
messages between blocks is not the same.

Of course all SHOW, SEND, APND, � commands that reference messages will need to use the
message names that are used in the language blocks. For example:

Show (MSG_THANK_YOU, 1, 1, Normal)

The actual message text that is shown will depend on what language is currently in effect.

The first Start_Language command encountered will determine which language will be shown
first. To change the current language, use the new command:

Set_Language (language_name)

The changing of a language would likely be done in response to some kind of logon transaction
where the response from the server indicates what language the signed in user has been
assigned. Assuming the language is parsed out of the response into a variable called
uvLanguage, the following code is example of how the language could be set:

If (uvLanguage = �English�)
Set_Language (English)
Elseif (uvLanguage = �Spanish�)
Set_Language(Spanish)
Elseif (uvLanguage = �German�)
Set_Language(German)

Note that the language name used in any Set_Language commands must match the name used in one
of the Start_Language commands. However, the language names shown in double quotes against
which the uvLanguage variable is compared can be whatever you establish as the means of
identifying the language between server and client.

If there are any system messages, such as those for the idle menu that need to be defined when
multiple languages are in use, the System_Message command can be used in each of the language
blocks, for each of these system messages.

When language blocks are in use you can also have Message commands that are not inside any
message block. You would do this for messages that do not need to be translated - such as
those that contain only numbers, spaces, dashes, identifiers, ... Message defined outside of
language blocks are referred to as 'common' messages. For the Message commands that define
these common messages, message names must still be used; message numbers cannot be used. You
can also use inline messages; these are considered common messages as well. Up to 256 common
messages can be defined.

Note: When language blocks are being used, the System_Message command cannot appear outside
of those language blocks.

Of course if only one language is being used, no Start_Language / End_Language blocks are needed
and therefore all Message and System_Message commands will not be inside a language block.

Note that when compiling scripts with DCTPB, Start_Language and End_Language are not considered valid
commands. But Set_Language can be included in scripts that are compiled by DCTPB; it will just be
ignored.

This behavior allows you to use the same set of scripts for a device that does not support multiple
languages (e.g. the version of the Client built for the DOS-based Antares terminal does not support
multiple languages due to limited memory) as well as for devices that do support multiple languages.

The following example illustrates how the scripts files can be organized to accomplish this.
- Assume that English is the language to be used on the devices that support only one language
- Named messages are used everywhere; numbered messages are not used.
- COMMON.MSG is created to contain messages that would not need to be translated - such as numbers,
strings of blanks, symbols, ...
- MSG_EN.MSG contains the English versions of messages
- MSG_SP.MSG contains the Spanish versions of messages
- SYSMSG_EN.MSG contains the English versions of the system messages (not used by DOS-based scripts)
- SYSMSG_SP.MSG contains the Spanish versions of the system messages (not used by DOS-based scripts)
- The transactions programs used by all devices are defined in TP1620.COD (which may IMBED other
script files)
- Create a 'top-level' script file for the Antares (e.g. ANTARES.TOP) that imbeds the English messages
and programs that it needs (Note that TERMTYPE must be the first command):

TERMTYPE ( DCT7524, ENFORCE_BINDINGS )

MakePGM ("TP1620.PGM")

IMBED ( COMMON.MSG )
IMBED ( MSG_EN.MSG )
IMBED ( TP1620.COD )

This file, ANTARES.TOP, will be compiled by DCTPB to generate TP1620.PGM. Because this is being
compiled by DCTPB, the MakePGM command is needed to tell it what .PGM file should be generated.
In the DCConnect User Interface, the Terminal Settings notebook will the Settings Source set to
and the Program Binding page on the Associations tab will need to be set
up with bindings to transaction programs in the TP1620.PGM file. Any other configuration of the
terminal, such as the CFR to use and the text of system messages and the idle menu, must all be
set up in that Terminal Settings notebook.

- Create a different 'top-level' script file (e.g. THEREST.TOP) for all of the devices that support
multiple languages and which will be configured in the DCConnect User Interface to have their
Settings Source be this .TOP file, indicating the Client will load the script files directly:

TERMTYPE ( DCT7524, ENFORCE_BINDINGS )

IMBED ( COMMON.MSG )

START_LANGUAGE ( English )

IMBED ( SYSMSG_EN.MSG )
IMBED ( MSG_EN.MSG )

END_LANGUAGE ()

START_LANGUAGE ( Spanish )

IMBED ( SYSMSG_SP.MSG )
IMBED ( MSG_SP.MSG )

END_LANGUAGE ()

BUFFERING_MODE(BUFFERED)

CFR_FILE(dclw32.dll, WIN32)
CFR_FILE(DCLck30.dll, Intermec_CK30)

IMBED ( TP1620.COD)

Because this .TOP file is being loaded directly by the Client (after being downloaded to the
Client by the Server along with all files referenced by it) it includes all the necessary commands
for configuring the Client, including what CFR to use and the buffering mode. In this case, none
of the settings are used in the Terminal Settings notebook that define what is configured in the
terminal. (But settings that describe the terminal, such as its name, address, time zone, startup
state do still apply).

Global User Variables, Local Variables, Parameters
--------------------------------------------------
When a transaction program is in progress, it has access to user variables
for storing and manipulating data. Different terminal types have different
numbers of user variables:

- The 7525 terminal has no user variables
- The 7526 terminal uses the download to tell it how many user variables
should be allocated. The maximum is 999 user variables (0-998) each being
999 bytes in length. But the download likely limits those maximums considerably.
- The 7527 terminal has 20 user variables: 0-19 and each can hold 128 bytes of data.
- The 7524 terminal/DCConnect Client had the same limits up to version 1.10. Starting
with version 1.10, 100 user variables were made available - still 128 bytes each.

In version 2.1.0 of the DCConnect Client, the underlying mechanism for maintaining
user variable content was changed so that rather than having separate, fixed buffers
for each user variable, the data for all user variables is maintained in a single
pool of memory. As a result, the sizes of individual user variables is limited only
by the size of the memory pool.

Also new in version 2.1.0, for transaction programs that are written for the
DCConnect Client, is the ability to DECLARE up to 92 local variables for each
subroutine and each transaction program, and the ability to pass up to 92
parameters to each subroutine. A special return code user variable is also
available for passing data back from a subroutine to its caller. All of these
other kinds of variables use the same pool of memory for their data as is used for
the 100 global variables. Any variable that does not contain any data does not
take up any space in the pool. However there is a structure that is added to the
pool for every subroutine call and for the starting of a transaction program.
This structure is about 50 bytes in size plus 8 bytes for every local variable
and every parameter. These 8 bytes are used to keep track of the offset and
length of the data in the pool for each variable and parameter.

Every local user variable name and parameter name that is defined for a particular
subroutine or transaction program must be unique for that subroutine or
transaction program. However, local variable names and parameter names may be
reused across different transaction programs and different subroutines.

The global user variables are accessible from all transaction programs and subroutines
and maintain their values until changed explicitly by a transaction program command
or CFR API. One exception to this is user variables 1-19 for 7527, 7524 terminals and
terminals running the DCConnect Client. For these terminals, user variables 1-19 are
cleared at the start of every transaction program.

User variable 0 is also treated differently. It is the variable that receives the
data whenever keyboard input or scanner input is received by one of the input
commands:

READ
AK
NK
KB
DB
VB

User variable 0 is always cleared at the start of one of these commands. It is also
cleared, just like user variables 1-19, at the start of every transaction program.

Starting with version 2.1.0, DCTPB now allows you to name your global user
variables using the NAME_UV command. This command can be used for any global user
variable regardless of the terminal type (except of course 7525s which do have have
user variables). Each global user variable may have only one name.

User variable 0 is predefined with two names that DCTPB has reserved for it:
uvInput and gInput. But you have the option to give user variable 0 another name
if you prefer something else.

Rules for Variable and Parameter Names
--------------------------------------
New with version 2.1.0 of DCTPB is the ability to name user variables for any
transaction program type, using the NAME_UV command. In
addition, for transaction programs that will run on version 2.1.0 or later of
the DCConnect Client, local variables and subroutine parameters can be declared,
each having a name.

For all of these names, the following rules apply:

- Length of the name must be from 1-32 characters

- Names cannot contain any white space, the comma character or equal sign

- Names cannot start with a number or minus sign

- Names are case insensitive. For example, you could declare a variable
called 'NUMROWS' and then use it in a CLRP command as 'numrows'.

- Names must be unique amongst all other variable names that are currently
in scope. This means the following:

- No parameter name or local variable name can be the same as any global
variable name.

- For each transaction program, all local variables for that transaction
program must be unique. (Other transaction programs and subroutines can
use the same variable names for their parameters and local variables).

- For each subroutine, all local variables for that subroutine must be
unique and cannot match any parameter name used in the same subroutine.
(Other transaction programs and subroutines can use the same variable
names for their parameters and local variables).

- For each subroutine, all parameters for that subroutine must be unique
and cannot match any local variable name used in the same subroutine.
(Other transaction programs and subroutines can use the same variable
names for their parameters and local variables).

- Names cannot be any of the following reserved keywords:

ABORT_PROGRAM DI0 - DI7 PREVIOUS_COLUMN TODCLK
ADDL1 - ADDL8 END_OF_PROGRAM PREVIOUS_ROW TOUCH1 - TOUCH40
ALL_DATA F1 - F28 RES2 - RES9 TRANSACTION_RECORD
ASCII_SEMICOLON FASTCLK RS232 UV0 - UV998
ASCII_SPACE gINPUT RS232_2 uvINPUT
ASCII_ZERO gRC SPF1 - SPF12 uvRC
BADGINIT NEXT_COLUMN SRC_MESSAGE_FILE VARIABLE_LENGTH
CLEAR_EOL NEXT_ROW SRC_OTHER
CLEAR_REST NO_PARAMETERS SRC_TRANS_RECORD
CURRENT_COLUMN NO_VALIDATION TCH1 - TCH40
CURRENT_ROW PF1 - PF12 THIS_PROGRAM

- Names cannot contain .val at the end (upper or lower case).

Subroutines
-----------
7526, 7527, 7524 terminals and terminals running the DCConnect Client support the
calling of subroutines so that common pieces of code can be reused, thus saving
space and reducing the chance for coding errors. The LABEL command is used to
mark the start of a subroutine and the RETURN command is used to indicate when
the subroutine should end and return to the caller. The GOSUB command is used
to call the subroutine. When the subroutine is called, control transfers to the
command following the LABEL command. The subroutine executes until a RETURN
command is encountered, at which time control transfers to the command following
the GOSUB command.

For the 7526, 7527 and 7524 terminals and terminals running versions of the
DCConnect Client prior to version 2.1.0, the way to pass information to and
from subroutines is to use global user variables.

New in version 2.1.0 of DCTPB, for transaction programs that will run on at
least version 2.1.0 of the DCConnect Client, is the ability to pass parameters
to the subroutine, declare local variables for the subroutine and to return
a value from the subroutine. Because local variables and parameters are
limited in the scope for which they are valid, there is also a new way to
define a subroutine so that it is clear where it begins and ends. The
commands SUB and ENDSUB are used to define the bounds of a subroutine in the
same way that PROGRAM and ENDPROGRAM are used to define the bounds of a
transaction program.

The following is an example of a subroutine defined this way:

SUB ADDL1:CLEAR_ROWS (pFirstRow, pNumRows, pNumCols)

Declare (locRowToClear = pFirstRow)
Declare (locRowCount = pNumRows)

LABEL (NextRow)
CLRP (locRowToClear, 1, pNumCols)
MATH (locRowToClear = locRowToClear + 1)
MATH (locRowCount = locRowCount - 1)
If (locRowCount > 0)
Goto (THIS_PROGRAM, NextRow)

Return

ENDSUB()

Subroutines are still assigned to one of the transaction programs in the
terminal - as specified by the identifier that follows the word SUB and
precedes the colon (ADDL1 above). Multiple subroutines can be a assigned
to the same transaction program.

You can also define a transaction program for a particular ID even when
one or more subroutines are also assigned to that transactin program
identifier. If that is done, the transaction program must be defined
before the associated subroutines are defined. When DCTPB compiles the
programs and subroutines, it will automatically add the command:

GOTO(THIS_PROGRAM, END_OF_PROGRAM)

at the end of the program so that execution of the program does not
proceed into the subroutines that are also assigned to this program.

Note: If you have one or more subroutines assigned to a particular ID and
there is no transaction program also assigned to that ID, then the
transaction program that is generated for this ID will be given
a default name using the format:

XXXXX_SUBROUTINES

where 'XXXXX' is the ID (e.g. F1, ADDL1, ...). When using the
DCConnect User Interface to bind this transaction program that
contains only subroutines, look for the program name in the format
shown above. For example:

F1_SUBROUTINES
ADDL1_SUBROUTINES

In the example above, the parameters pFirstRow, pNumRows and pNumCols
and the local variables locRowToClear and locRowCount are valid only
between the SUB and ENDSUB commands. However, other subroutines
could be defined that declare parameters and variables using any of
the same names used above. But those variables are considered to be
completely different variables.

Along with the new SUB / ENDSUB commands is an alternate way to call
the subroutine when passing parameters. You can use the GOSUB
command as before and just add any parameters after the label name.

For example, to call the subroutine above you could use:

GOSUB (ADDL1, CLEAR_ROWS, 1, 5, 20)

But you could also use the new CALL command which
provides a more natural way to call the subroutine:

CALL ADDL1:CLEAR_ROWS(1, 5, 20)

It is possible to call a subroutine and pass fewer parameters than
are defined in the actual subroutine. In this case, the parameters
that will have no data assigned to them will be the ones at the end
of the list. The TEST command and (as of version 2.2.0a of the DCConnect
Client) the IF command can be used within the subroutine to check
whether a parameter has data associated with it. In addition, as of
version 2.2.0a of the DCConnect Client, an unpassed parameter may be
passed to a nested subroutine in a CALL command. No other command
within the subroutine can reference a parameter if that parameter is
not assigned a value when the subroutine is called. If a reference to
a non-existent parameter is made by another command, an error will be
given when the transaction program is running on the terminal and tries
to execute that command; DCTPB cannot easily determine the existence of
such an error since it would have to analyze the path the code would
take through a subroutine for each call to that subroutine.

New in version 2.1.0 of DCTPB, for transaction programs that will run on at
least version 2.1.0 of the DCConnect Client, is a special variable called
the return code user variable. This variable has two names: uvRC or gRC
(capitalization does not matter). Whenever a subroutine issues a RETURN
command the value of uvRC is changed. If the RETURN command does not
specify a value, uvRC is cleared. Otherwise uvRC is set to the value
in the RETURN command. If the RETURN command specifies the return code
variable itself, then the value of the return code variable is not changed.
Presumably in this case the return code variable was explictly set
somewhere else in the subroutine.

If the command prior to the ENDSUB command is not a RETURN command
the DCTPB compiler will automatically add a RETURN command that specifies
the return code variable - thus preserving whatever value that variable
might have.

CFR Access To Variables and Parameters
--------------------------------------
As has always been the case for 7526, 7527, 7524 terminals and terminals
running the DCConnect Client, CFRs can access and change the contents
of global user variable using the CFR APIs ReadUserVariable(),
WriteUserVariable() and ClearUserVariable(). Each takes a value from 1
to the maximum global user variable that is valid for the terminal. User
variable 0 can also be read by the CFR even though it cannot be written
to or cleared.

Starting in version 2.1.0 of DCTPB, for transaction programs that are written
for version 2.1.0 of the DCConnect Client and later, the CFR can use the same
APIs to access and change local, variables, parameters and the return code
user variable. To accomplish this, certain ranges of values were defined
for each of the kinds of variables. Included in this list are values for the
transaction buffer, PF Strings and Touch Point Strings:

#define VAR_NUM_FIRST_GLOBAL 0
#define VAR_NUM_LAST_GLOBAL 99
#define VAR_NUM_TRANS_BUFFER 100
#define VAR_NUM_FIRST_PF_STRING 101
#define VAR_NUM_LAST_PF_STRING 124
#define VAR_NUM_FIRST_TOUCH_STRING 125
#define VAR_NUM_LAST_TOUCH_STRING 164
#define VAR_NUM_FIRST_LOCAL 801
#define VAR_NUM_LAST_LOCAL 892
#define VAR_NUM_FIRST_PARAMETER 901
#define VAR_NUM_LAST_PARAMETER 992
#define VAR_NUM_RETURN_CODE 999

So to read the first local variable defined in a subroutine/transaction
program in a CCFR call from that subroutine/transaction program, the CFR
should call ReadUserVariable specifying VAR_NUM_FIRST_LOCAL as the parameter.
Similarly, if the CFR needed to clear the variable represented by second
parameter in a subroutine that called the CFR, then the CFR should call
ClearUserVariable specifying VAR_NUM_FIRST_PARAMETER + 1 as the parameter.

Note: The transaction buffer cannot be written to or read by the CFR
APIs WriteUserVariable and ReadUserVariable respectively. Use
the CFR API WriteToTrans to write to the transaction buffer.

Now since local variables, parameters and probably global variables have
names, it would not be very easy to tell the CFR what number to use based
on the variable/parameter name. To resolve this, DCTPB provides a
mechanism whereby it will do the appropriate 3 digit numeric substitution
for variable names used in CCFR parameter strings if those variable names
are delineated by the percent sign (%).

For example, assuming the following NAME_UV command is in effect:

Name_UV (UV60, CURRENT_TAG)

then the CCFR command:

CCFR (3, "TG-%CURRENT_TAG%")

would have its parameter string converted by DCTPB to the following:

"TG-060"

As another example, if a subroutine was defined and the first parameter
for that subroutine was named "pFirstRow", then the CCFR command:

CCFR (3, "ADD-3-%pFirstRow%")

would have its parameter string converted by DCTPB to the following:

"ADD-3-901"

The CFR, knowing at which offset in the parameter string the 3-digit value
will be, can convert that 3-digit value to an integer and then pass it to
the appropriate CFR API call in order to read, write or clear that
variable/parameter.

Imbedding Files
---------------
Using the IMBED command, you can organize common transaction program code so
that it need only be modified in one place. The imbed command takes as a
parameter the name of the DCTPB32 script file to imbed. When DCTPB32 processes
imbedded files it inserts the code at the imbed point as if that code had
been entered inline.

Below is an example of using imbedded files to isolate common code. The
file TIME_ATT.COD is the main file that sets up two transaction programs -
one for clocking in and one for clocking out. The only difference between
the two is the starting data in the transaction: "CLCKIN " vs. "CLCKOUT".
After the starting data is set up in user-variable one, the code to actually
get the badge number from the user, apnd it to the transaction and send the
transaction is all done in the imbedded file GETBADGE.COD.

TIME_ATT.COD
------------
MAKEPGM(TIME_ATT.PGM)

PROGRAM(Clock_In, DCT7526_200)
CLRD(UV1)
APND(UV1, "CLCKIN ")
IMBED(GETBADGE.COD)
ENDPROGRAM()

PROGRAM(Clock_Out, DCT7526_200)
CLRD(UV1)
APND(UV1, "CLCKOUT")
IMBED(GETBADGE.COD)
ENDPROGRAM()

GETBADGE.COD
------------
AUTO OFF
SHOW( "Enter badge...", 1, 1, NORMAL)
READ(SENSOR_PORT, FIXED_LEN_READ, 7, NO_VALIDATION, NONE, ECHO_OFF_TIMEOUT)
APND(UV1, UV0)
SEND(HOST, UV1)

With the above setup, if it was decided that the badge number being read
should be validated against a file, that change could be made in one place,
GETBADGE.COD, and it would affect both the Clock_In and Clock_Out programs.

Transaction Program Control Using If/Else Commands
--------------------------------------------------
In version 2.2.0 of DCTPB, the DCConnect Server and the DCConnect Client,
support has been added for the use of If-Else flow-of-control
constructions, much like traditional programming languages. The If/Else
construct can take many forms, and is best explained with some examples:

// A simple If command
// Command A is executed only when the uvResult is equal to "OK"
// Command B is always executed.

If (uvResult == "OK")
Command A

Command B

// Execute a block of commands enclosed in braces if the
// condition is true. Again, Command B is always executed.

If (uvResult == "OK")
{
Command A
Command AA
Command AAA
}

Command B

// Execute a block of commands enclosed in braces if the
// condition is true. This time, use Else to cause Command B
// and Command BB to be executed only when the If condition is false.

If (uvResult == "OK")
{
Command A
Command AA
Command AAA
}
Else
{
Command B
Command BB
}

// Nest several levels of Ifs and brace sets to structure the
// flow of execution:
//
// Execute commands A and AA when the first If is true; when
// the second If is also true, execute commands AAA and AAAA.
// Next skip over the Else command and its nested if construct
// until you get down to Command D (which is always executed).
//
// When the first If is false, skip down to the matching Else
// command and execute the third If command -- if it is true,
// execute commands B and BB, if it is false, execute
// Command C.
//
// Command D is executed regardless of the result of any
// of the If statements.

If (uvResult == "OK")
{
Command A
Command AA
If (uvShowResult == "Y")
{
Command AAA
Command AAAA
}
}
Else
If (uvNumFailures #< 5)
{
Command B
Command BB
}
Else
Command C

Command D

// DCTPB also accepts the key word ELSEIF as a shortcut to specifying
// IF and ELSE as separate commands. This helps with readability when
// using an if-else construct as a kind of case statement. For example:

if (uvColor == "Green")
Command A
elseif (uvColor == "Red")
Command B
elseif (uvColor == "Blue")
Command C
elseif (uvColor == "Yellow")
Command D
elseif (uvColor == "Orange")
Command E
else
Command F // Invalid color

When an opening brace { is the next command after an If or Else,
this defines the start of a block of commands that are associated
with the If or Else command. All commands between that opening
brace and the matching closing brace belong to that If or Else
command. The commands that belong to an If or Else command
are executed whenever the If or Else condition is true.

If the next command after an If or Else is a regular command
(instead of an opening brace), only that command belongs to the
If or Else. Subsequent commands either belong to a higher-level
If or Else, or belong at the main level of the transaction program.

DCTPB does not place a limit on the number of levels of nested If/Else
contructs. However, the amount of available memory of the device that
is running the transaction program does limit the number of levels. However
each level that is nested only uses a few byes of the memory pool - which
is the same memory pool used to store the contents of all user variables.

For more information about the If command please see the IF Command.

For information about using AND, OR and NOT operators in an If command,
please see the following section.

Using AND, OR and NOT operators in If Commands
----------------------------------------------
Support for the If command was added in version 2.2.0 of DCTPB, the
DCConnect Server and the DCConnect Client. As part of that, the If
command supports the use of the AND / OR / NOT operators (and their
equivalents &&, &, ||, |, !) so that multiple comparison and logic
operations can be performed in a single 'If' command.

First a few quick examples:

// Make sure the dimensions are valid. Note the command
// is split across multiple lines and comments are included
// at the end of each of those lines.
if ((uvRow #< 1) OR (uvRow #> 16) OR // Dimensions of
(uvCol #< 1) OR (uvCol #> 20)) // terminal are 16x20
Goto InvalidDimensions

// This illustrates the use of multiple levels of comparison
// prioritized using parentheses
if (((UV1 == "1") and (UV2 == ")") and not (UV3 != "ABC") and (UV4 == UV14)) OR
((UV5 == UV6) and (UV7 == UV17)))
Goto Error

// The following loop should execute only 3 times
SetStr(uvCount, 5)
SetStr(uvRow, 1)
SetStr(uvColor, "Green")

Clrs()

Label(NEXT_MSG)

Show("You should see this 3 times", uvRow, 1, NORMAL)
Math(uvRow += 1)

Math(uvCount -= 1)
if (uvCount #== 2)
SetStr(uvColor, "Red")

if ((uvCount > 0) && (uvColor == "Green"))
Goto (THIS_PROGRAM, NEXT_MSG)

The following statements describe what syntax rules must be
followed when using these operators and describe how If
commands are processed.

- The entire command (after the word If) must be enclosed
within a single set of parentheses.

- Each comparison operation (e.g. UV1 == "1") must be enclosed
in a set of parentheses.

- The number of opening and closing parentheses must match
(ignoring any parentheses that are part of a literal string
or a comment).

- Any number of spaces and tabs can be included in the
If command (limited by the maximum total command size
mentioned below).

- The If command can span multiple lines. DCTPB looks for the
closing parenthesis that matches the opening parenthesis in
order to determine when it has a complete If command. The command
can be split any where you might normally add a space for padding;
it can't be split in the middle of a word or symbol or in the
middle of a literal string (enclosed in double quotes).

- Comments (starting with // or /*) can be used at the end of each
line, even when the If command spans several lines.

- DCTPB has an internal buffer of 4000 bytes to store a single If
command. As DCTPB reads in an If command that spans several lines,
it strips out leading and trailing white space and trailing comments
as it stores each line in the command. A single space is kept
between each line of data.

- The symbols AND, && and & can be used for the AND operation.

- The symbols OR, || and | can be used for the OR operation.

- The symbols NOT and ! can be used for the NOT operation.

- If using the words AND, OR and NOT instead of the symbols, you
can specify these words in upper, lower or mixed case.

- If using the words AND or OR, the previous character must be
white space or a closing parenthesis. The following character
must be white space, an opening parenthesis or the NOT operator (!).

- If using the word NOT, the previous character must be white space,
an opening parenthesis or the & or | operator. The following
character must be white space or an opening parenthesis.

- You can specify multiple AND or OR operations in the same set of
parentheses. For example: If ((C1) && (C2) && (C3) && (C4))
where C1, C2, ..., C4 are each comparison operations such as
uvColor == "Green".

- The AND and OR operators can be immediately followed by (a space and)
a NOT operator. For example: While ((C1) && !((C2) || (C3)))

- An opening parenthesis can only be preceded by one of the following:

- White space
- Another opening parenthesis
- A NOT / ! operator
- An OR / || / | operator
- An AND / && / & operator

- The opening parenthesis must be the first non-white space character
after the If keyword.

- A closing parenthesis can only be preceded by one of the following:

- White space
- Another closing parenthesis
- A comparison operation (e.g. UV1 == 45)

- Any of the AND or OR operators can only be preceded by one of the
following:

- White space
- A closing parenthesis.

- A NOT operator can only be preceded by one of the following:

- White space
- An opening parenthesis
- An OR / || / | operator
- An AND / && / & operator

- When evaluating an AND operation, if the left side of the operator
evaluates to be FALSE, the right side is not evaluated. The result
of this operation is FALSE regardless of what the result of
evaluating the right side would have been.

- When evaluating an OR operation, if the left side of the operator
evaluates to be TRUE, the right side is not evaluated. The result
of this operation is TRUE regardless of what the result of
evaluating the right side would have been.

Configuration Commands for DCConnect Client Text Downloads
----------------------------------------------------------
The configuration commands in this section are available only when the scripts
are to be loaded directly by the DCConnect Client (version 3.0.8f and later).
These configuration commands are used to set the same kinds of parameters
that are found in the Terminal Settings notebook of the DCConnect User
Interface; these are not commands in the transaction programs themselves but
control the behavior of the Client and what gets loaded to it. These include
CFR_FILE, SYSTEM_MESSAGE and LOCAL_VALIDATION.

Note that if DCTPB is used to compile script files that contain any of these
configuration commands, DCTPB will simply ignore these commands; it will not
give an error for them.

BUFFERING_MODE Command
----------------------
Supported Terminals:

Client 3.0.8f and later

Description:

Defines how DCConnect and the terminal interact. Choose Interactive, Buffered, or Both.
Note that 99% of the time, the default of Buffering is used.

Buffered Transactions are stored in a terminal buffer until the system unit polls
the terminal for data. This mode allows for quick transaction turnaround time at the
terminal. The terminal stops collecting transactions when the terminal transaction
buffer is full.

Interactive Transactions are processed by the system unit as they are entered at
the terminal. The terminal cannot accept another transaction until the current one is
processed.

Interactive/Buffered Transactions are held by the terminal only if they cannot be
processed by DCConnect as interactive transactions. All buffered transactions are
then sent to DCConnect when communications are reestablished. The terminal stops
collecting transactions when the terminal transaction buffer is full. Specifies
the start of a transaction program. The name and terminal type for the program
are specified using this command.

Format:

Buffering_Mode ( Mode )

Buffered
Interactive
Interactive_Buffered

Parameters:

Mode - Can be one of BUFFERED, INTERACTIVE, INTERACTIVE_BUFFERED as described above

Default:

If this command is not included, BUFFERED is the mode

Example:

Specify the buffering mode be Interactive, requiring a server response for each transaction:

Buffering_Mode ( Interactive )

CFR_FILE Command
----------------
Supported Terminals:

Client 3.0.8f and later

Description:

The DCConnect Client (and other terminal types) allow you to write C programs Custom
Function Routines (CFRs) that can be used to enhance the DCConnect transaction program
command set. Some examples of CFRs include a command that compares the contents of two
user variables or one that displays a digital input counter. A CFR may be written to
perform a range check for a particular piece of data that is collected. These commands
created by your CFR may return to the transaction program a SKIP (skip next statement),
NOSKIP (execute next statement), or ABORT transaction program.

Because of the underlying differences in hardware, a CFR is built specifically for a
certain terminal model; CFRs built for one terminal type will not run on other
incompatible models. The following ar different platforms that require CFRs to
be built differently - with different compilers/toolkits:

Intermec_5020 Windows CE 3.0, SH3 processor (Hitachi)
Intermec_600 Windows CE 2.12, X86 processor (AMD)
Intermec_700 Windows CE 3.0, Strong ARM 1110 processor (Intel)
Intermec_6651 Windows CE 3.0, MIPS processor (Toshiba)
Intermec_CK30 Windows CE .NET, XScale processor (Intel)
Intermec_CV60 Windows XP Embed, Intel P-III 800Mhz processor
LanPoint_CE Windows CE 3.0, X86 processor (AMD)
Symbol_81xx Windows Pocket PC, StrongArm SA1110 processor (but compatible with Intermec_700)
Symbol_90xx Windows CE .NET, ARM processor (Intel)
Symbol_91xx Windows CE 6.0, Marvell PXA320 processor (but compatible with Symbol_90xx)
Win32 Windows NT, 2000, 95, 98, ME, XP, 7, Server 20xx, ...
X86EMDebug Windows Debug, X86 processor

When building a CFR it is best to specify a name that identifies the type of terminal/operating
system/processor it will run on. However, long names are not currently supported for CFR names;
so you have 8 characters to use in addition to the .EXE or .DLL extension.

Note: When the DCConnect Server parses the text script files during a download, it looks for
the CFR_FILE command(s) and determines which CFR should be loaded to the terminal based on its
assigned terminal model.

Format:

CFR_File ( executable_name [, model ] )

Parameters:

executable_name - 8.3 name of the CFR exeutable. This will have a .DLL extension for Windows and
Windows CE / Pocket PC / Windows Mobile / ... platforms.

The specified file must exist on the server in the .\CFR directory where the
DCConnect Server is installed (by default C:\DCCONN\CFR).

model - This optional parameter indicates the terminal model type that will use the
specified executable.

If the scripts will be used on more than one different terminal model, the
CFR_FILE command should be repeated for each of those models with command
specifying a different executable name / model combination.

The Client is told its model from the TERM_SUB_MODEL parameter that is read
from either the MASTER.INI or EMULATOR.INI file upon start up or after a text
file download. The DCConnect Server sends MASTER.INI to the Client during a
download and it sets the TERM_SUB_MODEL parameter in that file based on the
Terminal Model parameter that is found on the General tab, Page 1 in the
Terminal Settings notebook in the DCConnect User Interface.

If the CFR_File parameter exists in the scripts only once and no model is
specified, then all Clients that receive a download of the scripts will also
be downloaded with the specified CFR executable.

If the CFR_File parameter exists in the scripts more than once and one of those
occurrences has no model specified, when that instance of the command is
processed, if no previous instance matched the model that the Client is using,
then the no-model instance of CFR_File will be used. Therefore, any CFR_File
command that specified a certain model, should appear before the no-model
instance of the CFR_File command, if one exists.

Default:

If no CFR_File command is specified, no CFR is downloaded to or loaded by the Client.

Example:

Specify two different CFR executables for the terminals that use this script on for the Intermec CK30
and compatible devices and one for standard Windows 32-bit or later platforms (e.g. Win 2000, XP, 7,
Server 2008, ...)

CFR_FILE(DCLck30.dll, Intermec_CK30)
CFR_FILE(dclw32.dll, WIN32)

COMMUNICATIONS_TIMEOUT Command
------------------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Defines the number of seconds that the DCConnect system unit must poll the DCT, process the transaction, and
send an acknowledgment. You can specify an INFINITE timeout or choose a specific number of seconds from 1-255.
If the system unit does not complete these tasks within the specified time period, the terminal times out and
displays the timeout prompt. Choosing a value of 0 seconds is the same as specifying INFINITE.

Format:

Communications_Timeout ( Timeout )

INFINITE
1-255

Parameters:

Timeout - Can be the keyword INFINITE or a number of seconds from 1-255

Default:

If this command is not included, the communications timeout is set to 25 seconds.

Example:

Specify the communications timeout be 60 seconds:

Communications_Timeout ( 60 )

DATE_SEPARATOR Command
----------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Determines what separator character is used between the year, month and day if the date is shown as part of
the Idle Prompt.

Format:

Date_Separator ( Separator )

SLASH
HYPHEN
PERIOD
/
-
.

Parameters:

Separator - Can be any of the keywords SLASH, HYPHEN or PERIOD or the actual separator character: / - or .

Default:

If this command is not included, the date separator is set to the slash character.

Example:

Specify the date separator to be the hyphen:

Date_Separator ( HYPHEN )

Date_Separator ( - )

ERROR_LOGGING Command
---------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Determines whether error transactions are generated for certain error situations - such as a timeout.

Format:

Error_Logging ( Yes_No )

YES
NO

Parameters:

Yes_No - Can be YES or NO

Default:

If this command is not included, error loging is not active.

Example:

Turn on Error Logging:

Error_Logging ( Yes )

FAST_CLOCK_INTERVAL Command
---------------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Specifies a range of time during which fast clocking should be active. This command can be specified more than once
to specify multiple fast clocking intervals.

When a fast clocking interval is active, the scanning of a bar code triggers the fast clocking transaction program (ID 30)
if one is assigned. If no program is assigned to ID 30, then scanning the bar code has no effect. And outside of fast
clocking intervals, the scanning of the bar code also has no effect - unless there is a transaction program assigned to ID 29.

The scan data is available in user variable 0 for the transaction program to access.

Note: Text based loading of transaction programs and the configuration does not currently support fast clocking without
any transaction program as can be done if the terminal settings notebook is used to configure the terminal. But the same
thing can be accomplished with a transaction program assigned to ID 30.

The initiation of a transaction by a badge swipe is typically done for a time-and-attendance application when the terminal
is functioning as a time clock and users are clocking in or clocking out at the beginning or end of the day or at lunch time.

Format:

Fast_Clock_Interval ( Start HH:MM, End HH:MM )

00-23 : 00-59, 00-23 : 00-59

Parameters:

Start HH:MM - The hour and minute of the start of the interval. The hour can be 0-23, the minute can be 0-59.
End HH:MM - The hour and minute of the end of the interval. The hour can be 0-23, the minute can be 0-59.

Default:

If this command is not included, no fast clocking intervals will be in effect.

Example:

Turn on fast clocking for 15 minutes before the beginning and and after the end of the first shift.

Fast_Clock_Interval ( 07:15, 07:30 )
Fast_Clock_Interval ( 16:00, 16:15 )

IDLE_DATE_FORMAT Command
------------------------
Supported Terminals:

Client 3.0.8f and later

Description:

Determines how the date is displayed on the terminal when the IDLE_PROMPT_FORMAT is set to either DATE_ONLY or DATE_TIME.

Note: for performance reasons, the date and/or time is not actually shown unless the keyword SHOW_IDLE_TIME is in effect in the DCConnect Client
EMULATOR.INI file.

Format:

Idle_Date_Format ( Format )

YYMMDD
MMDDYY
DDMMYY
JJJYY
YYJJJ

Parameters:

Format - indicates what order the year / month / day or year / Julian day should be. The choices are YYMMDD, MMDDYY, DDMMYY, JJJYY or YYJJJ.

Default:

If this command is not included, MMDDYY is the idle date format.

Example:

Specify the idle date format be year-month-day:

Idle_Date_Format ( YYMMDD )

IDLE_PROMPT_FORMAT Command
--------------------------
Supported Terminals:

Client 3.0.8f and later

Description:

Determines what is shown on the status row of the screen when the terminal is in idle mode. The Idle Prompt is always shown left-justified.
The date and/or time is shown right justified as specified by this setting.

Note: for performance reasons, the date and/or time is not actually shown unless the keyword SHOW_IDLE_TIME is in effect in the DCConnect Client
EMULATOR.INI file.

Format:

Idle_Prompt_Format ( Format )

TIME_ONLY
DATE_TIME
DATE_ONLY

Parameters:

Format - Can be one of TIME_ONLY, DATE_TIME or DATE_ONLY.

Default:

If this command is not included, the idle prompt format is DATE_TIME.

Example:

Specify the idle prompt format include only the time and not the date:

Idle_Prompt_Format ( TIME_ONLY )

IDLE_TIME_FORMAT Command
------------------------
Supported Terminals:

Client 3.0.8f and later

Description:

Determines how the time is displayed on the terminal when the IDLE_PROMPT_FORMAT is set to either TIME_ONLY or DATE_TIME.

Note: for performance reasons, the date and/or time is not actually shown unless the keyword SHOW_IDLE_TIME is in effect in the DCConnect Client
EMULATOR.INI file.

Format:

Idle_Time_Format ( Format )

12_HOUR
24_HOUR

Parameters:

Format - indicates what order the time should be. The choices are 12_HOUR or 24_HOUR.

Default:

If this command is not included, 12_HOUR is the idle time format.

Example:

Specify the idle time format be shown with a 24 hour clock instead of 12 hour:

Idle_Time_Format ( 24_HOUR )

INPUT_TIMEOUT Command
---------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Defines the number of seconds the user has between keystrokes to enter input data at a prompt. You can specify
an INFINITE timeout or choose a specific number of seconds from 1-255. If the user does not press a key or scan
a badge (if allowed) within the given time period, the transaction is cancelled and the timeout message is
displayed. When entering data on the keyboard, the input prompt duration is used as the maximum allowed time
between keystrokes before the transaction is cancelled. Choosing a value of 0 seconds is the same as specifying
INFINITE.

Note: Prompts that are displayed indefinitely are cleared if the user presses the clear key at the terminal,
if a program is started at the terminal that displays a message, if a message is sent to the terminal from
DCConnect or if the terminal receives a time synch command from DCConnect.

Format:

Input_Timeout ( Timeout )

INFINITE
1-255

Parameters:

Timeout - Can be the keyword INFINITE or a number of seconds from 1-255

Default:

If this command is not included, the input timeout is set to 10 seconds.

Example:

Specify the input timeout be 30 seconds:

Input_Timeout ( 30 )

LOCAL_VALIDATION Command
------------------------
Supported Terminals:

Client 3.0.8f and later

Description:

Used to specify a validation file that should be loaded to the terminal. Several
different validation file formats are supported:

- A standard text file contain validation data records, one per line, each ending
with a carriage return / line feed combination.

- A DCConnect generated .VAL file. This is a file that was generated by any of
the following methods:

1) Calling the DCConnect API, DcxSubmitValidationFile

2) Using the sample program Submit.exe

3) Using the Transaction Connection script command Submit_Validation

4) Using the Submit option on a Validatoin object in the DCConnect User Interface.

This .VAL file has a 14 byte header record followed by the data records, each
terminated by a record separator character (0x1e).

- A binary file. A file of this type is transmitted as is.

Note: When the DCConnect Server downloads text script files to the Client, it finds
all the Local_Validation commands to determine what files need to be loaded to
the terminal.

Format:

Local_Validation (XXXX.VAL, Source_file, File_Type [, Record_Length [, Sort_Order]] [, DELETE_UNZIPPED])

TEXT VARIABLE_LENGTH SORTED
DOTVAL 0 RANDOM
BINARY 1-n

Parameters:

XXXXX.VAL - This is the reference validation file name, which must end with .VAL. It is the
name that would be used in an AK, FB, KB, NK, READ, or VRFY command.

Source_file - The name of the source text file that should be loaded to the terminal. This file
must exist on the server in the .\VAL directory where the DCConnect Server is
installed (by default C:\DCCONN\VAL).

File_type - The file type must be one of TEXT, DOTVAL or BINARY (case-insensitive),
indicating which of the file formats, described above, is in use.

Record_length - Optional parameter, used only when the file type is TEXT. It indicates
the record size that each record in the file should be padded (with space) /
truncated to when the file is loaded by the Client. If this parameter is
set to VARIABLE_LENGTH or 0, then no padding / truncation is done when
the file is loaded.

Sort_order - Optional parameter, used only when the file type is TEXT. It should be
set to SORTED or RANDOM. If it is SORTED, that tells the Client it can
do a binary search on the records when performing a validation operation.
But if the parameter is RANDOM, a sequential search must be performed.

DELETE_UNZIPPED - If this keyword is included as the last paramter, it tells the Client to delete
the local uncompressed file after its contents are loaded. This can be useful
if there is data in the uncompressed file that should not be easily visible.

Default:

If this command is not included, no local validation files are loaded by the Client.

Examples:

Download the D2rSamp.val file that was previously submitted to the DCConnect Server:

Validation_File ( D2RSamp.VAL, D2RSamp.VAL, DOTVAL )

Download the text file BADGES.TXT, referred to as BADGES.VAL in transaction program
commands, containing records that are variable length:

Validation_File ( BADGES.VAL, Badges.txt, TEXT )

NON_PROMPT_TIMEOUT Command
--------------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Defines the number of seconds to display a non-prompt message on the terminal before replacing it with the
normal idle prompt. An example would be the "Transaction Accepted" message or "Time is Up" message.

Specify a number of seconds from 1-5 or the keyword DISABLED. If DISABLED (or the value 0) is specified,
this disables the displaying of the "Transaction Accepted" message and tells the terminal to use a value of
3 seconds for all error messages that are shown.

Format:

Non_Prompt_Timeout ( Timeout )

DISABLED
1-5

Parameters:

Timeout - Can be the keyword DISABLED or a number of seconds from 1-5

Default:

If this command is not included, the non-prompt timeout is set to 5 seconds.

Example:

Specify the non-prompt timeout be 3 seconds:

Non_Prompt_Timeout ( 3 )

NUMERIC_DELIMITER Command
-------------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Determines what separator character is allowed as the decimal point when a numeric value is entered by
the user. The possibilities are:

- Only the period is allowed
- Only the comma is allowed
- Both the period and comma are allowed

Format:

Numeric_Delimiter ( Delimiter )

PERIOD
COMMA
BOTH
.
,

Parameters:

Delimiter - Can be any of the keywords PERIOD, COMMA or BOTH or the actual delimiter character: . or ,
But including both the . and , is not allowed; use BOTH if both of these charaters should be
allowed.

Default:

If this command is not included, the numeric delimiter is set to the period character.

Example:

Specify that the comma be the decimal point (numeric delimiter):

Numeric_Delimiter ( COMMA )

Numeric_Delimiter ( , )

RS232_BACK_STRIP_LENGTH
-----------------------
Supported Terminals:

Client 3.0.9a and later

Description:

The number of characters to remove from the end of all incoming RS-232 messages received from a device.

Format:

RS232_Back_Strip_Length ( Length )

0-8

Parameters:

Length - The number of characters to remove from the end of all incoming RS-232 messages. This can be 0 or 1-8 characters.

Default:

If this command is not included, the RS-232 back strip length is 1. (Assuming there is a single terminator character).

Example:

Specify that no characters be stripped from the end of incoming RS-232 messages:

RS232_Back_Strip_Length ( 0 )

RS232_BAUD_RATE
---------------
Supported Terminals:

Client 3.0.9a and later

Description:

The baud rate that the Client should use when communicating with an attached device such as a scale or serial printer. This rate must be set to match the
communications speed of the attached device.

Format:

RS232_Baud_Rate ( Rate )

1200
2400
4800
9600
19200
38400

Parameters:

Rate - The baud rate to use. This can be one of: 1200, 2400, 4800, 9600, 19200 or 38400.

Default:

If this command is not included, the RS-232 baud rate is set to 9600.

Example:

Specify that the baud rate be 38400:

RS232_Baud_Rate ( 38400 )

RS232_DATA_BITS
---------------
Supported Terminals:

Client 3.0.9a and later

Description:

The number of data bits that the Client should use when communicating with an attached device such as a scale or serial printer. The number of
data bits must be set to match the communications setting of the attached device.

Format:

RS232_Data_Bits ( Count )

7
8

Parameters:

Count - The number data bits in each byte being transmitted to and from the target device. This can be set to 7 or 8 data bits.

Default:

If this command is not included, the Client uses 7 data bits.

Example:

Specify that the Client use 8 data bits when communicating with a serially attached device:

RS232_Data_Bits ( 8 )

RS232_FRONT_STRIP_LENGTH
------------------------
Supported Terminals:

Client 3.0.9a and later

Description:

The number of characters to remove from the front of all incoming RS-232 messages received from a device.

Format:

RS232_Front_Strip_Length ( Length )

0-8

Parameters:

Length - The number of characters to remove from the front of all incoming RS-232 messages. This can be 0 or 1-8 characters.

Default:

If this command is not included, the RS-232 front strip length is 0.

Example:

Specify that 2 characters be stripped from the front of all incoming RS-232 messages:

RS232_Front_Strip_Length ( 2 )

RS232_HEADER_STRING
-------------------
Supported Terminals:

Client 3.0.9a and later

Description:

This defines the set of characters to be added to the front of all outgoing messages on the RS-232 port and expected at the front of incoming
messages. This string is stripped from the front of incoming messages before they are received by a transaction program. Each character is
specified by its decimal ASCII value (001-255). Zero is not allowed because that would indicate the end of the string.

Up to eight characters can be included in the header string.

Here is a list of the decimal ASCII values of certain characters

1 Start of heading (SOH) 35 #
2 Start of text (STX) 36 $
3 End of text (ETX) 37 %
4 End of transmission (EOT) 38 &
5 Enquiry (ENQ) 39 ' (Single Quote)
6 Acknowledge (ACK) 40 (
7 Bell (BEL) 41 )
8 Backspace (BS) 42 *
9 Horizontal tab (HT) 43 +
10 Line feed / New Line (LF / NL)) 44 , (Comma)
11 Vertical tab (VT) 45 - (Hyphen)
12 Form Feed / page feed / New Page (FF / PF / NP) 46 . (Period)
13 Carriage return (CR) 47 /
14 Shift out (SO) 48-57 0-9
15 Shift in (condensed) (SI) 59 ; (Semicolon)
16 Data link escape (DLE) 60 <
17 Device control 1 (DC1) 61 =
18 Device control 2 (DC2) 62 >
19 Device control 3 (DC3) 63 ?
20 Device control 4 (DC4) 64 @
21 Negative Acknowledgement (NAK) 65-90 A-Z
22 Synchronize (SYN) 91 [
23 End transmitted block (ETB) 92 \
24 Cancel (CAN) 93 ]
25 End of medium (EM) 94 ^
26 Substitute / End of File (SUB / EOF) 95 _ (Underscore)
27 Escape (ESC) 96 ` (Back quote)
28 File separator (FS) 97-122 a-z
29 Group separator (GS) 123 {
30 Record separator (RS) 124 |
31 Unit separator (US) 125 }
32 Space 126 ~
33 !
34 "

Format:

RS232_Header_String ( Header_String )

Parameters:

Header_String - Up to 8 comma separated numbers, each from 1-255, representing the decimal ASCII value of a character.

Default:

If this command is not included, the RS-232 header string is empty.

Example:

Specify that the Client use a three character header string consisting of ESC STX STX:

RS232_Header_String ( 27, 2, 2 )

RS232_PARITY
------------
Supported Terminals:

Client 3.0.9a and later

Description:

The type of parity that the Client should use when communicating with an attached device such as a scale or serial printer. The parity
must be set to match the communications setting of the attached device.

Format:

RS232_Parity ( Parity_Type )

Odd
Even
None

Parameters:

Parity_Type - The type of parity to use when communicating with the target device. This can be set to Odd, Even or None.

Default:

If this command is not included, the Client uses Odd parity.

Example:

Specify that the Client use Even parity:

RS232_Parity ( Even )

RS232_RETRY_COUNT
-----------------
Supported Terminals:

Client 3.0.9a and later

Description:

The number of times to retry a failed read/write operation on the RS-232 port before the transaction is cancelled.

Format:

RS232_Retry_Count ( Retries )

0-9

Parameters:

Retries - The maximum number of attempts to retry. This can be 0-9.

Default:

If this command is not included, the RS-232 retry count is 3.

Example:

Specify that the RS-232 retry count be 5:

RS232_Retry_Count ( 5 )

RS232_STOP_BITS
---------------
Supported Terminals:

Client 3.0.9a and later

Description:

The number of stop bits that the Client should use when communicating with an attached device such as a scale or serial printer. The number of
stop bits must be set to match the communications setting of the attached device.

Format:

RS232_Stop_Bits ( Count )

1
2

Parameters:

Count - The number stop bits in each byte being transmitted to and from the target device. This can be set to 1 or 2 stop bits.

Default:

If this command is not included, the Client uses 1 stop bit.

Example:

Specify that the Client use 2 stop bits when communicating with a serially attached device:

RS232_Stop_Bits ( 2 )

RS232_TIMEOUT
-------------
Supported Terminals:

Client 3.0.9a and later

Description:

This timeout, in seconds, refers to the time allowed for the last characters to be received once the read of the RS-232 port has started.

Format:

RS232_Timeout ( Timeout )

0, 1-99

Parameters:

Timeout - Either 0 to indicate there should be no timeout or enter a value from 1-99 seconds.

Default:

If this command is not included, the RS-232 timeout is 10 seconds,

Example:

Specify that the RS-232 timeout be 5 seconds:

RS232_Timeout ( 5 )

RS232_TRAILER_STRING
--------------------
Supported Terminals:

Client 3.0.9a and later

Description:

This defines the set of characters to be added to the end of all outgoing messages on the RS-232 port and expected at the end of incoming
messages. This string is stripped from the end of incoming messages before they are received by a transaction program. Each character is
specified by its decimal ASCII value (001-255). Zero is not allowed because that would indicate the end of the string.

Up to eight characters can be included in the trailer string.

Fpr a list of decimal ASCII values for certain characters see RS232_HEADER_STRING.

Format:

RS232_Trailer_String ( Trailer_String )

Parameters:

Trailer_String - Up to 8 comma separated numbers, each from 1-255, representing the decimal ASCII value of a character.

Default:

If this command is not included, the RS-232 trailer string is a single Carriage Return character (13).

Example:

Specify that the Client use a three character trailer string consisting of ESC ETX ETX:

RS232_Trailer_String ( 27, 3, 3 )

RS232_XON_XOFF
--------------
Supported Terminals:

Client 3.0.9a and later

Description:

Indicates whether XON / XOFF flow control should be enabled when the Client communicates with the RS-232 attached device.

Format:

RS232_Xon_Xoff ( Setting )

Enabled
Disabled

0, 1-99

Parameters:

Setting - Set this to either ENABLED or DISABLED

Default:

If this command is not included, XON / XOFF flow control is disabled.

Example:

Specify that XON / XOFF flow control should be enabled:

RS232_Xon_Xoff ( Enabled )

SYSTEM_MESSAGE Command
----------------------
Supported Terminals:

Client 3.0.8f and later

Description:

Defines the text for one of the system messages that the Client might display. These are
the possible system message identifiers:

SYS_MSG_ALLOCATED_MEM_EXCEEDED SYS_MSG_IDLE_MENU_13 SYS_MSG_OUT_OF_SERVICE
SYS_MSG_BAD_QUERY_TYPE SYS_MSG_IDLE_MENU_14 SYS_MSG_PARAMETER_OUT_OF_RANGE
SYS_MSG_BADGE_INVALID_LENGTH SYS_MSG_IDLE_MENU_15 SYS_MSG_PGM_CMD_ERROR
SYS_MSG_BADGE_INVALID_OPERATION SYS_MSG_IDLE_MENU_16 SYS_MSG_POS_AND_LEN_PAST_END
SYS_MSG_BIOS_COM_UNAVAILABLE SYS_MSG_IDLE_MENU_17 SYS_MSG_REMOTE_VAL_IN_PROGRESS
SYS_MSG_BIOS_COM_WRITE SYS_MSG_IDLE_MENU_18 SYS_MSG_RS232_INVALID_LENGTH
SYS_MSG_BUFFER_FULL SYS_MSG_IDLE_MENU_19 SYS_MSG_RS232_MAX_LEN_REACHED
SYS_MSG_CAN_HAVE_1_TO_92_PARMS SYS_MSG_IDLE_PROMPT SYS_MSG_RS232_RETRY
SYS_MSG_CAN_HAVE_1_TO_92_LOCALS SYS_MSG_ILLEGAL_SKIP_ATTEMPTED SYS_MSG_RS232_TIMEOUT_LEN_NO_MATCH
SYS_MSG_CANT_SHOW_NOT_IN_SERVICE SYS_MSG_INVALID_DATA SYS_MSG_RS232_TIMEOUT_NO_END_MSG
SYS_MSG_DIVIDE_BY_ZERO SYS_MSG_INVALID_FIELD SYS_MSG_RS232_TIMEOUT_NO_START_MSG
SYS_MSG_FAST_CLOCK_PROMPT SYS_MSG_INVALID_OPERATION_CHARACTER SYS_MSG_RS232_VARIABLE_NOT_ALLOWED
SYS_MSG_HOST_CMD_ERROR SYS_MSG_INVALID_PGM_CMD SYS_MSG_SET_MODE_MUST_BE_1ST_CMD
SYS_MSG_HOST_DOWN_BUFFERING SYS_MSG_INVALID_PROGRAM_KEY SYS_MSG_STRING_TOO_LONG
SYS_MSG_HOST_TIMEOUT SYS_MSG_INVALID_SOURCE_VARIABLE SYS_MSG_TARGET_CANNOT_BE_SOURCE
SYS_MSG_IDLE_MENU_1 SYS_MSG_INVALID_TARGET_VARIABLE SYS_MSG_TXTN_ACCEPTED
SYS_MSG_IDLE_MENU_2 SYS_MSG_INVALID_VARIABLE SYS_MSG_TXTN_BUFFER_THRESHOLD_HIT
SYS_MSG_IDLE_MENU_3 SYS_MSG_LATCH_KEY_MUST_BE_1ST_CMD SYS_MSG_TXTN_TOO_LONG
SYS_MSG_IDLE_MENU_4 SYS_MSG_LINK_KEY_MUST_BE_1ST_CMD SYS_MSG_VAL_FAILED_EXTENDED
SYS_MSG_IDLE_MENU_5 SYS_MSG_LINK_PROMPT SYS_MSG_VAL_FAILED_FILE_2
SYS_MSG_IDLE_MENU_6 SYS_MSG_LINKED_KEY_CANT_LINK SYS_MSG_VAL_FAILED_FILE_3
SYS_MSG_IDLE_MENU_7 SYS_MSG_MESSAGE_NOT_FOUND SYS_MSG_VAL_FAILED_FILE_4
SYS_MSG_IDLE_MENU_8 SYS_MSG_MISSING_PARENTHESES SYS_MSG_VAL_FAILED_FILE_5
SYS_MSG_IDLE_MENU_9 SYS_MSG_NO_CFR_LOADED SYS_MSG_VAL_FAILED_FILE_6
SYS_MSG_IDLE_MENU_10 SYS_MSG_NOT_HEX_OR_DECIMAL SYS_MSG_VAL_FAILED_FILE_7
SYS_MSG_IDLE_MENU_11 SYS_MSG_ONLY_NUMERIC_DATA_VALID SYS_MSG_VAL_FAILED_REMOTE
SYS_MSG_IDLE_MENU_12 SYS_MSG_OPERATOR_TIMEOUT SYS_MSG_WAITING_FOR_HOST

It is not necessary to define message text for any of these; if no text is defined and the situation occurs in
the Client that would cause one of these messages to be display, the ID show above will be show in the Client.

If the Client will need to support multiple languages at the same time, the SYSTEM_MESSAGE commands can be
included within Start_Language / End_Language blocks for different languages. For more details see
Multiple Language Support.

Format:

System_Message ( System_Message_Identifier, Message_Text )

Parameters:

System_Message_Identifier - One of the message identifier listed above

Message_Text - Up to 40 characters of text enclosed in double quotes.

Default:

For any system message, if it is not defined in the scripts, the text is set to the identifier shown above.

Example:

Define the first 5 lines of the Idle Menu:

System_Message ( SYS_MSG_IDLE_MENU_1, "1. Receiving" )
System_Message ( SYS_MSG_IDLE_MENU_2, "2. Shipping" )
System_Message ( SYS_MSG_IDLE_MENU_3, "3. Manufacturing" )
System_Message ( SYS_MSG_IDLE_MENU_4, "4. Yard" )
System_Message ( SYS_MSG_IDLE_MENU_5, "5. Admin" )

TIME_SEPARATOR Command
----------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Determines what separator character is used between the hour, minute and second if the time is shown as part of
the Idle Prompt.

Format:

Time_Separator ( Separator )

PERIOD
COLON
.
:

Parameters:

Separator - Can be either of the keywords PERIOD or COLON or the actual separator character: . or :

Default:

If this command is not included, the time separator is set to the colon character.

Example:

Specify the time separator to be the period:

Time_Separator ( PERIOD )

Time_Separator ( . )

VALIDATION_TIMEOUT Command
--------------------------
Supported Terminals:

Client 3.0.9a and later

Description:

Defines the number of seconds the terminal will wait for a reply to a remote validation request generated by a
transaction program.

If a response to a remote validation request is not received before the timeout expires, the validation is
considered to have failed and the transaction program will either abort or take the failure path - depending
on the parameters of the transaction program command being executed.

You can specify an INFINITE timeout or choose a specific number of seconds from 1-999.

Format:

Validation_Timeout ( Timeout )

INFINITE
1-999

Parameters:

Timeout - Can be the keyword INFINITE or a number of seconds from 1-999

Default:

If this command is not included, the validation timeout is set to 5 seconds.

Example:

Specify the validation timeout be 30 seconds:

Validation_Timeout ( 30 )

Special Programming Commands
----------------------------
Below are the 'special' commands that can be used in a DCTPB32 script but which
aren't actual transaction program commands as far as the terminal is
concerned:

MAKEPGM Command
---------------
Description:

Defines the name of the output program file.

Format:

MakePgm( filename.PGM )

Parameters:

filename.PGM - Name of the output program file. The file extension should
be .PGM. Optionally the name may be enclosed in double
quotes. The filename can actually be a fully-qualified path
such as:

MakePgm(c:\dcconn\job\time_att.pgm)

You may also use an environment variable in the path. The
environment variable name must be enclosed in percent (%)
signs. For example:

MakePgm(%dcconn%\job\time_att.pgm)

Examples:

Specify the output file to be TIME_ATT.PGM:

MakePGM(TIME_ATT.PGM)

Specify the output file to be TIME_ATT.PGM in the job directory where DCConnect
is installed:

MakePGM(%DCCONN%\JOB\TIME_ATT.PGM)

MESSAGE Command
---------------
Description:

Defines the association between a message name/number and message text. Once
this association has been made, the message name/number can be used in place
of message text in the commands MSG, APND, SEND or SHOW.

Format:

Message( message_id, message_text, message_length )

Parameters:

message_id - Name or number to use in MSG, APND, SEND, and SHOW commands to represent
certain message text.

You may NOT mix named and numbered messages -- the first MESSAGE command
encountered will set the mode.

Certain commands, such as DECLARE, IF, GOSUB/CALL and RETURN, can use
named messages but cannot use numbered messages because the numbers would
be treated simply as numeric constants rather than message numbers.

Names may be up to 64 characters and may not contain commas, spaces,
equals sign (=), tab or new line characters.

The quantity of messages and numbering range varies by device type:
For 7525 terminals: 90 messages, numbers 10-99
For 7526 terminals: 989 messages, numbers 11-999
For 7527 and 7524/Client terminals: 8989 messages, numbers 10-8999.

message_text - The text to associate with the specified message name/number.
The text must be enclosed in double quotes. For 7525 and
7526 programs, the text should not exceed 40 bytes. For
7527 and 7524/Client programs, the text should not exceed
128 bytes.

If a double quote character is needed as part of the
message text, use two consecutive double quotes to
represent each one.

message_length - Specifies the length of the message. This parameter is optional
as of version 3.0.9. This should usually be eliminated or
be set to 0 indicating to get the length from the number of
characters in between the double quotes surrounding the
message text. Only if the message contains imbedded
NULLs do you need to specify the length.

If the Client will need to support multiple languages at the same time, the Message commands can be
included within Start_Language / End_Language blocks for different languages. In this case, message
names must be used for the first parameter; message numbers cannot be used. For more details see
Multiple Language Support.

Example:

Specify the named message MSG_ENTER_BADGE be associated with the text: Enter badge ...

Message( MSG_ENTER_BADGE, "Enter badge ...", 0 )

Specify message 15 be associated with the text: Enter badge ...

Message( 15, "Enter badge ...", 0 )

PROGRAM Command
---------------
Description:

Specifies the start of a transaction program. The name and terminal type
for the program are specified using this command.

Note: Do not use the Program / EndProgram commands when for the DCConnect Client
when it is reading text files directly because the Program command does not
contain key binding information. Use the KEY / EndKey commands instead.

Format:

Program( program_name, terminal_type )
DCT7524 <-- Use this for DCConnect Client too
DCT7525
DCT7526_100
DCT7526_200
DCT7527_1
DCT7527_2

Parameters:

program_name - Up to 32-character program name. The name may optionally
be enclosed in double quotes. All programs in the same
file must have unique names.

terminal_type - Defines which terminal type the program will be used in.
Select one of the names in the list above.

Example:

Specify the start of the Clock_In program for a 7526 model 200 terminal.

Program( Clock_In, DCT7526_200 )

ENDPROGRAM Command
------------------
Description:

Specifies the end of a transaction program.

Note that opening and closing parentheses are required after the ENDPROGRAM
command even though there are no parameters between them.

Format:

EndProgram( )

Parameters:

None

Example:

Specify the end of the Clock_In program for a 7526 model 200 terminal.

EndProgram( )

IMBED Command
-------------
Description:

Imbeds a transaction program or file into the current transaction program.
Unlike other commands, parentheses are not required. This command
incorporates parts of code that are reused and are not suitable for
subroutines. For instance, the handling of a particular input field may be
repeated many times into different transaction programs.

Format:

Imbed( filename.ext )

Parameters:

filename.ext - The name and extension of the file to be imbedded.

The filename can actually be a fully-qualified path such as:

Imbed(c:\dcconn\job\time_att.cod)

You may also use an environment variable in the path. The
environment variable name must be enclosed in percent (%)
signs. For example:

Imbed(%dcconn%\job\time_att.cod)

Example:

Imbed the section of code that reads and validates an employee number -
already saved as readbadg.cod

Imbed ( readbadg.cod )

Imbed the section of code that reads and validates an employee number -
already saved as readbadg.cod - but this time specify that the file be
found in the job directory where DCConnect is installed.

Imbed ( %dcconn%\job\readbadg.cod )

TERMTYPE Command
----------------
Description:

Specifies the terminal type for which all programs in the file will be
created. If you are using the PROGRAM command and you are specifying the
terminal type as the second parameter for each PROGRAM command, do not use
the TERMTYPE command.

If all programs in the file will be for the same terminal type, then use
the TERMTYPE command at the top of the file and do not specify the second
parameter for any PROGRAM command. If using the KEY command to start
programs instead of PROGRAM, then use TERMTYPE to specify the terminal
type to be used for all programs.

The TERMTYPE command is also required when the SUB command is used.
The ENFORCE_BINDINGS command is a required parameter in this case.

If no terminal type is specified, the default is DCT7526_200.

There is an optional second parameter for the TERMTYPE command,
ENFORCE_BINDINGS. If this parameter is used, you must use KEY/ENDKEY
rather than PROGRAM/ENDPROGRAM to start and end your programs. If
bindings are to be enforced, then DCTPB will use the binding information
from the KEY command when resolving branches between programs. It is
therefore imperative that, when using DCConnect, the bindings to programs
be set up exactly as specified in all of your KEY commands.

Use of the ENFORCE_BINDINGS option allows 7527 and 7524/Client programs to
use GOSUB, GOTO, ONKEY and ONSUB commands that branch to a different
transaction program. The DCTPB compiler will convert the labels to the
appropriate step numbers when generating the .PGM file. Without the
ENFORCE_BINDINGS option, 7524/Client and 7527 programs would have to use
explicit step numbers in GOSUB, GOTO, CALL, ONKEY and ONSUB commands that
branch to a different transaction program.

The TERMTYPE command must be used before any PROGRAM, KEY, SUB or MESSAGE
command.

Format:

TERMTYPE( terminal_type, [ ENFORCE_BINDINGS ] )

DCT7524 <-- Use this for DCConnect Client too
DCT7525
DCT7526_100
DCT7526_200
DCT7527_1
DCT7527_2

Parameters:

terminal_type - Defines which terminal type all program in the file will
use. Select one of the names in the list above.

ENFORCE_BINDINGS - This is an optional parameter which, if used, requires
the use of the KEY command rather than the PROGRAM
command. Use this parameter only if all programs in
the file are of the same terminal type and the binding
information in the KEY commands is accurate.

Do not include the square brackets if using this
parameter.

Examples:

Set the terminal type to be for the 7526 model 200 but don't enforce
bindings.

Termtype ( DCT7526_200 )

Set the terminal type to be for the 7524 terminal or terminals running the
DCConnect Client and enforce bindings.

Termtype ( DCT7524, ENFORCE_BINDINGS )

KEY Command
-----------
Description:

Alternate way to specify the start of a transaction program. The binding
and name for the program are specified using this command.

Format:

Key( binding ID, program_name )

F1 - F28, (1-28)
BADGINIT, (29)
*FASTCLK, (30)
*PF1 - PF12, (31-42)
*SPF1 - SPF12, (43-54)
*RS232, RS232_2, (55, 56)
*DI0 - DI7, (57-64)
**RES2 - RES9, (65-72)
**TCH1 - TCH40, (73-112)
**ADDL1 - ADDL8, (113-120)
**TODCLK (121)

(1-29, *30-64, **65-121)

*7525 terminals cannot use binding values greater than 29
**7526 terminals cannot use binding values greater than 64

Note: Even if a particular terminal type does not physically
have a certain type of binding event (e.g. 7526 terminals
do not have PF Keys, 7524/Client terminals do not have touch
points, ...) programs can still be bound to these binding
IDs because those programs can still be accessed using a
GOTO, GOSUB, ONKEY, ONSUB, ... command. These programs
can also be started remotely using the DCConnect API
DcxInitiateTermEvent().

Parameters:

binding ID - The name of the event to which the program will be bound.
Choose a name from the list above. Note: the binding
parameter is ignored unless the optional parameter
ENFORCE_BINDINGS is used with the TERMTYPE command. See
the TERMTYPE command above for more details.

program_name - Up to 32-character program name. The name may optionally
be enclosed in double quotes. All programs in the same
file must have unique names.

Example:

Specify the start of the Clock_Out program and specify that is be bound to
the pressing of the F2 key.

Key( F2, Clock_Out )

ENDKEY Command
--------------
Description:

Specifies the end of a transaction program. It means the same as
ENDPROGRAM.

Note that opening and closing parentheses are required after the ENDKEY
command even though there are no parameters between them.

Format:

EndKey( )

Parameters:

None

Example:

Specify the end of the Clock_In program for a 7526 model 200 terminal.

EndKey( )

NAME_UV Command
---------------
Description:

Starting with version 2.1.0 of DCTPB each global user variable (UV0 - UV19, UV99 or
UV999 depending on terminal type) can be given a name regardless of the terminal
type for which the transaction program is written. Each global user variable can
have one name.

DCTPB already predefines two names for user variable 0:

uvInput
gInput

But one other name may also be given to user variable 0.

For transaction programs that will run on version 2.1.0 of the DCConnect Client,
the return code user variable is given the names:

uvRC
gRC

As with all variable and parameter names, global user variable names are
case insensitive. For example, 'uvTimeout', 'UVTIMEOUT' and 'uvtimeout'
are all considered the same variable.

The user variable name used in any NAME_UV command can only be used in other
commands if those other commands follow the NAME_UV command.

Although you can still use the 'nnn' or 'uvnnn' notation for a user variable
after it has been named, it is recommended that only the user variable name
be used in case at some later point it is decided that the name should be
assigned to a different variable number.

Format:

Name_UV( varNumber, globalVarName )
0-19, UV0-UV19 (7527 terminals)
0-99, UV0-UV99 (7524/Client terminals)
0-999, UV0-UV999 (7526 terminals)
NEXT_UV

Parameters:

varNumber - User variable identifier using the syntax 'nnn' or 'uvnnn',
where 'nnn' is in the range:

0-19 for 7527 terminals
0-99 for 7524/Client terminals
0-999 for 7526 terminals

If you don't want to pick specific user variable numbers
you could instead use the:

NEXT_UV

keyword and DCTPB will assign the next unnamed user variable
number after the one used for the last NAME_UV command.

It is legal for the first NAME_UV command to specify NEXT_UV;
in this case user variable 1 is assigned the specified name.

globalVarName - Name for the global user variable. The name must follow the
Rules for Variable and Parameter Names.

Although not required, it is recommended that each global variable
name start with something like 'g' or 'uv' so that it can be
distinguished from names for parameters and local variables.

Examples:

Give names to user variables used for information that will be set by the
server application, in response to a transaction:

Name_UV (UV80, uvTX_STATUS)
Name_UV (UV81, uvTX_RESULT1)
Name_UV (UV82, uvTX_RESULT2)
Name_UV (UV83, uvTX_RESULT3)
Name_UV (UV84, uvTX_RESULT4)
Name_UV (UV85, uvTX_RESULT5)
Name_UV (UV86, uvTX_RESULT6)
Name_UV (UV87, uvTX_RESULT7)
Name_UV (UV88, uvTX_RESULT8)
Name_UV (UV88, uvTX_RESULT9)

Name the next user variable, which will be used to store a global timeout value.
If this follows the Name_UV commands in the previous example, UV89 will be
assigned to uvTimeout.

Name_UV ( NEXT_UV, uvTimeout )

SUB Command
-----------
Description:

New with version 2.1.0 of DCTPB, for transaction programs running on
version 2.1.0 or later of the DCConnect Client, is a way to define
the boundaries of a subroutine. This must be used if the subroutine
is to be passed any parameters or is to declare any local variables.

The syntax of the SUB command is different from most other commands in
that the opening parenthesis does not immediately follow the word SUB.
Instead, following the SUB keyword and some white space is the bindingID
indicating to which transaction program the subroutine is to be associated.
Following the binding ID must be a colon and then the SubroutineName
which is in effect a label. After the SubroutineName must be opening and
closing parentheses containing any parameters that are defined for the
subroutine. The parentheses are required even if there are no parameters
for this subroutine.

Up to 92 parameters may be declared for each subroutine. The parameter
names must follow the Rules for Variable and Parameter Names.

Up to 92 local variables may also be declared for the subroutine. For
more information about local variable please see the DECLARE command.

Because the subroutine name is like a label, all subroutines that are
assigned to the same transaction program must have unique names from
all the other subroutines for that transaction program and from any
label used in any of those subroutines or in the transaction program
itself (if it is defined).

While a GOSUB command can be used to call the subroutine, it is
recommended that the new CALL command be used instead because
its syntax is a better match for the syntax of the SUB command.

For more information see Subroutines.

Note: In order to use this SUB command, the keyword ENFORCE_BINDINGS
must be used on the TERMTYPE command.

Format:

SUB bindingID: SubroutineName (pParameter1, ... )
F1 - F28, (1-28)
BADGINIT, (29)
FASTCLK, (30)
PF1 - PF12, (31-42)
SPF1 - SPF12, (43-54)
RS232, (55)
RS232_2, (56)
DI0 - DI7, (57-64)
RES2 - RES9, (65-72)
TCH1 - TCH40, (73-112)
ADDL1 - ADDL8, (113-120)
TODCLK (121)
1-121

Parameters:

binding ID - The name of the event to which the subroutine will be bound.
Choose a name from the list above. You must use the
ENFORCE_BINDINGS parameter on the TERMTYPE command in order
for DCTPB to properly resolve calls to this subroutine that
are made from transaction programs and subroutines that are
bound to other binding IDs.

A colon must separate the 'binding ID' and the 'SubroutineName'.
However, that colon may be surrounded by spaces if desired.

SubroutineName - Because SubroutineNames are in effect labels, the rules
for creating them are them same as for labels. Subroutine
names are case insensitive, may contain the characters A-Z,
a-z, 0-9 and space and may be up to 30 characters in length.

Because DCTPB converts labels to 3-digit step numbers for
the DCConnect Client, you should not use labels that can be
interpreted as a step number in the range 1-999; DCTPB will
treat them as that step number instead of a label. For
example, "1", "01", "001" and "999" will all be interpreted
as step numbers by DCTPB rather than a label.

pParameter1, ... In between the parentheses can be one or more parameters, up
to 92 of them, for passing information to and from the
subroutine. The enclosing parentheses are required even if
there are no parameters.

Parameter names must follow the Rules for Variable and Parameter Names.

Although not required, it is recommended that each parameter
name start with a 'p' so that it can be distinguished from
names for local and global variables.

When a subroutine is called, the parameters passed to the
subroutine will be one of several possibilities:

Regardless of how it is passed the subroutine can both
read and change the contents of the source. However, when
text or a numeric constant is passed, that data is stored
in a temporary location in the memory pool. In that way,
the original text or numeric constant is not changed. It
follows that the caller will not see any changes made by
the subroutine to parameters that are passed as text or
numeric constants.

Conversely, any changes made by the subroutine to variables,
parameters, PF strings or Touch strings that were passed in
will remain in effect for the caller when the subroutine
returns. So be aware of side-effects that could result by
calls to subroutines that change the contents of their
parameters.

It is legal for the caller of a subroutine to pass fewer
parameters to the subroutine than are actually defined.
This is useful for creating subroutines that perform
operations on multiple items where the number of items
might vary from call to call. Examples might be:
appending pieces of data together or adding multiple
values together.

When the possibility exists that not all callers of
a subroutine will pass all the parameters, the subroutine
must use the TEST command for any optional parameter
in order to determine if it contains data. A runtime
error will result if any other command tries to use
a subroutine parameter for which no value was passed.
The following logic can be used to check whether a
variable parameter has data:

// TEST skips the next command if the target has data
TEST (pSomeParameter)
GOTO (THIS_PROGRAM, SkipUseOfParameter)

// One or more commands that use the optional parameter

LABEL (SkipUseOfParameter)

The second example below illustrates the use of
optional parameters.

Examples:

Specify the start of a subroutine called Add3Values which is to be
associated with binding ID ADDL1 and which takes 3 parameters: pAddend1,
pAddend2 and pAddend3. (The sum is to be returned via the return code
variable).

SUB ADDL1:Add3Values ( pAddend1, pAddend2, pAddend3 )

SET (uvRC, pAddend1)
MATH (uvRC += pAddend2)
MATH (uvRC += pAddend3)

RETURN (uvRC)

ENDSUB()

Now create a similar subroutine that can add anywhere from 2 to
10 different values together. In this case the first two parameters are
required.

SUB ADDL1:AddValues ( pAddend1, pAddend2, pAddend3, pAddend4, pAddend5,
pAddend6, pAddend7, pAddend8, pAddend9, pAddend10 )

SET (uvRC, pAddend1)
MATH (uvRC += pAddend2)

// If pAddend3 contains data, the GOTO is skipped and the MATH command is performed
TEST (pAddend3)
GOTO (THIS_PROGRAM, AddValues_Done)
MATH (uvRC += pAddend3)

TEST (pAddend4)
GOTO (THIS_PROGRAM, AddValues_Done)
MATH (uvRC += pAddend4)

TEST (pAddend5)
GOTO (THIS_PROGRAM, AddValues_Done)
MATH (uvRC += pAddend5)

TEST (pAddend6)
GOTO (THIS_PROGRAM, AddValues_Done)
MATH (uvRC += pAddend6)

TEST (pAddend7)
GOTO (THIS_PROGRAM, AddValues_Done)
MATH (uvRC += pAddend7)

TEST (pAddend8)
GOTO (THIS_PROGRAM, AddValues_Done)
MATH (uvRC += pAddend8)

TEST (pAddend9)
GOTO (THIS_PROGRAM, AddValues_Done)
MATH (uvRC += pAddend9)

TEST (pAddend10)
GOTO (THIS_PROGRAM, AddValues_Done)
MATH (uvRC += pAddend10)

LABEL (AddValues_Done)

RETURN (uvRC)

ENDSUB()

ENDSUB Command
--------------
Description:

Specifies the end of a subroutine.

Note that opening and closing parentheses are required after the ENDSUB
command even though there are no parameters between them.

For more information about subroutines, please see Subroutines.

Format:

EndSub()

Parameters:

None

Examples:

For examples of complete subroutine definitions, including the ENDSUB
command, see the examples for the SUB command.

Start_Language Command
----------------------
Supported Terminals:

Client 3.0.8f and later, text scripts only (DCTPB compile will give error for this command)

Description:

Specifies the start of a language block which contains Message and / or
System_Message commands.

For a discussion of language blocks and multiple language support, please
see Multiple Language Support.

This command is only valid for the DCConnect Client 3.0.8f and later when it is
using the SCRIPT_NAME parameter to load text script flies directly.

Format:

Start_Language ( Language_Identifier )

Parameters:

Language_Identifier - Any text name for the language - such as English, Spanish, French, ...
When a Set_Language command is used in a transaction program, its
language_identifier parameter must match the language_identifier parameter
in one of the Start_Language command.

Examples:

For examples of Start_Language / End_Language blocks, see Multiple Language Support.

End_Language Command
--------------------
Supported Terminals:

Client 3.0.8f and later, text scripts only (DCTPB compile will give error for this command)

Description:

Specifies the end of a language block which contains Message and / or
System_Message commands.

For a discussion of language blocks and multiple language support, please
see Multiple Language Support.

This command is only valid for the DCConnect Client 3.0.8f and later when it is
using the SCRIPT_NAME parameter to load text script flies directly.

Format:

End_Language ()

Parameters:

None

Examples:

For examples of Start_Language / End_Language blocks, see Multiple Language Support.

Transaction Programming commands
--------------------------------
This section lists and describes the transaction program commands for the
IBM 7524, IBM 7525, IBM 7526, IBM 7527 DCTs and terminals running the
DCConnect Client (also considered to be type DCT7524 by DCTPB). When working
with terminal user-variables (not supported by the 7525 DCT), user-variable 0
contains the last data read from an input device such as the keyboard or wand
port. Each new read overlays this data.

Immediately following each command heading in this section is an indicator to
show which terminals support the subject command. If the command is supported,
but is restricted for a particular device in any way, this restriction is noted
in the text description.

Every parameter on each command must be filled in. If you wish to skip a
parameter, there are choices such as, "DONT_USE" or "NONE" available.

For each command, the format is given The first line of the format shows the
command structure. Below each field are permitted values. Uppercase
indicates a value that must be entered exactly as displayed.

AK Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

Read a fixed number of characters from the alpha-numeric keypad. AK
positions the cursor on the terminal display prior to reading data. For
the 7524/Client, 7527 and the 7526 DCT's, the value read becomes the value
of the last read variable (VAR 0) and becomes part of the transaction record,
unless automatic transaction building has been turned off. For the 7525
DCTs, the value read is added to the transaction record.

Format:

AK ( data_length, validation_file, validation_type, autofill, position, display_buffer )
(1 - 40) (filename.VAL) ABORT_IF_PRESENT NO_AUTOFILL (1-40) NO_DISPLAY_DATA
NO_VALIDATION ABORT_IF_ABSENT AUTOFILL DONT_USE DISPLAY_DATA
SKIP_IF_PRESENT DONT_USE DONT_USE
SKIP_IF_ABSENT
NONE

Parameters:

data length - The number of characters to be read from the alpha-numeric
keypad. The length specified must be in the range 1-40.

validation_file - The name of the validation file to be used to validate the
input data.

validation_type - The action to be taken on the transaction as the result of
validating the input data.

autofill - Determines whether the field will be padded with blanks to
it's maximum size as determined by the data_length
parameter.

position - The column on the display where the input field starts.
An entry of 0 right justifies the input field on a
40-column display. The column specified must be in the
range 1-40.

display_buffer - Determines whether or not the data read from the input
device is displayed on the terminal's display as it is
read.

Example:

Read 10 characters starting at column 30 and verify them for presence in
file PIN.VAL. Do not display the data on the terminal display.

AK (10, "pin.val", ABORT_IF_ABSENT, DONT_USE, 30, NO_DISPLAY_DATA )

AKA Command
-----------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Changes the transaction ID returned with the transaction when it is sent to
the system unit and is valid only on the 7526, 7527, and 7524/Client
terminals. The user may specify any transaction ID from 1-255. This allows
the transaction program to appear to the system unit to have been initiated
by another transaction program. This is particularly useful when using the
7526 Model 100 that has only four keys.

Note: Prior to encountering an AKA command in a transaction program, the
transaction program ID can be changed by a GOTO, ONKEY, or any other command
that causes a branch to another transaction program. The transaction program
ID becomes that of the target program. As soon as an AKA command is
encountered all subsequent GOTO, ONKEY, or similar commands no longer affect
the transaction ID.

Note: The alias key id does not need to be physically present on the DCT to
be used for sending data to the host.

Format:

AKA ( transaction_id )

F1 - F28, (1-28)
BADGINIT, (29)
FASTCLK, (30)
PF1 - PF12, (31-42)
SPF1 - SPF12, (43-54)
RS232, RS232_2, (55,56)
DI0 - DI7, (57-64)
RES2 - RES9, (65-72)
TCH1 - TCH40, (73-112)
ADDL1 - ADDL8, (113-120)
TODCLK (121)
(1-255)
++Variable/Parameter

Note: Although the range of valid IDs to bind a transaction program is
less than 1-255 the transaction ID can be set to any of the above
IDs for any terminal type that supports this command.

++ Only valid for DCConnect Client version 2.1.0 or later

Parameters:

transaction id - The transaction ID that is to be sent back with the
transaction to the system unit.

New in version 2.1.0, for transaction programs that
will run on version 2.1.0 of the DCConnect Client
or later, is the ability to specify a variable (global,
local or return code) or parameter instead of a
one of the transaction IDs or numbers listed above.

At runtime, the variable or parameter must contain
a numeric value from 1 to 255 or the transaction
program will abort. The numeric value must be an
integer or (as of version 2.2.0a of the DCConnect Client)
if the value contains a decimal point, all digits after
the decimal point must be 0.

Examples:

Change the transaction ID for this transaction to DI0 (value of 57).

AKA ( DI0 )

Change the transaction ID based on the value in the parameter named pTxID.

AKA ( pTXID )

APND Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

This command enables the user to append a string to the end of a given user-
variable or to the end of the transaction buffer. For the 7524/Client or
7527, a string can be appended to the end of a PF key, shifted PF key, or
touch string.

For the 7524/Client or 7527, as a special use of this command, it is possible
to build up messages to send to the printer (7527 only) or to the RS-232 port.
This command may be used to redefine the macro strings attached to the PF
keys, shifted PF keys or Touch points. If a PF key or Touch point string
definition is changed during a transaction program, upon completion of the
transaction program the string definition returns to the value it had prior
to the start of the transaction program.

If your transaction program type is DCT7524 and your 7524/Client terminals
have a flash/program version later than 1.10, you have additional options to
qualify which part of the source data should be appended. The source may be
qualified as either a position and length or as a field number and delimiter
character.

Format:

APND ( target, source_name, source_record_number , source_field_type, position/field #, length/delimiter)
UV1 - UV998 SRC_MESSAGE_FILE... "any text message" SOURCE_POSITION, 1-999 ALL_DATA, 1-999
PF1 - PF12 MESSAGE number/name
SPF1 - PSF12 SRC_USER_VARIABLE.. UV0 - UV998 SOURCE_FIELD 1-999 ASCII_SEMICOLON
TOUCH1-TOUCH40 ++Variable/Parameter ASCII_SPACE
TRANSACTION_RECORD SRC_TRANS_RECORD... TRANSACTION_RECORD 0-255
Named Variable SRC_OTHER.......... PF1-PF12, TOUCH1-TOUCH40
++Local Variable Named Variable
++Parameter ++Local Variable ++Variable/Parameter
++uvRC, gRC ++Parameter
++uvRC, gRC

++ Only valid for DCConnect Client version 2.1.0 or later

Parameters:

Target - The target string to which data is to be appended.
For the 7526, it may be any of the 998 user-variables
(VAR 1-998) or the transaction buffer. For the
7524/Client or 7527, it may be any of the 19
user-variables (VAR 1-19), the transaction buffer,
any of the 24 PF key strings (PF 1-12, Shifted PF 1-12),
or any of the 40 Touch point strings (TOUCH 1-40 for
7527 Model 002 only).

7524/Client terminals with flash/program level later
than 1.10 have a maximum user-variable of 99 instead
of 19.

For the 7526, the target string may grow to a
maximum length of 999 characters if it is a user-
variable or 108 for the transaction buffer. For the
7524/Client or 7527, the target string may grow to a
maximum length of 128 characters if it is a
user-variable, 104 for the transaction buffer, or to
128 characters for a PF or Touch point string.

New with DCTPB 2.1.0, for transaction programs that
will run on version 2.1.0 of the DCConnect Client, the
target can also be a local variable, parameter or the
return code variable.

source_name - This parameter is optional as of version 2.1.0 of DCTPB.
In fact it should be omitted if the source is a local
user variable, parameter or the return code variable.

If it is included, choose one of the following values:

- SRC_MESSAGE_FILE - The source_record_number
specifies a message (text, number or name).

- SRC_USER_VARIABLE - The source_record_number is
a global user variable.

- SRC_TRANS_RECORD - The source_record_number
specifies the transaction record.

- SRC_OTHER - The source_record_number specifies
either a PF string or a touch string.

source_record_number - If the source is a message this can be an inline
message enclosed in double quotes or it is a message
name/number defined in one of the MESSAGE commands.
Messages are allowed for all supported terminal types.

If the source is a user variable this should specify
one ov UV0 through UVmax where 'max' is 998 for 7526
terminals, 19 for 7527 terminals and 7524/Client
terminals with flash/program level prior to 1.11.
For 7524/Client terminals with flash/program level
after 1.10, up to UV99 may be specified.

If the source is the transaction buffer, specify
TRANSACTION_RECORD. The transaction buffer is a
valid option for all supported terminal types.

For 7527 and 7524/Client terminals, the source may
be one of the PF strings (PF1 - PF12) or one of the
touch strings (TOUCH1 - TOUCH40).

New with DCTPB 2.1.0, for transaction programs that
will run on version 2.1.0 of the DCConnect Client, the
source can also be a local variable, parameter or the
return code variable.

source_field_type - Optional parameter indicating which part of the source
should be appended. The part may be specified as a
field or as a position/length pair. For this
parameter, use either the keyword SOURCE_POSITION or
SOURCE_FIELD. The next two parameters further
define each choice.

If this and the following parameters are not
included, all data starting at position 1 will be
appended.

position/field# - If you selected SOURCE_POSITION for the previous
parameter, this value is a number from 1 to 999
indicating the starting position. The first byte is
position 1.

An error will occur at the terminal if a position
is specified past the end of the available data -
unless position 1 is specified and ALL_DATA is
specified for the length.

If you selected SOURCE_FIELD for the previous
parameter, this value is a number from 1 to 999
indicating the field number. The first field is
field 1.

Fields are delimited by the character specified
in the next parameter. This character must be at
the end of each field - including the last field in
the data. Two consecutive delimiter characters
results in a field that is 0 length - which is valid.

An error will occur at the terminal if a field
number is specified and the available data does not
contain that many fields.

The variable/parameter must contain an integer
value or (as of version 2.2.0a of the DCConnect Client)
if the value contains a decimal point, all digits after
the decimal point must be 0.

The same errors described above can result in the
terminal at runtime if the variable/parameter
does not have a valid value.

length/delimiter - If you selected SOURCE_POSITION for the source
field type, this value is a number from 1 to 999
indicating the length of the data to take. The
keyword ALL_DATA may also be used to indicate that
all data be taken, no matter how long or short,
starting at the previously specified position.

An error will occur at the terminal if the length
specified goes past the end of the data available
in the source. It is not an error if ALL_DATA is
specified as long as the starting position is in
the available data.

The variable/parameter must contain an integer
value or (as of version 2.2.0a of the DCConnect Client)
if the value contains a decimal point, all digits after
the decimal point must be 0.

The same errors described above can result in the
terminal at runtime if the variable/parameter
does not have a value from 0-999. A value of 0
is equivalent to the ALL_DATA keyword.

If you selected SOURCE_FIELD for the source field
type, this parameter indicates a delimiter character
that marks the end of every field in the source data.
All fields must end with the specified delimiter
character - including the last field in the data.
It is not an error if a field is specified that
has a length of 0. This kind of field has two
delimiter characters in a row in the data - the one
ending the field itself and the one ending the
prior field.

When the data from a field is appended, the
delimiter character is not appended.

The delimiter character parameter is specified as
a value from 0-255 indicating the ASCII value of
the character or it is specified as the actual
character enclosed in single or double quotes. The
following keywords are also allowed:

ASCII_SPACE
ASCII_ZERO
ASCII_SEMICOLON

New in version 2.1.0 of the Client and DCTPB is the
ability to specify a variable (global, local or return
code) or parameter instead of a numeric value or one of
the keywords above.

At runtime, the variable or parameter must contain a numeric
value from 0 to 255 or the transaction program will abort.

Examples:

Append the text message "unidentified error" to the transaction record.

APND ( TRANSACTION_RECORD, SRC_MESSAGE_FILE, "unidentified error" )

Append the contents of user-variable 3 to user-variable 2

APND ( UV2, SRC_USER_VARIABLE, UV3 )

Append field 4 of user-variable 3 to user-variable 2. The delimiter
character is a semicolon

APND ( UV2, SRC_USER_VARIABLE, UV3, SOURCE_FIELD, 4, ASCII_SEMICOLON)

Append all data starting at position 10 of the transaction record to
user-variable 9.

APND ( UV9, SRC_TRANS_RECORD, TRANSACTION_RECORD, SOURCE_POSITION, 10, ALL_DATA)

Same as the previous command but without the second parameter:

APND ( UV9, TRANSACTION_RECORD, SOURCE_POSITION, 10, ALL_DATA)

Same as the previous command, but use the local variable lStartPosition
for the 'position' parameter:

APND ( UV9, TRANSACTION_RECORD, SOURCE_POSITION, lStartPosition, ALL_DATA)

APNDSTR Command
---------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Append a fixed, inline text string to a terminal variable or parameter.

Format:

APNDSTR ( target, string_len, text )
(UV1 - UV19) (0, 1-999) "any text string"
(UV1 - UV998)* series of ASCII values in hex
(UV1 - UV99)** numeric constant
Named Variable
++Local Variable
++Parameter
++uvRC, gRC

* 7526 only
** 7524/Client with flash/program level later than 1.10
++ DCConnect Client version 2.1.0 or later

Parameters:

target - The terminal user-variable to which the text is appended.
On the 7526 it may be one of the 998 user-variables. For
the 7524/Client or 7527, it may be any of the 19 user-
variables (VAR 1-19).

7524/Client terminals with flash/program level later than
1.10 have a maximum user-variable of 99 instead of 19.

New with DCTPB 2.1.0, for transaction programs that will
run on version 2.1.0 of the DCConnect Client, the target
can also be a local variable, parameter or the return
code variable.

string_len - This parameter is optional as of version 2.1.0 of DCTPB.

If it is included, it specifies the length of the string
to be appended to the target user-variable. You can use
0 for the length to indicate that the exact length of
the 'text' parameter be used. But you might as well
eliminate this parameter altogether.

any text string - The character string, enclosed within double quotes, to be
appended to the user-variable. For every double quote
character that must be part of the actual text, you must
enter two double quotes in a row in the text. The
maximum length is 999 characters.

series of ASCII
values in hex - As an alternative to a text string, you may specify one
or more ASCII values in hex, each preceded by a backslash.
For example, to append the carriage return (0x0d) and
line feed (0x0a) characters to UV1, use the command:

APNDSTR ( UV1, 0, \0d\0a )

There can be whitespace before each backslash. For example:

APNDSTR ( UV1, 0, \0d \0a )

If double quotes surround the series of ASCII values, DCTPB
will not convert the characters in the string.

Note: The ASCII value \00 (null character) should not be
appended to a user variable because many operations
involving user variables assume the user variable
data is null terminated.

numeric
constant - As of version 2.1.0 of DCTPB, if the first character of
the 'text' parameter is a number, then DCTPB accepts it
all not worrying about the enclosing double quotes. If
the numeric constant was enclosed in double quotes, the
result would be the same.

Examples:

Append the text string "unknown error" to user-variable 1.

APNDSTR ( UV1, 13, "unknown error" )

or just:

APNDSTR ( UV1, 0, "unknown error" )

Append the following string to user variable 12: The boss said "Go home".

APNDSTR ( UV12, 0, "The boss said ""Go home""." )

Append the STX character to UV31.

APNDSTR ( UV31, 0, \02 )

Append the number 100 to UV50 (and don't use the length parameter)

APNDSTR (UV50, 100)

Append the string "Error" to the return code user variable.

APNDSTR (uvRC, "Error")

AUTO Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

This command permits the user to take control of the transaction building
function. If this command is not specified, the data returned by every read
operation in the transaction program is automatically appended to the
transaction buffer, and when the transaction completes, the transaction
buffer is sent to the transaction queue where it can be polled by the host.
When AUTO is set OFF, data read is not automatically appended to the
transaction buffer. If it is required as part of the translation then you
append it yourself. For the 7524/Client, 7526, and 7527, this is a useful
feature if, for example, it is desirable to read data from a sensor device
and print it without ever having it sent to the system unit, or to perform a
formatting operation on the data before placing it in the transaction. For
additional information, see the FRMT command.

At the conclusion of the transaction processing, a setting of OFF causes no
transaction to be written to the system unit. The SEND command allows
sending the transaction to the system unit. This provides the option of
having processing remain purely local to the terminal.

The last setting of AUTO remains in effect until the transaction ends or
another AUTO command is encountered that changes it.

AUTOTRANS_ON - Appends the data returned by every read operation to the
transaction buffer. When the transaction completes, the transaction buffer
is sent to the transaction queue where it can be polled by the host.

AUTOTRANS_OFF - The user must append the data to the transaction buffer and
SEND it, unless AUTO is turned on again before the end of the transaction
program. Otherwise, no transaction is saved when the transaction program
completes.

Format:

AUTO ( mode )
AUTOTRANS_OFF
AUTOTRANS_ON

Parameters:

mode - The setting of the automatic transaction build feature. The default is
to set automatic transaction building ON. This feature is
automatically turned on at the beginning of every transaction.

Example:

Turn off automatic transaction building.

AUTO ( AUTOTRANS_OFF )

Block Commands { and }
----------------------
Supported Terminals:

DCConnect Client version 2.2.0 or later

Description:

The opening { and closing } braces are used in conjunction with the 'If',
'Else' (and 'ElseIf') commands to delineate a block of commands that should
be executed or not executed based on the result of an If command being
evaluated.

For more information, please see the IF Command, ELSE Command,
and Transaction Program Control Using If/Else Commands.

BNAV Command
------------
Supported Terminals:

7527

Description:

This command indicates the beginning of a screen navigation group. This
group must be ended with an ENAV command.

Four commands specify field navigation regions within a transaction program;
BNAV, NAV, INAV and ENAV. These commands are used in conjunction with the
READ command. Each command in this group cannot be used without the other
commands.

Navigation groups always begin with BNAV command and end with an ENAV
command. Up to 10 regions may be defined within these two commands. In
addition, multiple groups of field navigation commands may be contained
within a single transaction program.

The navigation regions may be selected on the 7527 terminal as follows:

Previous field - The reverse tab key above the "1" key

Next Field - The forward key above the "3" key

Enter - Moves the same as the Next Field key

The input field is defined with the following sequence of commands: NAV,
INAV, READ. NAV specifies the row and column where input is to take place,
INAV waits for input data, and READ reads the input data.

Format:

BNAV ( )

Parameters:

none

Example:

Start a navigation region.

BNAV ( )

BOX Command
-----------
Supported Terminals:

7527

Description:

Draw a box on the 7527 screen. Enables framing certain regions of the 7527
screen for clarity.

Format:

BOX ( row, column, width, height )
CURRENT_ROW CURRENT_COLUMN (1-320) (1-200)
(1-200) (1-320)

Parameters:

row - The row on the terminal display to begin drawing. The row number
corresponds to a pixel row, a terminal display is 200 x 320 pixels.
Row 1 is the upper right row of a screen.

column - The column on the terminal display to begin drawing. Column 1 is
the left most column of a screen.

width - The width of the box expressed in pixel rows. The total of column
plus width must not exceed 320.

height - The height of the box expressed in pixels. The row plus height must
not exceed 200.

Example:

Draw a box which frames the screen with a 4 pixel border on all sides

BOX ( 5, 5, 310, 190 )

BRAUV Command
-------------
Supported Terminals:

7526

Description:

Compare two user-variables, then branch to a program label based on the
results of the compare. If the comparison is true, control branches to
label. Otherwise, the step after the BRAUV command is executed.

Format:

BRAUV ( source, operator, test_uv, program ID, label )
(0-998) LT (0-998) ABORT_PROGRAM "label_name"
UV0-UV998 GT UV0-UV998 THIS_PROGRAM
LE F1-F28, (1-28)
GE BADGINIT, (29)
EQ FASTCLK, (30)
NE PF1-PF12 (31-42)
SPF1-SPF12 (43-54)
RS232, (55)
RS232_2 (56)
DI0-DI7, (57-64)
(1-64)
Parameters:

source - The user-variable that is compared

operator - The compare operator for comparing two user-variables.
Operators are defined as follows:

LT - less than
GT - greater than
LE - less than or equal to
GE - greater than or equal to
EQ - equal to
NE - not equal to

test_uv - The second user-variable used for comparison

program ID - Defines the transaction program to which execution will
transfer. This may be the same program that is currently
executing or a different one. Valid programs are the ones
with ID values in the range 1-64.

A value of ABORT_PROGRAM indicates that the program should
be aborted.

Note: END_OF_PROGRAM is also a valid value for this
parameter and it is synonymous with ABORT_PROGRAM.
However, ABORT_PROGRAM is a better term to use
because it more accurately describes what will
happen.

A value of THIS_PROGRAM indicates execution should stay
within the currently executing program.

label - Defines the step within the specified transaction program
to which execution should be transferred. The label is a
1-30 character user defined name given to a program step.
The label is not tied to a step number and is independent of
command insertion/deletion. (Although when DCTPB compiles
7527 and 7524/Client transaction programs, it converts
labels to step numbers).

For 7526 terminals, only the first 15 characters of the
label are considered significant. Therefore all labels used
in the same 7526 transaction program must be unique in their
first 15 characters.

Example:

Compare the contents of UV1 with UV2. If UV2 is greater than UV1, branch to
the Next_Issue label in the program assigned to F3 (program number 3).

BRAUV ( UV2, GT, UV1, 3, "Next_Issue" )

CALL Command
------------
Supported Terminals:

DCConnect Client version 2.1.0 or later

Description:

Allows transaction programs to transfer control to a subroutine and after
that subroutine completes (by issuing a RETURN command) control returns to
the command following the CALL command. The start of the subroutine is
defined either as a LABEL or using the SUB command. The latter is the
recommended method and is the required method if the subroutine is to be
passed any parameters or is to have its own local variables.

Subroutines are useful for keeping in one place a set of transaction program
commands that will be used by many different transaction programs. For
example, if several different transaction programs needed to prompt the
terminal user for a badge number and product number and then validate those
values, the steps to accomplish those activities could be put into a
subroutine. Then each transaction program that needed to perform those
activities would simply use the CALL command to call that subroutine rather
than having each program repeat those steps.

The use of subroutines can reduce the amount of terminal memory that is
consumed by the transaction programs.

For more information about subroutines please see Subroutines.

Format:

CALL binding ID: SubroutineName (Parameter1, ... )
F1 - F28, (1-28) UV0-UV99
BADGINIT, (29) Named Variable
FASTCLK, (30) Local Variable
PF1 - PF12, (31-42) Parameter
SPF1 - SPF12, (43-54) uvRC, gRC
RS232, RS232_2, (55,56) PF1-PF12
DI0 - DI7, (57-64) TOUCH1-TOUCH40
RES2 - RES9, (65-72) numeric constant
TCH1 - TCH40, (73-112) "text"
ADDL1 - ADDL8, (113-120) Named message
TODCLK (121)

(1-121)

Note: Even though terminals running the DCConnect Client cannot
actually start a transaction program using all of triggers
associated with the binding IDs listed above (e.g. touch points),
subroutines can still be bound to these binding IDs and
therefore the CALL command can still call subroutines that
are bound to those IDs.

Parameters:

binding ID - Defines the transaction program to which the specified
SubroutineName is bound. The binding ID and SubroutineName
combination used here should match those that are used in
the SUB command that defines the target
subroutine.

Note: Although ABORT_PROGRAM, END_OF_PROGRAM and THIS_PROGRAM
will not result in a compile error, if the CALL command
is only used to call subroutines that are defined with
the SUB command, these other keywords would never be used.

SubroutineName - This is a SubroutineName that was specified in the
SUB command that defines the target
subroutine.

Parameter1, ... - One or more parameters may be passed to the subroutine -
provided that subroutine was defined using the SUB command
and the subroutine definition includes parameters.

When passing parameters to a subroutine, each parameter
may be of any of the following types:

- Named or unnamed global user variable
- Local variable of the caller's subroutine or transaction
program.
- The return code user variable
- Parameter passed to the caller, if the caller is a subroutine
- PF Key string
- Touch Point string
- Numeric constant
- Text enclosed in double quotes
- Named message (note that a message number cannot be used
because it would simply be treated as a numeric constant
rather than a message number).

For text enclosed in double quotes and numeric constants, the
DCConnect Client actually allocated temporary storage from its
memory pool to store the text/constant as if it was a variable.
This allows the subroutine to make changes to the parameter
that is associated with that text/constant without an error
occurring. But the caller of the subroutine will not see
those changes.

It is legal for the CALL command pass fewer parameters to
the subroutine than are actually defined. Please refer to
the discussion of the parameters for the SUB command for
more information about this capability.

The compiler will generate an error if the CALL command
includes more parameters than the subroutine definition.

Example:

Call the subroutine ADDL1:AddValues and pass it 5 values. See the examples
for the SUB command for the definition of this subroutine.

CALL ADDL1:AddValues (lTotalsMon, lTotalsTue, lTotalsWed, lTotalsThu, lTotalsFri )

CLRS ()
SHOW ("Totals for the week: ", 1, 1, NORMAL)
FRMT (uvRC, CUSTOM_INTEGER, "%d" )
SHOW (uvRC, CURRENT_ROW, CURRENT_COLUMN, NORMAL)

Call the same subroutine to add three constants:

CALL ADDL1:AddValues ( 1234, 5678, 9101112 )

Call the subroutine AskYesNo which is bound to ADDL2 and which takes no parameters:

Call ADDL2: AskYesNo ()

CCFR Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Provides a method to call a CFR user-defined routine that has been downloaded
to the terminal. This command is valid for the 7526, 7524/Client, and 7527.

For example, you may want to create your own validation routines that can
then be called by this transaction program command. The name of the .EXE
file for CFRs should be defined for the terminal type and the version to be
downloaded must be specified in the Terminal Setting notebook.

See the IBM 7526 Programming Technical Reference that contains information
about writing CFRs for the 7526. The IBM 7527 Extended Terminal Services
Technical Reference contains information about writing CFRs for the 7527.
The 7524 Extended Terminal Services / DCConnect Client Technical Reference
contains information about writing CFR's for the 7524/Client. The
DCConnect Client also contains information about creating CFRs.

The CFR may return one of 3 possible values indicating what the transaction
program is to do next:

- ABORT The transaction program should be aborted
- NO_SKIP The next command should be performed.
- SKIP The next command should be skipped and the following one should
be performed instead.

Note: As of version 2.2.0a of the DCConnect Client, if a skip is to be done
and the next command is an IF command, then the entire if-else
construct is skipped.

Format:

CCFR ( function, parameters )
(0-9) (parameter string)
NO_PARAMETERS
++Variable/Parameter

++ Valid only for DCConnect Client version 2.1.0 or later

Parameters:

function - Specifies which function the CFR is to execute when it is
called. The number must be in the range 0-9.

parameters - The parameter string, if any, needed by the CFR being called
(maximum 99 characters). The parameter string may not contain
semicolons or colons.

New in version 2.1.0, for transaction programs that will run
on version 2.1.0 of the DCConnect Client or later, is the
ability to specify a variable (global, local or return code)
or parameter instead of a hard-coded parameter string.

Using a parameter of variable still restricts the parameter
string to 99 characters. However, the parameter or variable
data may contain semicolons or colons. If the variable or
parameter contains more than 99 characters, the extra
characters are ignored.

Examples:

Call the CFR with function number 7 and the parameter string "SUB".

CCFR ( 7, "SUB" )

Call the same CFR and use the parameter string in the parameter named
pParms:

CCFR ( 7, pParms )

CLRD Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

For the 7526, this command clears the contents of a user-variable or the
transaction buffer.

For the 7524/Client or 7527, this command clears the contents of a user-
variable, the transaction buffer, a PF key string, or a Touch point string.

This provides the ability to re-use data variables when desired. For the
7524/Client or 7527, if a PF key string or Touch point string is cleared
during a transaction program, upon completion of the transaction program the
string definition returns to the value it had before the transaction program
started.

In version 2.1.0 of DCTPB, for transaction programs written for DCConnect
Client 2.1.0 and later, local variables, parameters and the return code
variable can be cleared. And more than one variable or parameter can be
cleared in a single CLRD command.

Format:

CLRD ( target )
( UV1 - UV19 ) 7524/Client and 7527
( UV1 - UV99 ) 7524/Client with flash/program level > 1.10
( UV1 - UV998 ) 7526 only
( 101 - 164 ) 7524/Client and 7527
TRANSACTION_RECORD All (except for 7525)
Named Variable
++Local Variable
++Parameter
++uvRC, gRC

++ Valid only for DCConnect Client 2.1.0 or later

Parameters:

target - The data area to be cleared. For the 7526, it may be any of
the 998 user-variables (VAR 1-998) or the transaction
buffer.

For the 7524/Client or 7527, it may be any of the 19
user-variables, the transaction buffer, any of the 24 PF
key strings (PF 1-12, Shifted PF 1-12), or any of the 40
Touch point strings (TOUCH 1-40).

7524/Client terminals with flash/program level later than
1.10 have a maximum user-variable of 99 instead of 19.

Variable numbers 101 - 164 are PF strings (101-112),
Shifted PF strings (113-124), and touch screen regions
(125-164).

Note: On the 7526 terminal user-variable 100 is not
accessible by this command.

In version 2.1.0 of DCTPB, for transaction programs that
will run on DCConnect Client 2.1.0 and later, local
variables, parameters and the return code variable
can be cleared using this command.

Examples:

Clear user-variable 3.

CLRD ( UV3 )

Clear the parameters pNumErrors, pLastError, pLastErrorText:

CLRD ( pNumErrors, pLastError, pLastErrorText )

CLRP Command
------------
Supported Terminals:

7524/Client, 7527

Description:

Partially clears the screen of the 7524/Client or 7527 terminal

Format:

CLRP ( row, column, length, #rows++)
(1-20) (1-40) (1-40) (1-20)++
CURRENT_ROW CURRENT_COLUMN CLEAR_EOL CLEAR_REST++
PREVIOUS_ROW++ PREVIOUS_COLUMN++ ++Variable/Parameter ++Variable/Parameter
NEXT_ROW++ NEXT_COLUMN++
++Variable/Parameter ++Variable/Parameter

++ Only valid for version 2.1.0 of DCConnect Client or later

Parameters:

row - The row on the terminal display to begin clearing. The valid range
for the row number depends on the terminal type and the display size
selected for the terminal:

- 7527 Model 001 = 2 rows
- 7527 Model 002 = 14 or 20 rows
- 7524/Client = 20 rows. However depending on the physical
screen size, the arrow keys may be needed to
scroll the screen in order to see some of the rows.

The following keyword:

CURRENT_ROW

can also be used to indicate the cursor should remain in the
same row. For 7527 terminals, CURRENT_ROW can only be
used if CURRENT_COLUMN is also used for the column parameter.

As of version 2.1.0 of DCTPB, for transaction programs running on
version 2.1.0 or later of the DCConnect Client, the following
keywords can be used to tell the Client to move the cursor up or
down one row from its current position before starting to clear:

PREVIOUS_ROW
NEXT_ROW

If the cursor is already at row 1 and PREVIOUS_ROW is used or
if the cursor is already at row 20 and NEXT_ROW is used, the
cursor row will not be changed; the Client does not give an
error.

Also new in version 2.1.0, for transaction programs that will run
on version 2.1.0 of the DCConnect Client or later, is the
ability to specify a variable (global, local or return code)
or parameter instead of a numeric value or one of the keywords
listed above.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

If the variable/parameter contains the value 0, that is
treated the same as CURRENT_ROW.

column - The column on the terminal display to begin clearing. The valid
range for the column number depends on the terminal type and the
display size selected for the terminal:

- 7527 Model 001 = 40 columns
- 7527 Model 002 = 32 or 40 columns
- 7524/Client = 40 rows. However depending on the physical
screen size, the arrow keys may be needed to
scroll the screen in order to see some of the
columns.

The following keyword:

CURRENT_COLUMN

can also be used to indicate the cursor should remain in the
same column. For 7527 terminals, CURRENT_COLUMN can only
be used if CURRENT_ROW is also used for the row parameter.

As of version 2.1.0 of DCTPB, for transaction programs running on
version 2.1.0 or later of the DCConnect Client, the following
keywords can be used to tell the Client to move the cursor left
or right one column from its current position before starting to
clear:

PREVIOUS_COLUMN
NEXT_COLUMN

If the cursor is already at column 1 and PREVIOUS_COLUMN is used
or if the cursor is already at column 40 and NEXT_COLUMN is used,
the cursor column will not be changed; the Client does not give
an error.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client)if the value contains a
decimal point, all digits after the decimal point must be 0.

If the variable/parameter contains the value 0, that is
treated the same as CURRENT_COLUMN.

length - The length of the string to be cleared. If the keyword:

CLEAR_EOL

is used, the specified row will be cleared from the specified
column up to and including the end of the same row.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains a
decimal point, all digits after the decimal point must be 0.

If the variable/parameter contains the value 0, that is
treated the same as CLEAR_EOL.

#rows - New with version 2.1.0, for transaction programs that will
run on the DCConnect Client version 2.1.0 or later is the
ability to add this fourth parameter to specify that more
than one row be cleared. The same set of columns is
cleared in each row - as specified by the column and length
parameters.

A value from 1 to 20 can be specified. If the value specified
is more than the number of rows available from the starting
row specified above to the bottom of the screen, the Client
will adjust the value so that the last row is the bottom
row; no error will result at the terminal.

The keyword CLEAR_REST can be used to tell the Client to
clear all rows from the starting row indicated by the row
parameter all the way to the bottom of the screen.

If needed, a variable (global, local or return code) or
parameter can be specified instead of a numeric value or
the CLEAR_REST keyword. If the variable/parameter contains
the value 0, that is treated the same as CLEAR_REST.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

Examples:

Clear the display screen starting at row 2, column 4, for a length of 8.

CLRP ( 2, 4, 8 )

Clear the entire row below the current cursor position:

CLRP ( NEXT_ROW, 1, CLEAR_EOL )

Clear a 5 row by 10 column rectangle in the middle of
the screen 16x20 with the upper left corner being at row
6, column 6.

CLRP ( 6, 6, 10, 5 )

Use subroutine parameters for each of the CLRP parameters:

CLRP ( pRow, pColumn, pNumCols, pNumRows )

CLRS Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Clear the terminal display and place the cursor in the upper left hand corner.

Format:

CLRS ()

Parameters:

None

Example:

Clear the display screen.

CLRS ()

CMPUV Command
-------------
Supported Terminals:

7526

Description:

Compare two user-variables. If the result of the compare is true, the next
command in the transaction program is skipped. If false, the next command is
executed.

Format:

CMPUV ( source, operator, test_uv )
(0-998) LT (0-998)
UV0-UV998 GT UV0-UV998
LE
GE
EQ
NE

Parameters:

source - The user-variable that is compared

operator - The compare operator for comparing two user-variables. Operators
are defined as follows:

LT - less than
GT - greater than
LE - less than or equal to
GE - greater than or equal to
EQ - equal to
NE - not equal to

test_uv - The second user-variable used for comparison

Example:

Compare the contents of UV3 and UV 4. If they are equal, the next command is
skipped. If not, the next command is executed.

CMPUV ( UV3, EQ, UV4 )

CURS Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Position the cursor at a particular row and column of the display screen.

Format:

CURS ( row, column )
(1-20) (1-40)
CURRENT_ROW++ CURRENT_COLUMN++
PREVIOUS_ROW++ PREVIOUS_COLUMN++
NEXT_ROW++ NEXT_COLUMN++
++Variable/Parameter ++Variable/Parameter

++ Valid only for version 2.1.0 of the DCConnect Client and later

Parameters:

row - The row position where the cursor should be placed. The valid range
for the row number depends on the terminal type and the display size
selected for the terminal:

- 7526 Model 100 = 1 row
- 7526 Model 200 = 2 rows
- 7527 Model 001 = 2 rows
- 7527 Model 002 = 14 or 20 rows
- 7524/Client = 20 rows. However depending on the physical
screen size, the arrow keys may be needed to
scroll the screen in order to see some of the rows.

PREVIOUS_ROW
NEXT_ROW

If the cursor is already at row 1 and PREVIOUS_ROW is used or
if the cursor is already at row 20 and NEXT_ROW is used, the
cursor row will not be changed; the Client does not give an
error.

Version 2.1.0 of DCTPB and the DCConnect Client also support the
use of the keyword:

CURRENT_ROW

to indicate the cursor should remain in the same row. Of course
if the column is also set to CURRENT_COLUMN, the CURS command
does nothing.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

If the variable/parameter contains the value 0, that is
treated the same as CURRENT_ROW.

column - The column position where the cursor should be placed. The valid
range for the column number depends on the terminal type and the
display size selected for the terminal:

- 7526 Model 100 = 16 columns
- 7526 Model 200 = 40 columns
- 7527 Model 001 = 40 columns
- 7527 Model 002 = 32 or 40 columns
- 7524/Client = 40 rows. However depending on the physical
screen size, the arrow keys may be needed to
scroll the screen in order to see some of the
columns.

As of version 2.1.0 of DCTPB, for transaction programs running on
version 2.1.0 or later of the DCConnect Client, the following
keywords can be used to tell the Client to move the cursor left
or right one column from its current position:

PREVIOUS_COLUMN
NEXT_COLUMN

Version 2.1.0 of DCTPB and the DCConnect Client also support the
use of the keyword:

CURRENT_COLUMN

to indicate the cursor should remain in the same column. Of course
if the row is also set to CURRENT_ROW, the CURS command does
nothing.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client)if the value contains a
decimal point, all digits after the decimal point must be 0.

If the variable/parameter contains the value 0, that is
treated the same as CURRENT_COLUMN.

Examples:

Position the cursor at row 2, column 10.

CURS ( 2, 10 )

Move the cursor down one row but keep the column the same:

CURS ( NEXT_ROW, CURRENT_COLUMN)

Move the cursor to column 1 of the row specified by a subroutine parameters
called pStartRow:

CURS ( pStartRow, 1 )

DB Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

Read a variable number of characters from a sensor device and display the
characters read on the display screen. The Enter key must be pressed to
complete the command.

If the read is from a magnetic device and the first byte of data is a secure
head indicator (hex 10), then the badge content is not displayed when read
and instead an asterisk (*) is displayed (7525, 7526, and 7527) for each
input character.

For 7524/Client, 7526, and 7527 DCTs, the value excluding the secure head
character, becomes the value of the last read variable (VAR 0) and becomes
part of the transaction buffer unless automatic transaction building has
been turned off. For 7525 DCTs, the value read is added to the transaction
buffer.

Format:

DB ( data_length )
(1 - 40)

Parameters:

data_length - The maximum number of characters to read from a sensor device.
The length specified must be in the range 1-40.

Example:

Read and display a maximum of three characters from a sensor device.

DB ( 3 )

DBI Command
-----------
Supported Terminals:

7527

Description:

Display a bit image on the 7527 Model 002 graphic screen.

Format:

DBI ( row, column, attrib, record )
CURRENT_ROW CURRENT_COLUMN NORMAL (0-9999)
(1-200) (1-320) INVERT

Parameters:

row - The row on the terminal display to begin displaying. The row
number corresponds to the pixel row (terminal display is 200 x 320
pixels). Row 1 is the top row of a screen.

column - The column on the terminal display to begin drawing. Column 1 is
the left most column of a screen.

attrib - The attributes of the bit image

record - The record number of the bit image.

Example:

Display bit image record number 200 at row 20, column 30, with normal
attributes.

DBI ( 20, 30, NORMAL, 200 )

DECLARE Command
---------------
Supported Terminals:

DCConnect Client version 2.1.0 or later

Description:

Used to declare local variables for subroutines and transaction programs.
The local variable exists only for the duration of the subroutine/program.

Declare commands are valid in subroutines only if those subroutines are
defined using the SUB command. For more information about subroutines
please see Subroutines.

All local variables must be declared before any other command (other than
comments) in the subroutine/transaction program. They will initially be
empty unless the DECLARE command specifies a value to be assigned. The
compiler will give an error if a DECLARE command is found after any
other (non-DECLARE, non-comment) command.

The initial value of the local variable can be set to any of the following:

- Named or unnamed global user variable
- The return code user variable (legal but unusual usage)
- Parameter passed to the subroutine, if in a subroutine
- A previously defined local variable in the same subroutine/program
- PF Key string
- Touch Point string
- Text enclosed in double quotes
- Numeric constant
- Named message (note that a message number cannot be used because it would
simply be treated as a numeric constant rather than a message number).

Up to 92 local variables can be declared for each subroutine and for
each transaction program.

Format:

DECLARE ( localVarName )

DECLARE ( localVarName = varParmOrConst )

Parameters:

localVarName - Name for the local variable. The name must follow the
Rules for Variable and Parameter Names.

Although not required, it is recommended that each local variable
name start with something like 'l' or 'loc' so that it can be
distinguished from names for parameters and global variables.

varParmOrConst - Used to set the initial value of the local variable. If not
used, the local variable is initially empty. If used, an
equal sign must follow the local variable name, with or
without surrounding spaces or tabs. Following the equal sign
can be any one of the entities listed above.

Examples:

Declare three local variables for getting the length, width and height. These
all start out empty.

DECLARE ( locLength )
DECLARE ( locWidth )
DECLARE ( locHeight )

Declare a local variable for the starting row and column and initialize each
to 1.

DECLARE (locRow = 1 )
DECLARE (locCol = 1 )

For an example where local variables are set to the value of subroutine
parameters, please see Subroutines.

DLAY Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Delay the execution of the transaction for a given amount of time. This
command is necessary to display several screens of information to a user, and
can be used to pause between screens so that a reader can finish reading. It
may be used whenever a pause in the action is required.

Format:

DLAY ( delay_time )
( 1 - 99 )
++Variable/Parameter

++ Valid only for DCConnect Client 2.1.0 or later

Parameters:

delay_time - The number of seconds to delay execution. It must be in the
range 1-99.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

At runtime, the variable or parameter must contain a numeric
value from 1 to 99 or the transaction program will abort.

Examples:

Pause 5 seconds to allow the you to read a message.

DLAY ( 5 )

Delay the number of seconds specified in the global variable gPromptDelay:

DLAY ( gPromptDelay )

ELSE Command
------------
Supported Terminals:

DCConnect Client version 2.2.0 or later

Description:

This command is used in conjunction with the command 'If' It defines a
transaction program step or set of steps that should be executed only
when the comparison operation(s) of the If command yield a false result.

If more than one command should be performed only when the 'If' comparison
is false, then that block of commands should be enclosed in a pair of
opening and closing braces: { }.

If the Else command is to be followed immediately by an 'If' command
(without an opening brace in between) then the shortcut command ELSEIF
command can be used to combine the two commands. See ELSEIF Command.

Format:

ELSE

Parameters:

None

Example:

For examples please see the IF Command and
and Transaction Program Control Using If/Else Commands.

ELSEIF Command
--------------
Supported Terminals:

DCConnect Client version 2.2.0 or later

Description:

The ELSEIF command is simply shorthand for the two separate commands ELSE
and IF and can be used when the one command to be performed in an ELSE
clause is another IF command.

This helps with readability when using an if-else construct as a kind of
case statement.

For more information please see the IF Command, ELSE Command,
and Transaction Program Control Using If/Else Commands.

ENAV Command
------------
Supported Terminals:

7527

Description:

End a navigation screen region. For more information about screen
navigation, see the BNAV command.

Format:

ENAV ( )

Parameters:

None

Example:

End a screen navigation region.

ENAV ( )

ENCRYPT Command
---------------
Supported Terminals:

Client 3.0.8f and later

Description:

Applies an encryption algorithm to the contents of a user variable. The
initial implementation supports the blowfish algorithm:

- The Blowfish algorithm requires an external key to be provided which
is combined with an internal DCS supplied key. That combined key and
the source data are the inputs to the encryption algorithm.

The Blowfish algorithm is intended to be used for encrypting passwords that
will be sent to the DCConnect Server and ultimately a Transaction Connection (TC)
script that will use the LDAP_ValidateUser or LDAP_ChangePassword functions.
These TC functions use the blowfish algorithm to decrypt the encrypted password
so that the decrypted password can be provided in internal LDAP API calls. The
same key that is used in the Client Encrypt command must be provided to the TC script
that will be interfacing with LDAP; the TC decryption logic uses the same
internal key during decryption that the Client Encrypt command uses during encryption.

Format:

ENCRYPT ( targetVar, sourceVarOrConstant, encryptionType, encryptionKeyParmOrConstant )

UV0-UV99 UV0-UV99 BLOWFISH UV0-UV99
Named Variable Named Variable Named Variable
Local Variable Local Variable Local Variable
Parameter Parameter Parameter
uvRC, gRC uvRC, gRC uvRC, gRC
PF1-PF12 PF1-PF12
TOUCH1-TOUCH40 TOUCH1-TOUCH40
numeric constant numeric constant
"text" "text"
Named message Named message

Parameters:

targetVar - The terminal variable into which the encryption output will
be stored. It may be any global or local user variable,
parameter or the return code variable.

sourceVarOrConstant - The variable containing the value to be encrypted or the
literal value to be encrypted. This can be any of the
following:

- Named or unnamed global user variable
- Local variable of the subroutine
- Parameter passed to the subroutine
- PF Key string
- Touch Point string
- Text enclosed in double quotes
- Numeric constant
- The return code user variable, uvRC (gRC)
- Named message (note that a message number cannot be used because it would
simply be treated as a numeric constant rather than a message number).

encryptionType - The only choice is BLOWFISH

encryptionKeyParmOrConstant - The variable containing the encryption key to use or the
literal value for that key. This can be any of the
same choices as are available for the sourceVarOrConstant above.

Example:

Encrypt the PW parameter passed into the subroutine, storing it in the local variable PWEncrypted,
using the encryption key set in the local varable EncryptionKey.

Sub F1 : Logon ( userId, PW )

Declare ( PWEncrypted )
Declare ( EncryptionKey = "A1b2C3" )

...

ENCRYPT ( PWEncrypted, PW, BLOWFISH, EncryptionKey )

...

EndSub ()

FB Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

Read a fixed number of characters from a sensor device. If the read is from
a magnetic device and the first byte of data is a secure head indicator (hex
10), then the badge content is not displayed when read and instead an
asterisk (*) is displayed (7525, 7526 and 7527) for each input character.
For 7524/Client, 7526 and 7527 DCTs, the value read excluding the secure head
character, becomes the value of the last read variable (VAR 0) and becomes
part of the transaction buffer unless automatic transaction building has been
turned off. For 7525 DCTs, the value read is added to the transaction
buffer.

Format:

FB ( data_length, validation_file, validation_type )
(1 - 40) (filename.VAL) ABORT_IF_PRESENT
NO_VALIDATION ABORT_IF_ABSENT
SKIP_IF_PRESENT
SKIP_IF_ABSENT
NONE

Parameters:

data_length - The number of characters to read from a sensor device. The
length specified must be in the range 1-40.

validation_file - The name of the validation file to be used to validate
the input data.

validation_type - The action to be taken on the transaction as the result of
validating the input data.

Example:

Read eight characters and verify that they do not exist in file BADGES.VAL.

FB ( 8, "badges.val", ABORT_IF_PRESENT )

FRMT Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

This command provides the capability to format a user-variable in several
ways. The variable may have leading or trailing characters removed, it may
be truncated to a given length, or filled with a specified character to
achieve the given length. This command is typically used to format a data
item prior to printing, it allows column alignment to be done in a printed
report. It is used in conjunction with verifying or sending send data items
to an RS-232 port or a transaction buffer. For the 7526, this command is
available only with microcode version 2.0+.

As of version 2.1.0 of DCTPB, for transaction programs running on version
2.1.0 of the DCConnect Client, over a dozen new formatting options were
added (which correspond to options for the Transaction Connection Format_UV
command). These are:

STRIP_LEADING_CHARS
STRIP_TRAILING_CHARS
STRIP_ALL_CHARS
TAKE_LEADING_CHARS
DROP_LEADING_CHARS
TAKE_TRAILING_CHARS
DROP_TRAILING_CHARS
PAD_LEADING
PAD_TRAILING
TAKE_MID_CHARS
DROP_MID_CHARS
UPPER_CASE
CUSTOM_STRING
CUSTOM_INTEGER
CUSTOM_FLOAT

See below for the parameters required for each.

For the original FRMT command is executed in the terminal, the following
actions are performed:
1. If the third parameter (right) is STRIP_CHARS, then as many
(right-char) characters that are found at the end of the source,
the user-variable are removed.
2. If the fifth parameter (left) is STRIP_CHARS, then as many (left-char)
characters that are found at the beginning of the source, the
user-variable are removed.
3. If the resulting size of the source user-variable is greater than
the length specified in the second parameter, the source
user-variable is truncated to that length.
4. If the resulting size of the source user-variable equaled the length in the
second parameter, nothing more is done.
5. If the resulting size is smaller than the specified length, then the source
is padded with the (fill_char) on the left or right as specified by the
seventh parameter (FILL_LEFT or FILL_RIGHT).

Format:

FRMT ( source, length, right, right_char, left, left_char, fill, fill_char)
(1-998) (1-128) DONT_STRIP_CHARS (0-255) DONT_STRIP_CHARS (0-255) FILL_LEFT (0-255)
VARIABLE_LENGTH STRIP_CHARS ASCII_SPACE STRIP_CHARS ASCII_SPACE FILL_RIGHT ASCII_SPACE
++Variable/Parm ASCII_ZERO ASCII_ZERO ASCII_ZERO
++PF1-PF12 ASCII_SEMICOLON ASCII_SEMICOLON ASCII_SEMICOLON
++TOUCH1-TOUCH40 ++Variable/Parm ++Variable/Parm ++Variable/Parm
Named Variable
++Local Variable
++Parameter
++uvRC, gRC

++ Valid only for DCConnect Client version 2.1.0 and later

The following options are valid only for transaction programs that will run on
version 2.1.0 of the DCConnect Client or later:

FRMT (source, STRIP_LEADING_CHARS, whichCharacter )
FRMT (source, STRIP_TRAILING_CHARS, whichCharacter )
FRMT (source, STRIP_ALL_CHARS, whichCharacter )
FRMT (source, TAKE_LEADING_CHARS, howMany )
FRMT (source, DROP_LEADING_CHARS, howMany )
FRMT (source, TAKE_TRAILING_CHARS, howMany )
FRMT (source, DROP_TRAILING_CHARS, howMany )
FRMT (source, PAD_LEADING, whichCharacter, finalLength )
FRMT (source, PAD_TRAILING, whichCharacter, finalLength )
FRMT (source, TAKE_MID_CHARS, startOffset, howMany )
FRMT (source, DROP_MID_CHARS, startOffset, howMany )
FRMT (source, UPPER_CASE )
FRMT (source, CUSTOM_STRING, formatString )
FRMT (source, CUSTOM_INTEGER, formatString )
FRMT (source, CUSTOM_FLOAT, formatString )

Parameters:

source - The user-variable that is to be formatted. For the 7526, it may
be any of the 998 user-variables (VAR 1-998). For the 7527, it
may be any of the 19 user-variables.

7524/Client terminals with flash/program level later than 1.10
have a maximum user-variable of 99 instead of 19.

New with DCTPB 2.1.0, for transaction programs that will run
on version 2.1.0 of the DCConnect Client, the source to be
formatted can also be a local variable, parameter or the return
code variable.

length - The number of characters in the formatted string. If this is
VARIABLE_LENGTH then the result is a varying length string created
as a result of the strip operations. No filling is done on a
variable length string. If the length is non-zero (in the range 1-128)
then the fill operation is performed after the strip operation
and the string that results from the format operation has this
fixed length.

New in version 2.1.0, for transaction programs that will
run on version 2.1.0 of the DCConnect Client or later, is
the ability to specify a variable (global, local or return
code) or parameter instead of a numeric value. If the variable
or parameter contains the value 0, this is equivalent to the
use of the VARIABLE_LENGTH keyword.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

right - Indicates whether or not characters to the right are to be
stripped or filled.

right_char - The character to strip, indicated by the decimal representation
of the ASCII character. The strip character usually is a blank
(ASCII 32) or a zero (ASCII 48). By default, there is no
stripping done, indicated by a zero entry.

See 'whichCharacter' below for more ways to specify this character.

left - Indicates whether or not characters to the left are to be
stripped or filled.

left_char - The character to strip, indicated by the decimal representation
of the ASCII character. The strip character usually is a blank
(ASCII 32) or a zero (ASCII 48). By default, there is no
stripping done, indicated by a zero entry.

See 'whichCharacter' below for more ways to specify this character.

fill - Indicates whether or not characters to the stripped/filled from
the left side or right side. FILL_LEFT and STRIP_LEFT are
synonyms because the parameter value only indicates the
direction - not whether filling or stripping is done. Whether
filling or stripping is done is determined by the length
parameter specified above and the length of the data in the
specified user-variable at the time that the FRMT command is
processed. For the same reason, FILL_RIGHT and TRUNC_RIGHT are
also synonyms.

fill_char - The character to use as a fill character if the formatted string
is to be fixed length and needs some filling after the strip
operation is finished. The type of character to fill with is
indicated by the decimal representation of the ASCII character.
The fill character chosen usually is a blank (ASCII 32) or a
zero (ASCII 48).

See 'whichCharacter' below for more ways to specify this character.

whichCharacter - For the STRIP_xxx and PAD_xxx format options and for the
'right_char', 'left_char' and 'fill_char' parameters listed
above, this is a value from 0-255 indicating the ASCII value
of the character or this can be the actual character enclosed
in single or double quotes. The following keywords are also
allowed:

ASCII_SPACE
ASCII_ZERO
ASCII_SEMICOLON

New in version 2.1.0 of the Client and DCTPB is the
ability to specify a variable (global, local or return
code) or parameter instead of a numeric value or one of
the keywords above.

At runtime, the variable or parameter must contain a numeric
value from 0 to 255 or the transaction program will abort.

howMany - For the TAKE_xxx and DROP_xxx format options this is a value
from 1-999 or it can be a variable/parameter that will contain
a quantity at run time indicating how many characters should
be taken/dropped.

If the quantity specified is longer than the amount of data
available to take or drop, then the quantity is changed to
the data length relative to the starting point and the
operation is performed without error.

If needed, a variable (global, local or return code) or
parameter can be specified instead of a numeric value.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

finalLength - For the PAD_LEADING and PAD_TRAILING format options, this
is a value from 1-999 indicating what the final data length
should be after the padding is done. This can also be a
variable or parameter that will contain the final length
at run time.

If the source variable is already at or longer than the
specified length, the variable is not changed.

If needed, a variable (global, local or return code) or
parameter can be specified instead of a numeric value.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

startOffset - For the TAKE_MID_CHARS and DROP_MID_CHARS format options,
this is a value from 0-999 indicating where in the data
of the source should characters start to be taken/dropped.
A startOffset of 0 indicates the first character. This
parameter can also be a variable or parameter that will
contain the start offset at run time.

If the startOffset is beyond the end of the data for the
TAKE_MID_CHARS format option, the end result will be that
the source variable is cleared.

If the startOffset is beyond the end of the data for the
DROP_MID_CHARS format option, the end result will be that
the source variable is unchanged.

If needed, a variable (global, local or return code) or
parameter can be specified instead of a numeric value.

The variable/parameter must contain an integer value or (as
of version 2.2.0a of the DCConnect Client) if the value
contains a decimal point, all digits after the decimal point
must be 0.

formatString - For the CUSTOM_STRING, CUSTOM_INTEGER and CUSTOM_FLOAT
format options, this is a string enclosed in double quotes
that contains the formatting directive. The Client uses
the C function sprintf to perform the formatting.

For CUSTOM_STRING, the formatString must include some
variation of %s.

For CUSTOM_INTEGER, the formatString must include some
variation of %d.

For CUSTOM_FLOAT, the formatString must include some
variation of %f.

The web page, Format Specification Fields,
describes how to create the formatting string.

Examples:

Format user-variable 1 into a 5 character string, stripping off leading
blanks, and zero filling the result on the left. This is used after reading
a number from the RS-232 port, so that the number can be made part of a
transaction that requires a five digit, zero-filled numeric value.

FRMT ( 1, 5, DONT_STRIP_CHARS, 0, STRIP_CHARS, ASCII_SPACE, FILL_LEFT, ASCII_ZERO )

Convert the parameter called pTitle to upper case:

FRMT ( pTitle, UPPER_CASE )

Pad the pTitle parameter out to 40 characters with spaces:

FRMT ( pTitle, PAD_TRAILING, 32, 40 )

Do the same thing and use ASCII_SPACE for the pad character:

FRMT ( pTitle, PAD_TRAILING, ASCII_SPACE, 40 )

Do the same thing and use the space character enclosed double quotes for
the pad character:

FRMT ( pTitle, PAD_TRAILING, " ", 40 )

The result of this operation is UV1 set to "ABCDEFGHIJ"

SETSTR ( UV1, "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ" )
FRMT ( UV1, TAKE_MID_CHARS, 10, 10 )

Format the number in user variable 3 into some descriptive text with
the floating point number taking up 5 places, 2 of which are to the
right of the decimal point.

FRMT ( UV3, CUSTOM_FLOAT, "Current hours worked = %5.2f" )

Pad trailing spaces to the contents of the parameter pTitle up to
the length specified in the parameter pFinalLen:

FRMT ( pTitle, PAD_TRAILING, ASCII_SPACE, pFinalLen )

GOSUB Command
-------------
Supported Terminals:

7524/Client, 7526

Description:

Allows transaction programs to transfer control to a specified subroutine in
the current program or another program, and then return back to the original
program step via the RETURN command (return from subroutine). The subroutine
is specified by the step number or label on the 7524/Client and by a label on
the 7526.

Subroutines are useful for keeping in one place a set of transaction program
commands that would be used by many different transaction programs. For
example, if several different transaction programs needed to prompt the
terminal user for a badge number and product number and then validate those
values, the steps to accomplish those activities could be put into a
subroutine. Then each transaction program that needed to perform those
activities would simply use the GOSUB command to call that subroutine rather
than having each program repeat those steps.

The use of subroutines can reduce the amount of terminal memory that is
consumed by the transaction programs.

For 7526 terminals, this command is available only if the microcode level is
version 2.0 or later.

For 7524/Client terminals, this command is available if the flash/program
level is 1.11C or later.

New in version 2.1.0 of DCTPB, for transaction programs that run on
version 2.1.0 or later of the DCConnect Client, is the ability to pass
parameters to the subroutine. In this case, subroutines must be defined
using the SUB command. There is also a more intuitive
form of the GOSUB command, the CALL command. For
more information about subroutines, please see Subroutines.

Format:

GOSUB ( program ID, label, ++Parameter1, ... )
ABORT_PROGRAM "label name"
THIS_PROGRAM (step number)
++SubroutineName
F1 - F28, (1-28)
BADGINIT, (29)
FASTCLK, (30)
PF1 - PF12, (31-42)
SPF1 - SPF12, (43-54)
RS232, RS232_2, (55,56)
DI0 - DI7, (57-64)
*RES2 - RES9, (65-72)
*TCH1 - TCH40, (73-112)
*ADDL1 - ADDL8, (113-120)
*TODCLK (121)

(1-64, *65-121)

*7526 terminals cannot use program IDs greater than 64
++Valid only for version 2.1.0 or later of the DCConnect Client

Note: Even though certain terminal types cannot actually start a
transaction program using all of triggers associated with
the program IDs listed above (e.g. 7526 terminals don't have
PF Keys and 7524/Client terminals do not have touch points),
programs can still be bound to these binding IDs and
therefore the GOSUB command can still branch to those
program IDs.

Parameters:

A value of ABORT_PROGRAM indicates that the program should
be aborted.

A value of THIS_PROGRAM indicates execution should stay
within the currently executing program.

Note, as of the March 2006 version of dctpb32.exe, you
can eliminate this parameter altogether if it should be
THIS_PROGRAM and you are not passing any parameters to
the subroutine (if passing parameters the CALL command
is recommended instead).

label - Defines the step within the specified transaction program to
which execution should be transferred. The label is a 1-30
character user defined name given to a program step. The
label is not tied to a step number and is independent of
command insertion/deletion. (Although when DCTPB compiles
7527 and 7524/Client transaction programs, it converts
labels to step numbers).

For 7526 terminals, only the first 15 characters of the
label are considered significant. Therefore all labels used
in the same 7526 transaction program must be unique in their
first 15 characters.

For a 7524/Client or 7527 program, if the branch is to a
program ID other than ABORT_PROGRAM, END_OF_PROGRAM or
THIS_PROGRAM and a label is used instead of a step number
then the ENFORCE_BINDINGS keyword must be used in the TERMTYPE
command. For more details, see the command TERMTYPE above.

stepnumber - For 7524/Client or 7527 programs, a stepnumber can be used
at any time. However, because the addition and removal of
commands in a program can change the validity of step
numbers, it is recommended that labels be used instead.
DCTPB will convert labels to step numbers when compiling.
See the comments above for 'label' for important information
about how to use labels. It is recommended that the only
time you use a step number is when the step is the first in
the program.

SubroutineName - For programs that will run on version 2.1.0 or later of the
DCConnect Client, a SubroutineName that was defined in a
SUB command can also be the target label
for the GOSUB command - because the subroutine label is in
effect a label.

Parameter1, ... - For programs that will run on version 2.1.0 or later of the
DCConnect Client, one or more parameters may be passed to
the subroutine - provided that subroutine was defined using
the SUB command and the subroutine
definition includes parameters.

Please refer to the CALL command for more
information about passing parameters to subroutines.

Examples:

Go to subroutine in this program starting at label 'Test_label'.

GOSUB ( THIS_PROGRAM, "Test_label" )

Using the shortcut syntax that implies THIS_PROGRAM:

GOSUB ( "Test_label" )

Call the subroutine ADDL1:AddValues and pass it 5 values. See the examples
for the SUB command for the definition of this subroutine.

GOSUB (ADDL1, AddValues, lTotalsMon, lTotalsTue, lTotalsWed, lTotalsThu, lTotalsFri )

CLRS ()
SHOW ("Totals for the week: ", 1, 1, NORMAL)
SHOW (uvRC, CURRENT_ROW, CURRENT_COLUMN, NORMAL)

Using the preferred CALL command, the syntax of the
subroutine call above would be:

CALL ADDL1:AddValues (lTotalsMon, lTotalsTue, lTotalsWed, lTotalsThu, lTotalsFri )

GOTO Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description

Allows transaction programs to transfer control to a specified step in the
current program or another program. The step is specified by the step number
or label on the 7524/Client or 7527 and by a label on the 7526.

The GOTO command may be used to map several triggering events such as Touch
point areas on the 7527, to the same transaction program. For example, on
the 7527, a GOTO command could map Touch points 39, 35, and 34 to execute the
transaction program associated to touch point 40. This provides a large
Touch point target without the memory usage required if you had four complete
copies of the program configured for the terminal.

Format:

GOTO ( program ID, label )
ABORT_PROGRAM "label name"
THIS_PROGRAM (step number)
++END_OF_PROGRAM
F1 - F28, (1-28)
BADGINIT, (29)
FASTCLK, (30)
PF1 - PF12, (31-42)
SPF1 - SPF12, (43-54)
RS232, RS232_2, (55,56)
DI0 - DI7, (57-64)
*RES2 - RES9, (65-72)
*TCH1 - TCH40, (73-112)
*ADDL1 - ADDL8, (113-120)
*TODCLK (121)

(1-64, *65-121)

*7526 terminals cannot use program IDs greater than 64
++Valid only for DCConnect Client version 2.1.0 or later

Parameters:

A value of ABORT_PROGRAM indicates that the program should
be aborted. When this value is used for the program ID, the
second parameter is optional and, if present, is ignored.

A value of THIS_PROGRAM indicates execution should stay
within the currently executing program.

Note, as of the March 2006 version of dctpb32.exe, you
can eliminate this parameter altogether if it should be
THIS_PROGRAM. In other words, if only one parameter is
provided in this command, and it is not ABORT_PROGRAM
or END_OF_PROGRAM, then that parameter is assumed to be
the label/step and the target program is assumed to be
THIS_PROGRAM.

label - Defines the step within the specified transaction program to
which execution should be transferred. The label is a 1-30
character user defined name given to a program step. The
label is not tied to a step number and is independent of
command insertion/deletion. (Although when DCTPB compiles
7527 and 7524/Client transaction programs, it converts
labels to step numbers).

For 7526 terminals, only the first 15 characters of the
label are considered significant. Therefore all labels used
in the same 7526 transaction program must be unique in their
first 15 characters.

For a 7524/Client or 7527 program, if the branch is to a
program ID other than ABORT_OF_PROGRAM, END_OF_PROGRAM or
THIS_PROGRAM and a label is used instead of a step number then
the ENFORCE_BINDINGS keyword must be used in the TERMTYPE
command. For more details, see the command TERMTYPE above.

For terminals running version 2.1.0 or later of the
DCConnect Client, the keyword END_OF_PROGRAM can be used
to cause the transaction program to jump to end, ending
without error. This is different from the use of END_OF_PROGRAM
or ABORT_PROGRAM for the program ID where the transaction
program ends in the same was as if the Esc key had been
pressed. When the Esc key is pressed, the program ends
immediately and no transaction is sent, even if there is
data in the transaction buffer. But if END_OF_PROGRAM is
used as the label parameter in the GOTO command, while
the transaction program still ends immediately, if there is
data in the transaction buffer and automatic transaction
sending has not been turned off via the AUTO command, a
transaction containing that data will be generated and sent.

Examples:

Go to current transaction step 27.

GOTO ( THIS_PROGRAM, 27 )

Go to the label TRY_AGAIN in the current program:

GOTO ( THIS_PROGRAM, TRY_AGAIN )

Use the new shortcut syntax:

GOTO ( TRY_AGAIN )

Abort the transaction program.

GOTO ( ABORT_PROGRAM )

Goto to the end of the current program. A transaction will be sent if the
transaction buffer contains data and automatic transaction sending has not
been turned off.

GOTO ( THIS_PROGRAM, END_OF_PROGRAM )

HF Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

This command defines that this transaction program definition is to be used
as a hot key. It is used as a check to verify that the terminal is actually
in communication with the system unit and that it can send a transaction to
the system unit. Pressing the hot key causes the terminal to send the system
unit a transaction that consists of a program identifier, date/time stamp,
and terminal sequence number. This must be the first and only command in a
transaction program.

Format:

HF ( )

Parameters:

None

Example:

Specify that this program is to be used as a hot key.

HF ()

IF Command
----------
Supported Terminals:

DCConnect Client version 2.2.0 or later

Description:

Perform a comparison operation on two or more pieces of data, yielding
a true or false result. If that result is true, the next command or
block of commands is executed. If that result is false, the next
command or block of commands is skipped.

If the 'If' command has a corresponding 'else' command then if the result
of the 'If' command was false, the command or block of commands after the
else command will be executed. But if that result was true, the commands
in the else clause will be skipped.

The logical operators, 'and', 'or' and 'not', can be used in the If
command in order to perform more complex comparison operations. These
logical operators can be represented in several different ways, show below.

'If' commands can be nested within other 'if' and 'else' commands.

The operands in the 'If' command can be any of the following:

- Global user variable
- Local variable
- Parameter
- Return code variable
- String constant
- Numeric constant
- PF Key or Touch Point string
- Named message (note that a message number cannot be used because it would
simply be treated as a numeric constant rather than a message number).

As of version 2.2.0a of the DCConnect Client, the IF command can be used
within a subroutine to check whether a subroutine parameter has been
passed. (If empty, the variable has not been passed - or an empty
value has been passed.)

The following comparison operators are supported:

Symbol Meaning
------ -------
= Equal to
== Equal to
>= Greater than or equal to
=> Greater than or equal to
<= Less than or equal to
=< Less than or equal to
!= Not equal to
<> Not equal to
< Less than
> Greater than

The above comparison operators perform a 'string'
comparison of the data. For example, if UV1 contains
the two byte string "17" and UV2 contains the one byte
string "6", then UV1 is less than UV2. This would look
like:

if (UV1 < UV2) // This is true

All string comparisons are case-sensitive.

However, if a numeric comparison should be performed instead, then
use the '#' symbol before the comparison operator.

if (UV1 #< UV2) // This is false

When a numeric comparison is done, the values are converted
to their floating point representation and then the numeric
comparison is done. As a result the values 01, 1, 1.0, 1.00, ...
would all be equal.

Note: The exception to this are the flavors of the DCConnect
Client that are built for the Antares terminals. Floating
point operations are not supported on these devices; therefore
all comparison operations are integer operations. Version 2.2.0a
of the DCConnect Client for the Antares includes the change
that forces all comparison operations to be integer operations.

The logical operators: And, Or and Not can be
represented using any of the following syntax:

AND
&&
&

OR
||
|

NOT
!

Use parentheses to ensure the proper order of evaluation. The outermost
set of parentheses is always required, even for the simplest comparison.

The shorthand syntax, ELSEIF can be used to combine an ELSE command and
an IF command when the IF immediately follows the ELSE in the transaction
program. For more information, please see the ELSEIF Command.

For more information about If-else constructs please see the following:
- Transaction Program Control Using If/Else Commands
- Using AND, OR and NOT operators in If Commands

Format:

IF [ ( ] (var_1 comparison_op var_2) [ logical_op (var_3 comparison_op var_4) ... ) ]

Parameters:

var_1 - The first global variable / local variable / parameter / return code
variable / string constant / numeric constant / PF Key or Touch String
to be compared
comparison_op - A comparion operator (see above) to use to compare var1 and var2
var_2 - The second variable / parameter / ... to be compared

logical_op - An optional logical operator that can be used to combine multiple
comparison operations.

var_3, ... - The var_x/comp op/var_y sequence can be repeated multiple times,
with logical operations in between.

Examples:

// Check whether uvRow is greater than or equal to 15 by doing a numeric comparison.
// If that is true, set the row and column back to 1. If it is false, increment
// the row by 1.
if (uvRow #>= 15)
{
SetStr(uvRow, 1)
SetStr(uvCol, 1)
}
else
Math (uvRow += 1)

// If the row or column are out of range, goto error
if ((uvRow #< 1) OR (uvRow #> 16) OR // Dimensions of
(uvCol #< 1) OR (uvCol #> 20)) // terminal are 16x20
Goto (This_Program, InvalidDimensions)

// Use reverse logic of previous example
if (NOT ((uvRow #< 1) OR (uvRow #> 16) OR // Dimensions of
(uvCol #< 1) OR (uvCol #> 20)) // terminal are 16x20
Goto (This_Program, ValidDimensions)

// Since !(A | B | C | D) is equivalent to !A & !B & !C & !D we could also use:
if (!(uvRow #< 1) && !(uvRow #> 16) && // Dimensions of
!(uvCol #< 1) && !(uvCol #> 20)) // terminal are 16x20
Goto (This_Program, ValidDimensions)

// Perform the same operation using nested if commands
if (!(uvRow #< 1))
if (!(uvRow #> 16))
if (!(uvCol #< 1))
if (!(uvCol #> 20))
Goto (This_Program, ValidDimensions)

INAV Command
------------
Supported Terminals:

7527

Description:

Pause for input in a screen navigation region. This command is valid only
when placed between the BNAV and ENAV commands. For more information about
screen navigation, see the BNAV command.

Format:

INAV ( )

Parameters:

None

Example:

Pause for input within a navigation region.

INAV ( )

KB Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

Read a fixed number of characters from a sensor device or from the
alpha-numeric keypad.

If the read is from a magnetic device and the first byte of data is a secure
head indicator (hex 10), then the badge content is not displayed when read,
instead an asterisk (*) is displayed (7525, 7526, and 7527 only) for each
input character.

For 7524/Client, 7526 and 7527 DCTs, the value read excluding the secure head
character, becomes the value of the last read variable (VAR 0) and becomes
part of the transaction buffer, unless automatic transaction building has
been turned off. For 7525 DCTs, the value read is added to the transaction
buffer.

Format:

KB ( data_length, validation_file, validation_type )
(1 - 40) (filename.VAL) ABORT_IF_PRESENT
NO_VALIDATION ABORT_IF_ABSENT
SKIP_IF_PRESENT
SKIP_IF_ABSENT
NONE

Parameters:

data_length - The number of characters to read from a sensor device.
The length specified must be in the range 1-40.

validation_file - The name of the validation file to be used to validate
the input data.

validation_type - The action to be taken on the transaction as the result of
validating the input data.

Example:

Read eight characters and verify that they do not exist in file BADGES.VAL.

KB ( 8, "badges.val", ABORT_IF_PRESENT )

LABEL Command
-------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Allows the user to define a textual name to be associated with a step in a
transaction program. The LABEL command does not do actually do anything when
it is processed, but is used by other commands to reference transaction
program steps by name. The LABEL command is used in conjunction with other
commands that case control to be transferred to a step within the current
transaction program, or to another program. The commands that use labels to
reference program steps are GOTO, GOSUB, ONKEY, ONSUB and TEST. The CALL
command can also refernce a LABEL, but that 'label' should be part of the
SUB command, used for defining subroutines.

Labels must be unique within a single transaction program. Different
programs may use the same label name.

Format:

LABEL ( label )
(label name)

Parameters:

label - Defines a 1-30 character name to be associated with the current step
in the current transaction program. This label can be referenced by
commands located anywhere in the current transaction program. Labels
are case insensitive and may contain the characters A-Z, a-z, 0-9 and
space.

For 7526 terminals, only the first 15 characters of the label are
considered significant. Therefore all labels used in the same 7526
transaction program must be unique in their first 15 characters.

For 7527 and 7524/Client programs, do not use labels that can be
interpreted as a step number in the range 1-999 because DCTPB will
treat them as that step number instead of a label. For example, "1",
"01", "001" and "999" will all be interpreted as step numbers by
DCTPB.

Example:

Specify this line as label CONTINUE

LABEL ( "CONTINUE" )

LED Command
-----------
Supported Terminals:

7526, 7527

Description:

Turn on the indicated LED for up to 500 milliseconds. The panel leds, or the
LEDs on either of the two sensor ports may be turned on. It is assumed that
a magnetic device is connected to a port whose LED is to be activated. This
command makes it possible for the user to light a LED on a magnetic device to
indicate a good read.

Note: The transactions continues to execute during the LED time durations
(asynchronous).

Format:

LED ( indicator, time_on )
PANEL_LED_1 (1-99)
PANEL_LED_2* WAIT_FOREVER
PORT_A_LED_1
PORT_A_LED_2
PORT_A_LED_3
PORT_B_LED_1
PORT_B_LED_2
PORT_B_LED_3
BEEPER*

* BEEPER and PANEL_LED_2 are valid only for the 7526 terminal.

Parameters:

indicator - The LED to turn on. On the 7526, the choices include one of the
two panel LEDs, one of three possible LEDs on a magnetic device
attached to either sensor Port 1 or Port 2 or the beeper. On
the 7527, the choices include the Panel LED or one of the three
possible LEDs on a magnetic device attached to either sensor Port
1 or Port 2.

time_on - The number of 20 millisecond time intervals to light the
specified LED. It is expressed in multiples of 20 milliseconds.
For example, entering 25 in the data entry field yields the
duration of 500 milliseconds. WAIT_FOREVER lights the
specified LED forever.

Example:

Turn on the panel LED for 500 milliseconds.

LED ( PANEL_LED_1, 25 )

LF Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

This command, called the latch function, instructs the terminal to repeat the
transaction instructions until the CANCEL key is pressed, sending a
transaction after each complete routine. This feature can be used for
repetitive data entry routines. This must be the first command in a
transaction program.

This command exists for backwards compatibility with the original 7525
terminal. This command should never be needed in a 7524/Client, 7526, or 7527
terminal instead, a GOTO command accomplishes the same thing.

Note: If the transaction program using the LF command does not contain any
commands that read input, pressing cancel does not stop the latching
function. In this case, the terminal must be turned off, then back on.

Format:

LF ( )

Parameters:

None

Example:

Specify that this transaction program is to be latched.

LF ()

MATH Command
------------
Supported Terminals:

DCConnect Client version 2.1.0 or later

Description:

Perform math operation on the contents of terminal user variables. The
operations include:

Addition (+)
Subtraction (-)
Multiplication (*)
Division (/)
Modulus (%) (Calculates remainder)
Integer Division (\)

The operands are converted to floating point before the operation is
performed. The result of the operation is stored in the target as a
signed floating point value with 6 digits to the right of the decimal point.
This is true even for integer division, but in this case, the 6 digits
to the right of the decimal point are always zeros.

Note: The exception to this are the flavors of the DCConnect Client that are
built for the Antares terminals. Floating point operations are not supported
on these devices; therefore all math operations are integer operations.
Version 2.2.0a of the DCConnect Client for the Antares includes the change
that forces all comparison operations to be integer operations.

For example:

MATH (UV1 = 6 + 2)

will result in UV1 being set to:

8.000000

If some other representation is required, use the FRMT command with
the CUSTOM_INTEGER option to change that. For example:

FRMT (UV1, CUSTOM_INTEGER, "%d")

will result in UV1 being formatted as:

For more details, see FRMT.

If the target is the same as the first operand then a shortcut form
of the command is allowed. For example:

MATH (UV1 = UV1 + 1)

could instead be written as:

MATH (UV1 += 1)

If the second operand of a division operation, modulus operation or
integer division operation evaluates to 0 (or 0.0) the terminal will abort
the transaction program and give a divide by zero error.

Format:

MATH ( target = operand1 operator operand2 )
UV1-UV99 UV0-UV99 + UV0-UV99
Named Variable Named Variable - Named Variable
Local Variable Local Variable * Local Variable
Parameter Parameter / Parameter
uvRC, gRC uvRC, gRC % uvRC, gRC
PF1-PF12 PF1-PF12 \ PF1-PF12
TOUCH1-TOUCH40 TOUCH1-TOUCH40 TOUCH1-TOUCH40
numeric constant numeric constant

or if target is same as operand1 the following syntax can be used:

MATH ( Target operator= operand2)
UV1-UV99 += UV0-UV99
Named Variable -= Named Variable
Local Variable *= Local Variable
Parameter /= Parameter
uvRC, gRC %= uvRC, gRC
PF1-PF12 \= PF1-PF12
TOUCH1-TOUCH40 TOUCH1-TOUCH40
numeric constant

Note: For the first format, the equal sign must be surrounded by white
space. For the shortened format, the 2 character combination of
operator and equal sign cannot be separated and the pair must also
be surrounded by white space.

Parameters:

target - The user variable, local variable, parameter, return code
variable, PF string or touch point string that is to receive
the result of the math operation. User variable 0 is not
valid as the target.

operand1 - Either a numeric constant or a user variable (including 0),
local variable, parameter, return code variable, PF string
or touch point string that is the first operand in the math
operation.

operator - Indicates which math operation is to be peformed using the
operand. Must be one of the following:

+ - * / % \

where '+' indicates addition,
'-' indicates subtraction,
'*' indicates multiplication,
'/' indicates division,
'%' indicates moduluss (find remainder), and
'\' indicates integer division

operand2 - Either a numeric constant or a user variable (including 0),
local variable, parameter, return code variable, PF string
or touch point string that is the second operand in the math
operation.

Examples:

Multiply the parameters for pNumRows and pNumCols and store the result
in the local variable lNumChars:

MATH ( lNumChars = pNumRows * pNumCols )

Subtract 1 from the row counter local variable lNumRows:

MATH ( lNumRows -= 1 )

MODE Command
------------
Supported Terminals:

7524/Client, 7527

Description:

Change the mode (interactive or buffered) of the current transaction.

After the transaction program completes, the mode reverts back to what it was
prior to the start of the transaction program. For the 7524/Client terminal,
this command cannot be used if the terminal is configured to be interactive
or buffered mode.

Format:

MODE ( mode )
INTERACTIVE
BUFFERED

Parameters:

mode - The mode of the current transaction.

Example:

Set the mode for this transaction to be buffered

MODE ( BUFFERED )

MSG Command
-----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

Display a message

Format:

MSG ( "message text" / name / number )

Parameters:

"message text" / name / number - This can be an inline message enclosed in double
quotes or it is a message name/number defined in one of the MESSAGE
commands.

Example:

Display the message "Enter your ID" on the terminal display using an inline message.

MSG ( "Enter your ID" )

Display the message "Enter your ID" on the terminal display using a named message.

MESSAGE (MSG_ENTER_YOUR_ID, "Enter your ID", 0)

MSG ( MSG_ENTER_YOUR_ID )

NAV Command
-----------
Supported Terminals:

7527

Description:

The point in the navigation screen region where input is to take place. For
more information about screen navigation, see the BNAV command.

Format:

NAV ( row, column )
(1-20) (1-40)

Parameters:

row - The row position on the 7527 in which input takes place. Row 1 is
the top row of a screen.

column - The column position on the 7527 in which input takes place. Column
1 is the left most column of a screen.

Example:

Define a navigation input position at row 3, column 14.

NAV ( 3, 14 )

NAVZONE Command
---------------
Supported Terminals:

7527

Description:

Begin or end a navigation region. This command is an alias for both BNAV or
ENAV. For more information about screen navigation, see the BNAV command.

The utility BPTCD32 will write out the NAVZONE command rather than BNAV or
ENAV when processing a .PGM file.

Format:

NAVZONE ( )

Parameters:

None

Examples:

Start a screen navigation region.

NAVZONE ( )

End a screen navigation region.

NAVZONE ( )

NK Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

Read a fixed number of characters from the numeric keypad. For the
7524/Client, 7526, and 7527 DCT's, the value read becomes the value of the
last read variable (VAR 0) and becomes part of the transaction record, unless
automatic transaction building has been turned off. For the 7525 DCT's, the
value read is added to the transaction record.

Note: All the characters on the numeric keypad are accepted as input for the
command. On the 7527 DCT's, acceptable input includes decimal points ".",
comas ",", and hyphens "-". On the 7525 and 7526 DCT's, acceptable input
includes spaces and the characters + . - # $ % / & * . For the 7524/Client,
acceptable input includes spaces and the characters "." and "-".

Format:

NK ( data_length, validation_file, validation_type, autofill, position, display_buffer )
(1 - 40) (filename.VAL) ABORT_IF_PRESENT NO_AUTOFILL (1-40) NO_DISPLAY_DATA
NO_VALIDATION ABORT_IF_ABSENT AUTOFILL DONT_USE DISPLAY_DATA
SKIP_IF_PRESENT DONT_USE
SKIP_IF_ABSENT
NONE

Parameters:

data length - The number of characters to be read from the alpha-numeric
keypad. The length specified must be in the range 1-40.

validation_file - The name of the validation file to be used to validate the
input data.

validation_type - The action to be taken on the transaction as the result of
validating the input data.

autofill - Determines whether the field is padded with blanks to it's
maximum size as determined by the data_length parameter.

position - The column on the display where the input field starts. An
entry of zero right justifies the input field on a
40-column display. The column specified must be in the
range 1-40.

display_buffer - Determines whether or not the data read from the input
device is displayed on the terminal's display as it is
read.

Example:

Read 10 characters starting at column 30 and verify them for presence in file
PIN.VAL. Do not display the data on the terminal display.

NK (10, "PIN.VAL", ABORT_IF_ABSENT, DONT_USE, 30, NO_DISPLAY_DATA )

NOOP Command
------------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

Does nothing! However, this can be useful in cases where a CCFR command
might return either SKIP or NO_SKIP but you want to ignore that result.
Putting a NOOP command right after the CCFR command ensures that the only
command that could be skipped is the NOOP command.

IMPORTANT NOTE: Do not use the NOOP command as the first command of a
transaction program. If you do, the terminal will think the entire
program is empty.

Format:

NOOP ()

Parameters:

None

Example:

Make sure that the call to CCFR does not skip any meaningful commands - whether
it returns SKIP or NO_SKIP

CCFR (3, "PRINT LABEL UV1")
NOOP ()

ONKEY Command
-------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Used to wait for a particular key to be pressed and transfer execution to
another step in the current program or another program. This command is
valid with the 7526 with microcode version 2.0+ and with the 7524/Client and
7527 terminals. If a timeout occurs the transaction program is aborted.

This command is useful for creating multi-tiered menus that, for example,
re-use the same PF keys on your terminals.

For a single ONKEY command there may be up to 50 key IDs, each mapping
to separate programs or steps. The user must select a key ID, a program to
transfer control, and a label / step number within the current or other
program. To define the step, you must first know to which program you are
transferring. View that program to determine the entry point. The program
step is specified by the step number or label on the 7524/Client or 7527 and
by a label on the 7526.

Format:

The last three parameters can be repeated up to 49 more times to handle up to
50 different types of key presses for a single ONKEY command.

ONKEY ( timer, key ID, program ID, label, ...,)
WAIT_FOREVER_T F1-F28 (1-28) ABORT_PROGRAM "label name"
WAIT_TIMER !PF1-PF12 (31-42) THIS_PROGRAM (step number)
!!SPF1-SPF12 (43-54) F1-F28, (1-28)
!!!TCH1-TCH40 (73-112) BADGINIT, (29)
!!!!KEY0-KEY9 (31-40) FASTCLK, (30)
PF1-PF12 (31-42)
++ASCII_1 - ASCII_255 SPF1-SPF12 (43-54)
++EXTENDED_1 - EXTENDED_255 RS232 (55)
++ASCII_ENTER, KEY_ENTER RS232_2 (56)
++ASCII_SPACE, KEY_SPACE DI0-DI7 (57-64)
++KEY_CANCEL *RES2-RES9 (65-72)
++KEY_BACKTAB *TCH1-TCH40 (73-112)
++KEY_END, KEY_OK, KEY_SEND *ADDL1-ADDL8 (113-120)
++KEY_DELETE, KEY_CLEAR *TODCLK (121)
++KEY_BACKSPACE, KEY_BACKRUB, KEY_PA1
++KEY_TAB, KEY_PA2 1-64, *65-121
++KEY_INSERT, KEY_FILL

!Not valid for 7526 *7526 terminals can only use
!!7527 m1 or m2 only program IDs with values up to 64
!!!7527 m2 only
!!!!7526 only

++Only for version 2.1.0 of
DCConnect Client or later

Parameters:

timer - Indicates how long the terminal waits for any of the
specified keys to be pressed. The choices are
'WAIT_FOREVER_T' or 'WAIT_TIMER' which is the terminal's
input prompt duration.

key ID - The Id of the key that, when pressed, causes program
execution to be transferred to the specified program ID and
label/step that follow. The key ID may be any of the function
keys, PF keys, Shifted PF keys or Touch points, depending on
the model terminal being used.

New in version 2.1.0 of DCTPB, for transaction programs that
run on version 2.1.0 of the DCConnect Client or later, are
a set of new keywords for special keys along with special
notation to be able to specify any regular key or extended
key. The new keywords are:

KEY_ENTER, ASCII_ENTER - For the Enter key
KEY_SPACE, ASCII_SPACE - For the Space bar
KEY_CANCEL - For the Esc key. Note: When this is
used in an ONKEY command, it overrides
the default behavior of the Esc key
which is to cancel the transaction
program.
KEY_TAB, KEY_PA2 - For the Tab key
KEY_BACKTAB - For the Shift-Tab key
KEY_END, KEY_OK, KEY_SEND - For the End key
KEY_BACKSPACE, KEY_PA1,
KEY_BACKRUB - For the Backspace key
KEY_DELETE, KEY_CLEAR - For the Delete key
KEY_INSERT, KEY_FILL - For the Insert key

Note: The obscure key names such as KEY_PA1, KEY_PA2, and KEY_OK
are legacy names corresponding to constants found in CFRAPI24.H
which refer to special keys on the legacy IBM 7527 terminal.

For any other key, not covered by the keywords above, you must specify
the ASCII key value or Extended key value using the syntax:

ASCII_nnn

for normal ASCII keys or the syntax:

EXTENDED_nnn

for extended keys where, in both cases, 'nnn' is a value from 1-255.

For example, if you wanted to act on the 'X' key, which has
the ASCII value of 88, you can use the following keyword:

ASCII_88 - For the 'X' key

Note that lower case 'x' has the ASCII value 120 which would use
the following keyword:

ASCII_120 - For the 'x' key

However, if all keyboard input is being converted to upper case,
as is usually the default for the DCConnect Client, then only
ASCII_88 for the upper case 'X' should be used.

The EXTENDED_nnn notation is used for special keys such as
Home, PgUp, PgDn, or the the Arrow keys. For example, the
left arrow key has the extended key value of 75 and so the
following keyword would be used:

EXTENDED_75 - For the left arrow

The right arrow key has the extended value of 77 and so the
following keyword would be used:

EXTENDED_77 - For the right arrow

For any of the extended keys that are covered by one of the
KEY_xxx keywords listed above, do not use the corresponding
EXTENDED_nnn keyword because for most of these keys, some
special internal mapping is being done for those keys and
so the EXTENDED_nnn values will not work. For example, the
End key normally has the extended key value of 79. But the
internal mapping uses 3 instead. So EXTENDED_79 is not
the End key. Use KEY_END instead.

Note that the DCConnect Client by default uses the Home
key (EXTENDED_71), question mark key (ASCII_63) and the
equal sign key (ASCII_61) to bring up the DCConnect Client
menus. Therefore if you need to use any of these keys in
the ONKEY command, you must define an alternate key to
bring up the menus using the MENU_KEY keyword in EMULATOR.INI.

Similarly, by default the arrow keys are used to scroll
the screen for the DCConnect Client. So if you need to use
any of the arrow keys in an ONKEY command, you must disable
the scrolling of the screen via the arrow keys by using the
IGNORE_ARROW_KEYS keyword in EMULATOR.INI. This will of
course prevent the scrolling of the contents of the screen.

The following tables gives many of the common ASCII and
EXTENDED key values that are not covered by the keywords
above:

! = ASCII_33 0-9 = ASCII_48 - ASCII_57 | = ASCII_124
" = ASCII_34 : = ASCII_58 } = ASCII_125
# = ASCII_35 ; = ASCII_59 ~ = ASCII_126
$ = ASCII_36 < = ASCII_60
% = ASCII_37 = = ASCII_61 PF1-PF10 = EXTENDED_59 -
& = ASCII_38 > = ASCII_62 EXTENDED_68
' = ASCII_39 ? = ASCII_63 Home = EXTENDED_71
( = ASCII_40 @ = ASCII_64 Up = EXTENDED_72
) = ASCII_41 A-Z = ASCII_65 - ASCII_90 PgUp = EXTENDED_73
* = ASCII_42 [ = ASCII_91 Left = EXTENDED_75
+ = ASCII_43 \ = ASCII_92 Right = EXTENDED_77
, = ASCII_44 ] = ASCII_93 Down = EXTENDED_80
- = ASCII_45 ` = ASCII_94 PgDn = EXTENDED_81
. = ASCII_46 a-z = ASCII_95 - ASCII_122
/ = ASCII_47 { = ASCII_123

A value of ABORT_PROGRAM indicates that the program should
be aborted.

A value of THIS_PROGRAM indicates execution should stay
within the currently executing program.

label - Defines the step within the specified transaction program to
which execution should be transferred. The label is a 1-30
character user defined name given to a program step. The
label is not tied to a step number and is independent of
command insertion/deletion. (Although when DCTPB compiles
7527 and 7524/Client transaction programs, it converts
labels to step numbers).

For 7526 terminals, only the first 15 characters of the
label are considered significant. Therefore all labels used
in the same 7526 transaction program must be unique in their
first 15 characters.

For a 7524/Client or 7527 program, if the branch is to a
program ID other than ABORT_PROGRAM, END_OF_PROGRAM or
THIS_PROGRAM and a label is used instead of a step number then
the ENFORCE_BINDINGS keyword must be used in the TERMTYPE command.
For more details, see the command TERMTYPE above.

stepnumber - For 7524/Client or 7527 programs, a stepnumber can be used at
any time. However, because the addition and removal of
commands in a program can change the validity of step
numbers, it is recommended that labels be used instead.
DCTPB will convert labels to step numbers when compiling.
See the comments above for 'label' for important information
about how to use labels. It is recommended that the only
time you use a step number is when the step is the first in
the program.

Examples:

Wait for input prompt duration for F1 to be pressed, then go to step 12 of
the same program.

ONKEY ( WAIT_TIMER, F1, THIS_PROGRAM, 12,)

Wait for input prompt duration for PgDn or PgUp key to be pressed (this
assumes the IGNORE_ARROW_KEYS keyword is in effect).

ONKEY ( WAIT_TIMER, EXTENDED_75, THIS_PROGRAM, LABEL_LEFT_PRESSED,
EXTENDED_77, THIS_PROGRAM, LABEL_RIGHT_PRESSED )

Wait forever for Enter or Cancel (Esc) keys to be pressed.

ONKEY ( WAIT_FOREVER_T, KEY_ENTER, THIS_PROGRAM, LABEL_ENTER_PRESSED,
KEY_CANCEL, THIS_PROGRAM, LABEL_CANCEL_PRESSED )

ONSUB Command
-------------
Supported Terminals:

7524/Client, 7526

Description:

Used to wait for a particular key to be pressed and transfer control to a
specified subroutine in the current program or another program. At the
completion of the subroutine, control returns back to the original program
step by way of the RETURN (return from subroutine) Command. If a timeout
occurs the transaction program is aborted. This command is useful for
creating multi-tiered menus that, for example, re-use the same function keys
on your terminal. For a single ONSUB command there may be up to 50 key
IDs, each mapping to separate programs or steps. The user must select a key
ID, a program to transfer control, and a step within the current or other
program. The program step is specified by a program label created with the
LABEL Command.

For 7526 terminals, this command is available only if the microcode level is
version 2.0 or later.

For 7524/Client terminals, this command is available if the flash/program
level is 1.11C or later.

Format:

The last three parameters can be repeated up to 49 more times to handle up to
50 different types of key presses for a single ONSUB command.

ONSUB ( timer, key ID, program ID, label, ...,)
WAIT_FOREVER_T F1-F28 (1-28) ABORT_PROGRAM "label name"
WAIT_TIMER !PF1-PF12 (31-42) THIS_PROGRAM (step number)
!!SPF1-SPF12 (43-54) F1-F28, (1-28)
!!!TCH1-TCH40 (73-112) BADGINIT, (29)
!!!!KEY0-KEY9 (31-40) FASTCLK, (30)
PF1-PF12 (31-42)
++ASCII_1 - ASCII_255 SPF1-SPF12 (43-54)
++EXTENDED_1 - EXTENDED_255 RS232 (55)
++ASCII_ENTER, KEY_ENTER RS232_2 (56)
++ASCII_SPACE, KEY_SPACE DI0-DI7 (57-64)
++KEY_CANCEL *RES2-RES9 (65-72)
++KEY_BACKTAB *TCH1-TCH40 (73-112)
++KEY_END, KEY_OK, KEY_SEND *ADDL1-ADDL8 (113-120)
++KEY_DELETE, KEY_CLEAR *TODCLK (121)
++KEY_BACKSPACE, KEY_BACKRUB, KEY_PA1
++KEY_TAB, KEY_PA2 1-64, *65-121
++KEY_INSERT, KEY_FILL

!Not valid for 7526 *7526 terminals can only use
!!7527 m1 or m2 only program IDs with values up to 64
!!!7527 m2 only
!!!!7526 only

++Only for version 2.1.0 of
DCConnect Client or later

Parameters:

timer - Indicates how long the terminal waits for any of the
specified keys to be pressed. The choices are
'WAIT_FOREVER_T' or 'WAIT_TIMER' which is the terminal's
input prompt duration.

key ID - The ID of the key that, when pressed, causes program
execution to be transferred to the specified program ID and
label/step that follow. The key ID may be any of the function
keys, PF keys, Shifted PF keys or Touch points, depending on
the model terminal being used.

A value of ABORT_PROGRAM indicates that the program should
be aborted.

A value of THIS_PROGRAM indicates execution should stay
within the currently executing program.

label - Defines the step within the specified transaction program to
which execution should be transferred. The label is a 1-30
character user defined name given to a program step. The
label is not tied to a step number and is independent of
command insertion/deletion. (Although when DCTPB compiles
7527 and 7524/Client transaction programs, it converts
labels to step numbers).

For 7526 terminals, only the first 15 characters of the
label are considered significant. Therefore all labels used
in the same 7526 transaction program must be unique in their
first 15 characters.

stepnumber - For 7524/Client or 7527 programs, a stepnumber can be used at
any time. However, because the addition and removal of
commands in a program can change the validity of step
numbers, it is recommended that labels be used instead.
DCTPB will convert labels to step numbers when compiling.
See the comments above for 'label' for important information
about how to use labels. It is recommended that the only
time you use a step number is when the step is the first in
the program.

Examples:

Wait forever for F1 to be pressed, then call subroutine 'test_sub' in this
transaction program.

ONSUB ( WAIT_FOREVER_T, F1, THIS_PROGRAM, "test_sub" )

Wait for input prompt duration for PgDn or PgUp key to be pressed (this
assumes the IGNORE_ARROW_KEYS keyword is in effect).

ONSUB ( WAIT_TIMER, EXTENDED_75, ADDL1, SUB_SCROLL_LEFT,
EXTENDED_77, ADDL1, SUB_SCROLL_RIGHT )

Wait forever for Enter or Cancel (Esc) keys to be pressed.

ONSUB ( WAIT_FOREVER_T, KEY_ENTER, ADDL1, SUB_ENTER_PRESSED,
KEY_CANCEL, ADDL1, SUB_CANCEL_PRESSED )

QUERY Command
-------------
Supported Terminals:

Client 3.0.8i and later

Description:

Used to query information about a particular variable or the Client environment. The following
query types are available:

LENGTH - Returns the number of characters in the specified variable

IS_NUMERIC - Returns Y or N depending on whether the specified variable contains only digits

IS_NUMBER - Returns Y or N depending on whether the specified variable contains a valid
number. The number may contain a minus sign to start with and may contain
a decimal point.

NUM_ROWS - Returns the current value of the NUM_ROWS setting that can be set in EMULATOR.INI.
It is the number of rows that is visible at one time (the height of the view port).
Note there is always a 20x40 'canvas' to which the transaction program can write;
but the view port can be configured to be anything from 1 to 20 rows in height.

NUM_COLS - Returns the current value of the NUM_COLS setting that can be set in EMULATOR.INI.
It is the number of columns that is visible at one time (the width of the view port).
Note there is always a 20x40 'canvas' to which the transaction program can write;
but the view port can be configured to be anything from 1 to 40 columns in width.

NUM_COLUMNS - Same as NUM_COLS

CURSOR_ROW - Returns the current cursor row - a value from 1 to 20.

CURSOR_COL - Returns the current cursor row - a value from 1 to 40.

CURSOR_COLUMN - Same as CURSOR_COL

DATE - Returns the date in the format MM/DD/YYYY

KEY_NAME_VALUE - Returns the numeric value (1-121) of the key name found in the specified variable. Here
is the mapping between key names and their numeric values

F1 - F28 maps to 1 - 28
BADGINIT maps to 29
FASTCLK maps to 30
PF1 - PF12 maps to 31 - 42
SPF1 - SPF12 maps to 43 - 54
RS232 maps to 55
RS232_2 maps to 56
DI0 - DI7 maps to 57 - 64
RES2 - RES9 maps to 65 - 72
TCH1 - TCH40 maps to 73 - 112
ADDL1 - ADDL8 maps to 113 - 120
TODCLK maps to 121

Format:

QUERY ( ResultVar, QueryType [, SourceVar ] )

UV0-UV99 LENGTH UV0-UV99
Named Variable IS_NUMERIC Named Variable
Local Variable IS_NUMBER Local Variable
Parameter NUM_ROWS Parameter
uvRC, gRC NUM_COLS uvRC, gRC
NUM_COLUMNS
CURSOR_ROW
CURSOR_COL
CURSOR_COLUMN
DATE
KEY_NAME_VALUE

Parameters:

ResultVar - The terminal variable into which the result of the query will
be stored. It may be any global or local user variable,
parameter or the return code variable.

The ResultVar is cleared out before the result is put into it.

QueryType - One of the query types listed and described above.

SourceVar - For the following query types, this is the variable that
the query should be performed against:

LENGTH IS_NUMERIC IS_NUMBER KEY_NAME_VALUE

The variable can be a global variable, local variable,
parameter or the return code variable.

Examples:

Get the current date and store it in the return code variable:

QUERY ( uvRc, DATE )
RETURN ( uvRc )

Get the length of the user variable uvLocation and store it in the uvLength user variable:

QUERY ( uvLength, LENGTH, uvLocation )

Get the current width of the view port:

QUERY ( uvScreenWidth, NUM_COLS )

RDDI Command
------------
Supported Terminals:

7526, 7527

Description:

Read the value of a given DI/DO point. Both digital input and digital output
points may be read although this command is intended for reading digital
input. The value read, in the form of an ASCII 0 or 1, becomes the value of
the last read variable (VAR 0) and becomes part of the transaction buffer
unless automatic transaction building has been turned off. If the 7527
switch is set to parallel rather than DI/DO at the time this command is
executed, an error occurs at the 7527 terminal.

Format:

RDDI ( point_number )
(0-7)

Parameters:

Point - The point whose value is to be read. It must be in the range 0-7.

Example:

Read digital input point 3.

RDDI ( 3 )

READ Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

This command provides a general purpose read capability for the 7524/Client,
7526 and the 7527 terminal. You may choose to read either fixed or variable
length data from one or more of the following input devices:

numeric keypad
alphanumeric keypad
sensor ports
RS-232 port (7526 and 7527 only)
PF Key string (7526 and 7527 only)
Touch Point (7527 Model 002, only).

A choice may be to verify the input against a verification file.

The data read excluding any secure head character, hex 10, that might be
present on a magnetic read, becomes the value of the last read variable (VAR
0) and becomes part of the transaction buffer unless automatic transaction
building has been turned off.

On the 7527, when using RS-232 communications, a read is done of the number
of characters specified in the length, or until the termination sequence, as
specified in the RS-232 configuration parameters, is reached. If neither the
proper number of characters nor the termination sequence is received by the
timeout default indicated as part of the terminal configuration, the
transaction is aborted.

When reading from a sensor port, the transaction is aborted if there is no
response before the input prompt duration in the terminal configuration
expires. Any keyboard read that is not satisfied is aborted after the
timeout for the input prompt duration expires.

For the 7524/Client and 7527, if either the numeric keypad or alpha-numeric
keypad is selected as an input device, the PF Key and Touch Point string
(7527 only) definitions can be used to fill the input fields by pressing the
desired PF Key or Touch Point.

Format:

READ ( device_mask, read_type, read_length, validation_file, validation_type, echo )
NUMERIC_KEYPAD FIXED_LEN_READ (1-99) (filename.VAL) ABORT_IF_PRESENT ECHO_OFF_TIMEOUT
ALPHA_KEYPAD VARIABLE_LEN_READ ++Variable/Parm NO_VALIDATION ABORT_IF_ABSENT ECHO_ON_TIMEOUT
SENSOR_PORT SKIP_IF_PRESENT ECHO_OFF_WAIT
NUMERIC_DATA_ONLY SKIP_IF_ABSENT ECHO_ON_WAIT
PF_KEY NONE
TOUCH_SCREEN
EIA_232

++Valid only for DCConnect Client version 2.1.0 or later

Parameters:

device_mask - Device that is permitted for input. If multiple devices are
to be permitted, a vertical bar "|" must separate the
devices. For instance, "NUMERIC_KEYPAD|SENSOR_PORT".

read_type - Whether to read an exact (fixed) number of characters or to
allow a read of a variable number of characters.

read_length - The number of characters to read from the specified device
or devices. If the read is Fixed length, this is the exact
number of characters to read; if it is Variable length, this
is the maximum number of characters to read. The length
specified must be in the range 1-128.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

At runtime, the variable or parameter must contain
a numeric value from 0 to 128 or the transaction
program will abort. A value of 0 is interpreted as a
variable length read.

validation_file - It is the name of the validation file to be used to validate
the input data. An entry of NO_VALIDATION represents no
verification. Up to a maximum of 52 validation files may be
used, and may reside on the terminal, or the system unit.
For the 7526, 6 files may be downloaded to the terminal and
the remainder must reside on the system unit.

validation_type - Whether the validation is considered successful depends on
whether the data item is present or absent in the validation
file. The skip actions are only available on the 7526 with
microcode version 2.0+ and on the 7524/Client or 7527
terminal. If one of the aborted actions is chosen and the
attempted validation fails, the transaction is terminated
and a message appears on the display screen indicating the
validation failed. If one of the skip actions is chosen,
the next command defined for this transaction program is
skipped or executed based on the result of the validation.

Note: As of version 2.2.0a of the DCConnect Client, if a
skip is to be done and the next command is an IF
command, then the entire if-else construct is skipped.

echo - If Echo is ON then any input received from the keyboard, PF
Keys (7524/Client or 7527 only), Touch Points (7527 Model 2,
only), or sensor ports is displayed on the screen as it is
received. The input is displayed at the current cursor
location. If the read is from a magnetic device and the
first byte of data is a secure head indicator (hex 10), then
the badge content is not displayed when read. Instead,
an asterisk (*) is displayed for each input character. The
setting of Echo is only reflected in the command line if the
selected input device is the keyboard or sensor. Input from
the RS-232 port for the 7527 is never echoed to the screen.
Timeout is the length of time the terminal waits for user
input. The terminal can wait forever for user input or wait
only for the input Prompt duration.

Examples:

Read exactly six bytes of alpha-numeric data from the sensor ports or the
alpha-numeric keypad and verify the input is in the file BADGES.VAL. Echo
the input to the screen.

READ ( SENSOR_PORT|ALPHA_KEYPAD, FIXED_LEN_READ, 6, "badges.val", ABORT_IF_ABSENT, ECHO_ON_TIMEOUT )

Do the same READ except get the read length from the subroutine parameter pReadLen:

READ ( SENSOR_PORT|ALPHA_KEYPAD, FIXED_LEN_READ, pReadLen, "badges.val", ABORT_IF_ABSENT, ECHO_ON_TIMEOUT )

RETURN Command
--------------
Supported Terminals:

7524/Client, 7526

Description:

Return from a subroutine. For more information about calling subroutines, see the
GOSUB command or CALL command.

For 7526 terminals, this command is available only if the microcode level is
version 2.0 or later.

For 7524/Client terminals, this command is available if the flash/program
level is 1.11C or later.

For programs that will run on version 2.1.0 or later of the DCConnect Client,
the RETURN command can specify a value to be returned. Whatever value is
specified is assigned to the special return code user variable, uvRC (aka gRC).
uvRC is cleared before the specified value is assigned.

If no parameter is provided on the RETURN command, uvRC is cleared.

The value to be returned from the subroutine can be specified as any of the following:

Returning uvRc (gRC) is the only way to preserve the current value of uvRC when
returning from the subroutine. Use this syntax when you explicitly set uvRC
elsewhere in the subroutine and do not want to change its value when returning
from the subroutine.

For more information about subroutines, please see Subroutines.

Format:

RETURN ( ++ReturnValue )

UV0-UV99
Named Variable
Local Variable
Parameter
uvRC, gRC
PF1-PF12
TOUCH1-TOUCH40
numeric constant
"text"
Named message

++Valid only for version 2.1.0 or later of the DCConnect Client

Parameters:

ReturnValue - For programs that will run on version 2.1.0 or later of the
DCConnect Client, this specifies the value that will be
assigned to uvRC as the subroutine returns control to its
caller. See the discussion above for more information
about what can be returned and how uvRC is affected.

Example:

End the subroutine and return to the caller program. For the DCConnect Client
version 2.1.0 and later, this will clear uvRC (gRC) as well.

RETURN ()

Return from the subroutine, preserving the current value of uvRC:

RETURN (uvRC)

Return from the subroutine, setting the value of uvRC to the 2 byte string "OK":

RETURN ("OK")

Return from the subroutine, setting the value of uvRC to the ASCII representation
of the number 12:

RETURN (12)

RETURN ("12")

Return from the subroutine, setting the value of uvRC to the value of the local
variable lResult that was defined in the subroutine:

SUB ADDL1:DoSomething()

DECLARE (lResult = 0)

// Your code here that might change 'lResult'

RETURN (lResult)

ENDSUB()

SEND Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

This command provides a general purpose Write facility for the 7524/Client,
7526 and 7527 terminals.

In the case of the HOST or RS_422 port, a time stamp and a sequence number is
automatically appended to the transaction. Writing to the host port is used
when the AUTO feature is turned off and the user is controlling all
transaction building and transmission himself. This enables him to send a
transaction record before the end of the transaction and possibly finish up
the transaction program with some printing or other processing that does not
generate data needed by the system unit. Multiple transactions may be sent
from a single transaction program.

When using the RS-232 port on 7524/Client, 7526, and 7527 terminal, you must
provide all the framing characters needed for the message. Give the framing
characters by configuring a predefined header and trailer that is added to
every record sent over the RS-232 port (7524/Client or 7527 only), or by
building an output message in a user-variable.

On the 7527, if the printer is the selected target device, and the 7527
parallel port switch is set to DI/DO rather than the printer at the time this
command is executed, an error will occur at the 7527 terminal.

Format:

SEND ( target, source, record_number )
PRINTER SRC_MESSAGE_FILE "any text data"
RS_422 message number / name
RS_232 SRC_USER_VARIABLE (0-998) or UV0-UV998
HOST SRC_TRANS_RECORD TRANSACTION RECORD
SRC_OTHER PF1-PF12, TOUCH1-TOUCH40
Named Variable
++Local Variable
++Parameter
++uvRC, gRC

++DCConnect Client 2.1.0 or later

Parameters:

target - The target device to which the source data is to be written. For
the 7526, the target device can be the host port and printer only
unless the terminal is equipped with the Ethernet/serial/parallel
adapter. On the 7527, the target device may be the RS-232 port, the
printer port or the host RS422 port. On the 7524/Client the target
may be the host port or the RS232 port.

source - This parameter is optional as of version 2.1.0 of DCTPB.
In fact it should be omitted if the source is a local
user variable, parameter or the return code variable.

If it is included, choose one of the following values:

- SRC_MESSAGE_FILE - The record_number
specifies a message (text, number or name).

- SRC_USER_VARIABLE - The record_number is
a global user variable.

- SRC_TRANS_RECORD - The record_number
specifies the transaction record.

- SRC_OTHER - The record_number specifies
either a PF string or a touch string.

record_number - If the source is a message this can be an inline
message enclosed in double quotes or it is a message
name/number defined in one of the MESSAGE commands.
Messages are allowed for all supported terminal types.

If the source is the transaction buffer, specify
TRANSACTION_RECORD. The transaction buffer is a
valid option for all supported terminal types.

For 7527 and 7524/Client terminals, the source may
be one of the PF strings (PF1 - PF12) or one of the
touch strings (TOUCH1 - TOUCH40).

New with DCTPB 2.1.0, for transaction programs that will
run on version 2.1.0 of the DCConnect Client, the data
to be sent can also come from a local variable, parameter
or the return code variable.

Example:

Send the contents of user-variable 1 to the RS-232 port:

SEND ( RS_232, SRC_USER_VARIABLE, UV1 )

Send the contents of user-variable 1 to the RS-232 port but don't use 2nd parameter:

SEND ( RS_232, UV1 )

SET Command
-----------
Supported Terminals:

Client

Description:

As of version 2.1.0 of the DCConnect Client, support for the SET command
was added. This command is equivalent to the APND command except that
it clears the target before appending to it.

For all the details please see APND.

SETSTR Command
------------
Supported Terminals:

Client

Description:

As of version 2.1.0 of the DCConnect Client, support for the SETSTR command
was added. This command is equivalent to the APNDSTR command except that
it clears the target before appending to it.

For all the details please see APNDSTR.

Set_Language Command
--------------------
Supported Terminals:

Client 3.0.8f and later, text scripts only (DCTPB compile will ignore this command)

Description:

Use this command to change the current language to one of the languages
defined in any of the Start_Language blocks.

For a discussion of language blocks and multiple language support, please
see Multiple Language Support.

This command is only valid for the DCConnect Client 3.0.8f and later when it is
using the SCRIPT_NAME parameter to load text script flies directly.

Format:

Set_Language ( Language_Identifier )

Parameters:

Language_Identifier - One of the Language_Indentifier names used in any of the
Start_Language blocks.

Examples:

For an example of the Set_Language command, see Multiple Language Support.

SF Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

This command is used to combine the input from two different transaction
programs to form a single transaction. When the final data input for the
first transaction program has been completed, the standard link prompt
(message 9) from the message file is displayed. After the second transaction
program is initiated, all input that is added to the transaction buffer from
the second program is appended after the data from the first program. In
addition the program number of the second program is put in the transaction
buffer after the data from the first program and before the data from the
second program. When the second program completes, a single transaction is
sent from the terminal containing the data from both transaction programs.

The SF command must be the first command in a transaction program. The
linked transaction program cannot itself contain an SF command (it can
contain an LF command).

This feature is particularly useful for the 7525 terminal that has a limited
number of commands in each transaction program. The 7525 and 7526 terminals
do not allow any data verification to be done in any transaction program
command in the linked second transaction program. These restrictions do not
apply to any of the other terminal types. The transaction data buffer may
still only contain 108 bytes (prior to adding date/time stamp and other
framing characters).

This command exists for backward compatibility with the original 7525
terminal. This command should never be needed in a 7524/Client, 7526, and
7527 terminal.

Format:

SF ( )

Parameters:

None

Example:

Link to a second function transaction program at the end of this one.

SF ( )

SHOW Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

This command causes data from a selected source to be written to the
terminal's display screen. The data is written at the row and column
specified, and is written with the data attributes specified. If both the
row and the column are set to zero, the data is shown at the current cursor
position. If the row is set to zero, then the column must be zero and if the
column is set to zero, then the row must be zero. The data attribute, valid
only for the 7524/Client and 7527, is only valid for data being displayed on
this one command; the display attribute reverts to normal immediately after
this display command completes.

Format:

SHOW ( source, record_number, row, column, attrib )
SRC_MESSAGE_FILE "any text record" (1-20) (1-40) UNDERLINE
message number/name (1-2)* (1-40) REVERSE
SRC_USER_VARIABLE UV0-UV998** CURRENT_ROW+ CURRENT_COLUMN+ REVERSE_UNDER
SRC_TRANS_RECORD TRANSACTION_RECORD PREVIOUS_ROW++ PREVIOUS_COLUMN++ BLINK
SRC_OTHER (PF1-PF12)*** NEXT_ROW++ NEXT_COLUMN++ BLINK_UNDER
(TOUCH1-TOUCH40)*** ++Variable/Parm ++Variable/Parm BLINK_REVERSE
BLINK_REVERSE_UNDER
NORMAL*
Named Variable
++Local Variable
++Parameter
++uvRC, gRC

* The only valid values for the 7526
** Only the 7526 supports 999 user-variables
*** Only 7524/Client and 7527
+ For 7527 and 7526 terminals CURRENT_ROW and CURRENT_COLUMN can only be used when
both are used. For 7524/Client terminals, CURRENT_ROW can be used with a non-zero
column value and CURRENT_COLUMN can be used with a non-zero row value.
++ Only version 2.1.0 of the DCConnect Client or later

Parameters:

source - This parameter is optional as of version 2.1.0 of DCTPB.
In fact it should be omitted if the source is a local
user variable, parameter or the return code variable.

If it is included, choose one of the following values:

- SRC_MESSAGE_FILE - The record_number specifies a
message (text, number or name).

- SRC_USER_VARIABLE - The record_number is a global user
variable.

- SRC_TRANS_RECORD - The record_number specifies the
transaction record.

- SRC_OTHER - The record_number specifies either
a PF string or a touch string.

record_# - If the source is a message this can be an inline
message enclosed in double quotes or it is a message
name/number defined in one of the MESSAGE commands.
Messages are allowed for all supported terminal types.

If the source is the transaction buffer, specify
TRANSACTION_RECORD. The transaction buffer is a
valid option for all supported terminal types.

For 7527 and 7524/Client terminals, the source may
be one of the PF strings (PF1 - PF12) or one of the
touch strings (TOUCH1 - TOUCH40).

New with DCTPB 2.1.0, for transaction programs that will
run on version 2.1.0 of the DCConnect Client, the data
to be shown can also come from a local variable, parameter
or the return code variable.

row - The row position where the text should be shown. The valid range
for the row number depends on the terminal type and the display size
selected for the terminal:

The following keyword:

CURRENT_ROW

can also be used to indicate the cursor should remain in the
same row. For 7526/7527 terminals, CURRENT_ROW can only be
used if CURRENT_COLUMN is also used for the column parameter.

PREVIOUS_ROW
NEXT_ROW

If the cursor is already at row 1 and PREVIOUS_ROW is used or
if the cursor is already at row 20 and NEXT_ROW is used, the
cursor row will not be changed; the Client does not give an
error.

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

If the variable/parameter contains the value 0, that is
treated the same as CURRENT_ROW.

column - The column position where the text should be shown. The valid
range for the column number depends on the terminal type and the
display size selected for the terminal:

The following keyword:

CURRENT_COLUMN

can also be used to indicate the cursor should remain in the
same column. For 7526/7527 terminals, CURRENT_COLUMN can only
be used if CURRENT_ROW is also used for the row parameter.

As of version 2.1.0 of DCTPB, for transaction programs running on
version 2.1.0 or later of the DCConnect Client, the following
keywords can be used to tell the Client to move the cursor left
or right one column from its current position:

PREVIOUS_COLUMN
NEXT_COLUMN

The variable/parameter must contain an integer value or (as of
version 2.2.0a of the DCConnect Client) if the value contains
a decimal point, all digits after the decimal point must be 0.

If the variable/parameter contains the value 0, that is
treated the same as CURRENT_COLUMN.

attribute - The display attribute to use for this one message.
This parameter is valid for only 7524/Client and 7527
terminals. The possible display attributes include all
combinations of blinking, reverse video and
underlining. If no attribute is specified, the data is
displayed with no blinking, normal video and no
underlining, that is considered to be normal
attributes.

Example:

Display message "scan your badge" at row 4, column 5 in normal attribute
mode:

SHOW ( SRC_MESSAGE_FILE, "scan your badge", 4, 5, NORMAL )

Same command except that the first parameter is left out:
mode.

SHOW ( "scan your badge", 4, 5, NORMAL )

TERM Command
------------
Supported Terminals:

7524/Client, 7527

Description:

End the transaction program and send what is currently in the transaction
buffer. The transaction mode byte for such a transaction is "U" if the
terminal is currently in buffered mode or it is a "T" if the terminal is
currently in interactive mode.

Format:

TERM ()

Parameters:

None

Example:

Terminate this transaction program

TERM ()

TEST Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

For the 7526 with microcode version 2.0+, 7524/Client or 7527, this command
is used to test a single user-variable for the presence or absence of data.
Based on the results of the TEST Command, the next command can be skipped or
program execution can be transferred to another step in the current program
or another program. If the user-variable contains data, then the next
command is skipped otherwise, the next command is executed.

One way to remember this behavior is "Nothing = Next, Something = Skip".

Note: As of version 2.2.0a of the DCConnect Client, if a skip is to be done
and the next command is an IF command, then the entire if-else
construct is skipped.

Format:

TEST ( source )
(UV0-UV19) 7524/Client with flash/program level 1.10 or earlier, 7527
(UV0-UV99) 7524/Client with flash/program level later than 1.10
(UV0-UV998) 7526 only
Named Variable
++Local Variable
++Parameter
++uvRC, gRC

++ DCConnect Client version 2.1.0 or later

Parameters:

source - The number of the user-variable to be tested VAR 0-19 for 7524/Client
or 7527 or VAR 0-998 for 7526 with microcode version 2.0+.

7524/Client terminals with flash/program level later than 1.10 have
a maximum user-variable of 99 instead of 19.

New with DCTPB 2.1.0, for transaction programs that will run on
version 2.1.0 of the DCConnect Client, the data to be tested can
also come from a local variable, parameter or the return code
variable.

The TEST command and (as of version 2.2.0a of the DCConnect Client)
the IF command can be used within a subroutine to check whether a
subroutine parameter has been passed. (If empty, the variable has
not been passed - or an empty value has been passed.)

Examples:

Test user-variable 11 for the presence of data

TEST ( UV11 )

Test the optional parameter pExtraParm1 for the presence of data:

TEST ( pExtraParm1 )

VB Command
----------
Supported Terminals:

7524/Client, 7525, 7526, 7527

Description:

Read a variable number of characters from a sensor device but, unlike DB, do
not display the characters read on the display screen. For 7524/Client, 7526
and 7527 DCTs, the value read excluding the secure head character, hex 10,
that might be present on a magnetic read, becomes the value of the last read
variable (VAR 0) and becomes part of the transaction buffer unless automatic
transaction building has been turned off. For 7525 DCTs, the value read is
added to the transaction buffer.

Format:

VB ( data_length )
( 1 - 40 )

Parameters:

data length - The number of characters to be read from the alpha-numeric
keypad. The length specified must be in the range 1-40. When
the input is added to the transaction buffer, it is padded with
blanks to reach the maximum length.

Example:

Read and display a maximum of five characters from a sensor device.

VB ( 5 )

VERSION Command
---------------
Supported Terminals:

Client 3.0.8k and later, text scripts only (DCTPB compile will ignore this command)

Description:

Defines a version string for the scripts. The Client and Server use this value
to determine if the Client has the same version of the scripts that the server
has for it. When the Client starts up, it reads the locally stored scripts
and pulls out the Version from the scripts, if it is defined. The Client then
tells the server what version it has and if the server reads its copy of the
scripts and finds a different version string, the server initiates a download of
its copy of the scripts to the Client. But if the version from the Client
matches the version the server found, then no download is performed; the Client
uses its local copy.

Note that comparison is simply and equal to / not equal to comparison; it is not
a greater than or less than comparison.

It is recommended that the version string include the date in it so that it
indicates when it was created.

Note: The VERSION command is not used by the DCTPB compiler when it generates
a .PGM file from scripts; the DCTPB compiler just ignores the command. So the
scripts can be used for older devices that need to be downloaded from a .PGM
file as well as newer devices that can use the text-based script loading
capabilities of the DCConnect Client.

Format:

VERSION ( Version_String )

Parameters:

Version_String - A string from 1-32 characters indicating the version of the
scripts. It is recommended that this include the date.

This can optionally be enclosed in double quotes.

Example:

Set the version:

Version ( V4.5_2013-11-20 )

VRFY Command
------------
Supported Terminals:

7524/Client, 7526, 7527

Description:

Verify that a user-variable contains valid data by comparing it against the
contents of a validation file. Though most validations are done on the read
operation, it is possible to need to format the data, using the FRMT or APND
command, before validations can be done. The VRFY command makes is possible
to validate whenever convenient in the application.

Format:

VRFY ( source, validation_file, validation_type )
(0-998)* (filename.VAL) ABORT_IF_PRESENT
(UV0-UV998)* ABORT_IF_ABSENT
Named Variable SKIP_IF_PRESENT
++Local Variable SKIP_IF_ABSENT
++Parameter
++uvRC, gRC

* Only 7526
++ Only DCConnect Client version 2.1.0 or later

Parameters:

source - The variable or parameter that is to be verified. On the
7526, it is possible to perform validation on one of the
user-variables (VAR 1-998) or on the last data read
(VAR 0), although the latter sort of validation is best
done directly in the read operation, if possible. For the
7524/Client or 7527, it is possible to perform validation
on one of the user-variables (VAR 1-19) or on the last
data read (VAR 0), although the latter sort of validation
is best done directly in the read operation.

7524/Client terminals with flash/program level later than
1.10 have a maximum user-variable of 99 instead of 19.

New with DCTPB 2.1.0, for transaction programs that will
run on version 2.1.0 of the DCConnect Client, the data to
be verified can also come from a local variable, parameter
or the return code variable.

validation_file - This is the name of the verification file to be used to
validate the input data. Files may reside in the terminal
for local validation or on the PC for remote validation.

validation_type - Whether the validation is considered successful depends on
whether the data item is present or absent in the
validation file. The skip actions are available on the
7526 with microcode version 2.0+ and on the 7524/Client and
7527. If one of the aborted actions is chosen and the
attempted validation fails, the transaction is terminated
and a message appears on the display screen indicating the
validation failed. If one of the skip actions is chosen,
the next command defined for this transaction program is
skipped or executed based on the result of the validation.

Note: As of version 2.2.0a of the DCConnect Client, if a
skip is to be done and the next command is an IF
command, then the entire if-else construct is
skipped.

Example:

Verify that the data in user-variable 1 is found in file pin.val

VRFY ( UV1, "pin.val", ABORT_IF_ABSENT )

WRDO Command
------------
Supported Terminals:

7526, 7527

Description:

Write a value to a given DO point. It is not necessary to select a
particular value for the DO point to take; but you may select to toggle the
current value of the point, to make it the opposite of what it is currently.

The chosen setting may be held for a given time; after that it returns to its
original setting. This feature makes it possible to pulse a point for a time
which is useful in such applications as opening a door latch for a few
seconds after a valid employee badge has been read.

If the 7527 parallel port switch is set to printer rather than DI/DO at the
time this command is executed, an error occurs at the 7527 terminal.

Note: On the 7527, if two consecutive WRDO commands are issued, the second
one is not done until the duration from the first WRDO command expires.

Format:

WRDO ( point_number, write_value, time_value, mode )
(0-7) CLEAR_DO_POINT (1-99) NONE
SET_DO_POINT WAIT_FOREVER DO_ASYNCH *
TOGGLE_DO_POINT DO_SYNCH *

* valid for the 7526 only

Parameters:

point_number - The point whose value is to be written. It must be in the
range 0-7 and be a DO point.

write_value - The value that the point is to take. It is possible to
set the point on (high), to clear it (low), or to change its
state from on to off, or off to on, by selecting to toggle the
point.

Note: The meaning of "high" and "low" to the external device
may vary. Experiment to determine the true effect of the
values sent from a WRDO command on the external device. The
default state of all DO points on the 7526 and the 7527
terminals is "high", that means that all devices attached to
the terminal should be "active-low". Writing a DO high on the
7527 opens the circuit. However, \writing a DO high
on the 7526 closes the circuit.

time_value - The amount of time to hold the DO point at its new setting. A
value of zero, indicates that this is a permanent setting for
the point until it is changed in a later command. Any other
value is the amount of time in seconds to hold the setting of
the point before letting it revert to its setting when the
command was first executed.

mode - This defines the mode of execution for this command in the
transaction program. This mode can be:

DO_ASYNCH - Point is set and next command is executed
right away. (7526 only)
DO_SYNCH - Wait for the specied duration before next
command is executed. (7526 only)
NONE - Use this for 7527 and 7524/Client terminals.

Example:

Toggle the value of DO point 0 for 5 seconds on a 7527 terminal.

WRDO ( 0, TOGGLE_DO_POINT, 5, NONE )

WTDI Command
------------
Supported Terminals:

7526, 7527

Description:

Cause the transaction program to suspend execution and wait for a digital
input point to achieve a given state. If the point does not reach the
correct value within the time limit, the transaction is aborted. If the
point is already in the correct state when the command is executed, no wait
will be done.

Format:

WTDI ( point_number, wait_value, timeout )
(0-7) CLEAR_DI_POINT (1-99)
SET_DI_POINT WAIT_FOREVER

Parameters:

point_number - The point to be monitored until its value reaches the required
state. It must be in the range 0-7.

wait_value - The transaction waits until the point reaches this value. It
is possible to wait for the point to be cleared (low) or to be
set (high).

timeout - The amount of time in seconds to wait for the point to achieve
the required state. The timeout must be in the range 0
to 99 seconds.

Example:

Wait for DI point 3 to go high with a timeout of two seconds.

WTDI ( 3, SET_DI_POINT, 2 )

Command/Key Relationships
-------------------------
The following table shows the relationships between the transaction program
commands for data input, the display of data on the DCT, and the meaning of
some of the special keys during the command operation.

Information is displayed in the chart for the following keys and operations:

Input Shown

This tells whether the input in response to the command is displayed on
the terminal screen as it is entered. Although the chart may say yes to
the display of input, if the input is from a magnetic device, and the
first byte is the secure header indicator (a hex 10), the input is shown
as a series of asterisks (*) to the length of the input data.

Fill Key

This column indicates the effect, if any, of pressing the Fill Key on the
keyboard. A no indicates that the key has no effect. In some input
operations, pressing the Fill key before the completion of the input
causes the field to be filled with leading zeros or trailing blanks out to
the length specified. The fill key has no effect on varying length input
operations.

Autofill

In some keyboard input operations, if the Enter key is pressed before the
full amount of input has been entered, the field is automatically filled
to its maximum length. This column shows for which commands this takes
place.

Enter key

This column defines which input operations require the Enter key to
indicate that input is complete. The Enter key is required for all
keyboard input operations and for sensor input using the DB and KB
commands that display input on the screen.

Command/Key Relationships Table:

---------------------------------------------------------------------------
| Command | Input | Fill Key | Autofill | Enter Key |
| | Shown | | | |
|-----------------|---------|-----------------|-------------|-------------|
| AK fixed alpha- | Yes | Trailing | Trailing | Required |
| numeric keypad | | blanks | blanks | |
|-----------------|---------|-----------------|-------------|-------------|
| DB variable | Yes | No | Trailing | Required |
| sensor | | | blanks | |
|-----------------|---------|-----------------|-------------|-------------|
| FB fixed | No | No | No | Not used |
| sensor | | | | |
|-----------------|---------|-----------------|-------------|-------------|
| KB fixed sensor | Keypad | Keypad-trailing | Keypad-no | Keypad |
| or alpha- | -yes | blanks | | -required |
| numeric keypad | Sensor | | Sensor-no | Sensor |
| | -yes | Sensor-no | | -required |
|-----------------|---------|-----------------|-------------|-------------|
| NK fixed | Yes | No | Leading | Required |
| numeric keypad | | | zeroes | |
|-----------------|---------|-----------------|-------------|-------------|
| VB variable | No | No | Trailing | Not used |
| sensor | | | blanks | |
|-----------------|---------|-----------------|-------------|-------------|
| READ general | Echo | Variable-no | Variable-no | KA-required |
| purpose read | | | | KN-required |
| | K -yes | Fixed | Fixed | SA-not used |
| | K -yes | | | SN-not used |
| | SA-yes | KA-trailing | KA-trailing | |
| | SN-yes | blanks | blanks | |
| | | KN-leading | KN-leading | |
| | No echo | zeroes | zeroes | |
| | | SA-no | SA-no | |
| | KA-no | SN-no | SN-no | |
| | KN-no | | | |
| | SA-no | | | |
| | SN-no | | | |
---------------------------------------------------------------------------