How it Works
Pepperl+Fuchs
Loading...
N
O
Loading...
Loading...
OHV300
Table of contents
Loading...

Pepperl+Fuchs OHV300 Javascript Programming Manual

FACTORY AUTOMATION
MANUAL

JAVASCRIPT PROGRAMMING GUIDE

With regard to the supply of products, the current issue of the following document is
applicable: The General Terms of Delivery for Products and Services of the Electrical
Industry, published by the Central Association of the Electrical Industry (Zentralverband
Elektrotechnik und Elektroindustrie (ZVEI) e.V.) in its most recent version as well as the
supplementary clause: "Expanded reservation of proprietorship"
2
JavaScript Programming Guide
1 Introduction ............................................................................ 10
1.1 Document Organization ...................................................................... 10
1.2 Document and Coding Conventions .................................................. 10
1.3 Related Documents ............................................................................. 10
1.4 Related Utility ....................................................................................... 11
2 Programming Environment ................................................... 12
2.1 Editor ..................................................................................................... 12
2.2 CodeViewer Application ...................................................................... 12
2.3 Security ................................................................................................. 12
2.4 Debugging ............................................................................................ 13
3 Programming Concepts ........................................................ 14
3.1 Simplicity .............................................................................................. 14
3.2 The OHV300 gui Object ....................................................................... 15
3.2.1 Softkey Implementation ..........................................................................................16
3.2.2 Forms ....................................................................................................................16
3.2.3 Menus ....................................................................................................................17
3.2.4 Text .......................................................................................................................19
3.3 Event ..................................................................................................... 19
3.3.1 Decode Events ......................................................................................................20
3.3.2 Key Events .............................................................................................................21
3.3.3 Command Execution ..............................................................................................22
3.4 Reader Configuration .......................................................................... 22
3.5 Symbol Decoding ................................................................................ 23
3.5.1 Transform Data by Symbology ...............................................................................25
3.5.2 Evaluate Data Format ............................................................................................26
3.5.3 Detect Format Errors ..............................................................................................27
3
JavaScript Programming Guide
3.5.4 Let the Handheld Process the Decode ...................................................................27
3.5.5 Ignore the Decode .................................................................................................28
3.5.6 Determine the Orientation of the Decode ................................................................28
3.6 Host Communication ........................................................................... 29
3.7 Data in Handheld Local Storage ........................................................ 30
3.8 Demo Programs ................................................................................... 30
4 Class Reference ..................................................................... 31
4.1 decode .................................................................................................. 31
4.1.1 Properties ..............................................................................................................31
4.1.1.1 data ............................................................................................................................... 31
4.1.1.2 symbology ..................................................................................................................... 31
4.1.1.3 symbology_ex ............................................................................................................... 32
4.1.1.4 symbologyModifier ........................................................................................................ 32
4.1.1.5 symbologyModifier_ex .................................................................................................. 32
4.1.1.6 symbologyIdentifier ....................................................................................................... 32
4.1.1.7 x .................................................................................................................................... 32
4.1.1.8 y .................................................................................................................................... 32
4.1.1.9 time ............................................................................................................................... 33
4.1.1.10 quality_percent ............................................................................................................. 33
4.1.1.11 qrPosition ...................................................................................................................... 33
4.1.1.12 qrTotal ........................................................................................................................... 33
4.1.1.13 qrParity .......................................................................................................................... 33
4.1.1.14 linkage ........................................................................................................................... 33
4.1.1.15 bounds .......................................................................................................................... 33
4.1.1.16 numExtraFields ............................................................................................................. 34
4.1.1.17 decoderType ................................................................................................................. 34
4.1.1.18 aimSymbology .............................................................................................................. 34
4.1.1.19 aimModifier ................................................................................................................... 35
4.1.1.20 decodeOutputFormat .................................................................................................... 35
4
JavaScript Programming Guide
4.2 gui .......................................................................................................... 36
4.2.1 Methods .................................................................................................................36
4.2.1.1 alert ............................................................................................................................... 36
4.2.1.2 confirm .......................................................................................................................... 37
4.2.1.3 prompt ........................................................................................................................... 38
4.2.1.4 putBox ........................................................................................................................... 39
4.2.1.5 sendKey ........................................................................................................................ 40
4.2.1.6 sendText ....................................................................................................................... 40
4.2.1.7 show.............................................................................................................................. 40
4.2.1.8 showForm ..................................................................................................................... 41
4.2.1.9 showMenu .................................................................................................................... 41
4.2.1.10 showSubMenu .............................................................................................................. 42
4.2.1.11 splash and clearSplash ................................................................................................. 42
4.2.1.12 sync............................................................................................................................... 43
4.2.2 Properties ..............................................................................................................43
4.2.2.1 inputMode ..................................................................................................................... 43
4.2.2.2 key ................................................................................................................................ 44
4.2.2.3 leftSoftkey ..................................................................................................................... 44
4.2.2.4 rightSoftkey ................................................................................................................... 44
4.2.2.5 statusText ..................................................................................................................... 45
4.2.3 Objects ..................................................................................................................45
4.2.3.1 gui.Button ...................................................................................................................... 45
4.2.3.2 gui.Edit .......................................................................................................................... 46
4.2.3.3 gui.Form ........................................................................................................................ 48
4.2.3.4 gui.Image ...................................................................................................................... 49
4.2.3.5 gui.Label ....................................................................................................................... 50
4.2.3.6 gui.Menu ....................................................................................................................... 50
4.2.3.7 gui.MenuItem ................................................................................................................ 51
4.2.3.8 gui.MultiLineEdit ........................................................................................................... 51
4.2.3.9 gui.Separator ................................................................................................................ 52
5
JavaScript Programming Guide
4.2.3.10 gui.Softkey .................................................................................................................... 53
4.2.3.11 gui.Text ......................................................................................................................... 54
4.2.3.12 gui.ToggleButton ........................................................................................................... 55
4.2.4 Predefined Softkey Objects ....................................................................................57
4.2.4.1 backSoftkey .................................................................................................................. 57
4.2.4.2 cancelSoftkey ............................................................................................................... 57
4.2.4.3 okSoftkey ...................................................................................................................... 57
4.2.4.4 selectSoftkey ................................................................................................................ 57
4.2.5 Form and Menu Common Methods ........................................................................57
4.2.5.1 append(control)............................................................................................................. 57
4.2.5.2 prepend(control) ........................................................................................................... 58
4.2.5.3 setActiveChild(control) .................................................................................................. 58
4.2.6 Form and Menu Common Properties ......................................................................58
4.2.6.1 caption .......................................................................................................................... 58
4.2.6.2 onKey ............................................................................................................................ 59
4.3 reader .................................................................................................... 59
4.3.1 Methods .................................................................................................................59
4.3.1.1 beep .............................................................................................................................. 59
4.3.1.2 defaultSettings .............................................................................................................. 60
4.3.1.3 getKeyboardStatus ....................................................................................................... 60
4.3.1.4 processCommand......................................................................................................... 61
4.3.1.5 readSetting.................................................................................................................... 61
4.3.1.6 runScript ........................................................................................................................ 61
4.3.1.7 saveSettings ................................................................................................................. 62
4.3.1.8 setDisplayLed ............................................................................................................... 62
4.3.1.9 setInterval ..................................................................................................................... 63
4.3.1.10 clearInterval .................................................................................................................. 63
4.3.1.11 setTimeout .................................................................................................................... 63
4.3.1.12 clearTimeout ................................................................................................................. 64
4.3.1.13 shiftJisToUnicode ......................................................................................................... 64
6
JavaScript Programming Guide
4.3.1.14 writeSetting ................................................................................................................... 64
4.3.1.15 unicodeToShiftJis ......................................................................................................... 65
4.3.2 Properties ..............................................................................................................65
4.3.2.1 onCommand ................................................................................................................. 65
4.3.2.2 onCommandFinish ........................................................................................................ 66
4.3.2.3 onDecode ..................................................................................................................... 67
4.3.2.4 onDecodeAttempt ......................................................................................................... 68
4.3.2.5 onIdle ............................................................................................................................ 69
4.3.2.6 onStandby ..................................................................................................................... 69
4.3.2.7 batteryLevel .................................................................................................................. 70
4.3.2.8 red ................................................................................................................................. 70
4.3.2.9 green ............................................................................................................................. 70
4.3.2.10 amber ............................................................................................................................ 70
4.3.2.11 none .............................................................................................................................. 70
4.3.2.12 cabled ........................................................................................................................... 71
4.3.2.13 charging ........................................................................................................................ 71
4.3.2.14 hardwareVersion ........................................................................................................... 71
4.3.2.15 oemId ............................................................................................................................ 71
4.3.2.16 readerId ......................................................................................................................... 71
4.3.2.17 softwareVersion ............................................................................................................ 71
4.3.2.18 bdAddr .......................................................................................................................... 72
4.4 storage .................................................................................................. 72
4.4.1 Methods .................................................................................................................72
4.4.1.1 append .......................................................................................................................... 72
4.4.1.2 erase ............................................................................................................................. 72
4.4.1.3 findFirst ......................................................................................................................... 73
4.4.1.4 findNext ......................................................................................................................... 73
4.4.1.5 read ............................................................................................................................... 74
4.4.1.6 rename .......................................................................................................................... 74
4.4.1.7 size ................................................................................................................................ 74
7
JavaScript Programming Guide
4.4.1.8 upload ........................................................................................................................... 74
4.4.1.9 write .............................................................................................................................. 75
4.4.1.10 getHeader ..................................................................................................................... 76
4.4.1.11 saveOffsetWindow ........................................................................................................ 76
4.4.2 Properties ..............................................................................................................76
4.4.2.1 fullness_percent ............................................................................................................ 76
4.4.2.2 isFull .............................................................................................................................. 77
4.4.2.3 logFullness_percent ...................................................................................................... 77
4.5 comm..................................................................................................... 77
4.5.1 Methods .................................................................................................................77
4.5.1.1 connect ......................................................................................................................... 77
4.5.1.2 disconnect ..................................................................................................................... 77
4.5.1.3 sendPacket ................................................................................................................... 77
4.5.1.4 sendText ....................................................................................................................... 78
4.5.2 Properties ..............................................................................................................78
4.5.2.1 isConnected .................................................................................................................. 79
4.6 Functions .............................................................................................. 79
4.6.1 Dialog ....................................................................................................................79
4.6.1.1 alert ............................................................................................................................... 79
4.6.1.2 confirm .......................................................................................................................... 80
4.6.1.3 prompt ........................................................................................................................... 81
4.6.2 Other Functions .....................................................................................................82
4.6.2.1 gc .................................................................................................................................. 82
4.6.2.2 include .......................................................................................................................... 82
4.6.2.3 print ............................................................................................................................... 82
4.6.2.4 setStandbyMessage ..................................................................................................... 83
4.6.2.5 wdt ................................................................................................................................ 83
5 Glossary and Acronyms ........................................................ 84
6 Input Modes ............................................................................ 85
8
JavaScript Programming Guide
7 Format Specifiers ................................................................... 86
8 Supported JavaScript Core ................................................... 87
9 Symbology ID & Modifier Information .................................. 89
9
Introduction

1 Introduction

This manual describes the application programming interface for OHV300 handhelds. It is assumed the user will have programming knowledge and familiarity with the JavaScript language.
Handhelds read code and can be programmed to transmit code data over a selected
communications link or to store data in reader memory (batch mode).
The programming environment provides interfaces to:
Read and manipulate data in reader memory. Display information on the OHV300 screen. Retrieve data from reader hardware or OHV300 key pad. Access data sent by host. Transmit data to a host computer via communications link. Select type of communications link. Set, change, and retrieve reader configuration settings.

1.1 Document Organization

This document is organized as follows:
Section 1, Introduction: gives a product description and describes how to use this
document.
Section 2, Programming Environment: identifies tools used to create and load
application software into reader.
Section 3, Programming Concepts: discusses how to accomplish various operations
on the reader using the application programming interface.
Section 4, Class Reference: presents classes, objects, methods, properties, and
constructors that support application programs.
Section 5 – 9: Appendix

1.2 Document and Coding Conventions

The JavaScript library uses the following naming conventions:
identifiers: mixed-case with a capital letter where words join (soCalledCamelCase);
acronyms and other initialisms are capitalized like words, e.g., nasaSpaceShuttle, httpServer
variables and properties: initial lower case classes (i.e., constructors): initial capital functions: initial lower case

1.3 Related Documents

10
unit of measure: suffix to name, separated from name by underscore, using correct
case when it’s significant, e.g., offset_pixels, width_mm, power_MW, powerRatio_dB
OHV manuals Interface Configuration Document
Introduction
Example!
Visit http://www.pepperl-fuchs.com to obtain this application.

1.4 Related Utility

Vision Configurator
11
Programming Environment

2 Programming Environment

This document is not a JavaScript manual. The following sources are a few of the many JavaScript reference books and online documents:
JavaScript: The Complete Reference, Second Edition
by Thomas Powell, et al.
JavaScript Demystified (Demystified)
by James Keogh.
JavaScript in 10 Simple Steps or Less
by Arman Danesh.
http://www.javascript.com/

2.1 Editor

You can use your favorite editing product to create and modify JavaScript code. Turn off any smart quote options in the editor. Smart quotes are not valid in JavaScript.

2.2 CodeViewer Application

The CodeViewer Application runs as a JavaScript application on the OHV300. The menu driven application has features for changing configuration settings and for defining the applications that run on the reader. JavaScript developers can make use of the following keywords in the CodeViewer Application:
Title – Displays the title of the JavaScript rather than the file name in CodeViewer’s
‘Application’ menu. Add a comment to your script formatted as $Title: <title of script>$ to
implement.
Revision – Displays the revision of the JavaScript from the CodeViewer’s ‘Application/<script>’ submenu. Add a comment to your script formatted as $Revision: <revision of script>$ to implement.

2.3 Security

Each handheld reader contains a unique reader ID. Select features of the reader are protected by license. A license file is required for each reader licensed to use protected features. Third party software licenses may also be protected using the encryption utility.
12
Programming Environment

2.4 Debugging

The handheld reader contains a built-in error log that can be used when debugging scripts. To debug the script when an error has occurred, send the ‘(‘ command to the reader; the reader responds by sending the error log to the communications port. The error log may contain messages from the firmware that should be ignored. JavaScript errors in the log can be identified by the format: filename:lineNumber. If there are many error codes in the error log, send the ‘)’ command to clear the log and repeat the steps to create the error, leaving only one entry in the log.
Example:
X ap/gerror-log. storage_init: flMountVolume fail status 26, formatting.storage_formatFilesystem: status 0.
temp.js:3: TypeError: gui.aler is not a function. X ap/dEOF.
This error log contains one firmware error and one JavaScript error. The JavaScript error description begins with temp.js:3: and tells us that on line three of the temp.js file, gui.aler is not recognized as a function. In this case, gui.alert has been misspelled (it is missing the t).
13
Programming Concepts
Note!
The default application allows scripts to be run by host command or configuration code scan; the command is “|run:scriptName.js” (using your own scriptName).

3 Programming Concepts

To help the developer create unique applications for the reader, we provide this JavaScript Programming Guide. The developer can create complex business applications with prompts and data entry through the OHV300 user interface features (keypad and display screen).
The features of the programming interface include:
A graphical user interface Event handlers Symbol decoding Host communications Local data storage Handheld configuration
In support of these features, the environment defines the following objects:
gui reader storage comm
Using these features, you can create robust, interactive, and sophisticated user applications.
A script can be made the default application using the configuration utility, or it may be run from the configuration utility without making it the default.

3.1 Simplicity

The “Hello World!” application is traditionally the first application presented in a
programming guide. It is an easy to code and understand application that illustrates how the programming environment works.
In its simplest form, the “Hello World!” application in the OHV300 environment sends text
to the display. With the following single line of code, you can display “Hello World!” in the
screen defined by the standard OHV300 gui object (section 4.1).
gui.show(new gui.Text("Hello World!"));
Execution of this script displays the image shown in Figure 1.
14
Programming Concepts
Note!
The text is displayed in a text box control with a scroll bar to the right as defined by the OHV300 gui object.
Figure 1 – Hello World Application

3.2 The OHV300 gui Object

The OHV300 application development environment defines a standard GUI display for application software (Figure 2). The display supports simple prompts and data entry.
Figure 2 – The Standard GUI Display
The standard display consists of a status bar, a display area, and labels for the left and right software programmable keys (softkeys) at the top of the OHV300 key pad (see Figure
6).
The scroll bar on the right side of the screen indicates the relative position within the displayed object as the operator scrolls through forms, menus, or text using the up and down keys on the keypad. This scrolling feature allows the application to display objects larger than the display area.
Use the gui interface to develop forms and menus applications, and use the “show” methods to display them.
15
Programming Concepts

3.2.1 Softkey Implementation

Softkeys are general purpose, programmable keys. The softkeys are independent of the GUI display. The gui.showForm, gui.showMenu, and gui.showSubmenu methods include softkey definitions appropriate for the implementation.
The following example shows the basic approach to programming the softkeys and implementing their event handlers.
// define send-key functions used by common softkeys
function sendEnter() { gui.sendKey(gui.key.enter); }
function sendEscape() { gui.sendKey(gui.key.escape); }
// create some common softkeys
var selectSoftkey = new gui.Softkey("Select", sendEnter);
var okSoftkey = new gui.Softkey("OK", sendEnter);
var backSoftkey = new gui.Softkey("Back", sendEscape);
var cancelSoftkey = new gui.Softkey("Cancel", sendEscape);
See section 0 (gui object) for more information.

3.2.2 Forms

Forms are the building blocks of your application. Each form represents a set of actions you want to present to the user on screen.
Use the gui.Form object (section 4.2.3.3) to define the forms for your application. Section
4.2.3 defines the form object and several constructors that you can use to create controls on your application form.
The following examples demonstrate how to create a form. The event handler functions need to be defined for your application.
// JavaScript Form Demo Script Document
// form event handlers
function myFormOnOk(){/* processing code (example: save the Employee #) */}
function myFormOnCancel(){/* processing code (example: return to main menu) */}
// create the form object
var myForm = new gui.Form(myFormOnOk, myFormOnCancel);
// create the edit control
var edit = new gui.Edit("");
// create the label control
var label = new gui.Label("Employee #:");
// position the controls on the form
16
Programming Concepts
myForm.append(label);
myForm.append(edit);
// Create the caption that will appear on the status bar
myForm.caption = "form demo";
// show the form
gui.showForm(myForm);
When the Form Demo Script runs, the OHV300 displays the following image:
Figure 3 – Form Demo Display
The user enters an employee number into the edit control and presses the left button (OK) to submit the data.

3.2.3 Menus

Use the gui.Menu object (section 4.2.3.6) to define the menus for your application. Use the gui.MenuItem constructor to define the controls in the menu. Each control has an associated onClick property that defines the function of the OHV300.
The following example demonstrates how to build and display menus and submenus.
// JavaScript Menu Demo Script Document
// menu event handlers
function onTimeCard(){alert(postAlertFunc, "TimeCard");}
function onInventory()
{
gui.showSubMenu(subMenu, myMenu);
}
function onCapital(){alert(postAlertFunc, "capital");}
function onStock(){alert(postAlertFunc, "stock");}
// create menu objects
var myMenu = new gui.Menu();
var subMenu = new gui.Menu();
// create menu entries
var timeCardApp =
17
Programming Concepts
new gui.MenuItem("Time Card", onTimeCard);
var inventoryApp =
new gui.MenuItem("Inventory", onInventory);
var separator =
new gui.Separator(1, gui.separatorStyle.horizontalLine);
myMenu.caption = "menu demo";
subMenu.caption = "subMenu demo";
// create subMenu entries
var capital =
new gui.MenuItem("Capital", onCapital);
var stock =
new gui.MenuItem("Stock", onStock);
// position the controls on the menus
myMenu.append(separator);
myMenu.append(inventoryApp);
myMenu.append(timeCardApp);
subMenu.append(capital);
subMenu.append(stock);
//Specify a child to be selected when the menu is displayed (optional)
myMenu.setActiveChild(inventoryApp);
subMenu.setActiveChild(capital);
// set the caption text for the status bar
myMenu.caption = "menu demo";
// show the menu
gui.showMenu(myMenu);
When the Menu Demo application is initiated, the OHV300 displays the following image:
Figure 4 – Menu Demo Display
18
Programming Concepts
The Select button sends gui.softkey.enter to run the highlighted application. In this example, the Inventory option is selected. The script then displays the Inventory submenu shown in Figure 5.
Figure 5 – Sub Menu Demo Display

3.2.4 Text

Use the gui.Text object (section 4.2.3.11) to show text. Text may exceed the display area, toggling the arrow buttons to view all data. This should not be used to control text within menus or forms.

3.3 Event

The JavaScript environment is event driven. The reader firmware waits for an event such as a pressed key. The application gains control of an event by setting an object's event properties to functions. Events include:
send and receive of communications packets decode operations pressed keys command execution change of reader mode (idle, standby, and power down)
An application gains control only when:
The reader application defines an event property. The application creates a function and assigns it to the event property. The event occurs.
The application can disable an event by setting the event property to null.
19
Programming Concepts

3.3.1 Decode Events

The reader object defines an event onDecode. Section 4.3.2.3 discusses decode events.
Example:
var numDecodes = 0;
var numDecodesProcessed = 0;
reader.onDecodeAttempt = function(count)
{
numDecodes = count;
numDecodesProcessed = 0;
}
reader.onDecode = function(decode)
{
if( ++numDecodesProcessed < numDecodes )
{
// process individual decode, save in variables, etc.
}
else
{
// process the whole set, using saved variables, etc.
}
}
20
Programming Concepts
Key
Object
Event Handler Property
Enter – button located in the center of the arrow keys
gui.Form
gui.Menu
gui.Text
gui.Button
gui.MenuItem
onOk
onOk
onOk
onClick
onClick
Clear – bottom right button
gui.Form
gui.Menu
gui.Text
onCancel
onCancel
onCancel
Left Button – top left soft key
gui
onClick
Right Button – top right soft key
gui
onClick

3.3.2 Key Events

The clear, enter, and left and right buttons (softkeys) can be programmed to seamlessly integrate with user specific events.
The possibilities are shown in Table 1. The GUI objects are documented in section 4.2.3.
Figure 6 – OHV300 Keypad
1. Left Softkey
2. Right Softkey
3. Clear/Escape Button
4. Enter Button
Table 1 – Keys to Event Mapping
21
Programming Concepts
Key
Object
Event Handler Property
Any Other Buttons
gui.Form
gui.Menu
gui.Text
onKey
onKey
onKey

3.3.3 Command Execution

The reader application defines a number of commands that can be sent to the firmware from the host or by reading codes. The reader (section 4.3) defines an event by the onCommand function. If onCommand is set, the reader finds the specified event before running the command and transmitting the data.

3.4 Reader Configuration

The configuration settings define the active capabilities of the handheld. The application development environment defines the reader object (section 4.3), which contains methods for manipulating handheld settings. The Interface Configuration Document defines the configuration items and the values that can be set for each item.
The application developer can dynamically change the active settings by using the reader.writeSetting method. This method changes the operational value of the setting, but that value is lost when the reader is turned off. The current values of all settings can be saved by using the reader.saveSettings method, which writes the current values of the settings to flash memory from where they are restored on power up.
Example:
reader.writeSetting(0x1b, 4);
gui.confirm( yesFunc, noFunc, "Setting changed.\n\nSave now? ",
"Setting Change")
//This function will be called if user presses Yes softkey
yesFunc = function() {
if ( !reader.saveSettings() )
alert(postAlertFunc, "Error Saving Settings");
}
Retrieve the current value of a setting by using the reader.readSetting method. Restore factory default settings by using the reader.defaultSettings method.
22
Programming Concepts

3.5 Symbol Decoding

The primary function of the OHV300 is scanning, decoding, and processing one­dimensional and two-dimensional barcodes. The reader can read a wide range of code types, or symbologies, and provide access to the data after decoding. The reader decodes in one of two ways:
Pressing the read key on the key pad. A decode command from the reader.processCommand method.
The reader.onDecode defines an event that allows the application to access data.
To program the OHV300 to scan and transmit data, follow the below commands.
function onDecode(decode)
{
// Processing
}
reader.onDecode = onDecode;
There are four basic options for decoding scanned data:
Process the data in the script, such as fill in form fields, and return null. Let the data be further processed by the handheld firmware, typically for sending
and/or storing, by returning decode.
Transform the data and let the handheld firmware process the changed data by
setting decode.data as necessary and returning decode.
Invalidate the decode by returning false. The handheld will act as though the decode
never occurred.
The following pseudocode presents an example of decode processing addressing the four options. The example transforms decode data based on certain symbologies. Then the example checks the format of the decode data to determine the next processing steps.
Subsections following the pseudocode discuss the processing steps in the following example.
23
Programming Concepts
Example:
function onDecode(decode)
{
data = decode.data;
if (decode.symbology == some-special-symbology)
{
data = transformed decode.data;
}
else if (decode.symbology
== some-other-special-symbology)
{
data = differently transformed decode.data;
}
if (data matches employee-badge format)
{
loginForm.employeeField.text = decode.data;
loginForm.pinField.text = "";
gui.showForm(loginForm);
return null;
}
else if (data matches part-number format)
{
stockForm.partField.text = decode.data;
gui.showForm(stockForm);
return null;
}
else if (data matches shelf-number format)
{
stockForm.shelfField.text = decode.data;
gui.showForm(stockForm);
return null;
}
else if (data matches wrong formats)
{
warning.text = "bad code for this application";
24
Programming Concepts
Note!
Sometimes symbology is used to distinguish otherwise like-formatted data; for example, shelf tags may have the same number of digits as UPC codes for the products on the shelves, but have different barcode symbologies that can be used to determine whether the decode is a shelf tag or a product UPC code.
gui.showForm(warning);
return null;
}
else if (data matches format that is to be ignored)
{
return false; // invalidate the decode
}
else // code should be processed by handheld firmware
{
if ( code should be processed
with transformed data)
{
decode.data = data; // replace the data field
// with transformed data
}
return decode;
}
}

3.5.1 Transform Data by Symbology

Barcodes read by the handheld are encoded in unique symbologies. Particularly within two-dimensional codes, common data items may be present in different locations within the decode depending on the encoding symbology. In the example, line 5 checks the value of decode.symbology and transforms the decode data to a common format. To check symbology, compare decode.symbology against the symbology codes documented in the Interface Configuration Document.
25
Programming Concepts

3.5.2 Evaluate Data Format

After the data is converted into a common data format based on the symbology, the application determines the data format and processes according to data content.
if (data matches employee-badge format)
{
loginForm.employeeField.text = decode.data;
loginForm.pinField.text = "";
gui.showForm(loginForm);
return null;
}
else if data matches part-number format
{
stockForm.partField.text = decode.data;
gui.showForm(stockForm);
return null;
}
else if (data matches shelf-number format)
{
stockForm.shelfField.text = decode.data;
gui.showForm(stockForm);
return null;
}
The previous statements from the example demonstrate the processing of data within the decode handler. Based on the data format, the application program extracts data from the decode and displays appropriate forms.
These examples execute a return null statement to consume the decode for the specified data formats.
26
Programming Concepts
Note!
Do not code alert, confirm, or prompt, either as functions or as gui methods, in an onDecode or onCommand event handler. The events originate in the handheld firmware, resulting from decodes, commands, or communication events. While the event handler is running, the main application is held idle until the event handler returns. If the event handler is waiting for the user to finish with alert, confirm, or prompt, the main application will be forced to wait as well, resulting in timeout errors.

3.5.3 Detect Format Errors

If the format matches a known format that should not be used in the current application context, the application can send a warning message, which is displayed in "warning" form.
else if data matches wrong formats
{
warning.text = "bad code for this application";
gui.showForm(warning);
return null;
}
In this case, the example returns a null to consume the decode.

3.5.4 Let the Handheld Process the Decode

If you want the handheld to process the decode, set the decode as the return statement parameter. If you have changed decode data and want the changes available to the handheld, set the appropriate data field in the decode to the changed value before returning the decode.
else // code should be processed by handheld firmware
{
if ( code should be processed
with transformed data)
{
decode.data = data; // replace the data field
// with transformed data
}
return decode;
}
27
Programming Concepts
Note!
Normally, the handheld will sound a good-decode beep at the end of decode processing. If you do not want invalidated decodes to cause the usual good-decode beep in the handheld firmware, you must configure the reader to process the decodes via JavaScript before beeping. Then the handheld will only beep if there is at least one decode that is not invalidated. For more information, refer to the Interface Configuration Document.
If your reader.onDecode function returns false, you should configure the handheld to beep upon decode error.

3.5.5 Ignore the Decode

You can ignore a particular format by exiting the function with a return value of false as shown in the following code segment from the example.
else if (data matches format that is to be ignored)
{
return false; // invalidate the decode
}

3.5.6 Determine the Orientation of the Decode

You can determine the orientation of a code by using the bounds array. The bounds array has four elements that can be used to give the coordinates of the four corners of the code (the origin is the center of the decode field):
(decode.bounds[0].x, decode.bounds[0].y) = coordinates of top right corner (decode.bounds[1].x, decode.bounds[1].y) = coordinates of top left corner (decode.bounds[2].x, decode.bounds[2].y) = coordinates of bottom left corner (decode.bounds[3].x, decode.bounds[3].y) = coordinates of bottom right corner
These designations (e.g. top left) refer to the corners of the symbol, not as it appears in a particular image, but rather as it appears (most often) in its symbology specification. For example, for Data Matrix, array element 2, which contains the coordinates of the bottom left vertex of the symbol boundary, will always be proximate to the intersection of the two lines which form the “∟” of the symbol, regardless of the actual orientation (or mirroring) of the symbol in the image submitted to the decoder.
In normal orientation, we would expect the signs of the coordinates to be:
decode.bounds[0].x (-), decode.bounds[0].y (+) decode.bounds[1].x (-), decode.bounds[1].y (-) decode.bounds[2].x (+), decode.bounds[2].y (-) decode.bounds[3].x (+), decode.bounds[3].y (+)
28
Programming Concepts
Note!
Normally, the handheld will sound a good-decode beep at the end of decode processing. If you do not want invalidated decodes to cause the usual good-decode beep in the handheld firmware; you must configure the reader to process the decodes via JavaScript before beeping. Then the handheld will only beep if there is at least one decode that is not invalidated. For more information, refer to the Interface Configuration Document.
A code that is not “right side up” could be rejected by exiting the function with a return
value of false as shown in the following example.
if (decode.bounds[0].x > 0 && decode.bounds[0].y < 0 && decode.bounds[1].x > 0 && decode.bounds[1].y > 0 && decode.bounds[2].x < 0 && decode.bounds[2].y > 0 && decode.bounds[3].x < 0 && decode.bounds[3].y < 0)
{
return false; // invalidate the decode
}

3.6 Host Communication

The handheld application development environment defines a host communication comm object (section 4.4.2.3) to support communications with a host resident application. For example, Vision Configurator (section 1.4) is a host resident utility that communicates with the handheld reader for downloading files to the handheld.
From the host computer’s view, the handheld is a serial device accessible through a serial or USB port, or through Bluetooth Radio Frequency (RF) communications. Handheld configuration settings define the active host communications port.
The handheld host communications implementation supports two basic styles of communication: raw text and packets. It also supports a set of native protocols.
The application program transfers data to the host by writing to the handheld host communications port using methods defined by the hendheld reader comm object (section
4.4.2.3). Applications gain access to data sent by the host by implementing onCommand (and optionally onCommandFinish) event handlers defined by the handheld's reader object properties (section 4.3) and parsing the “|” command.
29
Loading...
+ 65 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use