UnifiedPOS (UPOS) Controls Combined JavaPOS and OPOS Controls. Programmer s Guide

Transcription

1 UnifiedPOS (UPOS) Controls Combined JavaPOS and OPOS Controls Programmer s Guide

2 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 Hand Held Products, Inc. All rights reserved. Web Address: 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.

3 Table of Contents Chapter 1 - Introduction Supported Java Versions Chapter 2 - Hand Held Products UPOS Installation and System Configuration Installation Procedures Installing Java Runtime v1.4.2_04 (optional) System Configuration Configuring Windows 2000 and XP PATH Environment Variable (required) Configuring Windows NT PATH Environment Variable (required) Configuring Windows 98 PATH Environment Variable (required) Installation and System Configuration Complete Updating Windows CLASSPATH Environment Variable (optional) Running Third Party (non-hand Held Products) Applications with Hand Held Products Devices Uninstall Instructions Chapter 3 - Hand Held Products UnifiedPOS Configuration Application Configuration Application Overview Configuration Settings Configuration Functions Add New En Save to XML Chapter 4 - Configuring Devices Bar Code Scanner (RS-232) Bar Code Scanner (USB) Bar Code Scanner (USB Serial Emulation) Transaction Terminal (RS-232) Transaction Terminal (USB) Transaction Terminal (RS-485) Chapter 5 - Hand Held Products JavaPOS and OPOS Controls Tester (UltraTester) Applications Hand Held Products JavaPOS Ultra Tester Hand Held Products OPOS Ultra Tester Running the UltraTester Chapter 6 - Hand Held Products JavaPOS Host Sample Application Running JavaPOS Host Sample Chapter 7 - Overview of UnifiedPOS DirectIO DirectIO Method DirectIO Event i

4 Chapter 8 - DirectIO Command Details for Scanner Controls JavaPOS Usage OPOS Usage Chapter 9 - DirectIO Command Details for Transaction Terminal Controls Supported DirectIO Commands for Interfacing to Transaction Terminals JavaPOS DirectIO Commands DISPLAY_Bitmap DISPLAY_Box DISPLAY_Clear DISPLAY_Logo DISPLAY_ResetLogo DISPLAY_SetFont DISPLAY_SetLogoFile DISPLAY_Text MEM_DeleteObj MEM_DeleteVar MEM_FindObj MEM_FindVar MEM_GetFree MEM_GetVar MEM_SetVar PINIO_SetMasterKeyID PINIO_SetSessionKey PROMPT_Number SCRIPT_Goto SCRIPT_GotoVar SCRIPT_IsPaused SCRIPT_IsRunning SCRIPT_IsScript SCRIPT_IsVar SCRIPT_Reset SCRIPT_Run SCRIPT_Set SCRIPT_Stop SYS_DownloadFirmware SYS_GetError SYS_GetModel SYS_GetName SYS_GetVersion SYS_IsAvailable SYS_IsError SYS_Reboot SYS_Reset SYS_SetDebug Text_GetVar Text_IsVar Text_SetVar OPOS DirectIO Commands PW_CLEARSCREEN PW_DISPLAYBITMAPFILE PW_DISPLAYBOX PW_DISPLAYLOGO ii

5 PW_MEMDELETEOBJ PW_MEMDELETEVAR PW_MEMFINDOBJ PW_MEMFINDVAR PW_MEMGETFREE PW_MEMGETVAR PW_MEMSETVAR PW_NUMBERPAD PW_PUTTEXT PW_RESETLOGO PW_SCRIPTGOTO PW_SCRIPTGOTOVAR PW_SCRIPTISPAUSED PW_SCRIPTISRUNNING PW_SCRIPTISSCRIPT PW_SCRIPTISVAR PW_SCRIPTRESET PW_SCRIPTRUN PW_SCRIPTFILELOAD PW_SCRIPTSTOPLOAD PW_SETFONT PW_SETLOGO PW_SETMKEY PW_SETSKEY PW_SYSDOWNLOAD PW_SYSGETERROR PW_SYSGETMODEL PW_SYSGETNAME PW_SYSGETVERSION PW_SYSISAVAILABLE PW_SYSISERROR PW_SYSREBOOT PW_SYSRESET PW_SYSSETDEBUG PW_TEXTGETVAR PW_TEXTISVAR PW_TEXTSETVAR Chapter 10 - Technical Assistance iii

6 iv

7 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: 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. Device Category Line Display POS Keyboard PIN Pad MSR - Magnetic Stripe Reader Signature Capture Tone Indicator Scanner (Bar Code Reader) Hand Held Products Physical Device TT8000 Series Transaction Terminal TT8000 Series Transaction Terminal TT8000 Series Transaction Terminal TT8000 Series Transaction Terminal TT8000 Series Transaction Terminal TT8000 Series Transaction Terminal 2020, 3800, 4010, 4080, 4200, 4600g ( 1 IT4600), 4620, 4800i ( 1 IT4800), 3800r ( 1 IT5600), 3820 ( 1 IT5620), 3800i ( 1 IT5800) 1. Former model number 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) 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 (which includes the JRE 1.3.1) and above. UnifiedPOS (UPOS) Controls Programmer s Guide 1-1

8 1-2 UnifiedPOS (UPOS) Controls Programmer s Guide

9 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 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 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 example: 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 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. UnifiedPOS (UPOS) Controls Programmer s Guide 2-1

10 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

11 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

12 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 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 3 rd 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 en: # # 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

13 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 en names corresponding to 7 UnifiedPOS controls (device categories) that were installed by the UnifiedPOS controls component. En Name Device Category Hand Held Products Physical Device L1 Line Display Transaction Team 8000 Series Terminal SCAN1 Scanner 2020, 3800, 4010, 4080, 4200, 4600g ( 1 IT4600), 4620, 4800i ( 1 IT4800), 3800r ( 1 IT5600), 3820 ( 1 IT5620), 3800i ( 1 IT5800) 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 1. Former model number The following is an example of the screen that is displayed when the UPOS Configuration Application is executed: UnifiedPOS (UPOS) Controls Programmer s Guide 3-1

14 Configuration Settings Setting Device Bus Port Name, Baud Rate, Parity Data Bits Stop Bits, Flow Control USB Device, USB Device Serial # Connection Port, Connection Slot, Device ID, Initialize POS Subsystem Log File Text Rows, Column Rows Custom Script Form Signature Format 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. 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 Properties are only selectable if Device Bus is set to USB. 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. Otherwise, leave the box unchecked. 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 regis key: HKLM\SW\OLEforRetail\ServiceInfo\Hand Held Products\Logpath These parameters may only be set for a Line Display Device category. This parameter may only be set for PinPad and POSKeyboard Device categories. This parameter is used only when interfacing 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). 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

15 Configuration Functions Add New En 1. On the initial Hand Held Products UnifiedPOS Configuration Application screen, select New En 2. Enter a meaningful Device ID (En 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 en. 4. Modify settings for new en 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. UnifiedPOS (UPOS) Controls Programmer s Guide 3-3

16 3-4 UnifiedPOS (UPOS) Controls Programmer s Guide

17 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 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 en. 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 ( 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 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 en and verify the scanner appears, followed by the virtual COM port number. UnifiedPOS (UPOS) Controls Programmer s Guide 4-1

18 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 en. 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

19 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 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. UnifiedPOS (UPOS) Controls Programmer s Guide 5-1

20 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

21 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 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: 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 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. UnifiedPOS (UPOS) Controls Programmer s Guide 6-1

22 To initiate a transaction, a bar code must either be scanned or manually entered via the Manual Item En 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

23 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; Command Data Object Command number whose specific values are assigned by the UnifiedPOS service. An array of one modifiable integer whose specific values or usage vary by command and UnifiedPOS service. Additional data whose usage varies by command and UnifiedPOS service. DirectIO Event JavaPOS Usage: Interface: jpos.events.directiolistener Method: directiooccurred (DirectIOEvent e); OPOS Usage: Event: DirectIOEvent The DirectIOEvent contains the following properties: Property Type 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 service. This property may be set. UnifiedPOS (UPOS) Controls Programmer s Guide 7-1

24 7-2 UnifiedPOS (UPOS) Controls Programmer s Guide

25 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 jpos.scannerctrl = new jpos.scanner; ctrl.open ( SCAN1 ); String strcmd = TERMID? ; Ctrl.directIO(0, new int[0], strcmd); catch(jposexception jpe) 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 Private Sub DoDirectIO_Click() On Error Goto ehandler 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 UnifiedPOS (UPOS) Controls Programmer s Guide 8-1

26 8-2 UnifiedPOS (UPOS) Controls Programmer s Guide

27 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. 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 UnifiedPOS (UPOS) Controls Programmer s Guide 9-1

28 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 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 en 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

29 JavaPOS Command Page OPOS Command Page 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 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. java.lang.string java.awt.point Full pathname to Bitmap File xstart,ystart in pixels (upper left corner of displayed bitmap image) DeviceIOData.m_sDIOData: "Nothing returned." 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)); ctrl.directio( DISPLAY_Bitmap, new int[0], cmdargs ); UnifiedPOS (UPOS) Controls Programmer s Guide 9-3

30 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. java.awt.point java.awt.point xstart,ystart (starting x,y coordinate position in pixels) xwidth,yheight (width/height of box in pixels) DeviceIOData.m_sDIOData: "Nothing returned." 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)); ctrl.directio( DISPLAY_Box, new int[0], cmdargs ); DISPLAY_Clear This command clears all contents of the display. None DeviceIOData.m_sDIOData: "Nothing returned." ctrl.directio( DISPLAY_Clear, new int[0], null ); 9-4 UnifiedPOS (UPOS) Controls Programmer s Guide

31 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. None DeviceIOData.m_sDIOData: "Nothing returned." ctrl.directio( DISPLAY_Logo, new int[0], null ); DISPLAY_ResetLogo This command resets the displayed default logo to the unit's system logo. None DeviceIOData.m_sDIOData: "Nothing returned." ctrl.directio( DISPLAY_ResetLogo, new int[0], null ); DISPLAY_SetFont This command sets the font to be used when displaying text. java.lang.integer ID that identifies font type UnifiedPOS (UPOS) Controls Programmer s Guide 9-5

32 The font type may be one of the following TT8800CommandConst interface constants: DISPLAY_Font8x8 DISPLAY_Font16x16 DISPLAY_Font6x8 DISPLAY_Font8x12 DISPLAY_Font12x16 DISPLAY_Font16x24 DeviceIOData.m_sDIOData: "Nothing returned." java.lang.integer nfontid = new java.lang.integer(display_font16x16); ctrl.directio( DISPLAY_SetFont, new int[0], nfontid ); 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. java.lang.string Full pathname to Bitmap File DeviceIOData.m_sDIOData: "Nothing returned." java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( c:\\mybitmap.bmp ); ctrl.directio( DISPLAY_SetLogoFile, new int[0], cmdargs ); 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

33 Note: The text display does not automatically wrap any text characters whose position is beyond the LCD's row width; these characters are truncated. java.awt.point java.awt.string xstart,ystart (starting x,y coordinate position in pixels) 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 DeviceIOData.m_sDIOData: "Nothing returned." 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" )); ctrl.directio( DISPLAY_Text, new int[0], cmdargs ); MEM_DeleteObj Unit deletes the given item ID display object from memory, if it exists. java.lang.integer ID of item to delete from memory DeviceIOData.m_sDIOData: "Nothing returned." UnifiedPOS (UPOS) Controls Programmer s Guide 9-7

34 java.lang.integer n = new java.lang.integer(15); ctrl.directio( MEM_DeleteObj, new int[0], n ); MEM_DeleteVar Unit deletes a data variable defined by name from memory. java.lang.string Name of variable to delete from memory DeviceIOData.m_sDIOData: "Nothing returned". java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add(new String( myvar )); ctrl.directio( MEM_DeleteVar, new int[0], cmdargs ); 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. java.lang.integer Item ID to find in memory DeviceIOData.m_sDIOData: TRUE if id is found in memory, FALSE otherwise. 9-8 UnifiedPOS (UPOS) Controls Programmer s Guide

35 java.lang.integer n = new java.lang.integer(15); ctrl.directio( MEM_FindObj, new int[0], n ); MEM_FindVar java.lang.string Name of variable to find in memory DeviceIOData.m_sDIOData: TRUE if variable is found in memory, FALSE otherwise. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add(new String( myvar )); ctrl.directio( MEM_FindVar, new int[0], cmdargs ); MEM_GetFree Unit returns the number of free kilobytes of user memory. None DeviceIOData.m_sDIOData: nfreememory + " KB free user memory." Where nfreememory is an integer value. UnifiedPOS (UPOS) Controls Programmer s Guide 9-9

36 ctrl.directio(mem_getfree, new int[0], null); MEM_GetVar This command retrieves the contents of a specified memory variable. java.lang.string Name of variable to retrieve from memory DeviceIOData.m_sDIOData: contents of the variable. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add(new String( myvar )); ctrl.directio( MEM_GetVar, new int[0], cmdargs); 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. java.lang.string java.lang.byte[] Named data variable in memory Transaction Terminal command. DeviceIOData.m_sDIOData: TRUE if contents of variable are successfully assigned based on result of given command. FALSE otherwise UnifiedPOS (UPOS) Controls Programmer s Guide

37 java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( "myvar" ); cmdargs.add(java.lang.byte[]); ctrl.directio( MEM_SetVar, new int[0], cmdargs ); PINIO_SetMasterKeyID This command sets the Master key to the specified value. int Number '0' through '9' 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. int[] nmasterkeyid = new int[1]; nmasterkeyid[0] = 3; ctrl.directio( PINIO_SetMasterKey, nmasterkeyid, null ); PINIO_SetSessionKey This command sets the Session key to the specified value. java.lang.string Transaction/session key (16 hex-ascii digits) DeviceIOData.m_sDIOData: Contains the set transaction/session key. UnifiedPOS (UPOS) Controls Programmer s Guide 9-11

38 String str = new String ( MyKey ); ctrl.directio( PINIO_SetSessionKey, new int[0], str); 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 en 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 en pad prompt. Decimal is the maximum number of decimal fractions to be entered into the en pad prompt. java.lang.string java.lang.integer java.lang.integer Title to be displayed on number en pad Maximum number of digits in entered number Maximum number of decimal fraction in entered number DeviceIOData.m_sDIOData: String representing entered number. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add(java.lang.string)); cmdargs.add(java.lang.integer)); cmdargs.add(java.lang.integer)); ctrl.directio( PROMPT_Number, new int[0], cmdargs ); SCRIPT_Goto This command branches script execution to the specified label within the script. java.lang.string Script program label DeviceIOData.m_sDIOData: TRUE if script execution successfully branched to the specified label, FALSE otherwise UnifiedPOS (UPOS) Controls Programmer s Guide

39 java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( padsignature ); ctrl.directio(script_goto, new int[0], cmdargs); SCRIPT_GotoVar This command branches script execution to the label contained within the text variable specified. java.lang.string Script text variable containing desired script label DeviceIOData.m_sDIOData: TRUE if script execution successfully branched to the specified label, FALSE otherwise. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( mytextvar ); ctrl.directio(script_gotovar, new int[0], cmdargs); SCRIPT_IsPaused This command queries the device to determine if a script is currently paused. None DeviceIOData.m_sDIOData: TRUE if a script is paused, FALSE otherwise. UnifiedPOS (UPOS) Controls Programmer s Guide 9-13

40 ctrl.directio(script_ispaused, new int[0], null); 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. None DeviceIOData.m_sDIOData: TRUE if a script is running, FALSE otherwise. ctrl.directio(script_isrunning, new int[0], null); SCRIPT_IsScript This command queries the unit to see if a script is loaded into the device. None DeviceIOData.m_sDIOData: TRUE if a script is loaded, FALSE otherwise. ctrl.directio(script_isscript, new int[0], null); 9-14 UnifiedPOS (UPOS) Controls Programmer s Guide

41 SCRIPT_IsVar This command queries the unit to see if the specified variable is the name of a loaded script. java.lang.string Named of variable to test DeviceIOData.m_sDIOData: TRUE if named variable is a loaded script, FALSE otherwise. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add(new String( myscript )); ctrl.directio(script_isvar, new int[0], cmdargs); SCRIPT_Reset This command resets scripts and cancel any running script. None DeviceIOData.m_sDIOData: "Nothing returned" ctrl.directio(script_reset, new int[0], (Object)null); UnifiedPOS (UPOS) Controls Programmer s Guide 9-15

42 SCRIPT_Run This command selects a script named name as the active script and executes it at the beginning or at the optional label. java.lang.string java.lang.string Script named name, typically "AUTORUN" Optional script program label, typically "main" DeviceIOData.m_sDIOData: TRUE if script was run, FALSE otherwise. 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 ctrl.directio(script_run, new int[0], cmdargs); 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. java.lang.string java.lang.string 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. DeviceIOData.m_sDIOData: TRUE if script loaded successfully, FALSE otherwise. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( "AUTORUN" ); cmdargs.add( "c:\\myscript.bin" ); ctrl.directio(script_set, new int[0], cmdargs); 9-16 UnifiedPOS (UPOS) Controls Programmer s Guide

43 SCRIPT_Stop This command stops any running script. None DeviceIOData.m_sDIOData: "Nothing returned" ctrl.directio(script_stop, new int[0], null); 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. java.lang.string Full pathname to file containing firmware DeviceIOData.m_sDIOData: SUCCESS or FAIL DeviceIOData.m_byRawData[0]: 0 if successful, non-zero indicates error. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( c:\\firmware.schex ); ctrl.directio(sys_downloadfirmware, new int[0], cmdargs ); UnifiedPOS (UPOS) Controls Programmer s Guide 9-17

44 SYS_GetError This command retrieves the error string from the device. None 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. ctrl.directio(sys_geterror, new int[0], (Object)null); SYS_GetModel This command returns the unit model number as a java.lang.string value in DeviceIOData.m_sDIOData. None DeviceIOData.m_sDIOData: string representing the model number ctrl.directio(sys_getmodel, new int[0], (Object)null); 9-18 UnifiedPOS (UPOS) Controls Programmer s Guide

45 SYS_GetName This command returns the unit model name as a java.lang.string value in DeviceIOData.m_sDIOData. None DeviceIOData.m_sDIOData: Name of device connected ctrl.directio(sys_getname, new int[0], (Object)null); 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 ) None DeviceIOData.m_sDIOData: Version info of firmware in device ctrl.directio(sys_getversion, new int[0], (Object)null); UnifiedPOS (UPOS) Controls Programmer s Guide 9-19

46 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. None DeviceIOData.m_sDIOData: TRUE if system available, FALSE otherwise. ctrl.directio(sys_isavailable, new int[0], (Object)null); SYS_IsError This command retrieves the current error status of the device. This command does not clear the unit's error status. None DeviceIOData.m_sDIOData: TRUE if an error, FALSE otherwise ctrl.directio(sys_iserror, new int[0], (Object)null); SYS_Reboot This command reboots the unit. None DeviceIOData.m_sDIOData: "Nothing returned" 9-20 UnifiedPOS (UPOS) Controls Programmer s Guide

47 ctrl.directio(sys_reboot, new int[0], (Object)null); SYS_Reset This command resets the system software, devices, and defaults. None DeviceIOData.m_sDIOData: "Nothing returned" ctrl.directio(sys_reset, new int[0], (Object)null); 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. 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" DeviceIOData.m_sDIOData: "Nothing returned" UnifiedPOS (UPOS) Controls Programmer s Guide 9-21

48 java.lang.byte[] debugon = new Byte((byte)0x01), new Byte((byte)0x00) java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add(debugon); ctrl.directio(sys_setdebug, new int[0], cmdargs ); 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. java.lang.string Variable name with text data type DeviceIOData.m_sDIOData: TRUE if contents of variable are retrieved. FALSE otherwise. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( MyVar ); ctrl.directio( TEXT_GetVar, new int[0], cmdargs); Text_IsVar This command determines if the specified variable contains text data. java.lang.string Variable name with text data type DeviceIOData.m_sDIOData: TRUE if specified variable does contain text data. FALSE otherwise UnifiedPOS (UPOS) Controls Programmer s Guide

49 java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( myvar ); ctrl.directio( TEXT_IsVar, new int[0], cmdargs); Text_SetVar This command sets the contents of a variable to the specified text string. java.lang.string java.lang.string Variable name with text data type Variable data DeviceIOData.m_sDIOData: TRUE if contents of variable are successfully set. FALSE otherwise. java.util.linkedlist cmdargs = new java.util.linkedlist(); cmdargs.add( "MyVar" ); cmdargs.add( "Some Text" ); ctrl.directio( TEXT_SetVar, new int[0], cmdargs ); UnifiedPOS (UPOS) Controls Programmer s Guide 9-23

50 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. None DirectIOEvent-lpsString: "Nothing returned." result = ctrl.directio(pw_clearscreen, n, str) 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. String Full pathname to Bitmap File and xstart,ystart in pixels (upper left corner of displayed bitmap image) DirectIOEvent-lpsString: "Nothing returned." str = "5,5,c:\my bitmap.bmp" result = ctrl.directio(pw_displaybitmapfile, n, str) 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. String xstart,ystart (starting x,y coordinate position in pixels) and xwidth,yheight (width/height of box in pixels) DirectIOEvent-lpsString: "Nothing returned." 9-24 UnifiedPOS (UPOS) Controls Programmer s Guide

51 str = "0,0,20,20" result = ctrl.directio(pw_displaybox, n, str) 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. None DirectIOEvent-lpsString: "Nothing returned." result = ctrl.directio(pw_displaylogo, n, str) PW_MEMDELETEOBJ Unit deletes the given item ID display object from memory, if it exists. String ID of item to delete from memory DirectIOEvent-lpsString: "Nothing returned." str = "15" result = ctrl.directio(pw_memdeleteobj, n, str) PW_MEMDELETEVAR Unit deletes a data variable defined by name from memory. String Name of variable to delete from memory DirectIOEvent-lpsString: "Nothing returned". UnifiedPOS (UPOS) Controls Programmer s Guide 9-25

52 str = "myvar" result = ctrl.directio(pw_memdeletevar, n, str) 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. String Item ID to find in memory DirectIOEvent-lpsString: TRUE if id is found in memory, FALSE otherwise. str = "15" result = ctrl.directio(pw_memfindobj, n, str) PW_MEMFINDVAR String Name of variable to find in memory DirectIOEvent-lpsString: TRUE if variable is found in memory, FALSE otherwise. str = "myvar" result = ctrl.directio(pw_memfindvar, n, str) PW_MEMGETFREE Unit returns the number of free kilobytes of user memory. None DirectIOEvent-lpsString: nfreememory + " KB free user memory." Where nfreememory is an integer value UnifiedPOS (UPOS) Controls Programmer s Guide

53 result = ctrl.directio(pw_memgetfree, n, str) PW_MEMGETVAR This command retrieves the contents of a specified memory variable. String Name of variable to retrieve from memory DirectIOEvent-lpsString: contents of the variable. str = "myvar" result = ctrl.directio(pw_memgetvar, n, str) 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. String Named data variable in memory and Transaction Terminal command DirectIOEvent-lpsString: TRUE if contents of variable are successfully assigned based on result of given command. FALSE otherwise. str = "myvar,x10x29x00x00" result = ctrl.directio(pw_memsetvar, n, str) UnifiedPOS (UPOS) Controls Programmer s Guide 9-27

54 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 en 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 en pad prompt. Decimal is the maximum number of decimal fractions to be entered into the en pad prompt. String Title to be displayed on number en pad, maximum number of digits in entered number, and maximum number of decimal fraction in entered number DirectIOEvent-lpsString: String representing entered number. str = txtnumberpostitions & "," & txtunitpositions & "," & txtnumberform result = ctrl.directio(pw_numberpad, n, str) 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. String 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 DirectIOEvent-lpsString: "Nothing returned." str = "0,0,My text" result = ctrl.directio(pw_puttext, n, str) 9-28 UnifiedPOS (UPOS) Controls Programmer s Guide

55 PW_RESETLOGO This command resets the displayed default logo to the unit's system logo. None DirectIOEvent-lpsString: "Nothing returned." result = ctrl.directio(pw_resetlogo, n, str) PW_SCRIPTGOTO This command branches script execution to the specified label within the script. String Script program label DirectIOEvent-lpsString: TRUE if script execution successfully branched to the specified label, FALSE otherwise. str = "padsignature" result = ctrl.directio(pw_scriptgoto, n, str) PW_SCRIPTGOTOVAR This command branches script execution to the label contained within the text variable specified. String Script text variable containing desired script label DirectIOEvent-lpsString: TRUE if script execution successfully branched to the specified label, FALSE otherwise. str = "mytextvar" result = ctrl.directio(pw_scriptgotovar, n, str) UnifiedPOS (UPOS) Controls Programmer s Guide 9-29

56 PW_SCRIPTISPAUSED This command queries the device to determine if a script is currently paused. None DirectIOEvent-lpsString: TRUE if a script is paused, FALSE otherwise. result = ctrl.directio(pw_scriptispaused, n, str) 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. None DirectIOEvent-lpsString: TRUE if a script is running, FALSE otherwise. result = ctrl.directio(pw_scriptisrunning, n, str) PW_SCRIPTISSCRIPT This command queries the unit to see if a script is loaded into the device. None DirectIOEvent-lpsString: TRUE if a script is loaded, FALSE otherwise. result = ctrl.directio(pw_scriptisscript, n, str) 9-30 UnifiedPOS (UPOS) Controls Programmer s Guide

57 PW_SCRIPTISVAR This command queries the unit to see if the specified variable is the name of a loaded script. String Named of variable to test DirectIOEvent-lpsString: TRUE if named variable is a loaded script, FALSE otherwise. str = "myscript" result = ctrl.directio(pw_scriptisvar, n, str) PW_SCRIPTRESET This command resets scripts and cancel any running script. None DirectIOEvent-lpsString: "Nothing returned" result = ctrl.directio(pw_scriptreset, n, str) PW_SCRIPTRUN This command selects a script named name as the active script and executes it at the beginning or at the optional label. String Script named name, typically "AUTORUN" and optional script program label, typically "main" DirectIOEvent-lpsString: TRUE if script was run, FALSE otherwise. str = "AUTORUN,main" result = ctrl.directio(pw_scriptrun, n, str) UnifiedPOS (UPOS) Controls Programmer s Guide 9-31

58 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. String 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. DirectIOEvent-lpsString: TRUE if script loaded successfully, FALSE otherwise. str = "AUTORUN,c:\myScript.bin" result = ctrl.directio(pw_scriptfileload, n, str) PW_SCRIPTSTOPLOAD This command stops any running script. None DirectIOEvent-lpsString: "Nothing returned" result = ctrl.directio(pw_scriptstopload, n, str) PW_SETFONT This command sets the font to be used when displaying text. Integer ID that identifies font type 9-32 UnifiedPOS (UPOS) Controls Programmer s Guide

59 The font type may be one of the following TT8800CommandConst interface constants: DISPLAY_Font8x8 DISPLAY_Font16x16 DISPLAY_Font6x8 DISPLAY_Font8x12 DISPLAY_Font12x16 DISPLAY_Font16x24 DirectIOEvent-lpsString: "Nothing returned." n = PW_FONT6X8 result = ctrl.directio(pw_setfont, n, str) PW_SETLOGO This command loads a bitmap to be the default logo displayed. String Full pathname to Bitmap File DirectIOEvent-lpsString: "Nothing returned." str = "c:\mybitmap.bmp" result = ctrl.directio(pw_setlogo, n, str) PW_SETMKEY This command sets the Master key to the specified value. Integer Number '0' through '9' 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

60 n = 3 result = ctrl.directio(pw_setmkey, n, str) PW_SETSKEY This command sets the Session key to the specified value. String Transaction/session key (16 hex-ascii digits) DirectIOEvent-lpsString: Contains the set transaction/session key. str = " ABCDEF" result = ctrl.directio(pw_setskey, n, str) 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. String Full pathname to file containing firmware DirectIOEvent-lpsString: SUCCESS or FAIL. str = "c:\firmware.schex" result = ctrl.directio(pw_sysdownload, n, str) 9-34 UnifiedPOS (UPOS) Controls Programmer s Guide

61 PW_SYSGETERROR This command retrieves the error string from the device. None DirectIOEvent-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. result = ctrl.directio(pw_sysgeterror, n, str) PW_SYSGETMODEL This command returns the unit model number. None DirectIOEvent-lpsString: string representing the model number result = ctrl.directio(pw_sysgetmodel, n, str) PW_SYSGETNAME This command returns the unit model name. None DirectIOEvent-lpsString: Name of device connected UnifiedPOS (UPOS) Controls Programmer s Guide 9-35

62 result = ctrl.directio(pw_sysgetname, n, str) 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 ) None DirectIOEvent-lpsString: Version info of firmware in device result = ctrl.directio(pw_sysgetversion, n, str) 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. None DirectIOEvent-lpsString: TRUE if system available, FALSE otherwise. result = ctrl.directio(pw_sysisavailable, n, str) 9-36 UnifiedPOS (UPOS) Controls Programmer s Guide

63 PW_SYSISERROR This command retrieves the current error status of the device. This command does not clear the unit's error status. None DirectIOEvent-lpsString: TRUE if an error, FALSE otherwise result = ctrl.directio(pw_sysiserror, n, str) PW_SYSREBOOT This command reboots the unit. None DirectIOEvent-lpsString: "Nothing returned" result = ctrl.directio(pw_sysreboot, n, str) PW_SYSRESET This command resets the system software, devices, and defaults. None DirectIOEvent-lpsString: "Nothing returned" result = ctrl.directio(pw_sysreset, n, str) If result <> 0 Then MsgBox ("Error : " & result) UnifiedPOS (UPOS) Controls Programmer s Guide 9-37

64 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. Byte[] with the following values: DirectIOEvent-lpsString: "Nothing returned" n = 1 result = ctrl.directio(pw_syssetdebug, n, str) PW_TEXTGETVAR new Byte((byte)0x01), new Byte((byte)0x00) - Debug set "ON" new Byte((byte)0x0), new Byte((byte)0x00) - Debug set "OFF" 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. String Variable name with text data type DirectIOEvent-lpsString: TRUE if contents of variable are retrieved. FALSE otherwise. str = "MyVar" result = ctrl.directio(pw_textgetvar, n, str) PW_TEXTISVAR This command determines if the specified variable contains text data. String Variable name with text data type DirectIOEvent-lpsString: TRUE if specified variable does contain text data. FALSE otherwise UnifiedPOS (UPOS) Controls Programmer s Guide

65 str = "myvar" result = ctrl.directio(pw_textisvar, n, str) PW_TEXTSETVAR This command sets the contents of a variable to the specified text string. String Variable name with text data type and variable data DirectIOEvent-lpsString: TRUE if contents of variable are successfully set. FALSE otherwise. str = "MyVar,Some Text" result = ctrl.directio(pw_textsetvar, n, str) UnifiedPOS (UPOS) Controls Programmer s Guide 9-39

66 9-40 UnifiedPOS (UPOS) Controls Programmer s Guide

67 10 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) , Option 4 (8 a.m. to 6 p.m. EST) Fax number: (315) [email protected] UnifiedPOS (UPOS) Controls Programmer s Guide 10-1

68 10-2 UnifiedPOS (UPOS) Controls Programmer s Guide

69 UnifiedPOS (UPOS) Controls Programmer s Guide 10-3

70 10-4 UnifiedPOS (UPOS) Controls Programmer s Guide

71

72 Hand Held Products, Inc. 700 Visions Drive P.O. Box 208 Skaneateles Falls, NY UPOS-PG Rev F 7/06