upos-pg rev f user guides/unified... · unifiedpos (upos) controls programmer’s guide 2 - 1 2...
TRANSCRIPT
UnifiedPOS (UPOS) Controls Combined JavaPOS and OPOS Controls
Programmer’s Guide
Disclaimer
Hand Held Products, Inc. d/b/a Hand Held Products (“Hand Held Products”) reserves the right to make changes in specifications and other information contained in this document without prior notice, and the reader should in all cases consult Hand Held Products to determine whether any such changes have been made. The information in this publication does not represent a commitment on the part of Hand Held Products.
Hand Held Products shall not be liable for technical or editorial errors or omissions contained herein; nor for incidental or consequential damages resulting from the furnishing, performance, or use of this material.
This document contains proprietary information which is protected by copyright. All rights are reserved. No part of this document may be photocopied, reproduced, or translated into another language without the prior written consent of Hand Held Products.
© 2004-2006 Hand Held Products, Inc. All rights reserved.
Web Address: www.handheld.com
Microsoft® Visual C/C++®, Windows® 95, Windows® 98, Windows® 2000, and Windows NT® are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Other product names mentioned in this document may be trademarks or registered trademarks of other companies and are the property of their respective owners.
Table of Contents
Chapter 1 - Introduction
Supported Java Versions .....................................................................................................................1-1
Chapter 2 - Hand Held Products UPOS Installation and System Configuration
Installation Procedures ........................................................................................................................2-1Installing Java Runtime v1.4.2_04 (optional) ...............................................................................2-1
System Configuration ..........................................................................................................................2-1Configuring Windows 2000 and XP PATH Environment Variable (required)............................2-2Configuring Windows NT PATH Environment Variable (required) ...........................................2-3Configuring Windows 98 PATH Environment Variable (required).............................................2-3Installation and System Configuration Complete .........................................................................2-4Updating Windows CLASSPATH Environment Variable (optional) ..........................................2-4
Running Third Party (non-Hand Held Products) Applications with Hand Held Products Devices....2-4Uninstall Instructions...........................................................................................................................2-4
Chapter 3 - Hand Held Products UnifiedPOS Configuration Application
Configuration Application Overview ..................................................................................................3-1Configuration Settings .........................................................................................................................3-2Configuration Functions ......................................................................................................................3-3
Add New Entry .............................................................................................................................3-3Save to XML.................................................................................................................................3-3
Chapter 4 - Configuring Devices
Bar Code Scanner (RS-232) ................................................................................................................4-1Bar Code Scanner (USB).....................................................................................................................4-1Bar Code Scanner (USB Serial Emulation).........................................................................................4-1Transaction Terminal (RS-232)...........................................................................................................4-2Transaction Terminal (USB) ...............................................................................................................4-2Transaction Terminal (RS-485)...........................................................................................................4-2
Chapter 5 - Hand Held Products JavaPOS and OPOS Controls Tester (UltraTester) Applications
Hand Held Products JavaPOS Ultra Tester .........................................................................................5-1Hand Held Products OPOS Ultra Tester .............................................................................................5-1Running the UltraTester ......................................................................................................................5-2
Chapter 6 - Hand Held Products JavaPOS Host Sample Application
Running JavaPOS Host Sample ..........................................................................................................6-1
Chapter 7 - Overview of UnifiedPOS DirectIO
DirectIO Method..................................................................................................................................7-1DirectIO Event.....................................................................................................................................7-1
i
Chapter 8 - DirectIO Command Details for Scanner Controls
JavaPOS Usage Example.....................................................................................................................8-1OPOS Usage Example.........................................................................................................................8-1
Chapter 9 - DirectIO Command Details for Transaction Terminal Controls
Returns.................................................................................................................................................9-1Supported DirectIO Commands for Interfacing to Transaction Terminals .........................................9-2JavaPOS DirectIO Commands ............................................................................................................9-3
DISPLAY_Bitmap .......................................................................................................................9-3DISPLAY_Box ............................................................................................................................9-4DISPLAY_Clear ..........................................................................................................................9-4DISPLAY_Logo ..........................................................................................................................9-5DISPLAY_ResetLogo .................................................................................................................9-5DISPLAY_SetFont ......................................................................................................................9-5DISPLAY_SetLogoFile ...............................................................................................................9-6DISPLAY_Text ...........................................................................................................................9-6MEM_DeleteObj ..........................................................................................................................9-7MEM_DeleteVar ..........................................................................................................................9-8MEM_FindObj .............................................................................................................................9-8MEM_FindVar .............................................................................................................................9-9MEM_GetFree .............................................................................................................................9-9MEM_GetVar ............................................................................................................................9-10MEM_SetVar .............................................................................................................................9-10PINIO_SetMasterKeyID ............................................................................................................9-11PINIO_SetSessionKey ...............................................................................................................9-11PROMPT_Number .....................................................................................................................9-12SCRIPT_Goto ............................................................................................................................9-12SCRIPT_GotoVar ......................................................................................................................9-13SCRIPT_IsPaused ......................................................................................................................9-13SCRIPT_IsRunning ...................................................................................................................9-14SCRIPT_IsScript ........................................................................................................................9-14SCRIPT_IsVar ...........................................................................................................................9-15SCRIPT_Reset ...........................................................................................................................9-15SCRIPT_Run .............................................................................................................................9-16SCRIPT_Set ...............................................................................................................................9-16SCRIPT_Stop .............................................................................................................................9-17SYS_DownloadFirmware ..........................................................................................................9-17SYS_GetError ............................................................................................................................9-18SYS_GetModel ..........................................................................................................................9-18SYS_GetName ...........................................................................................................................9-19SYS_GetVersion ........................................................................................................................9-19SYS_IsAvailable ........................................................................................................................9-20SYS_IsError ...............................................................................................................................9-20SYS_Reboot ...............................................................................................................................9-20SYS_Reset .................................................................................................................................9-21SYS_SetDebug ...........................................................................................................................9-21Text_GetVar ...............................................................................................................................9-22Text_IsVar .................................................................................................................................9-22Text_SetVar ...............................................................................................................................9-23
OPOS DirectIO Commands...............................................................................................................9-24PW_CLEARSCREEN ...............................................................................................................9-24PW_DISPLAYBITMAPFILE ...................................................................................................9-24PW_DISPLAYBOX ..................................................................................................................9-24PW_DISPLAYLOGO ................................................................................................................9-25
ii
PW_MEMDELETEOBJ ............................................................................................................9-25PW_MEMDELETEVAR ...........................................................................................................9-25PW_MEMFINDOBJ ..................................................................................................................9-26PW_MEMFINDVAR ................................................................................................................9-26PW_MEMGETFREE .................................................................................................................9-26PW_MEMGETVAR ..................................................................................................................9-27PW_MEMSETVAR ...................................................................................................................9-27PW_NUMBERPAD ...................................................................................................................9-28PW_PUTTEXT ..........................................................................................................................9-28PW_RESETLOGO ....................................................................................................................9-29PW_SCRIPTGOTO ...................................................................................................................9-29PW_SCRIPTGOTOVAR ...........................................................................................................9-29PW_SCRIPTISPAUSED ...........................................................................................................9-30PW_SCRIPTISRUNNING ........................................................................................................9-30PW_SCRIPTISSCRIPT .............................................................................................................9-30PW_SCRIPTISVAR ..................................................................................................................9-31PW_SCRIPTRESET ..................................................................................................................9-31PW_SCRIPTRUN ......................................................................................................................9-31PW_SCRIPTFILELOAD ...........................................................................................................9-32PW_SCRIPTSTOPLOAD .........................................................................................................9-32PW_SETFONT ..........................................................................................................................9-32PW_SETLOGO .........................................................................................................................9-33PW_SETMKEY .........................................................................................................................9-33PW_SETSKEY ..........................................................................................................................9-34PW_SYSDOWNLOAD .............................................................................................................9-34PW_SYSGETERROR ...............................................................................................................9-35PW_SYSGETMODEL ..............................................................................................................9-35PW_SYSGETNAME .................................................................................................................9-35PW_SYSGETVERSION ...........................................................................................................9-36PW_SYSISAVAILABLE ..........................................................................................................9-36PW_SYSISERROR ...................................................................................................................9-37PW_SYSREBOOT ....................................................................................................................9-37PW_SYSRESET ........................................................................................................................9-37PW_SYSSETDEBUG ...............................................................................................................9-38PW_TEXTGETVAR .................................................................................................................9-38PW_TEXTISVAR .....................................................................................................................9-38PW_TEXTSETVAR ..................................................................................................................9-39
Chapter 10 - Technical Assistance
iii
iv
1
Un
Introduction
Hand Held Products provides a set of Java for Point of Service (JavaPOS or JPOS) and OLE for Retail Point of Sale (OPOS) controls that can be used to interface to a specified group of Hand Held Products products when writing JavaPOS or OPOS applications for retail environments. The Hand Held Products JavaPOS and Hand Held Products OPOS controls support RS-232, USB, and RS-485 interfaces to the connected device in Windows® XP, 2000, 98, and NT environments. These JavaPOS and OPOS controls are compliant with the UnifiedPOS Retail Peripheral Architecture specification v1.9 dated 1/16/2005. UnifiedPOS is an architectural specification for application interfaces to point-of-service devices that are used in the retail environment. The Hand Held Products JavaPOS and Hand Held Products OPOS Controls (from here on referred to as the Hand Held Products UnifiedPOS or UPOS controls) are two implementations of the UnifiedPOS specification. The UnifiedPOS specification can be found at:
http://www.javapos.com/public.app.guide.9.html
The Hand Held Products UPOS controls provide an application interface to the Hand Held Products Transaction Team™ 8000 Series Terminals and the following Hand Held Products scanners: 3800, 4600g, 4620, 4800i, 3800r, 3820, and 3800i. In the case of the Transaction Team™ 8000 Series Terminal, multiple device categories are supported within the one physical device. That is, the Transaction Team™ 8000 Series Terminal supports the following device categories: Line Display, MSR, PIN Pad, POS Keyboard, Signature Capture, and Tone Indicator. Hand Held Products provides a JavaPOS and OPOS control for each of those device categories along with a control for the Scanner device category.
The following table shows the relationship between the Hand Held Products product and the Hand Held Products UPOS control that provides an application interface to that product.
Note: Hand Held Products UPOS controls do not work with the Transaction Team 3100 terminal.
This programmer’s guide details the following:
• Installation and system configuration of Hand Held Products JavaPOS and OPOS controls• Hand Held Products UnifiedPOS Configuration Application• Hand Held Products JavaPOS Controls Tester application (JPOS UltraTester)• Hand Held Products OPOS Controls Tester application (OPOS UltraTester)• Hand Held Products JavaPOS Sample Host application• DirectIO methods that are specific to the Hand Held Products JavaPOS and OPOS controls
For further detailed information (methods, properties, events) about the application interfaces to the Hand Held Products supported devices, refer to the UnifiedPOS v1.9 specification with which the Hand Held Products JavaPOS and OPOS supported controls were developed to be in compliance.
Supported Java Versions
The Hand Held Products JavaPOS and OPOS controls both share common source code at the service layer that is used to communicate directly to the Hand Held Products supported products. This common source code requires the Java Runtime Environment (JRE) 1.3.1 and above to be installed and running on your environment prior to using the Hand Held Products UPOS controls. In order to develop JavaPOS or OPOS applications using the Hand Held Products UPOS controls, the JRE must either already exist on your system, or be selected during installation to be installed onto your system. JavaPOS applications written using the Hand Held Products JavaPOS controls must be developed using the Java SDK version 1.3.1 (which includes the JRE 1.3.1) and above.
Device Category Hand Held Products Physical Device
Line Display TT8000 Series Transaction Terminal
POS Keyboard TT8000 Series Transaction Terminal
PIN Pad TT8000 Series Transaction Terminal
MSR - Magnetic Stripe Reader TT8000 Series Transaction Terminal
Signature Capture TT8000 Series Transaction Terminal
Tone Indicator TT8000 Series Transaction Terminal
Scanner (Bar Code Reader) 2020, 3800, 4010, 4080, 4200, 4600g (1IT4600), 4620, 4800i (1IT4800), 3800r (1IT5600), 3820 (1IT5620), 3800i (1IT5800)
1. Former model number
ifiedPOS (UPOS) Controls Programmer’s Guide 1 - 1
1 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
2
Un
Hand Held Products UPOS Installation and System Configuration
To set up the Hand Held Products JavaPOS and/or OPOS controls to run in your environment, you must:
1. Run the Hand Held Products UnifiedPOS Installation program
2. Configure your Windows system environmental path variable
3. Run the Hand Held Products UnifiedPOS Configuration Application
This chapter details steps 1 and 2 above. See Hand Held Products UnifiedPOS Configuration Application beginning on page 3-1 for information about running the Hand Held Products UnifiedPOS Configuration Application.
The Hand Held Products UnifiedPOS Installation program allows you to install either the Hand Held Products JavaPOS and/or Hand Held Products OPOS controls, along with optional items, such as test programs, a sample program, and Java Runtime 1.4.2_04. The following are the components that can be selected during installation:
• Hand Held Products JavaPOS Controls (required, when OPOS Controls are selected)The Hand Held Products JavaPOS controls, which let you develop JavaPOS applications to interface to the supported Hand Held Products devices. This component also includes the Hand Held Products UnifiedPOS Configuration Application that lets you configure your communication parameters along with other miscellaneous items. See Hand Held Products UnifiedPOS Configuration Application beginning on page 3-1 for further details.
• Hand Held Products OPOS Controls (optional, depend on JavaPOS Controls)The Hand Held Products OPOS controls, which let you develop OPOS applications to interface to the supported Hand Held Products devices. This component also includes the Hand Held Products UnifiedPOS Configuration Application that lets you configure your communication parameters along with other miscellaneous items. See Hand Held Products UnifiedPOS Configuration Application beginning on page 3-1 for further details.
• Hand Held Products JavaPOS and OPOS UltraTester Applications (optional, depend on JavaPOS Controls)These applications test each of the supported Hand Held Products JavaPOS or OPOS controls. See Hand Held Products JavaPOS and OPOS Controls Tester (UltraTester) Applications beginning on page 5-1 for further details.
• Hand Held Products JavaPOS Sample Host Application (optional, depend on JavaPOS Controls)A sample retail point-of-sale application that uses all the Hand Held Products JavaPOS controls to interface to a Transaction Terminal and scanner. The Java source code for this sample host is installed so you may reference it when writing your own JavaPOS application. The Transaction Terminal binary script file is also installed and can be downloaded to the Transaction Terminal via the Hand Held Products JavaPOS or Hand Held Products OPOS UltraTester Application. See Hand Held Products JavaPOS Host Sample Application beginning on page 6-1 for further details.
• Java Runtime Environment (JRE) 1.4.2_04 (optional)Optional if JRE 1.3.1 or above is already resident on the system. Otherwise this is required to use either the Hand Held Products JavaPOS or Hand Held Products OPOS controls.
Installation Procedures
The following steps describe the Hand Held Products UPOS installation process:
1. Download the UPOS installation program, HandHeldUPOSInstall.exe, into a temporary folder on your hard drive (for exam-ple: C:\temp\handheld\upos).
2. Within Windows Explorer, locate the installation program, HandHeldUPOSInstall.exe. Begin the installation and follow the instructions on the screens that appear.
3. If installing OPOS controls, restart your system when prompted. Once your system is restarted, the UPOS installation program automatically starts up again to finish the installation. If you have selected not to install the JRE, your installation is now complete. Otherwise, the Java Runtime v1.4.2_04 installation begins.
Installing Java Runtime v1.4.2_04 (optional)Before utilizing the Hand Held Products UPOS controls, you must have JRE 1.3.1 or above installed on your PC. This installation is automatically launched when the Java Runtime 1.4.2_04 option is selected. The Typical installation installed the Java Runtime Environment by default in the C:\Program Files\Java\j2re1.4.2_04 folder. If you want to install the Java Runtime in another folder, perform a Custom installation.
System Configuration
After completing and verifying the installation, you must perform the following system configuration before utilizing the installed components. This will ensure that the JRE is in your Windows system environmental PATH variable. The following steps describe this process.
ifiedPOS (UPOS) Controls Programmer’s Guide 2 - 1
Configuring Windows 2000 and XP PATH Environment Variable (required)1. Right click on the My Computer icon and select Properties, then
click on the Advanced tab.
2. Click on Environment Variables to set the path system variable. Select Path under System Variables.
3. Note: <install_dir> stands for the directory where you installed the files. Click on Edit and enter <install_dir>\bin;<java_runtime_dir>\bin\client, where <install_dir>\bin indicates where the installation file is stored and <java_runtime_dir>\bin\client indicates where the Java Runtime Environment resides. For example: C:\Program Files\Hand Held Products\UPOS\bin; C:\Program Files\Java\j2re1.4.2_04\bin\client. Click OK.
2 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
Configuring Windows NT PATH Environment Variable (required)1. Right click on the My Computer icon and select Environment.
2. Select Path under System Variables.
3. Enter <install_dir>\bin and <java_runtime_dir>\bin\client at the end of the variable value string to indicate where the Java Runtime Environment resides. For example: C:\Program Files\Java\j2re1.4.2_04\bin; C:\Program Files\Java\j2re1.4.2_04\bin\client. Click OK.
Configuring Windows 98 PATH Environment Variable (required)1. On the Start Menu, select Run, enter msconfig, and click on OK.
2. Click on the Autoexec.bat tab.
3. Enter <install_dir>\bin and <java_runtime_dir>\bin\client at the end of the variable value string to indicate where the Java Runtime Environment resides. For example: C:\Program Files\Java\j2re1.4.2_04\bin; C:\Program Files\Java\j2re1.4.2_04\bin\client.Click OK.
UnifiedPOS (UPOS) Controls Programmer’s Guide 2 - 3
Installation and System Configuration CompleteThe setting of the Windows system environmental path variable completes the installation and system configuration for the Hand Held Products JavaPOS and/or OPOS controls. To utilize the installed controls, you must next configure them to fit your needs (communication parameters, special parameters to interface to a Transaction Terminal script, log files, etc.) by running the UnifiedPOS Configuration Application (see Hand Held Products UnifiedPOS Configuration Application beginning on page 3-1).
Updating Windows CLASSPATH Environment Variable (optional)The install adds several JAR files to your Windows system environmental CLASSPATH variable. By default, these JAR files are located under the <install_dir>/bin directory. If you are running other Java based applications on the same system, you may wish to modify the locations of the following 3rd party JAR files to reflect your environment:
• comm.jar• jcl.jar• jposXX-controls.jar (where XX denotes the version, for example jpos19-controls.jar)• xerces.jar
When any of these locations are modified, you should also update the following BAT files to reflect the changes:
• RunJposSampleHostApp.bat• RunJposUltraTester.bat• RunUposConfig.bat
Running Third Party (non-Hand Held Products) Applications with Hand Held Products Devices
Running a third party Java application requires the location of jpos.xml, which resides in <install_dir>\res. You must update the jpos.config.populatorFile attribute located within the jcl.jar file’s jpos.properties file. The following is an example of the new jpos.properties entry:
#------------------------------------------------------------------------------------
# Use this property for the JCL to load a specific file (cfg or XML)
# when not using multiple populators via the jpos.config.populator.class.
# multi-property
#------------------------------------------------------------------------------------
jpos.config.populatorFile=C://HandHeldProducts/UPOS/res/jpos.xml
You must verify that your third party application’s classpath includes the path to the device specific jar, hhpjpos.jar, as well as any dependent files such as comm.jar. The updated classpath will be similar to the following:
set classpath=%classpath%;c:\Hand Held Products\UPOS\bin\comm.jar;c:\<install.dir>
Uninstall Instructions
To uninstall the Hand Held Products JavaPOS Controls, OPOS Controls, JavaPOS UltraTester, OPOS UltraTester, and JavaPOS Sample Host Application components, use Add or Remove Programs from the Control Panel. Remove the Hand Held Products UPOS Controls software. To uninstall the Java Runtime component, remove the Java 2 Runtime Environment, SE v1.4.2_04 software.
2 - 4 UnifiedPOS (UPOS) Controls Programmer’s Guide
3
Un
Hand Held Products UnifiedPOS Configuration
ApplicationOnce the installation and system configuration are complete, you must configure the Hand Held Products JavaPOS and/or OPOS Controls. The installation of the Hand Held Products JavaPOS and/or OPOS Controls component includes the installation of the Hand Held Products UnifiedPOS Configuration Application. This application sets up your system for proper operation with the connected Hand Held Products device. The Hand Held Products UnifiedPOS Configuration Application allows you to configure parameters for your communication interface to the devices (RS-232, USB, or RS-485), and also configure special parameters to be used when interfacing to a Transaction Terminal script (custom script forms and signature formats).
To run the Hand Held Products UnifiedPOS Configuration Application, launch the <install_dir>\RunUposConfig.bat batch file in a Windows Explorer window. This file is in C:\<install_dir>\RunUposConfig.bat.
Configuration Application Overview
The configuration application comes with 7 default entry names corresponding to 7 UnifiedPOS controls (device categories) that were installed by the UnifiedPOS controls component.
The following is an example of the screen that is displayed when the UPOS Configuration Application is executed:
Entry Name Device Category Hand Held Products Physical Device
L1 Line Display Transaction Team™ 8000 Series Terminal
SCAN1 Scanner 2020, 3800, 4010, 4080, 4200, 4600g (1IT4600), 4620, 4800i (1IT4800), 3800r (1IT5600), 3820 (1IT5620), 3800i (1IT5800)
1. Former model number
K1 POSKeyboard Transaction Team™ 8000 Series Terminal
P1 PinPad Transaction Team™ 8000 Series Terminal
M1 MSR Transaction Team™ 8000 Series Terminal
S1 SignatureCapture Transaction Team™ 8000 Series Terminal
T1 ToneIndicator Transaction Team™ 8000 Series Terminal
ifiedPOS (UPOS) Controls Programmer’s Guide 3 - 1
Configuration Settings
Setting Description
Device Bus Each device category supports three types of Device Bus values: RS-232, USB, and RS-485. When you select the device bus, the corresponding properties selections for that interface are enabled.
Port Name, Baud Rate, Parity – Data Bits – Stop Bits, Flow Control
RS-232 properties are only selectable if Device Bus is set to RS-232. These values must match the values that are set for the PC communications port and for the Hand Held Products device.Note: If the scanner is connected to a USB port, but configured as USB COM port emulation, then you
must select RS-232 as the device bus, and select the correct virtual COM port. All other RS-232 parameters (baud rate, parity, data bits, stop bits, and flow control) can be ignored for USB COM port emulation.
USB Device, USB Device Serial #
USB Properties are only selectable if Device Bus is set to USB.
Connection Port, Con-nection Slot, Device ID, Initialize POS Sub-system
RS-485 properties are only selectable if Device Bus is set to RS-485. These values must match the values that are set for the Hand Held Products device. Connection Port:: Use the default value. Connection Slot:: Use the default value.Device ID: Refer to Transaction Terminal (RS-485) on page 4-2 to configure the Device ID.Initialize POS Subsystem: Check this box if your application is the first to initialize the POS subsystem. Other-
wise, leave the box unchecked.
Log File If a Log File name is specified, a log file will be kept for those UPOS controls activities in the <install_dir> folder.Note: The OPOS Service Object always creates a log file, “<device>so.log”, and stores it in the install
directory by default (<install_dir>) or in the location specified by the registry key: HKLM\SW\OLEforRetail\ServiceInfo\Hand Held Products\Logpath
Text Rows,Column Rows
These parameters may only be set for a Line Display Device category.
Custom Script Form This parameter may only be set for PinPad and POSKeyboard Device categories. This parameter is used only when inter-facing to a corresponding script residing on a Transaction Terminal. This value represents the name of the form in the script to which the PinPad and/or POS Keyboard UPOS control will interface. For the PinPad control, this parameter must match the name of the Pinpad form in the script. For the POS Keyboard control, this parameter must match the name of the form in the script that will be sending data via the POS Keyboard control. When this parameter is specified, the UPOS control goes to the specified script form on the Transaction Terminal upon the beginning of an EFT Transaction (PinPad control), and/or upon the device being enabled (POS Keyboard control).
Signature Format This parameter may only be set for the SignatureCapture Device category and has valid values of: Packet, CMP, and CMP_Base64. This value represents the type of signature data returned by Transaction Terminal to SignatureCapture UPOS control. This is used only in conjunction with a corresponding script residing on a Transaction Terminal. This parameter must match the format of the signature output from the script.
3 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
Configuration Functions
Add New Entry1. On the initial Hand Held Products UnifiedPOS Configuration Application screen, select New Entry …
2. Enter a meaningful Device ID (Entry Name) and select an appropriate Device Category (UPOS Control). If you utilize the UPOS control (by writing your own application or using the installed JavaPOS or OPOS UltraTester application), the Device ID must be passed to the JavaPOS or OPOS open(…) method to open communications with the desired device.
3. Click OK to add the new entry.
4. Modify settings for new entry as described on page 3-2.
Save to XMLThe UnifiedPOS Configuration Application saves modified UPOS configuration information in the <install_dir>\res\jpos.xml file. This file should never be edited by any program other than the Hand Held Products UnifiedPOS Configuration Application. Updated UPOS configuration information can be saved by clicking Save To XML.
UnifiedPOS (UPOS) Controls Programmer’s Guide 3 - 3
3 - 4 UnifiedPOS (UPOS) Controls Programmer’s Guide
4
Un
Configuring Devices
Bar Code Scanner (RS-232)
1. Connect the scanner to your computer/terminal according to the installation procedures in the scanner’s user guide.
2. Once the scanner has been fully connected, power up the terminal/computer.
3. Log on to your computer.
4. Scan the RS-232 Interface bar code in your scanner’s user guide.
5. Scan an appropriate baud rate bar code in your scanner’s user guide. This baud rate must match what was specified for the device by the UnifiedPOS Configuration Application.
6. Scan an appropriate RS-232 Word Length bar code in your scanner’s user guide. The parity - data bits - stop bits setting must match what was specified for the device by the UnifiedPOS Configuration Application.
7. Scan an appropriate RS-232 Handshaking RTS/CTS bar code in your scanner’s user guide. The RTS/CTS setting must match what was specified for the device by the UnifiedPOS Configuration Application.
Bar Code Scanner (USB)
1. Connect the USB interface cable to the scanner.
2. With the computer/terminal powered on, connect the USB connector to a target computer/terminal's USB port.
3. Immediately after the USB connection has been made, scan the USB HID bar code in your scanner’s user guide. This sets the terminal ID for the scanner to 131.
4. Wait until the new device has been detected and recognized by the Windows operating system.
5. Right click on My Computer and select Properties, then click on the Hardware tab.
6. Click on Device Manager.
7. Expand the Human Interface Devices entry. The following two entries should appear:
• HID-compliant device• USB Human Interface Device
Bar Code Scanner (USB Serial Emulation)
1. Download the Matrix USB Serial Emulation Driver from the Hand Held Products website (www.handheld.com). Unzip the archive to a location of your choice.
2. Connect the USB interface cable to the scanner.
3. With the computer/terminal powered on, connect the USB connector to a target computer/terminal’s USB port.
4. Immediately after the USB connection has been made, scan the USB COM Port Emulation bar code in your scanner’s user guide. This sets the terminal ID for the scanner to 130.
5. Wait until the new device has been detected and recognized by the Windows operating system. The operating system will ask for the driver (the .inf file). Direct it to the location where you unzipped the driver files.
6. Right click on My Computer and select Properties, then click on the Hardware tab.
7. Click on Device Manager.
8. Expand the Ports entry and verify the scanner appears, followed by the virtual COM port number.
ifiedPOS (UPOS) Controls Programmer’s Guide 4 - 1
Transaction Terminal (RS-232)
1. Connect the Transaction Terminal to your computer/terminal according to the installation procedures in the startup guide.
2. Upon startup of the Transaction Terminal, the initial screen prompts you to Touch the pad now to enter setup mode. Touch the screen with the stylus to enter setup mode.
3. Touch the Host button.
4. Check/Uncheck the Enable CTS holdoff check box as specified for the Transaction Terminal by the UnifiedPOS Configuration Application.
5. Check the appropriate Baud Rate (bps): check box as specified for the Transaction Terminal device by the UnifiedPOS Configuration Application.
6. Select Accept on the Host configuration screen.
7. Select Accept on the Setup screen.
Transaction Terminal (USB)
1. Connect the Transaction Terminal to your computer/terminal according to the installation procedures in the startup guide.
2. Wait until the new device has been detected and recognized by the Windows operating system.
3. Right click on My Computer and select Properties, then click on the Hardware tab.
4. Click on Device Manager.
5. Expand the Human Interface Devices entry. The following two entries should appear:
• HID-compliant device• USB Human Interface Device
Transaction Terminal (RS-485)
1. Power down the IBM 46XX register.
2. Connect the cable to the Transaction Terminal and to port 9 in the back of the register.
3. Power up the IBM46XX register.
4. Upon startup of the Transaction Terminal, the initial screen prompts you to Touch the pad now to enter setup mode. Touch the screen with the stylus to enter setup mode.
5. Touch the Host button.
6. Check that the correct Device ID is specified for the Transaction Terminal by the UnifiedPOS Configuration Application.
7. Select Accept on the Host configuration screen.
8. Select Accept on the Setup screen.
9. Power down the register, then power it back up.
4 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
5
Un
Hand Held Products JavaPOS and OPOS Controls Tester (UltraTester) Applications
The Hand Held Products JavaPOS and OPOS UltraTesters are optional components. These applications allow you to test all the Hand Held Products JavaPOS /OPOS controls individually. Before running the UltraTester, you must first configure your devices via the Hand Held Products UnifiedPOS Configuration Application. Refer to Hand Held Products UnifiedPOS Configuration Application beginning on page 3-1.
Hand Held Products JavaPOS Ultra Tester
To run the Hand Held Products JavaPOS UltraTester application, launch the <install_dir>\RunUPOSUltraTester.bat batch file in a Windows Explorer window. When the Hand Held Products JavaPOS UltraTester is initially executed, the following screen displays:
Hand Held Products OPOS Ultra Tester
To run the Hand Held Products OPOS UltraTester application, launch the <install_dir>\OPOSUltraTester.exe file in a Windows Explorer window.
ifiedPOS (UPOS) Controls Programmer’s Guide 5 - 1
When the Hand Held Products OPOS UltraTester is initially executed, the following screen displays:
Running the UltraTester
UltraTester allows you to perform the main functions provided by JavaPOS/OPOS. Using UltraTester, you can open the COM port, claim the device, enable data events, and then receive device data. It can also change supported JavaPOS/OPOS control properties and verify the new values. UltraTester also provides an interface for using and testing the various DirectIO functions available on the Hand Held Products JavaPOS/OPOS controls that interface to the Transaction Terminals.
The GUI items on the tabs on the right side of the application apply to the control shown on the currently displayed tab on the left side of the main window. For example, to open the keyboard control, you must first display the keyboard control tab on the left side of the application. Then click the Open button on the tab on the right side window. This operation opens only the keyboard control. By selecting different left side tabs, multiple controls can be opened and tested simultaneously.
5 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
6
Un
Hand Held Products JavaPOS Host Sample Application
The Hand Held Products JavaPOS Host Sample application is an optional component that simulates a point-of-sale register interfacing to a Transaction Terminal along with an Hand Held Products scanner. JavaPOS Host Sample exercises all the JavaPOS controls for the Transaction Terminal (MSR, Sig, PinPad, LineDisplay, Keyboard, Toner) and also exercises the scanner control. The Transaction Terminal contains a script that has the typical point-of-sale functionality (line item display, credit, debit, signature, instant credit application, survey, etc.). There is a separate script for RS-232/RS-485 connectivity and USB connectivity. Before running JavaPOS Host Sample, the Transaction Terminal script must be downloaded to the Transaction Terminal. This can be done via a directIO function using the Hand Held Products JavaPOS UltraTester, or can be done via an Hand Held Products supplied TT8000 Series Loader utility. The script files are in the following directories:
C:\<install_dir>\bin\UPOS_Sample_Script_USB.binC:\<install_dir>\bin\UPOS_Sample_Script_RS232_RS_485.bin
Once the script is downloaded, the Hand Held Products UnifiedPOS Configuration Application must be run to configure the JavaPOS controls properly (see Hand Held Products UnifiedPOS Configuration Application beginning on page 3-1). Along with setting the proper communication parameters to accommodate the connections for your devices, the following special parameters must be configured before running JavaPOS Host Sample:
To run JavaPOS Host Sample, launch the <install_dir> RunJposSampleHostApp.bat batch file in a Windows Explorer window. This file will be in a directory as follows:
C:\<install_dir>\RunJposSampleHostApp.bat
When JavaPOS Host Sample is initially executed, the following screen displays:
Note: In order to use Debit, your system must be injected with a DUKPT key. For information on key injection, contact Technical Support (see Technical Assistance on page 10-1).
Running JavaPOS Host Sample
When JavaPOS Host Sample is in its idle state, the application status area indicates it is waiting for a bar code scan to initiate a transaction. The survey button is enabled at this time and, if selected, initiates a survey on the Transaction Terminal.
Device Category Custom Script Form Signature Format
PinPad padPin n/a
POSKeyboard padInstantCredit_SSN n/a
SignatureCapture n/a CMP
Line Display padLineDisplay n/a
ifiedPOS (UPOS) Controls Programmer’s Guide 6 - 1
To initiate a transaction, a bar code must either be scanned or manually entered via the Manual Item Entry text box. JavaPOS Host Sample displays the scanned data and enables the payment buttons. The script also displays the scanned data. Credit, debit, or instant credit options may be selected to complete a transaction. When the transaction has been completed, a receipt window displays the data of the transaction. Canceling a transaction takes you back to the idle state. Selecting the exit button terminates JavaPOS Host Sample and returns to the idle screen in the script.
6 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
7
Un
Overview of UnifiedPOS DirectIO
UnifiedPOS provides a generic and standard interface of functionality to POS application developers. However, a device may provide functionality that is not otherwise supported by the standard UnifiedPOS Control for its device category. UnifiedPOS provides a mechanism for supporting the inclusion of device-specific functionality within the implementation of a UnifiedPOS control. This mechanism is provided via the DirectIO method of a UnifiedPOS control.
Along with the DirectIO method, UnifiedPOS has a mechanism for sending vendor-specific device data back to the application. This mechanism is provided via the DirectIO event of a UnifiedPOS control.
The Hand Held Products UnifiedPOS controls (Hand Held Products JavaPOS and OPOS controls) that provide the application interface to the Transaction Terminal (Line Display, MSR, PinPad, POS Keyboard, Signature Capture, Tone Indicator) all implement the DirectIO method to provide additional functionality to interface to the Transaction Terminal that is not otherwise supported by standard UPOS methods. The UnifiedPOS scanner control also implements the DirectIO method to support any Hand Held Products menu command being sent to an Hand Held Products scanner that is not otherwise supported by standard UPOS methods. The UnifiedPOS controls place the results from a DirectIO command in an object returned in the DirectIO event handler.
DirectIO Method
Syntax Void directIO (int command, int[] data, Object object) throws UposException;
DirectIO Event
JavaPOS Usage:
Interface: jpos.events.DirectIOListener
Method: directIOOccurred (DirectIOEvent e);
OPOS Usage:
Event: DirectIOEvent
The DirectIOEvent contains the following properties:
Parameter Description
Command Command number whose specific values are assigned by the UnifiedPOS service.
Data An array of one modifiable integer whose specific values or usage vary by command and UnifiedPOS service.
Object Additional data whose usage varies by command and UnifiedPOS service.
Property Type Description
EventNumber int Event number whose specific values are assigned by the UnifiedPOS service
Data int Additional numeric data. Specific values vary by the EventNumber and the Unified-POS service. This property may be set.
Object object Additional data whose usage varies by the EventNumber and the UnifiedPOS ser-vice. This property may be set.
ifiedPOS (UPOS) Controls Programmer’s Guide 7 - 1
7 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
8
Un
DirectIO Command Details for Scanner Controls
The Hand Held Products JavaPOS and OPOS Scanner Controls use the directIO method to send an Hand Held Products menu command to an Hand Held Products scanner. The resulting response is delivered to the your application via a directIO event. Refer to your scanner’s user guide for a list of menu commands and responses available for your particular scanner.
If the first parameter of the directIO method (see Command on page 7-1) is 0, the Hand Held Products JavaPOS or OPOS Scanner Control internally forms the correct Hand Held Products menu command syntax by adding SYN-M-CR to the beginning of the command. The third parameter of the directIO method (see Object on page 7-1) is treated as a string.
If the first parameter of the directIO method is 1, the scanner control treats the third parameter as a byte[] object and transmits those bytes as they are to the scanner.
JavaPOS Usage Example
try
{
jpos.Scannerctrl = new jpos.Scanner;
ctrl.Open (“SCAN1”);
String strCmd = “TERMID?”;
Ctrl.directIO(0, new int[0], strCMD);
}
catch(JPOSException jpe)
{
(Error handling code)
}
The following is the event handler for the response. Notice that the raw data received from the device is returned in the m_byRawIOData field of the DeviceIOData object.
Void directIOOccurred(jpos.events.DirectIOEvent event)
{
DeviceIOData ioData = (DeviceIOData)event.getObject();
java.lang.byte[] bytResults = ioData.m_byRawIOData
// Do some processing with bytResults
// …
}
OPOS Usage Example
Private Sub DoDirectIO_Click()
On Error Goto ehandler
Dim result As Long
Dim n As Long
Dim str As String
str = ”TERMID?.”
result = ScannerCO1.DirectIO(0, n, str)
if result <>0 Then
MsgBox “Error #:”&str (result)
End If
Exit Sub
ehandler:
MsgBox “Some Error”
Exit Sub
End Sub
ifiedPOS (UPOS) Controls Programmer’s Guide 8 - 1
8 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
9
Un
DirectIO Command Details for Transaction Terminal Controls
This section provides details on the directIO commands supported by the Hand Held Products UnifiedPOS controls that interface to a Transaction Terminal (Line Display, MSR, PinPad, POS Keyboard, Signature Capture, Tone Indicator). Each supported command is detailed with an example of use.
In order to use directIO method calls in your JavaPOS or OPOS application, you must pull a file into your application that defines all the constants that correspond to the various directIO commands that are supported:
For JavaPOS applications, the following import statement must be added at the beginning of the application to utilize supported directIO commands:
Import com.hhp.jpos.TT8800CommandConst;
For OPOS applications, you must include one of the following header files in your application to utilize supported directIO commands:
hhp.bas (for Visual Basic applications) or hhpcmd.h (for Visual C++ applications)
The first parameter of the directIO method (see Command on page 7-1) contains a command number whose defined values are provided by the above mentioned files. There is a separate static constant integer defined for each command supported. The three support files: TT8800CommandConst.java, hhp.bas, and hhpcmd.h, are installed in the docs directory: <install_dir>docs. See page 9-2 for a list of the Transaction Terminal specific commands that are supported in the directIO method calls.
The third parameter of the directIO method (see Object on page 7-1) contains any additional data required by the command.
For JavaPOS applications, parameters for commands sent to the Transaction Terminal are usually stored in a java.util.LinkedList of objects when more than one parameter is required by the command. If the command to be sent requires only one parameter, the object parameter is a Java wrapper object such as a java.lang.String, java.lang.Byte[], or java.lang.integer.
For OPOS applications, parameters for commands sent to the Transaction Terminal are usually stored in strings when more than one parameter is required by the command. If the command to be sent requires only one parameter, the object parameter is a byte or integer.
Returns
The data property for a directIO event is always set to the associated command that was sent to the Transaction Terminal. For JavaPOS, retrieve the associated command by calling the DirectIOEvent.getData() method. The return value is of type int and should be a directIO command constant defined by the TT8800CommandConst interface.
The object property for a directIO event is always a com.hhp.jpos.DeviceIOData object that contains results of a directIO command. Retrieve the results of a DirectIO command by calling the DirectIOEvent.getObject() method. The return value is of type java.lang.Object and should be cast to a com.hhp.jpos.DeviceIOData object. The following code snippet shows a typical event handler code:
JavaPOS Usage:Import com.hhp.jpos.DeviceIOData;
Void directIOOccurred(jpos.events.DirectIOEvent event)
{
DeviceIOData ioData = (DeviceIOData)event.getObject();
Java.lang.String sMyResults = ioData.m_sDIOData;
// Do some processing with sMyResults
// …
}
OPOS Usage:Private Sub DirectIOEvent(EventNumber As Long, Data As Long, AdditionalStringData As String)
// Do some processing with Data
End Sub
ifiedPOS (UPOS) Controls Programmer’s Guide 9 - 1
Supported DirectIO Commands for Interfacing to Transaction Terminals
The table below documents the specific DirectIO commands available to users of the Hand Held Products UPOS controls (Line Display, MSR, PinPad, POS Keyboard, Signature Capture, and Tone Indicator) that support interfacing to Transaction Terminals. Commands are named from constants defined in the files:
JavaPOS Usage Interface file:
<install_dir>\docs\TT8800CommandConst.java
OPOS Usage Header/include files:
<install_dir>\docs\hhp.bas or hhpcmd.h
JavaPOS Command Page OPOS Command Page Description
DISPLAY_Bitmap 9-3 PW_DISPLAYBITMAPFILE 9-24 Draw a bitmap on the display
DISPLAY_Box 9-4 PW_DISPLAYBOX 9-24 Draw a solid box
DISPLAY_Clear 9-4 PW_CLEARSCREEN 9-24 Clear the display
DISPLAY_Logo 9-5 PW_DISPLAYLOGO 9-25 Draw the default displayed logo centered within the screen
DISPLAY_ResetLogo 9-5 PW_RESETLOGO 9-29 Reset the stored logo to the default system logo
DISPLAY_SetFont 9-5 PW_SETFONT 9-32 Set the current display font
DISPLAY_SetLogoFile 9-6 PW_SETLOGO 9-33 Load a bitmap image file to be the default displayed logo
DISPLAY_Text 9-6 PW_PUTTEXT 9-28 Draw text on the display
MEM_DeleteObj 9-7 PW_MEMDELETEOBJ 9-25 Delete a memory item
MEM_DeleteVar 9-8 PW_MEMDELETEVAR 9-25 Delete a named data variable from memory
MEM_FindObj 9-8 PW_MEMFINDOBJ 9-26 Find an item in memory
MEM_FindVar 9-9 PW_MEMFINDVAR 9-26 Check if a named data variable is in memory
MEM_GetFree 9-9 PW_MEMGETFREE 9-26 Get amount of free user memory in kilobytes
MEM_GetVar 9-10 PW_MEMGETVAR 9-27 Get the contents of a named variable
MEM_SetVar 9-10 PW_MEMSETVAR 9-27 Set the contents of a named variable
PINIO_SetMasterKeyID 9-11 PW_SETMKEY 9-33 Set the PIN Pad Master Key ID
PINIO_SetSessionKey 9-11 PW_SETSKEY 9-34 Set the PIN Pad Session Key
PROMPT_Number 9-12 PW_NUMBERPAD 9-28 Display a string number entry pad prompt on the unit
SCRIPT_Goto 9-12 PW_SCRIPTGOTO 9-29 Branch script execution to a label
SCRIPT_GotoVar 9-13 PW_SCRIPTGOTOVAR 9-29 Branch script execution to a label contained in a variable
SCRIPT_IsPaused 9-13 PW_SCRIPTISPAUSED 9-30 Check if a script is paused
SCRIPT_IsRunning 9-14 PW_SCRIPTISRUNNING 9-30 Check if a script is running
SCRIPT_IsScript 9-14 PW_SCRIPTISSCRIPT 9-30 Check if a script is in memory
SCRIPT_IsVar 9-15 PW_SCRIPTISVAR 9-31 Check if the named variable is a loaded script
SCRIPT_Reset 9-15 PW_SCRIPTRESET 9-31 Reset scripts and cancel any running script
SCRIPT_Run 9-16 PW_SCRIPTRUN 9-31 Execute a script at the beginning or at a label
SCRIPT_Set 9-16 PW_SCRIPTFILELOAD 9-32 Download a new script onto the Transaction Terminal
SCRIPT_Stop 9-17 PW_SCRIPTSTOPLOAD 9-32 Stop a script
SYS_DownloadFirmware 9-17 PW_SYSDOWNLOAD 9-34 Download new firmware to the Transaction Terminal
9 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
JavaPOS DirectIO Commands
This section explains how to use DirectIO commands when developing JavaPOS applications for Transaction Terminals.
DISPLAY_Bitmap
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command draws a bitmap onto the screen starting at the specified coordinate.
Parameter Descriptionjava.lang.String Full pathname to Bitmap Filejava.awt.Point xStart,yStart in pixels (upper left corner of displayed bitmap image)
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add( "c:\\my bitmap.bmp" );
int xStart = 5;
int yStart = 5;
cmdArgs.add(new Point(xStart, yStart));
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( DISPLAY_Bitmap, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
SYS_GetError 9-18 PW_SYSGETERROR 9-35 Get the error code
SYS_GetModel 9-18 PW_SYSGETMODEL 9-35 Get the model number
SYS_GetName 9-19 PW_SYSGETNAME 9-35 Get the model name
SYS_GetVersion 9-19 PW_SYSGETVERSION 9-36 Get the model version
SYS_IsAvailable 9-20 PW_SYSISAVAILABLE 9-36 Check if the system is available
SYS_IsError 9-20 PW_SYSISERROR 9-37 Check if an error has occurred
SYS_Reboot 9-20 PW_SYSREBOOT 9-37 Reboot the unit
SYS_Reset 9-21 PW_SYSRESET 9-37 Reset the system software, devices, and defaults
SYS_SetDebug 9-21 PW_SYSSETDEBUG 9-38 Set system debug message option on or off
Text_GetVar 9-22 PW_TEXTGETVAR 9-38 Get a variable's text contents
Text_IsVar 9-22 PW_TEXTISVAR 9-38 Check if a variable is of text data type
Text_SetVar 9-23 PW_TEXTSETVAR 9-39 Set a text value to a variable
JavaPOS Command Page OPOS Command Page Description
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 3
DISPLAY_Box
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command draws a solid rectangular area using the current foreground color on the screen.
Parameter Descriptionjava.awt.Point xStart,yStart (starting x,y coordinate position in pixels)java.awt.Point xWidth,yHeight (width/height of box in pixels)
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
int nStartX = 0;
int nStartY = 0;
cmdArgs.add(new Point(nStartX, nStartY));
int nWidth = 20;
int nHeight = 20;
cmdArgs.add(new Point(nWidth, nHeight));
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( DISPLAY_Box, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
DISPLAY_Clear
This command clears all contents of the display.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( DISPLAY_Clear, new int[0], null );
}
catch (JposException jpe)
{
(Error handling code)
}
9 - 4 UnifiedPOS (UPOS) Controls Programmer’s Guide
DISPLAY_Logo
This command centers the default logo on the screen. See DISPLAY_SetLogoFile on page 9-6 for information about changing the default logo.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( DISPLAY_Logo, new int[0], null );
}
catch (JposException jpe)
{
(Error handling code)
}
DISPLAY_ResetLogo
This command resets the displayed default logo to the unit's system logo.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( DISPLAY_ResetLogo, new int[0], null );
}
catch (JposException jpe)
{
(Error handling code)
}
DISPLAY_SetFont
This command sets the font to be used when displaying text.
Parameter Descriptionjava.lang.Integer ID that identifies font type
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 5
The font type may be one of the following TT8800CommandConst interface constants:DISPLAY_Font8x8DISPLAY_Font16x16DISPLAY_Font6x8DISPLAY_Font8x12DISPLAY_Font12x16DISPLAY_Font16x24
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
Example
try
{
java.lang.Integer nFontID = new java.lang.Integer(DISPLAY_Font16x16);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( DISPLAY_SetFont, new int[0], nFontID );
}
catch (JposException jpe)
{
(Error handling code)
}
DISPLAY_SetLogoFile
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command loads a bitmap to be the default logo displayed.
Parameter Descriptionjava.lang.String Full pathname to Bitmap File
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(“c:\\mybitmap.bmp”);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( DISPLAY_SetLogoFile, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
DISPLAY_Text
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command draws text on the screen using the current font at the position specified by xStart,yStart.
9 - 6 UnifiedPOS (UPOS) Controls Programmer’s Guide
Note: The text display does not automatically wrap any text characters whose position is beyond the LCD's row width; these characters are truncated.
Parameter Descriptionjava.awt.Point xStart,yStart (starting x,y coordinate position in pixels)
java.awt.String Text to be displayed starting at xStart,yStart
Note: If connected to a PED Class A or PED Class B Transaction Terminal, this function is restricted to only allow the following text strings:
“Downloading firmware...”“Firmware download ERROR”“Downloading script...”“Script download ERROR”
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
int nStartX = 0;
int nStartY = 0;
cmdArgs.add(new Point(nStartX, nStartY));
cmdArgs.add(new String( "My text" ));
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( DISPLAY_Text, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
MEM_DeleteObj
Unit deletes the given item ID display object from memory, if it exists.
Parameter Descriptionjava.lang.Integer ID of item to delete from memory
Returns
DeviceIOData.m_sDIOData: "Nothing returned."
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 7
Example
try
{
java.lang.Integer n = new java.lang.Integer(15);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( MEM_DeleteObj, new int[0], n );
}
catch (JposException jpe)
{
(Error handling code)
}
MEM_DeleteVar
Unit deletes a data variable defined by name from memory.
Parameter Descriptionjava.lang.String Name of variable to delete from memory
Returns
DeviceIOData.m_sDIOData: "Nothing returned".
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(new String( “myVar” ));
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( MEM_DeleteVar, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
MEM_FindObj
After using a command to generate a memory item, this command can be used to check if the new item with the given ID is stored in memory.
Parameter Descriptionjava.lang.Integer Item ID to find in memory
Returns
DeviceIOData.m_sDIOData: TRUE if id is found in memory, FALSE otherwise.
9 - 8 UnifiedPOS (UPOS) Controls Programmer’s Guide
Example
try
{
java.lang.Integer n = new java.lang.Integer(15);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( MEM_FindObj, new int[0], n );
}
catch (JposException jpe)
{
(Error handling code)
}
MEM_FindVar
Parameter Descriptionjava.lang.String Name of variable to find in memory
Returns
DeviceIOData.m_sDIOData: TRUE if variable is found in memory, FALSE otherwise.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(new String( “myVar” ));
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( MEM_FindVar, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
MEM_GetFree
Unit returns the number of free kilobytes of user memory.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: nFreeMemory + " KB free user memory." Where nFreeMemory is an integer value.
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 9
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(MEM_GetFree, new int[0], null);
}
catch (JposException jpe)
{
(Error handling code)
}
MEM_GetVar
This command retrieves the contents of a specified memory variable.
Parameter Descriptionjava.lang.String Name of variable to retrieve from memory
Returns
DeviceIOData.m_sDIOData: contents of the variable.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(new String( “myVar” ));
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( MEM_GetVar, new int[0], cmdArgs);
}
catch (JposException jpe)
{
(Error handling code)
}
MEM_SetVar
This command sets the contents of a specified variable to the results of a fully-formed Transaction Terminal command. See the Transaction Terminal command specification for details on the commands.
Parameter Descriptionjava.lang.String Named data variable in memory
java.lang.Byte[] Transaction Terminal command.
Returns
DeviceIOData.m_sDIOData: TRUE if contents of variable are successfully assigned based on result of given command. FALSE otherwise.
9 - 10 UnifiedPOS (UPOS) Controls Programmer’s Guide
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add( "myVar" );
cmdArgs.add(java.lang.Byte[]);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( MEM_SetVar, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
PINIO_SetMasterKeyID
This command sets the Master key to the specified value.
Parameter Descriptionint Number '0' through '9'
Returns
DeviceIOData.m_sDIOData: Contains the set master key ID as a java.lang.String value. The master key ID is converted from an int value to a java.lang.String value.
Example
try
{
int[] nMasterKeyID = new int[1];
nMasterKeyId[0] = 3;
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( PINIO_SetMasterKey, nMasterKeyID, null );
}
catch (JposException jpe)
{
(Error handling code)
}
PINIO_SetSessionKey
This command sets the Session key to the specified value.
Parameter Descriptionjava.lang.String Transaction/session key (16 hex-ASCII digits)
Returns
DeviceIOData.m_sDIOData: Contains the set transaction/session key.
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 11
Example
try
{
String str = new String (“MyKey”);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( PINIO_SetSessionKey, new int[0], str);
}
catch (JposException jpe)
{
(Error handling code)
PROMPT_Number
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command displays a numeric entry prompt with an optional decimal point. MaxDigits plus 1 is the maximum number of digits (including the decimal point, if any) to be entered into the entry pad prompt. Decimal is the maximum number of decimal fractions to be entered into the entry pad prompt.
Parameter Descriptionjava.lang.String Title to be displayed on number entry pad
java.lang.Integer Maximum number of digits in entered number
java.lang.Integer Maximum number of decimal fraction in entered number
Returns
DeviceIOData.m_sDIOData: String representing entered number.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(java.lang.String));
cmdArgs.add(java.lang.Integer));
cmdArgs.add(java.lang.Integer));
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( PROMPT_Number, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
SCRIPT_Goto
This command branches script execution to the specified label within the script.
Parameter Descriptionjava.lang.String Script program label
Returns
DeviceIOData.m_sDIOData: TRUE if script execution successfully branched to the specified label, FALSE otherwise.
9 - 12 UnifiedPOS (UPOS) Controls Programmer’s Guide
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(“padSignature”);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_Goto, new int[0], cmdArgs);
}
catch (JposException jpe)
{
(Error handling code)
}
SCRIPT_GotoVar
This command branches script execution to the label contained within the text variable specified.
Parameter Descriptionjava.lang.String Script text variable containing desired script label
Returns
DeviceIOData.m_sDIOData: TRUE if script execution successfully branched to the specified label, FALSE otherwise.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(“myTextVar”);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_GotoVar, new int[0], cmdArgs);
}
catch (JposException jpe)
{
(Error handling code)
}
SCRIPT_IsPaused
This command queries the device to determine if a script is currently paused.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: TRUE if a script is paused, FALSE otherwise.
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 13
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_IsPaused, new int[0], null);
}
catch (JposException jpe)
{
(Error handling code)
}
SCRIPT_IsRunning
This command queries the device to determine if a script is currently running.
Note: A paused script is considered to be running, but a stopped script is not.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: TRUE if a script is running, FALSE otherwise.
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_IsRunning, new int[0], null);
}
catch (JposException jpe)
{
(Error handling code)
}
SCRIPT_IsScript
This command queries the unit to see if a script is loaded into the device.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: TRUE if a script is loaded, FALSE otherwise.
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_IsScript, new int[0], null);
}
catch (JposException jpe)
{
(Error handling code)
}
9 - 14 UnifiedPOS (UPOS) Controls Programmer’s Guide
SCRIPT_IsVar
This command queries the unit to see if the specified variable is the name of a loaded script.
Parameter Descriptionjava.lang.String Named of variable to test
Returns
DeviceIOData.m_sDIOData: TRUE if named variable is a loaded script, FALSE otherwise.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(new String( “myScript” ));
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_IsVar, new int[0], cmdArgs);
}
catch (JposException jpe)
{
(Error handling code)
}
SCRIPT_Reset
This command resets scripts and cancel any running script.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: "Nothing returned"
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_Reset, new int[0], (Object)null);
}
catch (JposException jpe)
{
(Error handling code)
}
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 15
SCRIPT_Run
This command selects a script named name as the active script and executes it at the beginning or at the optional label.
Parameter Descriptionjava.lang.String Script named name, typically "AUTORUN"java.lang.String Optional script program label, typically "main"
Returns
DeviceIOData.m_sDIOData: TRUE if script was run, FALSE otherwise.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(java.lang.String); // Required script named name
cmdArgs.add(java.lang.String); // OPTIONAL script program label
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_Run, new int[0], cmdArgs);
}
catch (JposException jpe)
{
(Error handling code)
}
SCRIPT_Set
Note: This function requires a signed parameter when connected to a PED Class A or PED Class B Transaction Terminal. The script file must be signed via the TT Security Utility Suite (TT SUS). For further details on signing firmware, see the TT SUS user documentation.
This command loads a new script from a file onto the Transaction Terminal.
Parameter Descriptionjava.lang.String Script variablename. Use the specially-defined variable name "AUTORUN" to cause the script to be
run automatically upon device startup.
java.lang.String Local filename of script to be loaded to the device.
Returns
DeviceIOData.m_sDIOData: TRUE if script loaded successfully, FALSE otherwise.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add( "AUTORUN" );
cmdArgs.add( "c:\\myScript.bin" );
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_Set, new int[0], cmdArgs);
}
catch (JposException jpe)
{
(Error handling code)
}
9 - 16 UnifiedPOS (UPOS) Controls Programmer’s Guide
SCRIPT_Stop
This command stops any running script.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: "Nothing returned"
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SCRIPT_Stop, new int[0], null);
}
catch (JposException jpe)
{
(Error handling code)
}
SYS_DownloadFirmware
Note: This function requires a signed parameter when connected to a PED Class A or PED Class B Transaction Terminal. The firmware file must be signed via the TT Security Utility Suite (TT SUS). For further details on signing firmware, see the TT SUS user documentation.
This command loads new firmware to the Transaction Terminal.
Parameter Descriptionjava.lang.String Full pathname to file containing firmware
Returns
DeviceIOData.m_sDIOData: “SUCCESS” or “FAIL” DeviceIOData.m_byRawData[0]: 0 if successful, non-zero indicates error.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(“c:\\firmware.schex”);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_DownloadFirmware, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 17
SYS_GetError
This command retrieves the error string from the device.
Parameter DescriptionNone
ReturnsDeviceIOData.m_sDIOData:
"No Error.
"Sending host data error.
"Receiving host data error.""Invalid command error."
"Not enough memory error."
"Encryption key not loaded error."
"Invalid command argument syntax error.""Invalid bitmap data format error."
"Unspecified error."
"Undefined error." - Unrecognized error code received from unit.
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_GetError, new int[0], (Object)null);
}
catch (JposException jpe)
{
(Error handling code)
}
SYS_GetModel
This command returns the unit model number as a java.lang.String value in DeviceIOData.m_sDIOData.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: string representing the model number
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_GetModel, new int[0], (Object)null);}
catch (JposException jpe)
{
(Error handling code)
}
9 - 18 UnifiedPOS (UPOS) Controls Programmer’s Guide
SYS_GetName
This command returns the unit model name as a java.lang.String value in DeviceIOData.m_sDIOData.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: Name of device connected
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_GetName, new int[0], (Object)null);
}
catch (JposException jpe)
{
(Error handling code)
}
SYS_GetVersion
This command returns the unit model version as a java.lang.String hex-ASCII value in DeviceIOData.m_sDIOData with the following format:
Major revision number (one ASCII character “1” to “9”)
"."
Minor revision number (one to three ASCII characters from “1” to “255”)
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: Version info of firmware in device
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_GetVersion, new int[0], (Object)null);
}
catch (JposException jpe)
{
(Error handling code)
}
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 19
SYS_IsAvailable
Use this command to determine if the Transaction Terminal is connected to the communications port and is still able to receive and send data.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: TRUE if system available, FALSE otherwise.
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_IsAvailable, new int[0], (Object)null);
}
catch (JposException jpe)
{
(Error handling code)
}
SYS_IsError
This command retrieves the current error status of the device. This command does not clear the unit's error status.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: TRUE if an error, FALSE otherwise
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_IsError, new int[0], (Object)null);
}
catch (JposException jpe)
{
(Error handling code)
}
SYS_Reboot
This command reboots the unit.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: "Nothing returned"
9 - 20 UnifiedPOS (UPOS) Controls Programmer’s Guide
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_Reboot, new int[0], (Object)null);
}
catch (JposException jpe)
{
(Error handling code)
}
SYS_Reset
This command resets the system software, devices, and defaults.
Parameter DescriptionNone
Returns
DeviceIOData.m_sDIOData: "Nothing returned"
Example
try
{
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_Reset, new int[0], (Object)null);
}
catch (JposException jpe)
{
(Error handling code)
}
SYS_SetDebug
This command sets the system debug option on or off. If the system debug message option is on, the LCD displays an error message when an error occurs. Touching the touchpad clears the error message from the LCD.
Parameterjava.lang.Byte[] with the following values:
{ new Byte((byte)0x01), new Byte((byte)0x00) } - Debug set "ON"{ new Byte((byte)0x0), new Byte((byte)0x00) } - Debug set "OFF"
Returns
DeviceIOData.m_sDIOData: "Nothing returned"
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 21
Example
try
{
java.lang.Byte[] debugON = { new Byte((byte)0x01), new Byte((byte)0x00) }
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(debugON);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO(SYS_SetDebug, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
Text_GetVar
This command retrieves the contents of a memory variable. Note that this command will convert from other data types when possible. For example, a num data type converts to text.
Parameter Descriptionjava.lang.String Variable name with text data type
Returns
DeviceIOData.m_sDIOData: TRUE if contents of variable are retrieved. FALSE otherwise.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add( “MyVar” );
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( TEXT_GetVar, new int[0], cmdArgs);
}
catch (JposException jpe)
{
(Error handling code)
}
Text_IsVar
This command determines if the specified variable contains text data.
Parameter Descriptionjava.lang.String Variable name with text data type
Returns
DeviceIOData.m_sDIOData: TRUE if specified variable does contain text data. FALSE otherwise.
9 - 22 UnifiedPOS (UPOS) Controls Programmer’s Guide
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add(“myVar”);
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( TEXT_IsVar, new int[0], cmdArgs);
}
catch (JposException jpe)
{
(Error handling code)
}
Text_SetVar
This command sets the contents of a variable to the specified text string.
Parameter Descriptionjava.lang.String Variable name with text data type
java.lang.String Variable data
Returns
DeviceIOData.m_sDIOData: TRUE if contents of variable are successfully set. FALSE otherwise.
Example
try
{
java.util.LinkedList cmdArgs = new java.util.LinkedList();
cmdArgs.add( "MyVar" );
cmdArgs.add( "Some Text" );
jpos.BaseControl ctrl = new jpos.BaseControl;
ctrl.directIO( TEXT_SetVar, new int[0], cmdArgs );
}
catch (JposException jpe)
{
(Error handling code)
}
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 23
OPOS DirectIO Commands
This section explains how to use DirectIO commands when developing OPOS applications for Transaction Terminals.
PW_CLEARSCREEN
This command clears all contents of the display.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: "Nothing returned."
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_CLEARSCREEN, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_DISPLAYBITMAPFILE
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command draws a bitmap onto the screen starting at the specified coordinate.
Parameter DescriptionString Full pathname to Bitmap File and xStart,yStart in pixels (upper left corner of displayed bitmap image)
Returns
DirectIOEvent-lpsString: "Nothing returned."
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "5,5,c:\my bitmap.bmp"
result = ctrl.DirectIO(PW_DISPLAYBITMAPFILE, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_DISPLAYBOX
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command draws a solid rectangular area using the current foreground color on the screen.
Parameter DescriptionString xStart,yStart (starting x,y coordinate position in pixels) and
xWidth,yHeight (width/height of box in pixels)
Returns
DirectIOEvent-lpsString: "Nothing returned."
9 - 24 UnifiedPOS (UPOS) Controls Programmer’s Guide
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "0,0,20,20"
result = ctrl.DirectIO(PW_DISPLAYBOX, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_DISPLAYLOGO
This command centers the default logo on the screen. See DISPLAY_SetLogoFile on page 9-6 for information about changing the default logo.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: "Nothing returned."
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_DISPLAYLOGO, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_MEMDELETEOBJ
Unit deletes the given item ID display object from memory, if it exists.
Parameter DescriptionString ID of item to delete from memory
Returns
DirectIOEvent-lpsString: "Nothing returned."
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "15"
result = ctrl.DirectIO(PW_MEMDELETEOBJ, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_MEMDELETEVAR
Unit deletes a data variable defined by name from memory.
Parameter DescriptionString Name of variable to delete from memory
Returns
DirectIOEvent-lpsString: "Nothing returned".
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 25
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "myVar"
result = ctrl.DirectIO(PW_MEMDELETEVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_MEMFINDOBJ
After using a command to generate a memory item, this command can be used to check if the new item with the given ID is stored in memory.
Parameter DescriptionString Item ID to find in memory
Returns
DirectIOEvent-lpsString: TRUE if id is found in memory, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "15"
result = ctrl.DirectIO(PW_MEMFINDOBJ, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_MEMFINDVAR
Parameter DescriptionString Name of variable to find in memory
Returns
DirectIOEvent-lpsString: TRUE if variable is found in memory, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "myVar"
result = ctrl.DirectIO(PW_MEMFINDVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_MEMGETFREE
Unit returns the number of free kilobytes of user memory.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: nFreeMemory + " KB free user memory." Where nFreeMemory is an integer value.
9 - 26 UnifiedPOS (UPOS) Controls Programmer’s Guide
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_MEMGETFREE, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_MEMGETVAR
This command retrieves the contents of a specified memory variable.
Parameter DescriptionString Name of variable to retrieve from memory
Returns
DirectIOEvent-lpsString: contents of the variable.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "myVar"
result = ctrl.DirectIO(PW_MEMGETVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_MEMSETVAR
This command sets the contents of a specified variable to the results of a fully-formed Transaction Terminal command. See the Transaction Terminal command specification for details on the commands.
Parameter DescriptionString Named data variable in memory and Transaction Terminal command
Returns
DirectIOEvent-lpsString: TRUE if contents of variable are successfully assigned based on result of given command. FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "myVar,x10x29x00x00"
result = ctrl.DirectIO(PW_MEMSETVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 27
PW_NUMBERPAD
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command displays a numeric entry prompt with an optional decimal point. MaxDigits plus 1 is the maximum number of digits (including the decimal point, if any) to be entered into the entry pad prompt. Decimal is the maximum number of decimal fractions to be entered into the entry pad prompt.
Parameter DescriptionString Title to be displayed on number entry pad, maximum number of digits in entered number, and
maximum number of decimal fraction in entered number
Returns
DirectIOEvent-lpsString: String representing entered number.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = txtNumberPostitions & "," & txtUnitPositions & "," & txtNumberForm
result = ctrl.DirectIO(PW_NUMBERPAD, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_PUTTEXT
Note: This function is restricted when connected to a PED Class A or PED Class B Transaction Terminal.
This command draws text on the screen using the current font at the position specified by xStart,yStart.
Note: The text display does not automatically wrap any text characters whose position is beyond the LCD's row width; these characters are truncated.
Parameter DescriptionString xStart,yStart (starting x,y coordinate position in pixels) and text to be displayed starting at
xStart,yStart
Note: If connected to a PED Class A or PED Class B Transaction Terminal, this function is restricted to only allow the following text strings:
“Downloading firmware...”“Firmware download ERROR”“Downloading script...”“Script download ERROR”
Returns
DirectIOEvent-lpsString: "Nothing returned."
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "0,0,My text"
result = ctrl.DirectIO(PW_PUTTEXT, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
9 - 28 UnifiedPOS (UPOS) Controls Programmer’s Guide
PW_RESETLOGO
This command resets the displayed default logo to the unit's system logo.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: "Nothing returned."
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_RESETLOGO, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SCRIPTGOTO
This command branches script execution to the specified label within the script.
Parameter DescriptionString Script program label
Returns
DirectIOEvent-lpsString: TRUE if script execution successfully branched to the specified label, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "padSignature"
result = ctrl.DirectIO(PW_SCRIPTGOTO, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SCRIPTGOTOVAR
This command branches script execution to the label contained within the text variable specified.
Parameter DescriptionString Script text variable containing desired script label
Returns
DirectIOEvent-lpsString: TRUE if script execution successfully branched to the specified label, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "myTextVar"
result = ctrl.DirectIO(PW_SCRIPTGOTOVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 29
PW_SCRIPTISPAUSED
This command queries the device to determine if a script is currently paused.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: TRUE if a script is paused, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SCRIPTISPAUSED, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SCRIPTISRUNNING
This command queries the device to determine if a script is currently running.
Note: A paused script is considered to be running, but a stopped script is not.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: TRUE if a script is running, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SCRIPTISRUNNING, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SCRIPTISSCRIPT
This command queries the unit to see if a script is loaded into the device.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: TRUE if a script is loaded, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SCRIPTISSCRIPT, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
9 - 30 UnifiedPOS (UPOS) Controls Programmer’s Guide
PW_SCRIPTISVAR
This command queries the unit to see if the specified variable is the name of a loaded script.
Parameter DescriptionString Named of variable to test
Returns
DirectIOEvent-lpsString: TRUE if named variable is a loaded script, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "myScript"
result = ctrl.DirectIO(PW_SCRIPTISVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SCRIPTRESET
This command resets scripts and cancel any running script.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: "Nothing returned"
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SCRIPTRESET, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SCRIPTRUN
This command selects a script named name as the active script and executes it at the beginning or at the optional label.
Parameter DescriptionString Script named name, typically "AUTORUN" and optional script program label, typically "main"
Returns
DirectIOEvent-lpsString: TRUE if script was run, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "AUTORUN,main"
result = ctrl.DirectIO(PW_SCRIPTRUN, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 31
PW_SCRIPTFILELOAD
Note: This function requires a signed parameter when connected to a PED Class A or PED Class B Transaction Terminal. The script file must be signed via the TT Security Utility Suite (TT SUS). For further details on signing firmware, see the TT SUS user documentation.
This command loads a new script from a file onto the Transaction Terminal.
Parameter DescriptionString Script variablename: use the specially-defined variable name "AUTORUN" to cause the script to be
run automatically upon device startup. Local filename of script to be loaded to the device.
Returns
DirectIOEvent-lpsString: TRUE if script loaded successfully, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "AUTORUN,c:\myScript.bin"
result = ctrl.DirectIO(PW_SCRIPTFILELOAD, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SCRIPTSTOPLOAD
This command stops any running script.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: "Nothing returned"
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SCRIPTSTOPLOAD, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SETFONT
This command sets the font to be used when displaying text.
Parameter DescriptionInteger ID that identifies font type
9 - 32 UnifiedPOS (UPOS) Controls Programmer’s Guide
The font type may be one of the following TT8800CommandConst interface constants:DISPLAY_Font8x8DISPLAY_Font16x16DISPLAY_Font6x8DISPLAY_Font8x12DISPLAY_Font12x16DISPLAY_Font16x24
Returns
DirectIOEvent-lpsString: "Nothing returned."
Example
Dim result As Long
Dim str As String
Dim n As Long
n = PW_FONT6X8
result = ctrl.DirectIO(PW_SETFONT, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SETLOGO
This command loads a bitmap to be the default logo displayed.
Parameter DescriptionString Full pathname to Bitmap File
Returns
DirectIOEvent-lpsString: "Nothing returned."
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "c:\mybitmap.bmp"
result = ctrl.DirectIO(PW_SETLOGO, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SETMKEY
This command sets the Master key to the specified value.
Parameter DescriptionInteger Number '0' through '9'
Returns
DirectIOEvent-lpsString: Contains the set master key ID as a String value. The master key ID is converted from an int value to a String value.
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 33
Example
Dim result As Long
Dim str As String
Dim n As Long
n = 3
result = ctrl.DirectIO(PW_SETMKEY, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SETSKEY
This command sets the Session key to the specified value.
Parameter DescriptionString Transaction/session key (16 hex-ASCII digits)
Returns
DirectIOEvent-lpsString: Contains the set transaction/session key.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "0123456789ABCDEF"
result = ctrl.DirectIO(PW_SETSKEY, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SYSDOWNLOAD
Note: This function requires a signed parameter when connected to a PED Class A or PED Class B Transaction Terminal. The firmware file must be signed via the TT Security Utility Suite (TT SUS). For further details on signing firmware, see the TT SUS user documentation.
This command loads new firmware to the Transaction Terminal.
Parameter DescriptionString Full pathname to file containing firmware
Returns
DirectIOEvent-lpsString: “SUCCESS” or “FAIL”.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "c:\firmware.schex"
result = ctrl.DirectIO(PW_SYSDOWNLOAD, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
9 - 34 UnifiedPOS (UPOS) Controls Programmer’s Guide
PW_SYSGETERROR
This command retrieves the error string from the device.
Parameter DescriptionNone
ReturnsDirectIOEvent-lpsString: "No Error.
"Sending host data error.
"Receiving host data error."
"Invalid command error.""Not enough memory error."
"Encryption key not loaded error."
"Invalid command argument syntax error."
"Invalid bitmap data format error.""Unspecified error."
"Undefined error." - Unrecognized error code received from unit.
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SYSGETERROR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SYSGETMODEL
This command returns the unit model number.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: string representing the model number
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SYSGETMODEL, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SYSGETNAME
This command returns the unit model name.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: Name of device connected
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 35
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SYSGETNAME, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SYSGETVERSION
This command returns the unit model version as a string hex-ASCII value with the following format:
Major revision number (one ASCII character “1” to “9”)
"."
Minor revision number (one to three ASCII characters from “1” to “255”)
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: Version info of firmware in device
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SYSGETVERSION, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SYSISAVAILABLE
Use this command to determine if the Transaction Terminal is connected to the communications port and is still able to receive and send data.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: TRUE if system available, FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SYSISAVAILABLE, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
9 - 36 UnifiedPOS (UPOS) Controls Programmer’s Guide
PW_SYSISERROR
This command retrieves the current error status of the device. This command does not clear the unit's error status.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: TRUE if an error, FALSE otherwise
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SYSISERROR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SYSREBOOT
This command reboots the unit.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: "Nothing returned"
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SYSREBOOT, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_SYSRESET
This command resets the system software, devices, and defaults.
Parameter DescriptionNone
Returns
DirectIOEvent-lpsString: "Nothing returned"
Example
Dim result As Long
Dim str As String
Dim n As Long
result = ctrl.DirectIO(PW_SYSRESET, n, str)
If result <> 0 Then MsgBox ("Error : " & result)
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 37
PW_SYSSETDEBUG
This command sets the system debug option on or off. If the system debug message option is on, the LCD displays an error message when an error occurs. Touching the touchpad clears the error message from the LCD.
ParameterByte[] with the following values: { new Byte((byte)0x01), new Byte((byte)0x00) } - Debug set "ON"
{ new Byte((byte)0x0), new Byte((byte)0x00) } - Debug set "OFF"
Returns
DirectIOEvent-lpsString: "Nothing returned"
Example
Dim result As Long
Dim str As String
Dim n As Long
n = 1
result = ctrl.DirectIO(PW_SYSSETDEBUG, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_TEXTGETVAR
This command retrieves the contents of a memory variable. Note that this command will convert from other data types when possible. For example, a num data type converts to text.
Parameter DescriptionString Variable name with text data type
Returns
DirectIOEvent-lpsString: TRUE if contents of variable are retrieved. FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "MyVar"
result = ctrl.DirectIO(PW_TEXTGETVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_TEXTISVAR
This command determines if the specified variable contains text data.
Parameter DescriptionString Variable name with text data type
Returns
DirectIOEvent-lpsString: TRUE if specified variable does contain text data. FALSE otherwise.
9 - 38 UnifiedPOS (UPOS) Controls Programmer’s Guide
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "myVar"
result = ctrl.DirectIO(PW_TEXTISVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
PW_TEXTSETVAR
This command sets the contents of a variable to the specified text string.
Parameter DescriptionString Variable name with text data type and variable data
Returns
DirectIOEvent-lpsString: TRUE if contents of variable are successfully set. FALSE otherwise.
Example
Dim result As Long
Dim str As String
Dim n As Long
str = "MyVar,Some Text"
result = ctrl.DirectIO(PW_TEXTSETVAR, n, str)
If result <> 0 Then MsgBox ("Error: " & result)
UnifiedPOS (UPOS) Controls Programmer’s Guide 9 - 39
9 - 40 UnifiedPOS (UPOS) Controls Programmer’s Guide
10
Un
Technical Assistance
If you need assistance using the UPOS Controls, please call your distributor or the nearest Hand Held Products technical support office. Have the following information ready so we can assist you quickly and efficiently:
• Current version of the UPOS Controls• Target Operating System• Approximate date of purchase and any other sale/evaluation related information• Precise nature of the problem
North America/Canada:
Telephone: (800) 782-4263, Option 4 (8 a.m. to 6 p.m. EST)Fax number: (315) 685-4960E-mail: [email protected]
ifiedPOS (UPOS) Controls Programmer’s Guide 10 - 1
10 - 2 UnifiedPOS (UPOS) Controls Programmer’s Guide
UnifiedPOS (UPOS) Controls Programmer’s Guide 10 - 3
10 - 4 UnifiedPOS (UPOS) Controls Programmer’s Guide
™
Hand Held Products, Inc.700 Visions DriveP.O. Box 208Skaneateles Falls, NY 13153-0208
UPOS-PG Rev F7/06