UnifiedPOS (UPOS) Controls
Combined JavaPOS and OPOS Controls
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.
Chapter 1 - Introduction
Supported Java Versions ...1-1
Chapter 2 - Hand Held Products UPOS Installation and System Configuration
Installation Procedures ...2-1
Installing Java Runtime v1.4.2_04 (optional) ...2-1
System Configuration ...2-1
Configuring Windows 2000 and XP PATH Environment Variable (required)...2-2
Configuring Windows NT PATH Environment Variable (required) ...2-3
Configuring Windows 98 PATH Environment Variable (required)...2-3
Installation and System Configuration Complete ...2-4
Updating Windows CLASSPATH Environment Variable (optional) ...2-4
Running Third Party (non-Hand Held Products) Applications with Hand Held Products Devices....2-4
Uninstall Instructions...2-4
Chapter 3 - Hand Held Products UnifiedPOS Configuration Application
Configuration Application Overview ...3-1
Configuration Settings ...3-2
Configuration Functions ...3-3
Add New Entry ...3-3
Save to XML ...3-3
Chapter 4 - Configuring Devices
Bar Code Scanner (RS-232) ...4-1
Bar Code Scanner (USB)...4-1
Bar Code Scanner (USB Serial Emulation)...4-1
Transaction Terminal (RS-232)...4-2
Transaction Terminal (USB) ...4-2
Transaction Terminal (RS-485)...4-2
Chapter 5 - Hand Held Products JavaPOS and OPOS Controls Tester (UltraTester) Applications
Hand Held Products JavaPOS Ultra Tester ...5-1
Hand Held Products OPOS Ultra Tester ...5-1
Running 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-1
DirectIO Event...7-1
Table of Contents
Chapter 8 - DirectIO Command Details for Scanner Controls
JavaPOS Usage Example...8-1
OPOS Usage Example...8-1
Chapter 9 - DirectIO Command Details for Transaction Terminal Controls
Returns...9-1
Supported DirectIO Commands for Interfacing to Transaction Terminals ...9-2
JavaPOS DirectIO Commands ...9-3
DISPLAY_Bitmap ...9-3
DISPLAY_Box ...9-4
DISPLAY_Clear ...9-4
DISPLAY_Logo ...9-5
DISPLAY_ResetLogo ...9-5
DISPLAY_SetFont ...9-5
DISPLAY_SetLogoFile ...9-6
DISPLAY_Text ...9-6
MEM_DeleteObj ...9-7
MEM_DeleteVar ...9-8
MEM_FindObj ...9-8
MEM_FindVar ...9-9
MEM_GetFree ...9-9
MEM_GetVar ...9-10
MEM_SetVar ...9-10
PINIO_SetMasterKeyID ...9-11
PINIO_SetSessionKey ...9-11
PROMPT_Number ...9-12
SCRIPT_Goto ...9-12
SCRIPT_GotoVar ...9-13
SCRIPT_IsPaused ...9-13
SCRIPT_IsRunning ...9-14
SCRIPT_IsScript ...9-14
SCRIPT_IsVar ...9-15
SCRIPT_Reset ...9-15
SCRIPT_Run ...9-16
SCRIPT_Set ...9-16
SCRIPT_Stop ...9-17
SYS_DownloadFirmware ...9-17
SYS_GetError ...9-18
SYS_GetModel ...9-18
SYS_GetName ...9-19
SYS_GetVersion ...9-19
SYS_IsAvailable ...9-20
SYS_IsError ...9-20
SYS_Reboot ...9-20
PW_MEMDELETEOBJ ...9-25
PW_MEMDELETEVAR ...9-25
PW_MEMFINDOBJ ...9-26
PW_MEMFINDVAR ...9-26
PW_MEMGETFREE ...9-26
PW_MEMGETVAR ...9-27
PW_MEMSETVAR ...9-27
PW_NUMBERPAD ...9-28
PW_PUTTEXT ...9-28
PW_RESETLOGO ...9-29
PW_SCRIPTGOTO ...9-29
PW_SCRIPTGOTOVAR ...9-29
PW_SCRIPTISPAUSED ...9-30
PW_SCRIPTISRUNNING ...9-30
PW_SCRIPTISSCRIPT ...9-30
PW_SCRIPTISVAR ...9-31
PW_SCRIPTRESET ...9-31
PW_SCRIPTRUN ...9-31
PW_SCRIPTFILELOAD ...9-32
PW_SCRIPTSTOPLOAD ...9-32
PW_SETFONT ...9-32
PW_SETLOGO ...9-33
PW_SETMKEY ...9-33
PW_SETSKEY ...9-34
PW_SYSDOWNLOAD ...9-34
PW_SYSGETERROR ...9-35
PW_SYSGETMODEL ...9-35
PW_SYSGETNAME ...9-35
PW_SYSGETVERSION ...9-36
PW_SYSISAVAILABLE ...9-36
PW_SYSISERROR ...9-37
PW_SYSREBOOT ...9-37
PW_SYSRESET ...9-37
PW_SYSSETDEBUG ...9-38
PW_TEXTGETVAR ...9-38
PW_TEXTISVAR ...9-38
PW_TEXTSETVAR ...9-39
1
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
2
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 Applicationbeginning 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 Applicationbeginning 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 Applicationbeginning 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) Applicationsbeginning 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 Applicationbeginning 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.
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
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.
Installation and System Configuration Complete
The 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 Applicationbeginning 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.
3
Hand Held Products
UnifiedPOS
Configuration
Application
Once 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
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 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.
Configuration Functions
Add New Entry
1. 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 XML
The 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.
4
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.
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.
5
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 Applicationbeginning 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.
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.
6
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.bin
C:\<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 Applicationbeginning 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
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.
7
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.
8
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
9
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
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
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 Description
java.lang.String Full pathname to Bitmap File
java.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
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 Description
java.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 Description
None Returns
DeviceIOData.m_sDIOData: "Nothing returned." Example
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 Description None
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 Description
None 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 Description
The font type may be one of the following TT8800CommandConst interface constants: DISPLAY_Font8x8 DISPLAY_Font16x16 DISPLAY_Font6x8 DISPLAY_Font8x12 DISPLAY_Font12x16 DISPLAY_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 Description
java.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 ); }
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 Description
java.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 Description
java.lang.Integer ID of item to delete from memory Returns
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 Description
java.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 Description
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 Description
java.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 Description
None Returns
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 Description
java.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 Description
java.lang.String Named data variable in memory java.lang.Byte[] Transaction Terminal command.
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 Description
int 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 Description
java.lang.String Transaction/session key (16 hex-ASCII digits) Returns
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 Description
java.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) }
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 Description
java.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 Description
None Returns
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 Description None
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 Description
None Returns
DeviceIOData.m_sDIOData: TRUE if a script is loaded, FALSE otherwise. Example
SCRIPT_IsVar
This command queries the unit to see if the specified variable is the name of a loaded script. Parameter Description
java.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 Description
None 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) }
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 Description
java.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 Description
java.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 {
SCRIPT_Stop
This command stops any running script. Parameter Description
None 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 Description
java.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) }
SYS_GetError
This command retrieves the error string from the device. Parameter Description
None Returns
DeviceIOData.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 Description
None Returns
DeviceIOData.m_sDIOData: string representing the model number Example
SYS_GetName
This command returns the unit model name as a java.lang.String value in DeviceIOData.m_sDIOData. Parameter Description
None 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 Description
None 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) }
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 Description None
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 Description
None 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) }
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 Description
None 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.
Parameter
java.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
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 Description
java.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
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 Description
java.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) }