123Scan Configuration Utility - About

Overview

Advanced Data Formatting is a powerful rule driven data editor within Zebra scanners. Rules are programmed within the 123Scan utility with a GUI based wizard that generates code in a unique interpreted ADF language. This code is loaded into the scanner and the ADF interpreter processes acquired decode data before it is transmitted to the attached host device. The 123Scan utility provides descriptions of the criteria and actions available in the ADF language. Most of the functionality within ADF is easy to understand and apply. This document provides additional details of the powerful ADF features that can be used to customize your scanner to meet your company's changing IT requirements.

Terminology

ADF Interpreter

Software that runs on the Zebra product that interprets ADF Rules after decode data is read and before the data is transmitted.

ADF Rule Formats

The format of ADF Rule data as it is stored in the scanner's Flash memory. 2000 bytes of rule storage is available on the scanner. The legacy versions of ADF (called ADF1 Format) limits the size of a rule to 127 bytes. This includes the criteria and action sections of a rule. The latest version of ADF (called ADF2 Format) limits the size of a rule from 310 to 670 bytes depending on the number of criteria sections. Refer to Highlights of ADF Features for more details on multiple criteria sections.

The current ADF Interpreter supports both Rule Formats, but only one format can be used at a time. If one rule is saved in the legacy format, then only rules of that format can be added.

Boolean Logic

Boolean Logic is a form of Mathematics that is centered on values that are either TRUE or FALSE. Each Criterion in a rule has a TRUE or FALSE value. Boolean Operators are used to show how the criteria are related to each other. When a Boolean Operator is applied, it has a TRUE or FALSE result.

Table 1: ADF Interpreter Supported Boolean Operators

Operator	Example	Meaning
NOT	NOT Code 39	If the criterion is FALSE, the NOT changes it to the TRUE result
AND	Length 14 AND Starts with “A”	If both criteria are TRUE, the result is TRUE. Otherwise the result is FALSE
OR	Length 8 OR Length 10	If one of the criteria are TRUE, the result is TRUE. Otherwise the result is FALSE
AND NOT	Length 10 AND NOT Starts with “C”	If both the left criterion is TRUE and the right criterion is FALSE, the result is TRUE. Otherwise the result is FALSE
OR NOT	Upc-a OR NOT ends with “X”	If either the left criterion is TRUE or the right criterion is FALSE, the result is TRUE. Otherwise the result is FALSE

Hexadecimal Numbers

In Mathematics, Hexadecimal numbers can be used to represent a number from 0 to 255 in two digits. Each hexadecimal digit has a value from 0 to 15 (0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F) The letters A to F are used to represent the values 10 to 15 respectively. In a two digit Hexadecimal number, the left digit is also from 0 to 15, but its value is assumed to be multiplied by 16.

In this document hexadecimal numbers are displayed with a back-slash \ followed with an “x” and two digits. For example: the hexadecimal number \x12 has the decimal value of 18 (1x16 + 2).

Highlights of ADF Features

ADF rules are programmed using a Graphical User Interface based utility.

123Scan 123Scan Utility

The 123Scan utility is the recommended way to program rules into the scanner. Depending on your product configuration, the utility can generate the correct ADF rule structure for your product.

Once rules are entered into the utility, they can be uploaded to your scanners directly. As an alternative, barcodes can be printed to enter the same rules through scanning.

123Scan Advanced Data Formatting Programmer's Guide

The legacy barcode menus in this document can still be used to program rules into the scanner. Not all ADF features are supported in the legacy ADF Programmer's guide.

ADF can be used to process barcode data of any length and prepare it for transmission to a host device.

The ADF Interpreter’s main function is to use rules to process the scanned bar code data in an input buffer and to move selected data to an output buffer. Each rule has a “criteria” section that describes the requirements for the rule to apply. If the rule applies, the rule’s list of actions is used to process the input buffer’s data. The results of the rule’s actions are stored in an output buffer. This output buffer data is transferred to the connected host device.

The legacy ADF Interpreter (called ADF1) is designed to work optimally with barcodes up to 255 bytes in length. When a barcode is longer, ADF1 can process these barcodes, but it may require multiple actions to move data or move the cursor 255 characters at a time.

To improve the operation of ADF, the latest version of ADF (called ADF2) has an “Full String Length” feature that allows the easy processing of barcodes up to 4096 bytes in length. This feature is enabled by default and it can be disabled in the General Settings section of 123Scan for each rule.

ADF Rules are processed in the order in which they are stored.

The ADF rules built in 123Scan are transferred to the Scanner and stored in the scanner’s Flash based storage.The order that ADF rules are stored is significant. The first rule that applies is the one that is chosen to process the input data.

General vs. Specific Rules

Rules with more stringent criteria are called “Specific Rules”, Rules that apply in most cases are called “General Rules”.

When assembling rules for your device, be careful to put the more specific rules higher on the list. When a “General Rule” is placed on the rule list above a more “Specific Rule” it has the effect of cancelling out the rules that follow it.

For example: Here is a list of rules that is more specific at the top, and more General at the bottom.

	Rule List (Criteria sections only)
Specific Rules	When the connected Host is IBM RS485 and barcode is UPC
	When rule set 1 is enabled and barcode is QR Code starting with “STOP”
	When a barcode begins with “GPC” and is length 12
	When a barcode contains “XYX” in any location
	When a barcode is Code 128 Length 10
	When a barcode is UPC
	When a barcode contains only Numeric data
	When a barcode is decoded in handsfree mode
General Rules	When any barcode is scanned

It is subjective on how “Specific” a rule is. When editing the rules in 123Scan, consider the rule order based on how the rules need to be applied.

All About Cursors

Similar to viewing data in an editor, ADF starts with a cursor on the starting position of the data. As actions are performed on the data, the cursor is moved forward or backward based on the actions used on the rule.

The ADF Interpreter uses a cursor to mark the next character to be processed by the next action. The image below shows a “data terminal” screen, and the cursor is on the “C” character in the word “Cursor”

As actions are processed, the cursor is moved forward for every character sent. So if the rule says to send data up to space (“ “), then the word Cursor is sent and the cursor is moved to the letter “p” of points.

In cases where the data needs to be skipped, ADF provides several Actions to move the cursor to a new position.

ADF Rules require that the data matches the rule.

When a rule is selected by the ADF interpreter due to matching criteria, then the Action section is applied. Actions will traverse the input data like a word processing application. A cursor is maintained that points to where the next action will process data.

Actions in the rule can move the cursor forward or backward a specified number of positions, or until a matching character or pattern is seen. If an action requests to move to a place in the data that does not exist, then the rule is said to have an “Action Failure” (See Failure Recovery for details).

ADF Rules build Output Data to be transmitted.

In summary, ADF is configured by writing one or more rules using the 123Scan2 graphical interface. These rules are transmitted to the scanner and stored in its Flash memory. When a barcode is scanned these rules are checked to see if a rule is found that would apply to the data.

Later on, when a barcode is scanned, the ADF Interpreter is called on the scanner to format the input data. The rule creates a buffer of Output Data. This data is handed off to the driver for the attached host device and the data is transmitted.

Understanding Criteria Within a Rule

Each ADF rule has a Criteria section that defines the types of barcode data that applies to a rule. The latest version of ADF has some improved capabilities in the Criteria section. These improvements provide a more powerful way of customizing the scanner.

The Criteria section defines the conditions required for a rule to apply to scanned data.

Each rule provides a list of criteria to determine if a specified set of actions should be applied to a barcode that is scanned. ADF provides several criteria to choose from when building a rule.

The source of the data
The length of the data
The type of barcode data scanned
The contents of the data
The means that the barcode scanner was triggered to read the data
The connected host that will receive the data
The rule is presently enabled or disabled using a Rule Set

ADF uses Boolean Logic to evaluate each of the criteria and determine if the rule applies. The ADF Interpreter will assume there is an AND or OR relationship between each criterion. 123Scan will automatically assign this relationship based on these requirements:

When more than one criterion of the same name follows another, they are assumed to have the OR relationship. (e.g. Length = 5 OR Length = 6 OR Length = 12)
When more than one criterion of a different name follows another, they are assumed to have the AND relationship. . (e.g. Code 39 AND Starts with “A”)

For example: The user wants a rule that applies when a code 128 barcode starts with XJT, MWX, or LKT. In this simple case, the ADF interpreter applies the following Boolean Operators according to its requirements.

The user can override the ADF Interpreter’s requirements by Manually inserting Boolean Operators between criteria to implement really special cases. See Tips for Power Users of ADF for more information.

Getting to know the Criteria supported in ADF.

Checking the Length of Scanned Data

ADF allows the checking of discrete lengths, lengths within a range, lengths below a value, lengths above a value. To illustrate length checking we have some sample barcodes:

The following are examples of what could be programmed in an ADF rule and the lengths of barcodes that would cause the rule to apply.

Length checking type	Criteria	Length 8	Length 10	Length 12
Discrete lengths	When length equals 10 or 12		✔	✔
Lengths within a range	When length in range 8 to 11	✔	✔
Lengths below a value	When length is below 10	✔
Lengths above a value	When length is above 10			✔

Checking the Type of Barcode Data Scanned

ADF can check the symbology type of barcode that was scanned. Zebra scanners can support many barcode types, and more than one symbology type could require similar formatting. ADF allows multiple code symbology types to apply to a rule.

To illustrate symbology type checking we have some sample barcodes:

The following are examples of what could be programmed in an ADF rule and the types of barcodes that would cause the rule to apply.

Symbology checking type	Criteria	UPC-A	Code128	QR Code
Single Code Type	When Code Type is UPC-A	✔
	When Code Type is Code 128		✔
	When Code Type is QR Code			✔
	When Code Type is Code 128 OR Code 39		✔
Code Type Group	When UPC/EAN	✔

Looking for Patterns of Data Within Scanned Barcode Data

ADF can check for patterns of data within the scanned barcode: At the start, at the end, at a specific position in the data, or in any position. Position numbers start with 1 at the first character of the scanned barcode data.

The following are examples of what could be programmed in an ADF rule and the types of barcodes that would cause the rule to apply.

Pattern matching type	Criteria
Starts With	When starts with “187”
At a specific position	When “-“ is at position 4
Ends With	When ends with “ICE”
In Any Location	When “ABC” is anywhere

Format Differently Depending on the Connected Host

One way of detecting where the scanner is used is by the type of host that it is connected to. The host connection type could be used to automatically select rules. This can be handy if one workstation used a USB connection and the same scanner can be plugged into another workstation with a RS232 connection. ADF rules can identify the type of Host connection that they belong to. If the rule does not apply then it is skipped. Actions within the rules can easily strip out certain non printable or alphabetic characters to suit one host.

Use the scanner’s Buttons to Select What Rules to Run

Zebra scanners support a variety of methods to trigger the reading a barcode. One scanner model has 2 buttons available to scan data. A rule could be programmed to format the data differently depending on how the decode was triggered.

One example is to use one trigger button to “add” an item and put it in the cart, and the other button to “remove” items from the cart. Data could be added to decode data depending on which button was used.

Rules Can Ignore Barcodes that Contain Unwanted Data

When processing data, sometimes the data has special characters or un-printable characters that are not applicable. ADF has a criterion that can be used to select the types of ASCII data that are allowed for a rule to apply. (see Appendix: ASCII Type Classification for a list of ASCII values and their default character type).

ADF supports the recognition of these types of ASCII data:

NON-PRINT - Non Printable ASCII value
WHITESPACE - Tabs, Spaces, Line Feeds, Vertical Tabs, Carriage Returns
NUMERIC - Values 0 to 9
ALPHA - Values A to Z and a to z
OTHER - ASCII values greater than 127
SPECIAL - Everything else (for example: !@#$%^&*()_+)
CUSTOM - A list of 1 to 16 ASCII characters that the user can select for a rule.

See Tips for Power Users of ADF for details on defining a custom character set.

A criterion can be added to a rule to select one or more ASCII categories that are allowed to be in the input data for the rule to apply. All of the selected ASCII categories must be represented in the barcode for the criterion to be TRUE.

The following barcode contains three categories: Numeric, Alphabetic, and Special.

For example, using this barcode, a criterion can be used in a rule that requires all three of these categories of data to match: When Scan data includes NUMERIC, ALPHA, SPECIAL

The barcode contains all three categories of data, so the criterion evaluates to TRUE.

The following barcode contains three categories: Numeric and Alphabetic.

Using the same rule, the criteria When Scan data includes NUMERIC, ALPHA, SPECIAL would evaluate to FALSE.

Rules Can Be Disabled or Enabled

ADF has a mechanism to enable or disable one or more rules at a time using Rule Sets. There are eight numbered Rule Sets supported by ADF and each rule can optionally be assigned to a Rule Set number using the Rule Set member criteria.

“This rule belongs to Rule Set x”

Each numbered Rule Set has a status, it is either enabled or disabled. All are disabled by default when the scanner powers up.

When a Rule Set is disabled, then the ADF Interpreter will skip all the rules that are a member of that rule set. When a rule is not assigned to a Rule Set, then the Rule is always Enabled.

For example, if a scanner has the following rules stored in the ADF Rule buffer. And the status of the eight Rule Sets are as shown above, then the shaded rules are skipped.

More details on this feature can be found in Tips for Power Users of ADF.

Building your Output Data with Actions

Each ADF rule has an Action section that defines how the decoded barcode data is processed before it is transmitted to the attached host. The latest version of ADF has some improved capabilities in the Action section. These improvements provide a more powerful way of customizing the scanner.

Changing Input Source

A new aspect of ADF is that it supports multiple data sources. When barcode data is scanned, the initial input source is the barcode data (shown with blue arrow). However, actions are available to change the input source for the rule to either a User Defined String, or to Asset Tracking Information (shown with white arrows).

Each input source has its own cursor. When the rule switches to User Defined String data or Asset Tracking Information then the cursor starts at the beginning of this data, however the barcode data cursor position is retained. When the input source is switched back to barcode data, ADF continues where it left off.

The next two sections provide examples of Input Source changing in use.

Send a large block of data

Sometimes the rule needs to append a large amount of data to the Output Data. For example, some printers require a lot of data to configure them. ADF rules can hold large user defined strings of printer configuration data, up to 128 bytes. Once in the rule, ADF actions can be used to parse the data to send in whatever format required.

The following is an example of “scan and print”. In this example, the string “^XA^XFE:BARCODE.ZPL^FS^FN11^FD” precedes the data to print and the string “^FS^PQ1^XZ” follows the data. A 2D barcode with a large amount of text is scanned. The blue arrows show the position of the cursor after each action.

Identify which scanner was used in collecting data

What if your process needs to know which scanner read a shipping barcode for its records. ADF can be programmed to transmit the scanner's model number or serial number with the needed data on the shipping label. This could be a way where the clerk's station could be identified

In this scenario, an Inventory taker is reading tags on units. This rule would send the model and serial number of the scanner followed by the inventory tag. The blue arrows show the position of the cursor after each action.

Actions that Provide User Feedback

Your business may use a process that requires the scanning of multiple barcodes and some User Feedback might help in the support of this process. ADF rules can be setup to adjust the LED lighting on the scanner, or to sound a beeper sequence or vibrate the scanner handle when a certain data pattern is seen. The vibrations can be in multiples so that they can stand out to the user.

For example, when a specific barcode is scanned (based on data contents) the scanner can give a single vibration and light the Green LED on the top of the scanner. And when incorrect data is scanned a Red LED can be lit and a triple vibration can be felt on the handle.

Beep Indication

An action can be used to sound a beeper sequence. The beeper sequence occurs when ADF processes the input data, before the output data is transmitted.

The following list shows all the available sequences.

1 to 5 High Frequency Tones of Short Duration
1 to 5 Low Frequency Tones of Short Duration
1 to 5 High Frequency Tones of Long Duration
1 to 5 Low Frequency Tones of Long Duration
High-Low-High-Low Frequency, Short Duration
High-Low-High-Low Frequency, Long Duration
2 Tones High-Low Frequency, Short Duration
2 Tones Low-High Frequency, Short Duration
High-Low-High Frequency, Short Duration
Low-High-Low Frequency, Short Duration
High-High-Low-Low Frequency, Short Duration

LED Indication

An action can be used to illuminate an LED, usually on the top of the scanner with a specified color for a number of seconds (From 1 to 10). Not all scanners support all colors. The LED sequence occurs when ADF processes the input data, before the output data is transmitted.

If the LED to illuminate is not supported by the scanner, this causes an “Action Failure”. See the “General Settings” section in 123Scan to select how to respond to this failure.

Vibrate Indication

An action can be used to vibrate the scanner handle in a special way by ADF rule. This only applies to scanners with vibration capability, such as Healthcare models.