UnifiedPOS Version 1.12 01142008

UnifiedPOS
UnifiedPOS
Retail Peripheral Architecture
Version 1.12 January 14, 2008
International Standard
For Implementation of Point Of Service Peripherals

UnifiedPOS Retail Peripheral Architecture
ii
Copyright © National Retail Federation, 2004-2008. All Rights Reserved.
Right to Copy
This document may be copied or used for purposes consistent with adoption of the ARTS
Standards. However, any changes or inconsistent uses must be pre-approved in writing by
the National Retail Federation (“NRF”). Consequently, this document may be furnished to
others, but derivative works (the term “derivative works” does not include functional
additions that do not modify or change the base standard as written) that comment on or
otherwise explain it or assist in its implementation may not cite or refer to the standard, in
whole or in part, without such permission. Moreover, this document may not be modified
in any way, such as by removing the copyright notice or references to the NRF, ARTS, or
its committees, except as needed for the purpose of developing ARTS standards using
procedures approved by NRF, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be revoked by the
National Retail Federation or its successors or assigns.
Disclaimer
THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS PROVIDED

ON AN “AS IS” BASIS AND THE ASSOCIATION FOR RETAIL TECHNOLOGY
STANDARDS (“ARTS”) AND THE NATIONAL RETAIL FEDERATION (“NRF”)
DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN
WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
ARTS AND NRF ASSUME NO RESPONSIBILITY FOR ERRORS OR OMISSIONS IN
THIS PUBLICATION OR OTHER DOCUMENTS WHICH ARE REFERENCED BY,
CITED BY, OR LINKED TO THIS PUBLICATION. THIS PUBLICATION COULD
INCLUDE TECHNICAL OR OTHER INACCURACIES OR TYPOGRAPHICAL
ERRORS. ARTS AND NRF RESERVE THE RIGHT TO MAKE IMPROVEMENTS
AND/OR CHANGES TO THE INFORMATION HEREIN.
UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Retail Peripheral Architecture iii
UnifiedPOS Technical Committee Members:

BearingPoint, Inc.,
Datalogic Scanning, Inc.,
Fujitsu Transaction Solutions Inc.,
IBM Corporation,
Microsoft Corporation,
Motorola, Inc.,
NCR Corporation,
OPOS-Japan,
Seiko Epson Corporation,
Wincor Nixdorf International GmbH.
UnifiedPOS Technical Committee Contributors:

360Commerce,
The Home Depot, Inc.,
PCMS Datafit Ltd.,
InstaPayment, Inc.,
J.C. Penney Company, Inc.,
Retail Solutions Providers Association (RSPA),
Sears, Roebuck & Co.,
Star Micronics, Inc.,
Sun Microsystems, Inc.,
Transaction Printer Group, Inc.,
Ultimate Technology Corporation
Information regarding the activities of the UnifiedPOS Committee can

be viewed at the following web site:
http://www.nrf-arts.org
UnifiedPOS
Information in this document is subject to change without notice.
JavaPOS is a trademark of Sun Microsystems, Inc.

Windows is a trademark of Microsoft Corporation.
Epson is a trademark of Seiko Epson Corporation.

iv
This page intentionally left blank.

Table of Contents
INTRODUCTION AND ARCHITECTURE
UNIFIEDPOS ARCHITECTURE FOR RETAIL ...............................................................33
WHAT IS UNIFIEDPOS? ......................................................................................................33
ABOUT THIS DOCUMENTATION ...........................................................................................34
GOALS ..................................................................................................................................37
DEPENDENCIES.....................................................................................................................37
UNIFIEDPOS RELATIONSHIP TO CONFORMING PLATFORM MAPPINGS ...............................37
WHO SHOULD READ THIS DOCUMENT................................................................................38
ARCHITECTURAL OVERVIEW ........................................................................................39
ARCHITECTURAL COMPONENTS...........................................................................................39
USE OF UML .......................................................................................................................40
Package Diagram .........................................................................................................42
DATA TYPES ........................................................................................................................43
DEVICE BEHAVIOR MODELS ................................................................................................44
INTRODUCTION TO PROPERTIES, METHODS, AND EVENTS ..................................................44
Properties (UML Attributes).........................................................................................44
Methods (UML Operations)..........................................................................................45
Events (UML Interfaces)...............................................................................................45
DEVICE INITIALIZATION AND FINALIZATION .......................................................................46
Initialization ..................................................................................................................46
Initialization and Error Reporting................................................................................46
Finalization ...................................................................................................................49
Summary .......................................................................................................................49
DEVICE SHARING MODEL ....................................................................................................50
Exclusive-Use Devices ..................................................................................................50
Sharable Devices ..........................................................................................................50
EVENTS ................................................................................................................................51
ERRORS ................................................................................................................................52
ERROR CODES ......................................................................................................................52
Extended Error Code ....................................................................................................53
DEVICE INPUT MODEL .........................................................................................................54
Error Handling .............................................................................................................55
Miscellaneous ...............................................................................................................56
DEVICE OUTPUT MODELS....................................................................................................57
Synchronous Output......................................................................................................57
Asynchronous Output....................................................................................................57
DEVICE POWER REPORTING MODEL ...................................................................................58
Model ............................................................................................................................58
Power State Diagram....................................................................................................59
Power Properties ..........................................................................................................60
Power Reporting Requirements for DeviceEnabled .....................................................61
DEVICE INFORMATION REPORTING MODEL ........................................................................62
Statistics Reporting Properties and Methods ...............................................................62
XML definitions for POS Device Statistics ...................................................................63
UPDATE FIRMWARE DEVICE MODEL ...................................................................................65
DEVICE STATES ...................................................................................................................66
Device State Diagram ...................................................................................................67
VERSION HANDLING ............................................................................................................68
DEPRECATION HANDLING ....................................................................................................69
HYDRA DEVICE CONSIDERATIONS ......................................................................................70
ii Table of Contents
Initial Connectivity Model ............................................................................................70

Control Object or Device Control (Control)...........................................................70
Service Object or Device Service (Service) ...........................................................70
Multi-Function (Hydra) Peripheral Devices...........................................................71
Considerations ..............................................................................................................73
CHAPTER 1
COMMON PROPERTIES, METHODS, AND EVENTS ...................................................75
SUMMARY ............................................................................................................................75
GENERAL INFORMATION ......................................................................................................78
Common PME Class Diagram......................................................................................78
PROPERTIES (UML ATTRIBUTES).........................................................................................80
METHODS (UML OPERATIONS) ...........................................................................................91
EVENTS (UML INTERFACES) .............................................................................................102
CHAPTER 2
BELT.......................................................................................................................................111
SUMMARY ..........................................................................................................................111
GENERAL INFORMATION ....................................................................................................115
Capabilities .................................................................................................................115
Belt Class Diagram.....................................................................................................116
Belt Sequence Diagram...............................................................................................117
Model ..........................................................................................................................119
Device Sharing............................................................................................................120
Belt State Diagram......................................................................................................120
PROPERTIES (UML ATTRIBUTES).......................................................................................121
METHODS (UML OPERATIONS) .........................................................................................128
CHAPTER 3
BILL ACCEPTOR ................................................................................................................135
SUMMARY ..........................................................................................................................135
Capabilities .................................................................................................................139
Bill Acceptor Class Diagram ......................................................................................140
Model ..........................................................................................................................141
Bill Acceptor Sequence Diagram................................................................................142
Bill Acceptor State Diagram.......................................................................................143
Device Sharing............................................................................................................143
CHAPTER 4
BILL DISPENSER ................................................................................................................155
SUMMARY ..........................................................................................................................155
Capabilities .................................................................................................................159
Bill Dispenser Class Diagram ....................................................................................160
Model ..........................................................................................................................161
Bill Dispenser Sequence Diagram ..............................................................................163
Bill Dispenser State Diagram .....................................................................................164
Device Sharing............................................................................................................164

Table of Contents iii
CHAPTER 5
BIOMETRICS .......................................................................................................................175
SUMMARY ..........................................................................................................................175
Capabilities .................................................................................................................179
Biometrics Class Diagram..........................................................................................181
Model ..........................................................................................................................182
Device Sharing............................................................................................................183
Biometrics Sequence Diagrams ..................................................................................184
Biometrics State Diagram...........................................................................................187
PROPERTIES (UML ATTRIBUTES) ......................................................................................188
CHAPTER 6
BUMP BAR ............................................................................................................................205
SUMMARY ..........................................................................................................................205
Capabilities .................................................................................................................209
Bump Bar Class Diagram...........................................................................................210
Model ..........................................................................................................................211
Input – Bump Bar .................................................................................................212
Output – Tone.......................................................................................................213
Device Sharing............................................................................................................213
Bump Bar State Diagram............................................................................................214
CHAPTER 7
CASH CHANGER.................................................................................................................231
SUMMARY ..........................................................................................................................231
Capabilities .................................................................................................................235
CashChanger Class Diagram .....................................................................................236
Model ..........................................................................................................................237
Cash Changer Sequence Diagram..............................................................................241
Cash Changer State Diagram.....................................................................................242
Device Sharing............................................................................................................242
CHAPTER 8
CASH DRAWER ...................................................................................................................265
SUMMARY ..........................................................................................................................265
Capabilities .................................................................................................................268
Cash Drawer Class Diagram......................................................................................268
Cash Drawer Sequence Diagram ...............................................................................269
Device Sharing............................................................................................................270

iv Table of Contents
CHAPTER 9
CAT - CREDIT AUTHORIZATION TERMINAL ...........................................................277
SUMMARY ..........................................................................................................................277
Description of terms....................................................................................................281
Capabilities .................................................................................................................282
CAT Class Diagram....................................................................................................284
Model ..........................................................................................................................285
Device Sharing............................................................................................................289
CAT Sequence Diagram..............................................................................................290
CAT State Diagram.....................................................................................................291
CHAPTER 10
CHECK SCANNER ..............................................................................................................323
SUMMARY ..........................................................................................................................323
Capabilities .................................................................................................................327
Check Scanner Class Diagram ...................................................................................328
Model ..........................................................................................................................329
Device Sharing............................................................................................................332
Check Scanner Sequence Diagram .............................................................................333
Check Scanner State Diagram ....................................................................................334
CHAPTER 11
COIN ACCEPTOR................................................................................................................361
SUMMARY ..........................................................................................................................361
Capabilities .................................................................................................................365
Coin Acceptor Class Diagram ....................................................................................366
Model ..........................................................................................................................367
Coin Acceptor Sequence Diagram..............................................................................368
Coin Acceptor State Diagram.....................................................................................369
Device Sharing............................................................................................................369
CHAPTER 12
COIN DISPENSER ...............................................................................................................381
SUMMARY ..........................................................................................................................381
Capabilities .................................................................................................................384
Coin Dispenser Class Diagram ..................................................................................385
Coin Dispenser Sequence Diagram ............................................................................386
Coin Dispenser State Diagram ...................................................................................387
Model ..........................................................................................................................388
Device Sharing............................................................................................................388

Table of Contents v
CHAPTER 13
ELECTRONIC JOURNAL ..................................................................................................395
SUMMARY ..........................................................................................................................395
Capabilities .................................................................................................................399
Electronic Journal Class Diagram .............................................................................400
Model ..........................................................................................................................401
Device Sharing............................................................................................................402
Electronic Journal Sequence Diagrams .....................................................................403
Electronic Journal State Diagram ..............................................................................405
CHAPTER 14
ELECTRONIC VALUE READER / WRITER..................................................................425
SUMMARY ..........................................................................................................................425
Capabilities .................................................................................................................430
Electronic Value R / W Class Diagram ......................................................................431
Model ..........................................................................................................................432
Input Model ..........................................................................................................433
Output Model........................................................................................................433
Support of sub-service use....................................................................................433
Transaction Mode Support ...................................................................................434
Device Sharing............................................................................................................434
Electronic Value Reader / Writer Sequence Diagram ................................................435
Electronic Value Reader / Writer State Diagram .......................................................438
CHAPTER 15
FISCAL PRINTER................................................................................................................465
SUMMARY ..........................................................................................................................465
Fiscal Printer Class Diagram.....................................................................................475
General Requirements ................................................................................................476
Fiscal Printer Modes ..................................................................................................477
Model ..........................................................................................................................478
Error Model ................................................................................................................479
Release 1.8 additional Model clarifications ...............................................................480
Fiscal Printer States ...................................................................................................482
Fiscal Printer State Diagram......................................................................................484
Document Printing......................................................................................................485
Ordering of Fiscal Receipt Print Requests .................................................................486
Fiscal Receipt Layouts................................................................................................488
Example of a Fiscal Receipt .......................................................................................489
Totalizers and Fiscal Memory ....................................................................................490
Counters......................................................................................................................490
VAT Tables..................................................................................................................490
Receipt Duplication ....................................................................................................490
Currency amounts, percentage amounts, VAT rates, and quantity amounts..............491
Currency Change ........................................................................................................491
Device Sharing............................................................................................................491

vi Table of Contents

CHAPTER 16
GATE ......................................................................................................................................613
SUMMARY ..........................................................................................................................613
Capabilities .................................................................................................................616
Gate Class Diagram ...................................................................................................617
Gate Sequence Diagram .............................................................................................618
Device Sharing............................................................................................................619
CHAPTER 17
HARD TOTALS ....................................................................................................................625
SUMMARY ..........................................................................................................................625
Capabilities .................................................................................................................629
Hard Totals Class Diagram........................................................................................630
Hard Totals Sequence Diagram..................................................................................631
Model ..........................................................................................................................632
Device Sharing............................................................................................................634
CHAPTER 18
IMAGE SCANNER ...............................................................................................................649
SUMMARY ..........................................................................................................................649
Capabilities .................................................................................................................653
Image Scanner Class Diagram ...................................................................................654
Image Scanner Sequence Diagram 1 ..........................................................................655
Model ..........................................................................................................................659
Device Sharing............................................................................................................659
Image Scanner State Diagram ....................................................................................660
CHAPTER 19
ITEM DISPENSER ...............................................................................................................673
SUMMARY ..........................................................................................................................673
Capabilities .................................................................................................................676
Item Dispenser Class Diagram...................................................................................677
Item Dispenser Sequence Diagram.............................................................................678
Model ..........................................................................................................................679
Device Sharing............................................................................................................679
Item Dispenser State Diagram....................................................................................679

Table of Contents vii
CHAPTER 20
KEYLOCK .............................................................................................................................687
SUMMARY ..........................................................................................................................687
Capabilities .................................................................................................................690
Keylock Class Diagram ..............................................................................................690
Keylock Sequence Diagram ........................................................................................691
Model ..........................................................................................................................692
Device Sharing............................................................................................................692
CHAPTER 21
LIGHTS ..................................................................................................................................699
SUMMARY ..........................................................................................................................699
Capabilities .................................................................................................................702
Lights Class Diagram .................................................................................................702
Lights Sequence Diagram ...........................................................................................703
Device Sharing............................................................................................................704
CHAPTER 22
LINE DISPLAY .....................................................................................................................711
SUMMARY ..........................................................................................................................711
Capabilities .................................................................................................................715
Line Display Class Diagram.......................................................................................716
Line Display Sequence Diagram ................................................................................717
Model ..........................................................................................................................718
Display Modes ............................................................................................................719
Data Characters and Escape Sequences ....................................................................720
Device Sharing............................................................................................................720
CHAPTER 23
MICR - MAGNETIC INK CHARACTER RECOGNITION READER .........................759
SUMMARY ..........................................................................................................................759
Capabilities .................................................................................................................762
MICR Class Diagram .................................................................................................763
MICR Sequence Diagram ...........................................................................................764
Model ..........................................................................................................................765
Device Sharing............................................................................................................766
MICR Character Substitution .....................................................................................767
CHAPTER 24
MOTION SENSOR ...............................................................................................................779
SUMMARY ..........................................................................................................................779

viii Table of Contents

Capabilities .................................................................................................................782
Motion Sensor Class Diagram....................................................................................782
Model ..........................................................................................................................783
Device Sharing............................................................................................................783
Motion Sensor Sequence Diagram..............................................................................784
Motion Sensor State Diagram.....................................................................................785
CHAPTER 25
MSR - MAGNETIC STRIPE READER .............................................................................791
SUMMARY ..........................................................................................................................791
Capabilities .................................................................................................................795
Clarifications for JIS-II data handling ..................................................................795
MSR Class Diagram ...................................................................................................796
Device Behavior Model...............................................................................................797
Input – MSR .........................................................................................................797
Output – MSR.......................................................................................................797
Device Sharing............................................................................................................798
MSR Sequence Diagram .............................................................................................799
MSR Device Authentication Sequence Diagram.........................................................800
MSR State Diagrams...................................................................................................801
CHAPTER 26
PIN PAD .................................................................................................................................835
SUMMARY ..........................................................................................................................835
Capabilities .................................................................................................................839
PIN Pad Class Diagram .............................................................................................840
PIN Pad Sequence Diagram .......................................................................................841
Feature Not Supported................................................................................................842
Note on Terminology...................................................................................................842
Model ..........................................................................................................................843
Device Sharing............................................................................................................844
PIN Pad State Diagram ..............................................................................................845
CHAPTER 27
POINT CARD READER / WRITER...................................................................................865
SUMMARY ..........................................................................................................................865
Capabilities .................................................................................................................870
Point Card Reader Writer Class Diagram .................................................................871
Model ..........................................................................................................................872
Input Model ..........................................................................................................872
Output Model........................................................................................................873
Card Insertion Diagram .............................................................................................874
Printing Capability .....................................................................................................875
Cleaning Capability ....................................................................................................876

Table of Contents ix
Initialization of Magnetic Stripe Data ........................................................................876

Device Sharing............................................................................................................876
Point Card Reader Writer Sequence Diagram ...........................................................879
Point Card Reader Writer State Diagram ..................................................................880
CHAPTER 28
POS KEYBOARD .................................................................................................................915
SUMMARY ..........................................................................................................................915
Capabilities .................................................................................................................918
POS Keyboard Class Diagram ...................................................................................918
POS Keyboard Sequence Diagram .............................................................................919
Model ..........................................................................................................................920
Keyboard Translation ...........................................................................................920
Device Sharing............................................................................................................920
CHAPTER 29
POS POWER .........................................................................................................................927
SUMMARY ..........................................................................................................................927
Capabilities .................................................................................................................930
Device Sharing............................................................................................................930
Model ..........................................................................................................................931
POSPower Class Diagram .........................................................................................932
POSPower Sequence Diagram ...................................................................................933
POSPower Standby Sequence Diagram .....................................................................934
POSPower State Diagram ..........................................................................................935
POSPower PowerState Diagram - part 1 ...................................................................936
POSPower State chart Diagram for Fan and Temperature .......................................939
POSPower Battery State Diagram..............................................................................940
POSPower Power Transitions State Diagram............................................................941
CHAPTER 30
POS PRINTER.......................................................................................................................955
SUMMARY ..........................................................................................................................955
Capabilities .................................................................................................................962
POS Printer Class Diagram .......................................................................................963
POS Printer Class Diagram Updates .........................................................................964
Model ..........................................................................................................................965
Device Sharing............................................................................................................971
POS Printer State Diagram ........................................................................................972
Page Mode Printing State Diagram ...........................................................................973
“Both sides printing” sequence Diagram...................................................................974
Page Mode printing sequence Diagram .....................................................................975

x Table of Contents
POS Printer State Diagrams (Low Level) ..................................................................981

METHODS (UML OPERATIONS) .......................................................................................1031
EVENTS (UML INTERFACES) ...........................................................................................1067
CHAPTER 31
REMOTE ORDER DISPLAY............................................................................................1073
SUMMARY ........................................................................................................................1073
GENERAL INFORMATION ..................................................................................................1078
Capabilities ...............................................................................................................1078
Remote Order Display Class Diagram .....................................................................1079
Model ........................................................................................................................1080
Device Sharing..........................................................................................................1084
PROPERTIES (UML ATTRIBUTES).....................................................................................1085
CHAPTER 32
RFID SCANNER .................................................................................................................1117
SUMMARY ........................................................................................................................1117
Capabilities ...............................................................................................................1121
RFID Scanner Class Diagram ..................................................................................1122
Model ........................................................................................................................1123
Input....................................................................................................................1123
Output .................................................................................................................1124
RFID Scanner Sequence Diagrams ..........................................................................1125
RFID Scanner State Diagram...................................................................................1128
Device Sharing..........................................................................................................1128
PROPERTIES (UML ATTRIBUTES) ....................................................................................1129
CHAPTER 33
SCALE ..................................................................................................................................1143
SUMMARY ........................................................................................................................1143
Capabilities ...............................................................................................................1146
Scale Class Diagram.................................................................................................1147
Scale Sequence Diagram ..........................................................................................1148
Model ........................................................................................................................1149
Device Sharing..........................................................................................................1149
CHAPTER 34
SCANNER (BAR CODE READER)..................................................................................1163
SUMMARY ........................................................................................................................1163
Capabilities ...............................................................................................................1166
Scanner Class Diagram ............................................................................................1166
Scanner Sequence Diagram ......................................................................................1167
Model ........................................................................................................................1168
Device Sharing..........................................................................................................1168

Table of Contents xi
CHAPTER 35
SIGNATURE CAPTURE ...................................................................................................1177
SUMMARY ........................................................................................................................1177
Capabilities ...............................................................................................................1180
Signature Capture Class Diagram............................................................................1181
Signature Capture Sequence Diagram .....................................................................1182
Model ........................................................................................................................1183
Device Sharing..........................................................................................................1184
CHAPTER 36
SMART CARD READER / WRITER...............................................................................1195
SUMMARY ........................................................................................................................1195
Capabilities ...............................................................................................................1199
Smart Card Reader / Writer Class Diagram ............................................................1200
Model ........................................................................................................................1201
Card Insertion Diagram ...........................................................................................1204
Device Sharing..........................................................................................................1205
Data Transfer Modes ................................................................................................1206
Smart Card Reader / Writer Sequence Diagram ......................................................1207
Smart Card Reader / Writer State Diagram .............................................................1208
PROPERTIES (UML ATTRIBUTES) ....................................................................................1209
CHAPTER 37
TONE INDICATOR............................................................................................................1225
SUMMARY ........................................................................................................................1225
Capabilities ...............................................................................................................1228
Tone Indicator Class Diagram .................................................................................1228
Tone Indicator Sequence Diagram ...........................................................................1229
Model ........................................................................................................................1230
Device Sharing..........................................................................................................1231
APPENDIX A
OLE FOR RETAIL POS — OPOS IMPLEMENTATION REFERENCE.........................1
WHAT IS “OLE FOR RETAIL POS?” ......................................................................................1
WHO SHOULD READ THIS SECTION ......................................................................................2
GENERAL OLE FOR RETAIL POS CONTROL MODEL ............................................................2
OPOS DEFINITIONS ...............................................................................................................3
Device Class....................................................................................................................3
Control Object or CO .....................................................................................................3
Service Object or SO.......................................................................................................3
OPOS Control or Control...............................................................................................3
HOW AN APPLICATION USES AN OPOS CONTROL ................................................................4
WHEN METHODS AND PROPERTIES MAY BE ACCESSED ......................................................5
Methods...........................................................................................................................5
Properties........................................................................................................................5
STATUS, RESULT CODE, AND STATE MODEL ........................................................................7

xii Table of Contents
Status Model....................................................................................................................8
Result Code Model..........................................................................................................8
State Model .....................................................................................................................9
EVENTS ................................................................................................................................11
OPOS Event Registration Sequence Diagram..............................................................13
INPUT MODEL ......................................................................................................................14
OUTPUT MODEL ...................................................................................................................16
Model ............................................................................................................................17
Properties......................................................................................................................18
OPOS COMPONENT DESCRIPTIONS .....................................................................................22
SECTION 1: OPOS DATA TYPES ..........................................................................................23
SECTION 2: OPOS INTERFACE DESCRIPTIONS .....................................................................25
OPOS COMMON PROPERTIES, METHODS, AND EVENTS .....................................................26
Common Properties ......................................................................................................26
Common Methods .........................................................................................................27
OPOS Programmatic Names ........................................................................................28
Properties......................................................................................................................29
Methods.........................................................................................................................46
Events ............................................................................................................................58
PERIPHERAL INTERFACES.....................................................................................................62
OPOS: CASH DRAWER ........................................................................................................63
Visual Basic Command Examples. ...............................................................................63
Initializing Properties, Methods, and Events................................................................63
Capabilities, Assignments and Descriptions Properties, Methods, and Events ...........63
Cash Drawer Operations Properties and Methods ......................................................64
Terminating Methods ....................................................................................................64
Visual C++ Command Examples. ................................................................................65
Cash Drawer Operations Properties and Methods ......................................................66
OPOS: MICR ......................................................................................................................67
Visual Basic Command Examples. ...............................................................................67
MICR Operations Properties, Methods, and Events ....................................................68
Visual C++ Command Examples. ................................................................................70
SECTION 3: OPOS REGISTRY USAGE ..................................................................................73
Service Object Root Registry Key .................................................................................73
Device Class Keys.........................................................................................................73

Table of Contents xiii
Device Name Keys and Values .....................................................................................74

Logical Device Name Values ........................................................................................74
Service Provider Root Registry Key .............................................................................75
Example.........................................................................................................................75
SECTION 4: OPOS APPLICATION HEADER FILES.................................................................77
SECTION 5: TECHNICAL DETAILS ........................................................................................78
System Strings (BSTR) ..................................................................................................78
System String Characteristics.................................................................................78
System String Usage...............................................................................................78
System Strings and Binary Data ...................................................................................79
Mapping of CharacterSet..............................................................................................80
SECTION 6: RELEASE 1.5 API CHANGE: CLAIMDEVICE AND RELEASEDEVICE ..................81
SECTION 7: OPOS APG CHANGE HISTORY ........................................................................82
Release 1.01 ..................................................................................................................82
Release 1.1 ....................................................................................................................83
Release 1.2 ....................................................................................................................85
Release 1.3 ....................................................................................................................87
Release 1.4 ....................................................................................................................89
Release 1.5 ....................................................................................................................90
Release 1.6 ....................................................................................................................92
Release 1.7 ....................................................................................................................93
SECTION 8: OPOS CONTROL PROGRAMMER’S GUIDE ........................................................94
Who Should Read This Section .....................................................................................94
General OLE for Retail POS Control Model................................................................95
OPOS Definitions..........................................................................................................96
Device Class ...........................................................................................................96
Control Object or CO .............................................................................................96
Service Object or SO ..............................................................................................96
OPOS Control or Control .......................................................................................96
Interface Overview........................................................................................................98
Methods.........................................................................................................................99
Open Method ..........................................................................................................99
Close Method..........................................................................................................99
Other Methods ........................................................................................................99
Properties....................................................................................................................100
String Properties ...................................................................................................100
LONG and BOOL Properties ...............................................................................100
Other Property Types............................................................................................100
Events ..........................................................................................................................101
Architecture: Firing an Event ...............................................................................101
Architectural Issue: Freezing Events by the Container ........................................101
Architectural Feature: Freezing Events by the Application .................................102
Summary of Event Firing .....................................................................................102
Control Object Responsibilities ..................................................................................103
Methods ................................................................................................................103
Properties ..............................................................................................................106
Events ...................................................................................................................107
Service Object Responsibilities and Implementation..................................................111
Methods ................................................................................................................111
Properties ..............................................................................................................118
Events ...................................................................................................................120
OPOS CPG Change History .......................................................................................121
Release 1.01..........................................................................................................121
Release 1.1............................................................................................................121
Release 1.2............................................................................................................122

xiv Table of Contents
Release 1.3............................................................................................................123
Release 1.4............................................................................................................124
Release 1.5............................................................................................................124
Release 1.6............................................................................................................125
Release 1.7............................................................................................................125
Common Control Objects ...........................................................................................126
Features.................................................................................................................126
Availability and Future.........................................................................................126
OPOS Internal Header Files ......................................................................................127
APPENDIX B
JAVA FOR RETAIL POS — JAVAPOS IMPLEMENTATION REFERENCE...............1
WHAT IS JAVA FOR RETAIL POS?.........................................................................................1
BENEFITS................................................................................................................................1
DEPENDENCIES.......................................................................................................................2
RELATIONSHIP TO OPOS .......................................................................................................2
APPENDIX OVERVIEW ............................................................................................................3
ARCHITECTURAL OVERVIEW .................................................................................................3
ARCHITECTURAL COMPONENTS.............................................................................................4
Additional Layers and APIs ............................................................................................5
JavaPOS Development Environment ..............................................................................5
DEVICE BEHAVIOR MODELS ..................................................................................................6
INTRODUCTION TO PROPERTIES, METHODS, AND EVENTS ....................................................6
DEVICE INITIALIZATION AND FINALIZATION .........................................................................7
Initialization ....................................................................................................................7
Finalization .....................................................................................................................7
Summary .........................................................................................................................8
DEVICE SHARING MODEL ......................................................................................................9
DATA TYPES ........................................................................................................................11
EXCEPTIONS .........................................................................................................................12
ErrorCode .....................................................................................................................13
ErrorCodeExtended ......................................................................................................14
EVENTS ................................................................................................................................15
Registering for Events...................................................................................................17
Event Delivery...............................................................................................................17
JavaPOS Event Registration Sequence Diagram .........................................................18
DEVICE INPUT MODEL .........................................................................................................19
Error Handling .............................................................................................................20
Miscellaneous ...............................................................................................................21
DEVICE OUTPUT MODELS....................................................................................................22
Error Handling........................................................................................................23
Miscellaneous .........................................................................................................23
Model ............................................................................................................................24
Properties......................................................................................................................25
DEVICE STATES ...................................................................................................................29
THREADS ..............................................................................................................................30

Table of Contents xv
VERSION HANDLING ............................................................................................................30

CLASSES AND INTERFACES ..................................................................................................31
SYNOPSIS .............................................................................................................................31
Application ....................................................................................................................31
Device Control ..............................................................................................................32
Device Service...............................................................................................................32
Helper Classes ..............................................................................................................33
SAMPLE CLASS AND INTERFACE HIERARCHIES ...................................................................34
Application Sample .......................................................................................................34
Device Control Sample .................................................................................................34
Scanner ...................................................................................................................34
POSPrinter ..............................................................................................................35
Device Service Sample ..................................................................................................35
“MyScannerService” ..............................................................................................35
“MyPrinterService” ................................................................................................36
SAMPLE APPLICATION CODE ...............................................................................................37
PACKAGE STRUCTURE .........................................................................................................38
jpos ................................................................................................................................39
jpos.events .....................................................................................................................43
jpos.services ..................................................................................................................43
DEVICE CONTROLS ..............................................................................................................46
DEVICE CONTROL RESPONSIBILITIES ..................................................................................46
DEVICE SERVICE MANAGEMENT .........................................................................................47
jpos.config/loader (JCL) and JavaPOS Entry Registry (JER)......................................47
jpos.config/loader (JCL) Characteristics .....................................................................47
PROPERTY AND METHOD FORWARDING ..............................................................................50
EVENT HANDLING................................................................................................................51
Event Listeners and Event Delivery ..............................................................................51
Event Callbacks ............................................................................................................52
DEVICE CONTROL VERSION HANDLING ..............................................................................53
DEVICE SERVICES ................................................................................................................55
DEVICE SERVICE RESPONSIBILITIES ....................................................................................55
PROPERTY AND METHOD PROCESSING ................................................................................55
EVENT GENERATION ............................................................................................................56
PHYSICAL DEVICE ACCESS ..................................................................................................57
API MAPPING RULES ...........................................................................................................57
JAVAPOS COMPONENT DESCRIPTIONS................................................................................58
SECTION 1: JAVAPOS DATA TYPES ....................................................................................59
Data Types ....................................................................................................................59
SECTION 2: JAVAPOS INTERFACE DESCRIPTIONS ...............................................................60
JAVAPOS COMMON PROPERTIES, METHODS, AND EVENTS ................................................61
Common Methods .........................................................................................................62
JavaPOS Class Names..................................................................................................63
Properties......................................................................................................................64
Methods.........................................................................................................................73
Events ............................................................................................................................83
JAVAPOS: CASH DRAWER...................................................................................................89
Java Command Examples .............................................................................................89
Cash Drawer Operations Properties, Methods, and Events.........................................90
Cash Drawer Terminating Methods .............................................................................90
JAVAPOS: MICR.................................................................................................................91

xvi Table of Contents
Java Command Examples .............................................................................................91

MICR Terminating Methods .........................................................................................93
SECTION 3: TECHNICAL DETAILS ........................................................................................94
OPOS to JavaPOS - API Mapping Rules .....................................................................94
Data Types..............................................................................................................94
Property and Method Names ..................................................................................95
Events .....................................................................................................................95
Constants ................................................................................................................95
API DEVIATIONS..................................................................................................................96
MAPPING OF CHARACTERSET ..............................................................................................97
HANDLING BINARY DATA INSIDE STRINGS .........................................................................98
SECTION 4: JAVAPOS CHANGE HISTORY ............................................................................99
Release 1.3 ....................................................................................................................99
Release 1.4 ..................................................................................................................100
Release 1.5 ..................................................................................................................101
Release 1.6 ..................................................................................................................103
Release 1.7 ..................................................................................................................105
APPENDIX C
POS FOR .NET IMPLEMENTATION REFERENCE .........................................................1
WHAT IS “POS FOR .NET?” ..................................................................................................1
OVERVIEW OF POS FOR .NET ..............................................................................................2
POS FOR .NET DEFINITIONS .................................................................................................4
Device Class....................................................................................................................4
Service Object or SO.......................................................................................................4
KEY POS FOR .NET FEATURES .............................................................................................4
.NET Interfaces for POS Peripherals .............................................................................4
Base Classes for Service Objects....................................................................................4
Basic Classes for Service Objects...................................................................................4
Device Category Support Level ......................................................................................5
Plug and Play..................................................................................................................6
Standardized Setup..........................................................................................................6
Device Enumeration........................................................................................................6
Software-Based Device Statistics....................................................................................6
Support for OPOS (COM-Based) Service Objects .........................................................6
Service Object Verification Program..............................................................................7
KEY PROGRAMMING CONSTRUCT DIFFERENCES FROM OPOS .............................................7
Naming Conventions .......................................................................................................7
Enumerations ..................................................................................................................7
Structures ......................................................................................................................25
CashCount Structure...............................................................................................25
CashCounts Structure .............................................................................................25
CashUnits Structure................................................................................................26
DirectIOData Structure...........................................................................................26
FiscalDataItem Structure ........................................................................................26
TotalsFileInfo Structure..........................................................................................27
VatInfo Structure ....................................................................................................27
VideoMode Structure .............................................................................................28
Complete Class Libraries Provided..............................................................................28
Return Values................................................................................................................29
Returning Properties.....................................................................................................29
Returning Lists ..............................................................................................................29

Table of Contents xvii
KEY PARAMETER DIFFERENCES ..........................................................................................31

KEY PROPERTY SIGNATURE DIFFERENCES ..........................................................................32
MORE INFORMATION ...........................................................................................................32
POSEXPLORER API ..............................................................................................................33
PosExplorer Properties ................................................................................................33
PosExplorer Methods....................................................................................................34
PosExplorer Events.......................................................................................................36
Global Configuration....................................................................................................37
SERVICE OBJECT REGISTRY .................................................................................................37
CONSUMING SERVICE OBJECTS ...........................................................................................37
OPOS ............................................................................................................................37
POS for .NET ................................................................................................................38
WRITING SERVICE OBJECTS ................................................................................................38
POS for .NET ................................................................................................................38
STATUS, STATE MODEL, AND EXCEPTIONS .........................................................................39
StatusUpdateEvent........................................................................................................39
ControlState ..................................................................................................................39
Exceptions .....................................................................................................................39
EVENTS ................................................................................................................................42
INPUT MODEL ......................................................................................................................43
OUTPUT MODEL ...................................................................................................................45
Asynchronous Output ...................................................................................................45
Model ............................................................................................................................46
POWER REPORTING PROPERTIES..........................................................................................47
POS FOR .NET COMPONENT DESCRIPTIONS .......................................................................50
POS for .NET Data Types.............................................................................................50
POS for .NET Common Properties, Methods, Events, Statistics, and Constants .........51
Common Properties ................................................................................................51
Common Methods ..................................................................................................52
Common Events .....................................................................................................52
Common Statistics..................................................................................................53
Common Constants ................................................................................................53
COMMON PROPERTIES .........................................................................................................54
COMMON METHODS.............................................................................................................61
COMMON EVENTS ................................................................................................................74
POS FOR .NET VS. UNIFIEDPOS MEMBERS .......................................................................75
INTERIM PROCEDURE AVAILABLE FOR LEGACY OPOS SERVICES...
SHIM CODE USAGE .............................................................................................................76
ARCHITECTURE STRUCTURES ..............................................................................................77
METHOD OF IMPLEMENTATION............................................................................................78
Shim Code Naming rules ..............................................................................................78
Shim Method Redefinition Rules ...................................................................................79
Shim Code Rules For In/Out Parameters .....................................................................79
METHOD OF ADMINISTRATION ............................................................................................80
SHIM CODE FILE NAMES .....................................................................................................80
Shim file list...................................................................................................................81
CLASS DIAGRAMS ................................................................................................................82

xviii Table of Contents
Interface Class ..............................................................................................................82

Basic Class....................................................................................................................82
Shim Class.....................................................................................................................83
Service Class.................................................................................................................83
APPENDIX D
XMLPOS — XML POS MAPPING REFERENCE ..............................................................1
OVERVIEW .............................................................................................................................1
XMLPOS requirements ...................................................................................................1
Out of Scope ....................................................................................................................1
REFERENCED DOCUMENTS ....................................................................................................2
TAXONOMY FOR CONVERSION FROM UNIFIEDPOS TO XML ...............................................2
XMLPOS ARCHITECTURE OVERVIEW ..................................................................................2
UnifiedPOS XML Requirements .....................................................................................2
Converting UnifiedPOS Methods and Events ..........................................................2
UnifiedPOS Synchronous XML Communications ..........................................................3
UnifiedPOS Asynchronous XML Communications ........................................................3
XMLPOS Common Properties Schema Architecture ..............................................4
XMLPOS Common Methods Schema Architecture ................................................4
Single Commands.....................................................................................................5
Command Sets..........................................................................................................5
UNIFIEDPOS XML ERRORS ..................................................................................................7
Device Error Codes and Message Severity Codes .........................................................7
Message Severity Codes...........................................................................................7
Standard Error Codes to Severity Codes........................................................................8
Standard Status Codes to Severity Codes .......................................................................9
UnifiedPOS Synchronous XML Errors.........................................................................10
UnifiedPOS Asynchronous XML Errors.......................................................................10
XMLPOS COMMON EVENTS ...............................................................................................11
UnifiedPOS Synchronous XML Events.........................................................................12
UnifiedPOS Asynchronous XML Events.......................................................................12
Single Events ..........................................................................................................12
Event Sets ...............................................................................................................12
XMLPOS COMMON PROPERTIES ........................................................................................14
XMLPOS COMMON DATA ..................................................................................................15
ARTS COMMON DATA ........................................................................................................16
UNIFIEDPOS DEVICES .........................................................................................................17
Belt ................................................................................................................................17
Belt Example ..........................................................................................................17
Belt Properties ........................................................................................................18
Belt Methods ..........................................................................................................19
Belt Events..............................................................................................................20
Device Error Codes to Message Severity Codes ....................................................20
Status Codes to Message Severity Codes ...............................................................20
Device Specific Status Messages ...........................................................................21
Bill Acceptor .................................................................................................................21
Bill Acceptor Example ...........................................................................................21
Bill Acceptor Properties .........................................................................................23
Bill Acceptor Methods ...........................................................................................24
Bill Acceptor Events...............................................................................................25
Device Specific Status Messages ...........................................................................26
Bill Dispenser................................................................................................................26
Bill Dispenser Example ..........................................................................................26
Bill Dispenser Properties ........................................................................................27

Table of Contents xix
Bill Dispenser Methods ..........................................................................................28

Bill Dispenser Events .............................................................................................29
Device Specific Stati ..............................................................................................30
Biometrics .....................................................................................................................30
Biometrics Example ...............................................................................................30
Biometrics Properties .............................................................................................32
Biometrics Methods................................................................................................33
Biometrics Events...................................................................................................34
Bump Bar ......................................................................................................................35
Bump Bar Example ................................................................................................35
Bump Bar Properties ..............................................................................................36
Bump Bar Methods.................................................................................................37
Bump Bar Events....................................................................................................38
Cash Changer ...............................................................................................................39
Cash Changer Example ..........................................................................................39
Cash Changer Properties ........................................................................................41
Cash Changer Methods...........................................................................................42
Cash Changer Events..............................................................................................43
Cash Drawer.................................................................................................................46
Cash Drawer Example ............................................................................................46
Cash Drawer Properties ..........................................................................................47
Cash Drawer Methods ............................................................................................48
Cash Drawer Events ...............................................................................................49
CAT ...............................................................................................................................50
CAT Example .........................................................................................................50
CAT Properties .......................................................................................................51
CAT Methods .........................................................................................................52
CAT Events ............................................................................................................53
Check Scanner ..............................................................................................................56
Check Scanner Example.........................................................................................56
Check Scanner Properties.......................................................................................59
Check Scanner Methods .........................................................................................60
Check Scanner Events ............................................................................................61
Coin Acceptor ...............................................................................................................64
Coin Acceptor Example..........................................................................................64

xx Table of Contents
Coin Acceptor Properties........................................................................................65

Coin Acceptor Methods..........................................................................................66
Coin Acceptor Events.............................................................................................67
Coin Dispenser..............................................................................................................69
Coin Dispenser Example ........................................................................................69
Coin Dispenser Properties ......................................................................................69
Coin Dispenser Methods ........................................................................................70
Coin Dispenser Events ...........................................................................................71
Electronic Journal ........................................................................................................73
Electronic Journal Example....................................................................................73
Electronic Journal Properties..................................................................................74
Electronic Journal Methods ....................................................................................75
Electronic Journal Events .......................................................................................76
Electronic Value Reader / Writer .................................................................................78
Electronic Value Reader / Writer Example ............................................................78
Electronic Value Reader / Writer Properties ..........................................................80
Electronic Value Reader / Writer Methods ............................................................81
Electronic Value Reader / Writer Events ...............................................................82
Fiscal Printer ................................................................................................................83
Fiscal Printer Example ...........................................................................................83
Fiscal Printer Properties .........................................................................................87
Fiscal Printer Methods............................................................................................88
Fiscal Printer Events...............................................................................................89
Status Codes to Message Severity Codes .............................................................103
Device Specific Stati ............................................................................................103
Gate.............................................................................................................................104
Gate Example .......................................................................................................104
Gate Properties .....................................................................................................104
Gate Methods........................................................................................................105
Gate Events...........................................................................................................106
Device Error Codes to Message Severity Codes ..................................................106
Device Specific Status Messages .........................................................................106
Hard Totals .................................................................................................................107
Hard Totals Example ............................................................................................107
Hard Totals Properties ..........................................................................................107
Hard Totals Methods ............................................................................................108
Hard Totals Events ...............................................................................................109
Image Scanner ............................................................................................................113

Table of Contents xxi
Image Scanner Example .......................................................................................113

Image Scanner Properties .....................................................................................115
Image Scanner Methods .......................................................................................116
Image Scanner Events ..........................................................................................117
Item Dispenser ............................................................................................................118
Item Dispenser Example.......................................................................................118
Item Dispenser Properties.....................................................................................119
Item Dispenser Methods.......................................................................................120
Item Dispenser Events ..........................................................................................121
Keylock........................................................................................................................122
Keylock Example .................................................................................................122
Keylock Properties ...............................................................................................123
Keylock Methods..................................................................................................124
Keylock Events.....................................................................................................125
Lights...........................................................................................................................126
Lights Example.....................................................................................................126
Lights Properties...................................................................................................127
Lights Methods .....................................................................................................128
Lights Events ........................................................................................................129
Line Display ................................................................................................................130
Line Display Example ..........................................................................................130
Line Display Properties ........................................................................................131
Line Display Methods ..........................................................................................132
Line Display Events .............................................................................................133
MICR...........................................................................................................................136
MICR Example.....................................................................................................136
MICR Properties...................................................................................................137
MICR Methods .....................................................................................................138
MICR Events ........................................................................................................139
Motion Sensor .............................................................................................................141
Motion Sensor Example .......................................................................................141
Motion Sensor Properties .....................................................................................141
Motion Sensor Methods .......................................................................................142
Motion Sensor Events...........................................................................................143

xxii Table of Contents
MSR.............................................................................................................................145
MSR Example ......................................................................................................145
MSR Properties ....................................................................................................146
MSR Methods.......................................................................................................147
MSR Events..........................................................................................................148
PIN Pad.......................................................................................................................150
PIN Pad Example .................................................................................................150
PIN Pad Properties ...............................................................................................152
PIN Pad Methods..................................................................................................153
PIN Pad Events.....................................................................................................154
Point Card Reader/Writer...........................................................................................156
Point Card Reader Example .................................................................................156
Point Card Reader Properties ...............................................................................158
Point Card Reader Methods..................................................................................159
Point Card Reader Events.....................................................................................160
POS Keyboard ............................................................................................................163
POS Keyboard Example.......................................................................................163
POS Keyboard Properties.....................................................................................163
POS Keyboard Methods .......................................................................................164
POS Keyboard Events ..........................................................................................165
POS Power..................................................................................................................166
POS Power Example ............................................................................................166
POS Power Properties ..........................................................................................167
POS Power Methods.............................................................................................168
POS Power Events................................................................................................169
POS Printer.................................................................................................................171
POS Printer Example............................................................................................171
POS Printer Properties..........................................................................................173
POS Printer Methods ............................................................................................174
POS Printer Events ...............................................................................................175
Remote Order Display ................................................................................................185
Remote Order Display Example...........................................................................185
Remote Order Display Properties.........................................................................186
Remote Order Display Methods ...........................................................................187
Remote Order Display Events ..............................................................................188

Table of Contents xxiii

RFID Scanner .............................................................................................................191
RFID Scanner Example ........................................................................................191
RFID Scanner Properties ......................................................................................194
RFID Scanner Methods ........................................................................................195
RFID Scanner Events ...........................................................................................196
Scale ............................................................................................................................197
Scale Example ......................................................................................................197
Scale Properties ....................................................................................................199
Scale Methods ......................................................................................................200
Scale Events..........................................................................................................201
Scanner Device ...........................................................................................................203
Scanner Device Example......................................................................................203
Scanner Properties ................................................................................................205
Scanner Methods ..................................................................................................206
Scanner Events .....................................................................................................207
Signature Capture ......................................................................................................208
Signature Capture Example ..................................................................................208
Signature Capture Properties ................................................................................210
Signature Capture Methods ..................................................................................211
Signature Capture Events .....................................................................................212
Smart Card Reader .....................................................................................................213
Smart Card Reader Example ................................................................................213
Smart Card Reader Properties ..............................................................................216
Smart Card Reader Methods.................................................................................217
Smart Card Reader Events....................................................................................218
Tone Indicator.............................................................................................................220
Tone Indicator Example .......................................................................................220
Tone Indicator Properties .....................................................................................221
Tone Indicator Methods........................................................................................222
Tone Indicator Events...........................................................................................223
NAFEM PROTOCOL ...........................................................................................................225
Administration Enterprise Group ...............................................................................225
Asset Management Enterprise Group .........................................................................226
Bulk Transfer Enterprise Group .................................................................................227
Clock Calendar Enterprise Group..............................................................................228
Inventory Management Enterprise Group ..................................................................229

xxiv Table of Contents
Maintenance Enterprise Group ..................................................................................230

Monitor Enterprise Group ..........................................................................................231
Notification Enterprise Group ....................................................................................232
Security Enterprise Group ..........................................................................................233
Utility Enterprise Group .............................................................................................234
DISTRIBUTED FILES ...........................................................................................................235
GLOSSARY..........................................................................................................................236
APPENDIX E
CHANGE HISTORY ................................................................................................................1
RELEASE VERSION 1.4 ...........................................................................................................1
RELEASE VERSION 1.5 ...........................................................................................................1
RELEASE VERSION 1.6 ...........................................................................................................3
RELEASE VERSION 1.7 ...........................................................................................................5
RELEASE VERSION 1.8 .........................................................................................................11
RELEASE VERSION 1.9 .........................................................................................................14
RELEASE VERSION 1.10 .......................................................................................................16
RELEASE VERSION 1.11 .......................................................................................................19
RELEASE VERSION 1.12 .......................................................................................................23
APPENDIX F
ADDITIONAL SOFTWARE REFERENCES........................................................................1
UML REFERENCES ................................................................................................................1
Web Location References................................................................................................1
Reading Material References..........................................................................................1
APPENDIX G
ADDITIONAL HARDWARE REFERENCES ......................................................................1
USB PLUSPOWER CONNECTOR .............................................................................................1
Overview .........................................................................................................................1
Host Side Connector .......................................................................................................1
Cable ...............................................................................................................................2
Peripheral Side Connection ............................................................................................2
Web Location References - USB connector EIA approval .............................................2
Reading Material References..........................................................................................3
ARTS Standard Endorsement..........................................................................................3
APPENDIX H
DEPRECATION HISTORY ....................................................................................................1
APPENDIX I
SYSTEMS MANAGEMENT INFORMATION.....................................................................1
WHAT IS “SYSTEMS MANAGEMENT?”...................................................................................1
HOW IS UNIFIEDPOS INVOLVED IN SYSTEMS MANAGEMENT?.............................................1
UNIFIEDPOS DEVICE INFORMATION REPORTING MODEL .....................................................3
CIM Structure .................................................................................................................3
ARCHITECTURAL OVERVIEW .................................................................................................6
Exclusive Use ..................................................................................................................6
Multiple Instances...........................................................................................................6
Limited Lifetime ..............................................................................................................6
Solution Creation ............................................................................................................6
UTILIZED CIM DATA TYPES..................................................................................................9
COMMON PROPERTIES, METHODS, AND EVENTS.................................................................10
Common Methods .........................................................................................................11
PROPERTIES ..........................................................................................................................11

Table of Contents xxv
Belt ................................................................................................................................13
Belt Class Diagram.................................................................................................15
Bill Acceptor .................................................................................................................16
Bill Acceptor Class Diagram..................................................................................18
Bill Dispenser................................................................................................................19
Bill Dispenser Class Diagram ................................................................................21
Biometrics .....................................................................................................................22
Biometrics Class Diagram ......................................................................................23
Bump Bar ......................................................................................................................24
Bump Bar Class Diagram .......................................................................................26
Cash Changer ...............................................................................................................27
Cash Changer Class Diagram .................................................................................29
Cash Drawer.................................................................................................................30
Cash Drawer Class Diagram...................................................................................32
Credit Authorization Terminal......................................................................................33
Credit Authorization Terminal Class Diagram.......................................................35
Check Scanner ..............................................................................................................36
Check Scanner Class Diagram ...............................................................................38
Coin Acceptor ...............................................................................................................39
Coin Acceptor Class Diagram ................................................................................41
Coin Dispenser..............................................................................................................42
Coin Dispenser Class Diagram...............................................................................44
Electronic Journal ........................................................................................................45
Electronic Journal Class Diagram ..........................................................................47
Electronic Value Reader/Writer ...................................................................................48
Electronic Value Reader/Writer Class Diagram.....................................................49
Fiscal Printer ................................................................................................................50
Fiscal Printer Class Diagram ..................................................................................53
Gate...............................................................................................................................54
Gate Class Diagram ................................................................................................55
Hard Totals ...................................................................................................................56
Hard Totals Class Diagram.....................................................................................58
Image Scanner ..............................................................................................................59
Image Scanner Class Diagram................................................................................60
Item Dispenser ..............................................................................................................61
Item Dispenser Class Diagram ...............................................................................63
Keylock..........................................................................................................................64
Keylock Class Diagram ..........................................................................................66
Light ..............................................................................................................................67
Light Class Diagram...............................................................................................69
Line Display ..................................................................................................................70
Line Display Class Diagram...................................................................................73
MICR.............................................................................................................................74
MICR Class Diagram .............................................................................................76
Motion Sensor ...............................................................................................................77
Motion Sensor Class Diagram................................................................................78
MSR...............................................................................................................................79
MSR Class Diagram ...............................................................................................81
PINPad..........................................................................................................................82
PINPad Class Diagram ...........................................................................................83
Point Card Reader/Writer.............................................................................................84
Point Card Reader/Writer Class Diagram ..............................................................87
POS Keyboard ..............................................................................................................88
POS Keyboard Class Diagram ...............................................................................90
Properties (UML attributes)....................................................................................91

xxvi Table of Contents
Methods (UML operations) ....................................................................................92

POS Power....................................................................................................................93
POS Power Class Diagram .....................................................................................94
POS Printer...................................................................................................................95
POS Printer Class Diagram ..................................................................................100
Remote Order Display Class Diagram .................................................................103
RFID Scanner .............................................................................................................104
RFID Scanner Class Diagram...............................................................................105
Remote Order Display Class Diagram .................................................................108
Scale ............................................................................................................................109
Scale Class Diagram.............................................................................................111
Methods (UML operations) ..................................................................................112
Scanner .......................................................................................................................113
Scanner Class Diagram.........................................................................................116
Properties (UML attributes)..................................................................................117
Signature Capture .......................................................................................................121
Signature Capture Class Diagram.........................................................................123
Smart Card Reader/Writer..........................................................................................124
Smart Card Reader/Writer Class Diagram ...........................................................126
Tone Indicator.............................................................................................................127
Tone Indicator Class Diagram..............................................................................129
TECHNICAL DETAILS .........................................................................................................130
MOF Files ...................................................................................................................130
APPENDIX J
DEVICE STATISTICS .............................................................................................................1
DEVICE CATEGORY NAMES ...................................................................................................1
COMMON STATISTICS FOR ALL DEVICE CATEGORIES ...........................................................3
XML DEFINITIONS FOR BIOMETRICS DEVICE STATISTICS.....................................................3
XML DEFINITIONS FOR BUMPBAR DEVICE STATISTICS ........................................................3
XML DEFINITIONS FOR CASHDRAWER DEVICE STATISTICS .................................................4
XML DEFINITIONS FOR CHECKSCANNER DEVICE STATISTICS ..............................................4
XML DEFINITIONS FOR ELECTRONICJOURNAL DEVICE STATISTICS .....................................4
XML DEFINITIONS FOR FISCALPRINTER DEVICE STATISTICS ...............................................4
XML DEFINITIONS FOR IMAGESCANNER DEVICE STATISTICS ..............................................5
XML DEFINITIONS FOR KEYLOCK DEVICE STATISTICS.........................................................5
XML DEFINITIONS FOR LINEDISPLAY DEVICE STATISTICS...................................................6
XML DEFINITIONS FOR MICR DEVICE STATISTICS ..............................................................6
XML DEFINITIONS FOR MOTIONSENSOR DEVICE STATISTICS ..............................................6
XML DEFINITIONS FOR MSR DEVICE STATISTICS ................................................................6
XML DEFINITIONS FOR PINPAD DEVICE STATISTICS ...........................................................7
XML DEFINITIONS FOR POSKEYBOARD DEVICE STATISTICS ...............................................7
XML DEFINITIONS FOR POSPRINTER DEVICE STATISTICS ...................................................7
XML DEFINITIONS FOR RFIDSCANNER DEVICE STATISTICS ................................................8
XML DEFINITIONS FOR SCALE DEVICE STATISTICS ..............................................................8
XML DEFINITIONS FOR SCANNER DEVICE STATISTICS .........................................................9
XML DEFINITIONS FOR SIGNATURECAPTURE DEVICE STATISTICS .......................................9
XML DEFINITIONS FOR TONEINDICATOR DEVICE STATISTICS..............................................9

List of Figures
Synchronous Communications .............................................................................................3
XML Common Properties Schema Architecture Sample ....................................................4
XML Common Methods Schema Architecture Sample .......................................................4
Asynchronous Example ........................................................................................................5
Asynchronous with Intelligent Controller Example .............................................................5
UnifiedPOS XML Events ...................................................................................................11
UnifiedPOS XMLPOS Common Properties ......................................................................14
UnifiedPOS XMLPOS Common Data ...............................................................................15
ARTS Common Data .........................................................................................................16
“Device Category” Domain View ......................................................................................17
Belt Properties Domain View .............................................................................................18
Belt Methods Domain View ...............................................................................................19
Belt Events Domain View ..................................................................................................20
Bill Acceptor Properties Domain View ..............................................................................23
Bill Acceptor Methods Domain View ................................................................................24
Bill Acceptor Events Domain View ...................................................................................25
Bill Dispenser Properties Domain View ............................................................................27
Bill Dispenser Methods Domain View ..............................................................................28
Bill Dispenser Events Domain View ..................................................................................29
Biometrics Properties Domain View ..................................................................................32
Biometric Methods Domain View .....................................................................................33
Biometrics Events Domain View .......................................................................................34
Bump Bar Properties Domain View ...................................................................................36
Bump Bar Methods Domain View .....................................................................................37
Bump Bar Events Domain View ........................................................................................38
Cash Changer Properties Domain View .............................................................................41
Cash Changer Methods Domain View ...............................................................................42
Cash Changer Events Domain View ..................................................................................43
Cash Drawer Properties Domain View ..............................................................................47
Cash Drawer Methods Domain View ................................................................................48
Cash Drawer Events Domain View ....................................................................................49
CAT Properties Domain View ...........................................................................................51
CAT Methods Domain View .............................................................................................52
CAT Events Domain View .................................................................................................53
Check Scanner Properties Domain View ...........................................................................59
Check Scanner Methods Domain View .............................................................................60
Check Scanner Events Domain View ................................................................................61
Coin Acceptor Properties Domain View ............................................................................65
Coin Acceptor Methods Domain View ..............................................................................66
Coin Acceptor Events Domain View .................................................................................67
Coin Dispenser Properties Domain View ..........................................................................69
Coin Dispenser Methods Domain View .............................................................................70
Coin Dispenser Events Domain View ................................................................................71
Electronic Journal Properties Domain View ......................................................................74
Electronic Journal Methods Domain View ........................................................................75
Electronic Journal Events Domain View ...........................................................................76
Electronic Value Reader / Writer Properties Domain View ..............................................80
Electronic Value Reader / Writer Methods Domain View .................................................81
Electronic Value Reader / Writer Events Domain View ....................................................82
Fiscal Printer Properties Domain View ..............................................................................87
Fiscal Printer Methods Domain View ................................................................................88
Fiscal Printer Events Domain View ...................................................................................89
Gate Properties Domain View ..........................................................................................104
Gate Methods Domain View ............................................................................................105
Gate Events Domain View ...............................................................................................106
Hard Totals Properties Domain View ..............................................................................107
Hard Totals Methods Domain View ................................................................................108
Hard Totals Events Domain View ....................................................................................109
Image Scanner Properties Domain View .........................................................................115
Image Scanner Methods Domain View ............................................................................116
Image Scanner Events Domain View ...............................................................................117
Item Dispenser Properties Domain View .........................................................................119
ii List of Figures
Item Dispenser Methods Domain View ...........................................................................120

Item Dispenser Events Domain View ..............................................................................121
Keylock Properties Domain View ....................................................................................123
Keylock Methods Domain View ......................................................................................124
Keylock Events Domain View .........................................................................................125
Lights Properties Domain View .......................................................................................127
Lights Methods Domain View .........................................................................................128
Lights Events Domain View ............................................................................................129
Line Display Properties Domain View ............................................................................131
Line Display Methods Domain View ...............................................................................132
Line Display Events Domain View ..................................................................................133
MICR Properties Domain View .......................................................................................137
MICR Methods Domain View .........................................................................................138
MICR Events Domain View ............................................................................................139
Motion Sensor Properties Domain View ..........................................................................141
Motion Sensor Methods Domain View ............................................................................142
Motion Sensor Events Domain View ...............................................................................143
MSR Properties Domain View .........................................................................................146
MSR Methods Domain View ...........................................................................................147
MSR Events Domain View ..............................................................................................148
PIN Pad Properties Domain View ....................................................................................152
PIN Pad Methods Domain View ......................................................................................153
PIN Pad Events Domain View .........................................................................................154
Point Card RW Properties Domain View .........................................................................158
Point Card RW Methods Domain View ...........................................................................159
Point Card RW Events Domain View ..............................................................................160
POS Keyboard Properties Domain View .........................................................................163
POS Keyboard Methods Domain View ...........................................................................164
POS Keyboard Events Domain View ..............................................................................165
POS Power Properties Domain View ...............................................................................167
POS Power Methods Domain View .................................................................................168
POS Power Events Domain View ....................................................................................169
POS Printer Properties Domain View ..............................................................................173
POS Printer Methods Domain View ................................................................................174
POS Printer Events Domain View ...................................................................................175
Remote Order Display Properties Domain View .............................................................186
Remote Order Display Methods Domain View ...............................................................187
Remote Order Display Events Domain View ..................................................................188
RFID Scanner Properties Domain View ..........................................................................194
RFID Scanner Methods Domain View ............................................................................195
RFID Scanner Events Domain View ................................................................................196
Scale Properties Domain View .........................................................................................199
Scale Methods Domain View ...........................................................................................200
Scale Events Domain View ..............................................................................................201
Scanner Properties Domain View ....................................................................................205
Scanner Methods Domain View .......................................................................................206
Scanner Events Domain View ..........................................................................................207
Signature Capture Properties Domain View ....................................................................210
Signature Capture Methods Domain View ......................................................................211
Signature Capture Events Domain View ..........................................................................212
Smart Card Reader Properties Domain View ...................................................................216
Smart Card Reader Methods Domain View .....................................................................217
Smart Card Reader Events Domain View ........................................................................218
Tone Indicator Properties Domain View ..........................................................................221
Tone Indicator Methods Domain View ............................................................................222
Tone Indicator Events Domain View ...............................................................................223
Administrative Enterprise Group Domain View ..............................................................225
Asset Management Enterprise Group Domain View .......................................................226
Bulk Transfer Enterprise Group Domain View ...............................................................227
Clock Calendar Enterprise Group Domain View .............................................................228
Inventory Management Enterprise Group Domain View ................................................229
Maintenance Enterprise Group Domain View .................................................................230
Monitor Enterprise Group Domain View .........................................................................231
Notification Enterprise Group Domain View ..................................................................232
Security Enterprise Group Domain View ........................................................................233
Utility Enterprise Group Domain View ...........................................................................234

I N T R O D U C T I O N A N D A R C H I T E C T U R E
UnifiedPOS Architecture for Retail
What Is UnifiedPOS?
UnifiedPOS is the acronym for Unified Point of Service. It is an architectural

specification for application interfaces to point-of-service devices that are used in
the retail environment. This standard is both operating system independent and
language neutral and defines:
• An architecture for application interface to retail devices.
• A set of retail device behaviors sufficient to support a range of POS solutions.
The UnifiedPOS standard will include:

• The UnifiedPOS Retail Peripheral Architecture overview.
• Text descriptions of the interface to the functions of the device.
• UML terminology and diagrams for each device category, to describe:
• Relationships between classes/interfaces and objects in the system.
• Basis for creating C++, Java, IDL, or other OO technology to implement the
UML design.
• Operational characteristics and details for implementations which are
compliant to the UnifiedPOS architecture. These were added in the
Appendices for UnifiedPOS starting in Version 1.6. As new Implementations
become available, additional Appendices will be added in future versions of
the standard.
The UnifiedPOS standard will not include:

• Specific language API specifications.
• Complete software components. Hardware providers, software providers, or
third-party providers develop and distribute these components.
• Certification mechanism; this must be handled by individual language
standard committees (such as the OLE for Retail POS (OPOS), POS for .NET,
and Java for Retail POS (JavaPOS) committees).
34 Introduction and Architecture
About This Documentation Updated in Release 1.12

Since the release of UnifiedPOS Version 1.4, the Retail Standards’ committees
had been maintaining three separate standard documents, OPOS, JavaPOS and
UnifiedPOS. The architecture and device characteristics are identical in each of
these documents. The addition of new device categories and/or enhancements to
existing chapters required consultation and agreement on the technical content for
the each of the separate standards. However, in addition to that technical work,
there is a heavy administrative burden in generating the correct documentation
for three different versions of the standard’s specification. That process was
inherently error prone in that the same changes had to be maintained in multiple
documents. Confusion has resulted in cases where differences have inadvertently
appeared in the documentation.
In order to simplify the process and bring a higher quality of review to ongoing
modifications of the documentation, the UnifiedPOS standard committee made a
change in the process for documenting its requirements. Beginning with
UnifiedPOS Version 1.6, only the UnifiedPOS document was updated and the
structure of the documentation was changed. The main body of the
documentation includes the abstracted generic description of all device categories
plus additional general design and utilization guidelines. Specific reference
platform requirements are now found in the included Appendices that outline the
implementation information for each of the specific existing implementations,
such as OPOS, JavaPOS and POS For Dot Net. (Note: OPOS-J, the POS
Standards body from Japan, has and plans to continue to maintain a translated
Japanese version of the OPOS documentation for their developer community.)
The documentation is arranged in such a fashion that allows the new user to
gather a general education about the UnifiedPOS Standard by reading the
“Introduction and Architecture” section. This section is designed to give an
overview of the material covered in the entire standard and provide an outline of
the design features that must be adhered to for a developer to implement the
standard. For a first time reader, this section should be read and understood, as it
will make the remaining chapters and appendices more beneficial. For a familiar
user, this section may serve as a “fall-back” reference for clarification of the
requirements when developing a Device Service or usage of the Device Services
by an Application.
Following the “Introduction and Architecture”, “Chapter 1” outlines the
Properties, Methods, and Events that are Common to all peripheral devices. It is
important to understand this section and make reference to it when questions arise
on the common functionality that apply to all device classes.
The following Chapters define each of the POS peripheral devices that are
covered in the standard. The specific Properties, Methods, and Events that are
peculiar to the peripheral are defined. Any additional helpful information relevant
to the POS peripheral are also included. As new POS peripherals are added a new
chapter will be added to describe the devices unique requirements.

What Is UnifiedPOS?: About This Documentation 35
Following the Chapters describing the POS peripheral devices, Appendices are
included that outline specific details on implementation dependencies for each of
the supported Operating Systems and/or language specific development
platforms.
“Appendix A” includes the definition, goals, and deliverables for OPOS. There
are explanations for the input/output and device sharing for Microsoft’s COM
model for the operation of the interface. Event and error handling unique to this
implementation is described. It concludes with a version change history that
guides the user in understanding the evolution of the OPOS implementation of
the standard.
“Appendix B” includes the definition, goals, and deliverables for JavaPOS.
There are explanations for the input/output and device sharing for the Java model
for the operation of the interface. Event and error handling unique to this
implementation is included. It also concludes with a version change history that is
helpful to the user to understand the evolution of the JavaPOS implementation
requirements.
“Appendix C” includes the definition, goals, and deliverables for POS for .NET.
There are explanations for the input/output and device sharing for Microsoft’s
.NET model for the operation of the interface and the differences from the OPOS
COM architecture that affect implementation. Event and error handling unique to
this implementation are described. It also includes a version change history
section and brief clarifications of the design philosophy.
“Appendix D” is included to provide information on the usage of XML for
peripheral message mapping. Future versions of the UnifiedPOS standard will
evolve to a greater dependence upon XML as the command and inter operability
infrastructure of choice. There is increasing interest and focus on using XML for
communicating with peripheral devices. It opens up many new possibilities for
creating Device Services that, when coupled with Universal Plug and Play
hardware connection technologies such as USB, will provide for true language
and operating system independence.
“Appendix E” incorporates an overall Change History for the documentation. It
is highly recommended that the experienced user refer to this section as an aide
for understanding the version to version documentation changes as a resource to
help in the updating of the device support and/or implementation changes
necessary to the software for efficient usage.
“Appendix F” provides some additional software reference material that may
prove helpful to the understanding of the principals and documentation constructs
that the UnifiedPOS standard incorporates. The developer is encouraged to check
this section as additional resource material will be added as the standard evolves
from version to version.
“Appendix G” includes additional hardware reference material that is pertinent
to the hardware design for compliance to the UnifiedPOS standard. The USB Plus
Power connector recommendations are outlined in this section as well.

“Appendix H” provides information on functionality and changes that are

documented in the UnifiedPOS standard in a version that will cause a previously
defined function to be deprecated. While every attempt is made to minimize the
use of Deprecation, the reader is highly encouraged to review this section to
ensure a firm understanding of direction the standard is evolving.
“Appendix I” includes the definition, goals, and deliverables for Systems
Management. Appendix I is targeted at a systems management solution developer
who requires access to POS-specific device information. It is also targeted to the
system developer who will provide device information from within the Services
he provided.
“Appendix J” includes the definitions and deliverables for UnifiedPOS Device
Statistics. This information was previously issued in a separate document, but
starting with v1.12, the device statistics appendix was added as an appendix to the
specification

What Is UnifiedPOS?: Goals 37
Goals
The goals of UnifiedPOS are to provide:
• Common device architecture that is international and extends across vendors,
platforms, and retail format.
• Standards for application to device interfaces in an operating system
independent and language neutral manner.
• Reduced implementation costs for vendors to support multiple (for example,
Windows/COM, Windows/.NET, and Java) platforms because they share the
same architecture. This should produce speed to market for innovation.
• An environment avoiding competition between standards while encouraging
competition among implementations.
Dependencies
Success of the goals of UnifiedPOS depends upon platform specific standard
committees (such as JavaPOS and OLE for Retail POS (OPOS) technical
committees) to advance the architecture into platform specific documentation,
API definitions and implementations.
The specific technical implementations require:
• Platform specific implementation references. (See Appendices A, B, & C.)
• Source files, including:
• Definition files. Various interface and class files described in the
standard.
• Example files. These will include a set of sample Control classes, to
illustrate the interface presented to an application.
UnifiedPOS Relationship to Conforming Platform Mappings

The UnifiedPOS specification formalizes and documents the underlying retail
device architecture, shared by the JavaPOS, OPOS, and POS for .NET standards,
in an operating system independent and language neutral manner. The first
release of the UnifiedPOS Specification was Version 1.4.
The JavaPOS, OPOS, and POS for .NET standards have been established as
conformant platform mappings of the UnifiedPOS specification. In UnifiedPOS
Version 1.6, appendices were added in order to document specific implementation
details for each of these platforms. JavaPOS will be recognized as the only
UnifiedPOS conformant, operating system neutral, Java language mapping (See
Appendix B). OPOS will be recognized as the only UnifiedPOS conformant
language neutral COM mapping (See Appendix A). POS for .NET will be
recognized as the only UnifiedPOS conformant language neutral .NET mapping
(See Appendix C). Future UnifiedPOS mappings to platforms other than Java,
COM, and .NET will be included as appendices to the UnifiedPOS specification
as they become available.

This acceptance of the existing standards is based on their close conformance to a

common design model. Historically, the OPOS standards provided device
interfaces for Win32-based terminals using ActiveX technologies. The OPOS
standard was used as the starting point for JavaPOS, due to:
• Similar purposes. Both standards involved developing device interfaces for
a segment of the software community.
• Reuse of device models. The majority of the OPOS documentation specifies
the properties, methods, events, and constants used to model device behavior.
These behaviors are in large part independent of programming language.
• Reduced learning curve. Many application and hardware vendors are
already familiar with using and implementing the OPOS APIs.
Therefore, retail application developers and Service writers can continue to write
their code in conformance with one or both of the JavaPOS or OPOS standards.
The content of the UnifiedPOS specification, however, along with the appropriate
Appendix, will constitute the definition of how an application can be developed
to meet the UnifiedPOS standard. The standards committees do not intend to
release future versions of the specific OPOS and JavaPOS documents after the
Version 1.6 specification.
The UnifiedPOS specification is also the basis for the POS for .NET
implementation, which similarly adheres to this common approach for the access
and control of POS peripherals.
Who Should Read This Document

The UnifiedPOS Architecture is targeted to the standard committees that will
provide the language specific mapping and Programmer’s Guides. However, the
application developer who will use POS devices, the system developer who will
write POS device code, and the suppliers of POS devices for retail may be
interested in the device characteristics as portrayed in this document.
This guide assumes that the standard committee member is familiar with the
following:
• General characteristics of POS peripheral devices.
• UnifiedPOS terminology and architecture.
• UML for reading the design.

Architectural Overview: Architectural Components 39
Architectural Overview
UnifiedPOS defines a multi-layered architecture in which a POS Application
interacts with the Physical or Logical Device through the UnifiedPOS Control
layer.
POS Application
UnifiedPOS Device
UnifiedPOS Control
UnifiedPOS Service
Physical (or logical) Device
Architectural Components
The POS Application (or Application) is an Application that uses one or more
UnifiedPOS devices.
UnifiedPOS Devices are divided into categories called Device Categories, such
as Cash Drawer and POS Printer.
Each UnifiedPOS Device is a combination of these components:
• Control for a device category. The Control class provides the interface
between the Application and the device category. It contains no graphical
component and is therefore invisible at runtime.
The Control has been designed so that all implementations of a device
category’s control will be compatible. Therefore, the Control can be
developed independently of the Service for the same device category (they
can even be developed by different companies).

• Service, which is a component called by the Control through the Service

Interface. The Service is used by the Control to implement UnifiedPOS-
prescribed functionality for a Physical Device. It can also call special event
methods provided by the Control to deliver events to the Application.
A set of Service classes can be implemented to support Physical Devices with
multiple Device Categories.
The Application manipulates the Physical Device (the hardware unit or
peripheral) by calling the platform specific APIs which conform to the
UnifiedPOS standard. Some Physical Devices support more than one device
category. For example, some POS Printers include a Cash Drawer kickout, and
some Bar Code Scanners include an integrated Scale. However with UnifiedPOS,
an application treats each of these device categories as if it were an independent
Physical Device. The UnifiedPOS Device standard developer is responsible for
presenting the peripheral in this way.
Note: Occasionally, a Device may be implemented in software with no user-
exposed hardware, in which case it is called a Logical Device.
Use of UML
The UnifiedPOS standard includes the use of UML terminology and diagrams to
define device categories. Following is a brief description of the extensions to
UML to make it better fit the UnifiedPOS architecture (this extension is expected
and allowed by the UML, see Booch98 reference in the “UML References” on
page D-1).
Should any discrepancies exist between the UML diagrams and the specification
text, then the text takes precedence.

Architectural Overview: Use of UML 41
Table of extensions to UML for UnifiedPOS.
Applies to UML
Name Meaning
Symbol
stereotype which flags the attribute as a
<<capability>> Class attribute
UnifiedPOS capability
stereotype which flags the attribute as a
<<prop>> Class attribute
UnifiedPOS property
stereotype to indicate that the class/interface
will be mapped to a UnifiedPOS event which in
<<event>> Class
turn is mapped to a JavaPOS event class or a
COM event for OPOS or a .NET event
constraint that indicates this Device Service or
Service Object follows the exclusive-use
exclusive-use Class behavior defined in the UnifiedPOS
documentation in section “Exclusive-Use
Devices” on page 50.
constraint that indicates this Device Service or
Service Object follows the sharable behavior
sharable Class
defined in the UnifiedPOS documentation in
section “Sharable Devices” on page 50.
constraint that indicates the mutability of the
read-only attribute. For example, in JavaPOS, read-only
Class attribute attributes translate to having a getter method for
read-write
the attribute and read-write attributes have getter
and setter methods for attributes.
access after constraint that indicates this attribute is
<open>| accessible when the service is in the state
indicated. For example {access after opened-
<open-claim>|
claim-enable} indicates that the attribute is
<open-enable>| Class attribute
accessible when the service has been opened,
<open-claim-enable> claimed and enabled in the order indicated.
constraint that indicates this method can throw
an exception if the implementation language
supports exception; otherwise, some mechanism
raises-exception Class operation
is used to notify the application that an invalid
condition occurred. A value is returned to
indicate the error.
use after constraint that indicates this operation is
<open>| accessible when the service is in the state
indicated. For example {use after open-claim-
<open-claim>| Class operation
enable} indicates that the method is accessible
<open-enable>| when the service has been opened, claimed and
<open-claim-enable> enabled in the order indicated.

Package Diagram
UnifiedPOS uses Static Structure Diagrams to define common interfaces.
upos events
(from upos)
Note: This package diagram is included to give some logical structure to the
interfaces in the UnifiedPOS interfaces UML diagrams. Some implementations
may have a corresponding equivalence for the packages and some may not. Also,
note that the name ‘upos’ may be replaced by an implementation specific prefix
(eg. JavaPOS uses Java packages and maps the prefix ‘upos’ to ‘jpos’).

Architectural Overview: Data Types 43
Data Types Updated in Release 1.12

UnifiedPOS uses textual references to data types which will be defined for
specific language usage:
POS for
UnifiedPOS JavaPOS OPOS UML UnifiedPOS text Usage
.NET
boolean boolean BOOL bool in boolean Boolean true or false.
boolean by boolean[1] BOOL* Not used ** inout Mutable boolean.
reference boolean
binary byte[] BSTR byte[] in binary Immutable array of bytes.
binary by byte[1][] BSTR* Not used ** inout Mutable array of bytes. (Both its size
reference binary and contents may be modified.)
array of byte[][] SAFEARRAY Not used ** in binary[] Immutable array of array of bytes.
binary of BSTR
byte byte LONG byte in byte 8-bit integer. (See HardTotals, setAll
method.)
int32 int LONG int or enum
in int32 32-bit integer.
int32 array int[] SAFEARRAY int[]
in int32 Immutable array of 32-bit integers.
of LONG array
int32 array int[1][] SAFEARRAY* Not used ** inout int32 Mutable array of 32-bit integers. (Both
by reference of LONG array its size and contents may be modified.)
int32 by int[1] LONG* Not used ** inout int32 Mutable 32-bit integer.
reference
currency long CURRENCY decimal in 64-bit integer. Sometimes used for
or CY currency currency values where 4 decimal
places are implied. E.g., if the integer
is “1234567”, then the currency value
is “123.4567”. See footnotea
currency by long[1] CURRENCY* Not used ** inout Mutable 64-bit integer.
reference or CY* currency
string String BSTR string in string Text character string.
string by String[1] BSTR* Not used ** inout Mutable text character string. (Both its
reference string size and contents may be modified.)
array of Point[] BSTR Point[] inout Immutable array of points. Used by
points point[] Signature Capture.
object Object BSTR* object inout An object. This will usually be
object subclassed to provide a Service-
specific parameter.
nls String LONG CultureInfo in nls Operating System National Language
Support data type.
a. Six decimal place precision is required for all computations in conversion between currencies but is not
required for the representation of the solution.
For Java:
The convention of type[1] (an array of size 1) is used to pass a mutable basic type. This is required since Java’s
primitive types, such as int and boolean, are passed by value, and its primitive wrapper types, such as Integer and
Boolean, do not support modification. For strings and arrays, do not use a null value to report no information.
Instead use an empty string (“”) or an empty array (zero length). In some chapters, an integer may contain a “bit-
wise mask”. That is, the integer data may be interpreted one or more bits at a time. The individual bits are
numbered beginning with Bit 0 as the least significant bit.
** POS for .NET does not use “out” parameters, return values are used instead.

Device Behavior Models
Introduction to Properties, Methods, and Events

An application accesses a POS Device via platform specific APIs.
The three elements of UnifiedPOS standard for APIs are:
• Properties. Properties are device characteristics or settings. A type is
associated with each property, such as boolean or string. An application may
retrieve a property’s value, and it may set a writable property’s value.
• Methods. An application calls a method to perform or initiate some activity
at a device. Some methods require parameters of specified types for sending
and/or returning additional information.
• Events. A Device implementation may call back into the application via
events. The application may need to register for events. The mechanism to do
this is implementation specific.
Properties (UML Attributes)

Note: For each interface a UML listing of the properties and methods of the
interface will be included in a table. The properties are indicated as attributes.
The generic UML naming pattern for attributes is the following:
visibility Name: type-expression = default-value { property-string }
where:
visibility in this document is always public for application visible interfaces but is
not explicitly shown.
Name is the name of the attribute
type-expression is the type of the attribute, which is one of UnifiedPOS types
defined in section “Data Types” on page 43.
default-value1 the default value of the attributes in UML, (optional)

property-string property value to apply to the element. For attributes, we define
two such strings: read-only and read-write, which indicates the mutability of the
attribute.
An example of a property attribute is as follows:

DeviceEnabled: boolean { read-write }
1. Not used by UnifiedPOS standard

Device Behavior Models: Introduction to Properties, Methods, and Events 45
Methods (UML Operations)

The generic UML pattern for methods is the following:
visibility name ( parameter-list ): return-type-expr { property string }
where:
parameter - list is a comma separated list of formal parameters using the
following generic UML naming pattern:
kind name: type-expression ( = default-value)2
where:
kind is either: ‘in’, ‘out’, or ‘inout’ with the default set to ‘in’ if absent
property-string is a property string to apply to the element. For methods an
additional property string called ‘raises-exception’ is defined which means that
this method can throw the exception if the implementation language supports
exception; otherwise, some mechanism is used to notify the application that an
invalid condition occurred.
An example of a method operation is as follows:
open ( logicalDeviceName: string ): void { raises-exception }
Events (UML Interfaces)

Events are being modeled as UML classes which will possibly contain attributes
stereotyped with the event stereotype. The generic UML pattern for events is a
UML box with the stereotype <<event>> (class diagram) with the event name
and a list of the properties. This representation is different from Properties and
Methods.
<< event >>

XxxEvent
where:
XxxEvent stands for the UnifiedPOS event name and the second
compartment of the box would contain a list of attributes for the event.
2. default-value is not used by the UnifiedPOS standard

Device Initialization and Finalization Updated in Release 1.11
Initialization
The first actions that an application must take to use a Device are:
• Obtain a reference to a Control,
• Prepare Control for the events that the application needs to receive, if
necessary.
To initiate activity with the Physical Device, an application calls the Control’s
open method:
The logicalDeviceName parameter specifies a logical device to associate with the
Device. The open method performs the following steps:
• Creates and initializes an instance of the proper Service class for the specified
name.
• Initializes many of the properties, including the descriptions and version
numbers of the Device.
More than one instance of a Control may have a Physical Device open at the same
time. Therefore, after the Device is opened, an application might need to call the
claim method to gain exclusive access to it. Claiming the Device ensures that
other Control instances do not interfere with the use of the Device. An application
can release the Device to share it with another Control instance– for example, at
the end of a transaction.
Before using the Device, an application must set the DeviceEnabled property to
true. This value brings the Physical Device to an operational state, while false
disables it. For example, if a Scanner Device is disabled, the Physical Device will
be put into its non-operational state (when possible). Whether physically
operational or not, any input is discarded until the Device is enabled.
Initialization and Error Reporting Added in Release 1.11

Error conditions may require that a Service fail during one or more of the
initialization APIs - open, claim, and/or DeviceEnabled=true. The following are
recommendations for initialization-time error handling by Service implementers.
These guidelines are not mandated, however, because of the wide variation in
some hardware devices and their initialization requirements, and due to variations
in already released Services.
open Primary purpose: Initialize the software stack, including the creation of
the Service and initialization of its supporting software components.
1) The Service must fail an open API call if software initialization fails.
Example: Supporting software components are not installed or
available, so fail the API call.

Device Behavior Models: Device Initialization and Finalization 47
2) If the Service must probe the device in order to correctly set open-
time properties (such as capabilities), then the Service should fail an
open API call if it cannot access the device.
Example: A Service supports several line display models and sets the
UnifiedPOS capabilities after communicating with the device. If the
device’s port is not available or the device does not respond, then the
Service cannot complete its open work and will need to fail the API
call.
3) For other cases, the Service should succeed the open API call and
report a failure (if needed) later.
Example: A Service cannot open an RS232 port during open. If the
previous case (#2) above does not apply, then the Service should
succeed the open and report the port open failure during claim, if the
port is still not available.
claim Primary purpose: Acquire exclusive access to the device, for exclusive-
use devices.
1) The Service must fail a claim API call if another process has claimed
the device and the claim timeout expires.
2) If the device is not accessible, then the Service should fail a claim
API call.
Examples: A required communications or I/O port cannot be opened
or claimed. The Service determines that the device is not present or
is offline. For each of these cases, the Service should fail the API
call.
3) For other cases, the Service should succeed the claim API call. This
specifically includes cases where runtime faults exist.
Examples: A POSPrinter receipt station is out-of-paper, or the
POSPrinter receipt station detects a printer jam. These are runtime
faults that occur from time to time during operation, and are user
correctable. The Service should succeed the claim. POSPrinter
runtime faults should be reported (after DeviceEnabled=true) by
StatusUpdateEvents and/or by exceptions from APIs such as
printNormal.
DeviceEnabled=true Primary purpose: Final preparation for operation and

application use.
1) If the device is not accessible, then the Service should fail a
DeviceEnabled= true API call. (Note that the device may have been
accessible at claim but is now inaccessible.)
Example: The Service determines that the device is not present or is
offline, so the Service should fail the API call.
2) For other cases, the Service should succeed the DeviceEnabled=true
API call. This specifically includes cases where runtime faults exist.
Examples: See claim case (#3) above.

An application developer must be prepared for failures at any of the initialization

points. With the variations in hardware devices and in their Service
implementations, a well-written application will respond predictably to the widest
range of error conditions and their reporting as possible.
Retail devices may communicate with a POS terminal using a wide variety of
ports, including RS232, RS485, Parallel, USB, Ethernet, and Wireless. In
addition, devices may be powered directly by the terminal or by an external
power source. These guidelines may be applied to all of these devices. Two
examples with typical initialization follow.
Example 1: Hand-held scanner attached to a terminal's powered RS232 port.
• open: Succeed if software initialization is successful.
• claim: Succeed if open was successful and if an attempt to communicate with
the device is successful.
• DeviceEnabled = true: Succeed if claim was successful and if an attempt
to communicate with the device is successful.
• While enabled: If the device is unplugged from the powered RS232 port,
then detect the power state change and report to the application. If the device
is later plugged back in, then detect the power state change and report to the
application. For many devices, power state changes can be accomplished by
monitoring the RS232 DSR signal. (Note that hot unplugging and plugging in
with this port type is probably not recommended by the hardware vendor.)
Example 2: Deck scanner/scale attached to a terminal's USB port, powered by a
“brick”.
• open: Succeed if software initialization is successful.
• claim: Succeed if open was successful and if an attempt to communicate with
the device is successful.
• DeviceEnabled = true: Succeed if claim was successful and if an attempt
to communicate with the device is successful.
• While enabled: If the device is unplugged from the USB port or from its
power source, then detect the power state change and report to the application.
If the device is later plugged back in, then detect the power state change and
report to the application. An operating system-specific mechanism detects
power state changes, such as an open, write, or read failure with specific
failure statuses.
Notice that the general initialization handling is very similar, even though the
second example will typically require somewhat more logic within the Service to
monitor and re-initialize the device connection.

Device Behavior Models: Device Initialization and Finalization 49
Finalization
After an application finishes using the Physical Device, it should call the close
method. If the DeviceEnabled property is true, close disables the Device. If the
Claimed property is true, close releases the claim on the device.
Before exiting, an application should close all open Devices to free device
resources in a timely manner.
Summary
In general, an application follows this general sequence to open, use, and close a
Device:
Obtain a Control reference.
Prepare for events if necessary.
Call the open method to instantiate a Service and link it to the Control.
Call the claim method to gain exclusive access to the Physical
Device. Required for exclusive-use Devices; optional for some
sharable Devices. (See “Device Sharing Model” on page 50 for more
information).
Set the DeviceEnabled property to true to make the Physical
Device operational. (For sharable Devices, the Device may be
enabled without first claiming it.)
Use the device.
Set the DeviceEnabled property to false to disable the Physical
Device.
Call the release method to release exclusive access to the Physical
Device.
Call the close method to unlink the Service from the Control.
Release events receipt if necessary
Remove the reference to the Control

Device Sharing Model
Devices fall into two sharing categories:

• Devices that are to be used exclusively by one Control instance.
• Devices that may be partially or fully shared by multiple Control instances.
Any Physical Device may be open by more than one Control instance at a time.
However, activities that an application can perform with a Control may be
restricted to the Control instance that has claimed access to the Physical Device.
Exclusive-Use Devices
The most common device type is called an exclusive-use device. An example is
the POS printer. Due to physical or operational characteristics, an exclusive-use
device can only be used by one Control at a time. An application must call the
Device’s claim method to gain exclusive access to the Physical Device before
most methods, properties, or events are legal. Until the Device is claimed and
enabled, calling methods or accessing properties may cause a failure condition to
occur.
An application may in effect share an exclusive-use device by calling the
Control’s claim method before a sequence of operations, and then calling the
release method when the device is no longer needed. While the Physical Device
is released, another Control instance can claim it.
When an application calls the claim method again (assuming it did not perform
the sequence of close method followed by open method on the device), some
settable device characteristics are restored to their condition at the release.
Examples of restored characteristics are the line display’s brightness, the MSR’s
tracks to read, and the printer’s characters per line. However, state characteristics
are not restored, such as the printer’s sensor properties. Instead, these are updated
to their current values.
Sharable Devices
Some devices are sharable devices. An example is the keylock. A sharable
device allows multiple Control instances to call its methods and access its
properties. Also, it may deliver its events to multiple Controls. A sharable device
may still limit access to some methods or properties to the Control that has
claimed it, or it may deliver some events only to the Control that has claimed it.

Device Behavior Models: Events 51
Events Updated in Release 1.12

UnifiedPOS architecture uses events to inform the application of various
activities or changes with the Device. The five event types follow.
Supported When A
Event Class Description Device Category
Supports...
DataEvent Input data has been placed into device Event-driven input
class-category properties.
ErrorEvent An error has occurred during event- Event-driven input
driven input or asynchronous output. -or-
Asynchronous
output
OutputCompleteEvent An asynchronous output has Asynchronous
successfully completed. output
StatusUpdateEvent A change in the Physical Device’s Status change
status has occurred. notification
Devices may be able to report device
power state. See “Device Power
Reporting Model” on page 58.
DirectIOEvent This event may be defined by a Service Always, for Service-
provider for purposes not covered by specific use
the specification.
The Service must enqueue these events on an internally created and managed
queue. All events are delivered in a first-in, first-out manner. (The only exception
is that a special input error event is delivered early if some data events are also
enqueued. See “Device Input Model” on page 54.) Events are delivered by an
internally created and managed Service thread. The Service causes event delivery
by calling an event firing callback method in the Control, which then delivers the
event to the application.
The following conditions cause event delivery to be delayed until the condition is
corrected:
• The application has set the property FreezeEvents to true.
• The event type is a DataEvent or an input ErrorEvent, but the property
DataEventEnabled is false. (See “Device Input Model” on page 54.)
Unless specified otherwise, properties that convey device state information (e.g.,
JrnEmpty and DrawerOpened) are kept current while the device is enabled,
regardless of the setting of the FreezeEvents property.
Rules for event queue management are:
• The Device may only enqueue new events while the Device is enabled.
• The Device delivers enqueued events until the application calls the release
method (for exclusive-use devices) or the close method (for any device), at
which time any remaining events are deleted.
• For input devices, the clearInput method clears data and input error events.
• For output devices, the clearOutput method clears data and output error
events.

Errors
UnifiedPOS architecture deals with two kinds of errors as discussed in “Methods
(UML Operations)” on page 45 and explanation of exceptions:
• Errors that are “invalid or bad invocations” which are recognized by the
Service validation of the request. Method invocations and property accesses
may be valid or invalid. If the action is invalid, an invalid condition is set and
the application is notified in a fashion appropriate to the platform. For specific
implementations, OPOS would produce a ResultCode other than
OPOS_SUCCESS and JavaPOS would produce an exception.
• Errors that are caused by errant device behavior and produce error events.
Error Codes Updated in Release 1.11

This section lists the general meanings of the error code property when an invalid
condition occurs. In general, the property and method descriptions in later
chapters list error codes only when specific details or information are added to
these general meanings. In UML each error code is:
E_xxx : int32 { frozen }
The error code is set to one of the following values:
Value Meaning
E_CLOSED An attempt was made to access a closed Device.
E_CLAIMED An attempt was made to access a Physical Device that
is claimed by another Control instance. The other
Control must release the Physical Device before this
access may be made. For exclusive-use devices, the
application will also need to claim the Physical Device
before the access is legal.
E_NOTCLAIMED An attempt was made to access an exclusive-use device
that must be claimed before the method or property set
action can be used.
If the Physical Device is already claimed by another
Control instance, then the status E_CLAIMED is
returned instead.
E_NOSERVICE The Control cannot communicate with the Service,
normally because of a setup or configuration error.
E_DISABLED Cannot perform this operation while the Device is
disabled.
E_ILLEGAL An attempt was made to perform an illegal or
unsupported operation with the Device, or an invalid
parameter value was used.

Device Behavior Models: Error Codes 53
E_NOHARDWARE The Physical Device is not connected to the system or

is not powered on.
E_OFFLINE The Physical Device is off-line.
E_NOEXIST The file name (or other specified value) does not exist.
E_EXISTS The file name (or other specified value) already exists.
E_FAILURE The Device cannot perform the requested procedure,
even though the Physical Device is connected to the
system, powered on, and on-line.
E_TIMEOUT The Service timed out waiting for a response from the
Physical Device, or the Control timed out waiting for a
response from the Service.
E_BUSY The current Service state does not allow this request.
For example, if asynchronous output is in progress,
certain methods may not be allowed.
E_EXTENDED A device category-specific error condition occurred.
The error condition code is held in an extended error
code.
E_DEPRECATED The requested operation can not be performed since it
has been deprecated. See “Deprecation Handling” on
page 69 for additional information.
When more than one error code is valid, the most descriptive code should be
selected. For example, the closed, claimed, not claimed, and disabled errors must
follow this order of error reporting precedence, from higher to lower:
E_CLOSED The device must be opened.
E_CLAIMED The device is opened but not claimed. Another application
has the device claimed, so it cannot be claimed at this time.
E_NOTCLAIMED The device is opened but not claimed. No other application
has the device claimed, so it can and must be claimed.
E_DISABLED The device is opened and claimed (if this is an exclusive-
use device), but not enabled.
Extended Error Code

The extended error code is set as follows:
• When the error code is E_EXTENDED, the extended error code is set to a
device category-specific value, and must match one of the values given in this
document under the appropriate device category chapter.
• When the error code is any other value, the extended error code may be set by
the Service to any Service-specific value. These values are only meaningful if
an application adds Service-specific code to handle them.

Device Input Model
The standard UnifiedPOS input model for exclusive-use devices is event-driven

input. Event-driven input allows input data to be received after DeviceEnabled is
set to true. Received data is enqueued as a DataEvent, which is delivered to an
application.
If the AutoDisable property is true when data is received, then the Device will
automatically disable itself, setting DeviceEnabled to false. This will inhibit the
Device from enqueuing further input and, when possible, physically disable the
device.
When the application is ready to receive input from the Device, it sets the
DataEventEnabled property to true. Then, when input is received (usually as a
result of a hardware interrupt), the Device delivers a DataEvent. (If input has
already been enqueued, the DataEvent will be delivered immediately after
DataEventEnabled is set to true.) The DataEvent may include input status
information through its Status property. The Device places the input data plus
other information as needed into device category-specific properties just before
the event is delivered.
Just before delivering this event, the Device disables further data events by
setting the DataEventEnabled property to false. This causes subsequent input
data to be enqueued by the Device while an application processes the current
input and associated properties. When an application has finished the current
input and is ready for more data, it enables data events by setting
DataEventEnabled to true.

Device Behavior Models: Device Input Model 55
Error Handling Updated in Release 1.12
If the Device encounters an error while gathering or processing event-driven

input, then the Device:
• Changes its State to S_ERROR.
• Enqueues an ErrorEvent with locus EL_INPUT to alert an application of the
error condition. This event is added to the end of the queue
• If one or more DataEvents are already enqueued for delivery, an additional
ErrorEvent with locus EL_INPUT_DATA is enqueued before the
DataEvents, as a pre-alert.
This event (or events) is not delivered until the DataEventEnabled property is
true, so that orderly application sequencing occurs.
Unlike a DataEvent, the Device does not disable further DataEvents or input
ErrorEvents; it leaves the DataEventEnabled property value at true. Note that
the application may set DataEventEnabled to false within its event handler if
subsequent input events need to be disabled for a period of time.
ErrorLocus Description
EL_INPUT_DATA Only delivered if the error occurred when one or more
DataEvents are already enqueued.
This event gives the application the ability to immediately clear
the input, or to optionally alert the user to the error before
processing the buffered input. This error event is enqueued
before the oldest DataEvent, so that an application is alerted of
the error condition quickly.
This locus was created especially for the Scanner: When this
error event is received from a Scanner Device, the operator can
be immediately alerted to the error so that no further items are
scanned until the error is resolved. Then, the application can
process any backlog of previously scanned items before error
recovery is performed.
EL_INPUT Delivered when an error has occurred and there is no data
available.
If some input data was buffered when the error occurred, then
an ErrorEvent with the locus EL_INPUT_DATA was
delivered first, and then this error event is delivered after all
DataEvents have been delivered.
If the Service has partial data that can be delivered with an
ErrorEvent, the related data properties should be filled in prior
to delivery of the event with this ErrorLocus. If there is no
partial data to be delivered with the ErrorEvent, the data
properties should be cleared prior to delivery of this event.
Note: This EL_INPUT event is not delivered if: an
EL_INPUT_DATA event was delivered and the application
event handler responded with an ER_CLEAR error response.

The application can cause the ErrorResponse property to be set one of the
following:
ErrorResponse Description
ER_CLEAR Clear the buffered DataEvents and ErrorEvents and exit
the error state, changing State to S_IDLE.
This is the default response for locus EL_INPUT.
ER_CONTINUEINPUT This response acknowledges the error and directs the
Device to continue processing. The Device remains in the
error state, and will deliver additional data events as
directed by the DataEventEnabled property. When all
input has been delivered and the DataEventEnabled
property is again set to true, another ErrorEvent is
delivered with locus EL_INPUT.
This is the default response when the locus is
EL_INPUT_DATA, and is legal only with this locus.
ER_RETRY This response directs the Device to retry the input. The
error state is exited, and State is changed to S_IDLE.
This response may only be selected when the device
chapter specifically allows it and when the locus is
EL_INPUT. An example is the scale.
The Device exits the Error state when one of the following occurs:
• The application returns from the EL_INPUT ErrorEvent.
• The application calls the clearInput method.
• The application returns from the EL_INPUT_DATA ErrorEvent with
ErrorResponse set to ER_CLEAR.
Miscellaneous Updated in Release 1.10
For some Devices, the Application must call a method to begin event driven
input. After the input is received by the Device, then typically no additional input
will be received until the method is called again to reinitiate input. Examples are
the MICR and Signature Capture devices. This variation of event driven input is
sometimes called “asynchronous input.”
The DataCount property contains the number of DataEvents enqueued by the
Device.
Calling the clearInput method deletes all input enqueued by a Device.
clearInput may be called after open for sharable devices and after claim for
exclusive-use devices.
Calling the clearInputProperties method sets all data properties, that were
populated as a result of firing a DataEvent or ErrorEvent, back to their default
values. This call does not reset the DataCount or State properties.
The general event-driven input model does not specifically rule out the definition
of device categories containing methods or properties that return input data
directly. Some device categories define such methods and properties in order to
operate in a more intuitive or flexible manner. An example is the Keylock device.
This type of input is sometimes called “synchronous input.”

Device Behavior Models: Device Output Models 57
Device Output Models
The UnifiedPOS output model consists of two output types: synchronous and
asynchronous. A device category may support one or both types, or neither type.
Synchronous Output
The application calls a category-specific method to perform output. The Device
does not return until the output is completed; this means the physical device has
performed the intended operation. For example the printer has successfully
transferred all the output data as ink on the paper.
This type of output is preferred when device output can be performed relatively
quickly. Its merit is simplicity.
Asynchronous Output Updated in Release 1.12

The application calls a category-specific method to start the output. The Device
validates the method parameters and produces an error condition immediately if
necessary. If the validation is successful, the Device does the following:
1. Buffers the request in program memory, for delivery to the Physical Device as
soon as the Physical Device can receive and process it.
2. Sets the OutputID property to an identifier for this request.
3. Returns as soon as possible.
When the Device successfully completes a request, an OutputCompleteEvent is
enqueued for delivery to the application. A property of this event contains the
output ID of the completed request. If the request is terminated before
completion, due to reasons such as the application calling the clearOutput
method or responding to an ErrorEvent with a ER_CLEAR response, then no
OutputCompleteEvent is delivered.
If an error occurs while processing a request, an ErrorEvent is enqueued which
will be delivered to the application after the events already enqueued, including
OutputCompleteEvents (according to the normal Event delivery rules on page
51). No further asynchronous output will occur until the event has been delivered
to the application. If the response is ER_CLEAR, then outstanding asynchronous
output is cleared. If the response is ER_RETRY, then output is retried; note that if
several outputs were simultaneously in progress at the time that the error was
detected, then the Service may need to retry all of these outputs.
This type of output is preferred when device output requires slow hardware
interactions. Its merit is perceived responsiveness, since the application can
perform other work while the device is performing the output.
Note: Asynchronous output is always performed on a first-in first-out basis.

Device Power Reporting Model Updated in Release 1.8
Applications frequently need to know the power state of the devices they use.
Note: This model is not intended to report Workstation or POS Terminal power
conditions (such as “on battery” and “battery low”). Reporting of these conditions
is now managed by the POSPower device category, see page 927.
Model
UnifiedPOS architecture segments device power into three states:
• ONLINE. The device is powered on and ready for use. This is the
“operational” state.
• OFF. The device is powered off or detached from the terminal. This is a “non-
operational” state.
• OFFLINE. The device is powered on but is either not ready or not able to
respond to requests. It may need to be placed online by pressing a button, or it
may not be responding to terminal requests. This is a “non-operational” state.
In addition, one combination state is defined:
• OFF_OFFLINE. The device is either off or offline, and the Service cannot
distinguish these states.
Power reporting only occurs while the device is open, claimed (if the device is
exclusive-use), and enabled.
Note - Enabled/Disabled vs. Power States

These states are different and usually independent. UnifiedPOS defines “disabled” /
“enabled” as a logical state, whereas the power state is a physical state. A device may
be logically “enabled” but physically “offline”. It may also be logically “disabled” but
physically “online”. Regardless of the physical power state, UnifiedPOS only reports
the state while the device is enabled. (This restriction is necessary because a Service
typically can only communicate with the device while enabled.)
If a device is “offline”, then a Service may choose to fail an attempt to “enable” the
device. However, once enabled, the Service may not disable a device based on its power
state.

Device Behavior Models: Device Power Reporting Model 59
Power State Diagram
[Device is closed]
PowerState Unknown
PS_UNKNOWN
[D evice is closed]
Known PowerStates
[Device is Off or Offline] Off/Offline States
PowerState Online PowerState Standard Off/Offline

PS_ONLINE PS_OFF_OFFLINE
[D evice is Online] [ CapPowerReporting == PR_ADVANCED ]
Advanced Off/Offline States
PowerState Advanced Offline

PS_OFFLINE
[Device is Off] [ Device is Offline ]
Po werState Advanced Off

PS_OFF

Power Properties
The UnifiedPOS device power reporting model adds the following common
elements across all device classes.
• CapPowerReporting property. Identifies the reporting capabilities of the
device. The UML pattern for the property is:
PR_xxx : int32 { frozen }
This property may be one of:
• PR_NONE. The Service cannot determine the state of the device.
Therefore, no power reporting is possible.
• PR_STANDARD. The Service can determine and report two of the power
states - OFF_OFFLINE (that is, off or offline) and ONLINE.
• PR_ADVANCED. The Service can determine and report all three power
states - ONLINE, OFFLINE, and OFF.
• PowerState property. Maintained by the Service at the current power
condition, if it can be determined. The UML pattern for the property is:
PS_xxx : int32 { frozen }
• PS_UNKNOWN
• PS_ONLINE
• PS_OFF
• PS_OFFLINE
• PS_OFF_OFFLINE
• PowerNotify property. The application may set this property to enable power
reporting via StatusUpdateEvents and the PowerState property. This
property may only be changed while the device is disabled (that is, before
DeviceEnabled is set to true). This restriction allows simpler implementation
of power notification with no adverse effects on the application. The
application is either prepared to receive notifications or doesn't want them,
and has no need to switch between these cases. The UML pattern for the
property is:
PN_xxx : int32 { frozen }
• PN_DISABLED
• PN_ENABLED

Device Behavior Models: Device Power Reporting Model 61
Power Reporting Requirements for DeviceEnabled
The following semantics are added to DeviceEnabled when

CapPowerReporting is not PR_NONE, and
PowerNotify is PN_ENABLED:
• When the Control changes from DeviceEnabled false to true, then begin
monitoring the power state:
• If the Physical Device is ONLINE, then:
PowerState is set to PS_ONLINE.
A StatusUpdateEvent is enqueued with its Status property set to
SUE_POWER_ONLINE.
• If the Physical Device’s power state is OFF, OFFLINE, or
OFF_OFFLINE, then the Service may choose to fail the enable by
notifying the application with error code E_NOHARDWARE or
E_OFFLINE.
However, if there are no other conditions that cause the enable to fail, and
the Service chooses to return success for the enable, then:
PowerState is set to PS_OFF, PS_OFFLINE, or
PS_OFF_OFFLINE.
SUE_POWER_OFF, SUE_POWER_OFFLINE, or
SUE_POWER_OFF_OFFLINE.
• When the Device changes from DeviceEnabled true to false, UnifiedPOS
assumes that the Device is no longer monitoring the power state and sets the
value of PowerState to PS_UNKNOWN

Device Information Reporting Model Added in Release 1.8

POS Applications, as well as System Management agents, frequently need to
monitor the current configuration and usage metrics of the various POS devices
that are attached to the POS terminal.
Examples of configuration data are the device’s Serial Number, Firmware
Version, and Connection Type. Examples of usage data for the POSPrinter device
are the Number of Lines Printed, Number of Hours Running, Number of paper
cuts, etc. Examples of usage data for the Scanner device are the Number of scans,
Number of Hours Running, etc. Examples of usage data for the MSR device are
the Number of successful swipes, Number of swipes resulting in errors, Number of
Hours Running, etc. See below for examples of XML definitions of the device
statistics accumulated per POS device category.
In some cases, the data may be accumulated and stored within the device itself. In
other cases, the data may be accumulated by the Service and stored, possibly on
the POS terminal or store controller.
In order for multiple applications (for example a POS application and a System
Management application) to obtain statistics from the same device, proper care
must be taken by both applications so that the device can be made accessible
when required. This is done by using the claim method and by setting
DeviceEnabled to true when access to a device is required and then setting
DeviceEnabled to false and using the release method when access to the device
is no longer needed. Coordination of device access via this mechanism is the
responsibility of the applications themselves.
Statistics Reporting Properties and Methods

The UnifiedPOS device information reporting model adds the following common
properties and methods across all device classes.
• CapStatisticsReporting property. Identifies the reporting capabilities of the
device. When CapStatisticsReporting is false, then no statistical data
regarding the device is available. This is equivalent to Services compatible
with prior versions of the specification. When CapStatisticsReporting is
true, then some statistical data for the device is available.
• CapUpdateStatistics property. Defines whether gathered statistics (or some
of them) can be reset/updated by the application. This property is only valid if
CapStatisticsReporting is true. When CapUpdateStatistics is false, then
none of the statistical data can be reset/updated by the application. Otherwise,
when CapUpdateStatistics is true, then (some of) the statistical data can be
reset/updated by the application.
• resetStatistics method. Can only be called if both CapStatisticsReporting
and CapUpdateStatistics are true. This method resets one, some, or all of the
resettable device statistics to zero.
• retrieveStatistics method. Can only be called if CapStatisticsReporting is
true. This method retrieves one, some, or all of the accumulated statistics for
the device.
• updateStatistics method. Can only be called if both CapStatisticsReporting
and CapUpdateStatistics are true. This method updates one, some, or all of
the resettable device statistics to the supplied values.

Device Behavior Models: Device Information Reporting Model 63
XML definitions for POS Device Statistics

The XML files containing the UnifiedPOS defined statistics for each device
category are provided as downloads from the web sites that also host this
specification. These statistics can be referenced individually by name or as a
group using the “U_” string as (part of) the parameter to the statistics methods.
Manufacturers/Service providers can add their specific statistics in the provided

“ManufacturerSpecific” section. These statistics can be referenced individually
by name or as a group using the “M_” string as (part of) the parameter to the
statistics methods.
The following table contains the definitions of the information contained in the
UnifiedPOS defined DeviceInformation section covering all device categories.
<DeviceInformation>
Definition description
XML Definition Name
UnifiedPOSVersion Version of the UnifiedPOS specification supported
DeviceCategory Device category (e.g., POSPrinter)
ManufacturerName Device manufacturer’s name
ModelName Device model name
SerialNumber Device serial number
ManufactureDate Device manufacture date
MechanicalRevision Device hardware revision
FirmwareRevision Device firmware revision
Interface Device hardware interface (e.g., serial, USB)
InstallationDate Device installation date

The following is an example of the XML file that describes the “UnifiedPOS”
defined statistics for the CashDrawer device category.
<?xml version=’1.0’ ?>

<UPOSStat version=”1.12.0” xmlns:xsi=”http://www.w3.org/2001/
XMLSchema-instance” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
namespace/” xsi:schemaLocation=”http://www.nrf-arts.org/
UnifiedPOS/namespace/ UPOSStat.xsd”>
<Event>
<Parameter>
<Name>DrawerGoodOpenCount</Name>
<Value>1353</Value>
</Parameter>
<Parameter>
<Name>DrawerFailedOpenCount</Name>
<Value>2</Value>
</Parameter>
<ManufacturerSpecific>
<Name>MyPersonalStat</Name>
<Value>14.32</Value>
<unitofmeasure>meters</unitofmeasure>
</ManufacturerSpecific>
</Event>
<Equipment>
<UnifiedPOSVersion>1.12</UnifiedPOSVersion>
<DeviceCategory UPOS=”CashDrawer”/>
<ManufacturerName>Cashdrawers R Us</ManufacturerName>
<ModelName>CD-123</ModelName>
<SerialNumber>12345</SerialNumber>
<ManufactureDate>1999-12-31</ManufactureDate>
<MechanicalRevision>1A</MechanicalRevision>
<FirmwareRevision>1.0 Rev. B</FirmwareRevision>
<Interface>RS232</Interface>
<InstallationDate>2000-03-01</InstallationDate>
</Equipment>
</UPOSStat>
The most up-to-date files defining the XML tag names that conform to the ARTS Data
Dictionary and example schemas for the statistics for all device categories can be
downloaded from the NRF-ARTS web site at http://www.nrf-arts.org.

Device Behavior Models: Update Firmware Device Model 65
Update Firmware Device Model Added in Release 1.9

POS Applications frequently require the ability to update the firmware in the
various POS devices that are attached to the POS terminal. This model defines a
consistent application interface for updating the firmware in a device controlled
by a UnifiedPOS control.
This model has the following capabilities:
• A property, CapUpdateFirmware, that indicates whether a device supports
firmware updating.
• A property, CapCompareFirmwareVersion, that indicates whether a
firmware file’s version can be compared against the firmware version of the
device.
• A method, updateFirmware, to perform an asynchronous update of the
firmware in a device.
• A method, compareFirmwareVersion, to compare the firmware file’s
version against the firmware version of the device.
• Additional StatusUpdateEvent Status values to report the progress of an
asynchronous update firmware process.
The update firmware process is an asynchronous operation that reports its
progress via StatusUpdateEvents. This update firmware process applies to all
device categories defined in UnifiedPOS.
The means by which a Service actually updates the firmware in the device is not
covered by this document, only the means by which the update firmware process
is started and progress is reported.

Device States
UnifiedPOS defines a property State with the following values:

S_CLOSED
S_IDLE
S_BUSY
S_ERROR
The State property is set as follows:
• State is initially S_CLOSED.
• State is changed to S_IDLE when the open method is successfully called.
• State is set to S_BUSY when the Service is processing output. The State is
restored to S_IDLE when the output has completed.
• The State is changed to S_ERROR when an asynchronous output encounters
an error condition, or when an error is encountered during the gathering or
processing of event-driven input.
After the Service changes the State property to S_ERROR, it notifies the
application of this error. The properties of this event are the error code and
extended error code, the locus of the error, and a mutable response to the error.

Device Behavior Models: Device States 67
Device State Diagram
Closed
State == S_CLOSED
/close
Opened
/open
[ async output in progress ]

Idle Busy
State == S_IDLE State == S_BUSY
[ async output done ]
[ input event error] [ error event done and async output ]
[async output error or input event error]
[ error even t done and no async output ]
Error
State == S_ERROR

Version Handling
As UnifiedPOS evolves, additional releases will introduce enhanced versions of

some Devices. UnifiedPOS imposes the following requirements on Control and
Service versions:
• Control requirements. A Control for a device category must operate with
any Service for that category, as long as its major version number matches the
Service's major version number. If they match, but the Control's minor version
number is greater than the Service’s minor version number, then the Control
may support some new methods or properties that are not supported by the
Service’s release. If an application calls one of these methods or accesses one
of these properties, the application will be notified of an error condition
(E_NO_SERVICE).
• Service requirements. A Service for a device category must operate with any
Control for that category, as long as its major version number matches the
Control's major version number. If they match, but the Service's minor version
number is greater than the Control's minor version number, then the Service
may support some methods or properties that cannot be accessed from the
Control.
When an application wishes to take advantage of the enhancements of a version,
it must first determine that the Control and Service are at the proper major version
and at or greater than the proper minor version. The versions are reported by the
properties DeviceControlVersion (see page 83) and DeviceServiceVersion (see
page 85).

Device Behavior Models: Deprecation Handling 69
Deprecation Handling Added in Release 1.11

In order to be able to rectify misunderstandings and/or ambiguities in the
specification, a method of deprecation is required in order to eliminate these
items over time.
Deprecation can be applied to Properties and Methods, as well as parameters,
constants, and enumerations.
When an element is marked as deprecated, then Service providers are required to
support the element’s functionality for the following two minor releases of the
standard. Starting with the third release of the standard after an element has been
marked as deprecated, usage of the element will result in an E_DEPRECATED
status.
When an element is marked as deprecated, then support for the element will be
removed from the standard in the next major release of the standard after it is
marked as deprecated.
All deprecated elements and the related versions when they were first marked as
deprecated are listed in “APPENDIX H Deprecation History” on page H-1.

Hydra Device Considerations Updated in Release 1.12

Initial Connectivity Model
When the development of the POS peripheral standard began, it was decided that
the most flexible methodology would be to have an application be able to
communicate to a peripheral through a two-layer process. Since the Microsoft’s
COM platform was the first supported architecture, Control Object and Service
Object names were chosen. Later when Java was defined and the technology used
precluded the use of “objects” as defined in the Windows world, the names were
closely linked using the terminology Device Control and Device Service.
Functionality however at the higher, abstracted level, remained the same.
Control Object or Device Control (Control)
A thin layer of software was defined that would allow for what is commonly
called “connecting the pipes” wherein a communication port would be opened
and a device name would be assigned so that the application is able to
communicate to the peripheral using that device name.
Service Object or Device Service (Service)
This incorporates usually vendor-specific code that interfaces with the peripheral
device to allow for accessing, monitoring, processing, all the functionality of the
peripheral device and exposing it to a common set of properties, methods, and
events that an application needs to interact with the peripheral.
For mono-function peripheral devices, the process is very straightforward. In the
most simplistic system one instance of a Control is instantiated to connect to the
Service. As example for a simple POSPrinter:
Note that only one physical connection port (RS-232 for example) is used in this example…
Application
Control
Service
Service for Functionality of Peripheral
Device and supports Physical
Connection to the Peripheral Device
POS Receipt
Printer

Device Behavior Models: Hydra Device Considerations 71
Keeping things simple but adding another level of complexity is the case when
more than one application needs to use the device. In this case, another Control is
instantiated to the peripheral Service and all applications need to recognize that
the peripheral is capable of being shared (for this example, assuming a shareable
device) and utilize the claim and release methodology that the standard provides.
In the POSPrinter example, this would look like…
Note that only one physical connection port (RS-232 for example) is used in this example…
Application One Application Two
Control One Control Two
Service
Service for Functionality of Peripheral Device and
supports Physical Connection to the Peripheral
Device
POS Receipt
Printer
Note, that as far as each application is concerned, it is connected to the peripheral

device and only one physical connection to the device is required... via the RS-
232 serial connection in this example. This served the needs of device sharing
where cooperating applications were utilized.
Multi-Function (Hydra) Peripheral Devices

The model needed to be expanded to cover the peripherals that
include multiple device class functionality in a single unit. An
example of such a device is a POS printer that may have
additional functionality of being able to control a Customer
Line Display, Cash Drawer, MICR, or other devices. These
peripherals are referred to as “Hydra” peripherals alluding to
the Greek mythology of a multi-headed animal that was
connected to a single body interface.
In the interaction of POS peripherals, the interface to the Application needs to be
agnostic in its knowledge in either of the following cases…one where multiple
physical peripheral devices are used or the other where one physical peripheral
device incorporates the functionality of multiple physical peripheral devices.
Where multiple physical peripheral devices are present, multiple “pipes” (RS-232
serial ports for instance) are required…one for each of the physical peripheral
devices.

In a Hydra peripheral only one “pipe” is required and it is used to communicate

with all the various Device peripheral functionality of the connected peripheral
device.
For example, consider the cases where in one instance a separate POSPrinter
device and a separate MICR device is present; in another instance, a Hydra
POSPrinter that has an incorporated MICR reader. The “look” to the
Application(s) has to be agnostic…it should not care nor should it have to know
which type of hardware device(s) are physically present. Ideally it should be able
to use the same Application code to interact with either of the two
implementations. For example:
Application interfacing with two distinct peripherals…
Application That Needs Functionality for

MICR POSPrinter
MICR POSPrinter
Control Control
MICR Service POSPrinter Service

Separate Physical Separate Physical
Device Device
RS-232 Port 1 RS-232 Port 2
Note that in this case the application running the MICR and the POSPrinter
consumes two separate ports but as far as the Application is concerned it
interfaces to the MICR and POSPrinter functionality without regard to the fact
that the two ports are used.

Device Behavior Models: Hydra Device Considerations 73
Application interfacing with a Hydra peripheral…
Application That Needs Functionality for

MICR POSPrinter
MICR POSPrinter
Control Control
Service For Hydra Device

Has Functionality for both MICR and POSPrinter In One
Physical Package
RS-232 Port 1
MICR Device Function POSPrinter Device Function
Note that in this case the application running the MICR and POSPrinter
consumes only one port but as far as the application is concerned it interfaces to
the MICR and POSPrinter functionality without regard to the fact that only one
port is used. It is up to the Hydra Service to control the port and route the
functionality to and from the proper interface.
Considerations
While the desire is to have both interconnection techniques work the same with
regards to the Application interface, problems do arise. In the Hydra case, an
error state in one of the specific device functions may block the usage of the other
function. This would not happen in the non-Hydra case since each peripheral is
truly separate.
In our Printer and MICR Hydra case, the printer running out of paper might
present a condition that would prevent reading a MICR code for instance. An
error condition of “Out of Paper” would be reported through the POSPrinter
interface but would not have any meaning to a route through the MICR interface.
The Application requesting a MICR read in the Hydra case would be presented
with an error or status condition that it would not get in the discrete MICR
peripheral case. This presents a potential “hang up” condition or unresolved error
situation.
Obviously an error condition needs to be reported to the application that is using
the MICR functionality to alert it of a problem and allow for resolution. Rather
than reporting a meaningless error of “Out of Paper” to the MICR application, a
general E_FAILURE error would be sent back to the MICR application to alert it
of the problem. The MICR application would then be responsible to go through
an error recovery procedure to rectify the situation. It would go through an error
recover operation that would present a console message informing the operator of
an impending problem with usage of the MICR device.

Operator knowledge of the specific device would then be used to correct the
problem. In this case knowing that the MICR is part of the printer would focus the
attention of the Operator to the “Paper Out” status indicator. The resolution would
be to replace the paper which would then clear the error condition for the MICR
as well as the Printer.
Notice that every attempt is made to make the interaction with the peripheral
device or Hydra peripheral device “look the same” to the application. Careful
Service design needs to be used to make sure this is accomplished. Device
vendors should define any limitations and unusual error conditions that may exist
when accessing such hydra devices in their user documentation. Application
developers should be aware of the possibility of discrete and Hydra POS devices
when crafting their software and plan their error resolution accordingly.

C H A P T E R 1
Common Properties, Methods, and Events

The following Properties, Methods, and Events are used for all device categories
unless noted otherwise in the Usage Notes table entry. For an overview of the
general rules and usage guidelines, see “Device Behavior Models” on page 44.
Summary Updated in Release 1.10
The following property list is a summary of the JavaPOS Common Properties.
This list is used throughout the main UnifiedPOS chapters. Further details may be
found in Appendix B, “Common Properties” on page B-61.
The OPOS implementation adds the following Common Properties:
BinaryConversion, OpenResult, ResultCode, and ResultCodeExtended.
Also, the last six properties are replaced by:
ControlObjectDescription, ControlObjectVersion, ServiceObjectDescription,
ServiceObjectVersion, DeviceDescription, and DeviceName.
Further details may be found in Appendix A, “Common Properties” on page A-26.
Properties (UML attributes)
Usage
Name Type Mutability Version
Notes
AutoDisable: boolean { read-write } 1.2 1
CapCompareFirmwareVersion: boolean { read-only } 1.9
CapPowerReporting: int32 { read-only } 1.3
CapStatisticsReporting: boolean { read-only } 1.8
CapUpdateFirmware: boolean { read-only } 1.9
CapUpdateStatistics: boolean { read-only } 1.8
CheckHealthText: string { read-only } 1.0
Claimed: boolean { read-only } 1.0
DataCount: int32 { read-only } 1.2 1
DataEventEnabled: boolean { read-write } 1.0 1
DeviceEnabled: boolean { read-write } 1.0
FreezeEvents: boolean { read-write } 1.0
OutputID: int32 { read-only } 1.0 2
PowerNotify: int32 { read-write } 1.3
PowerState: int32 { read-only } 1.3
State: int32 { read-only } 1.0
DeviceControlDescription: string { read-only } 1.0

DeviceControlVersion: int32 { read-only } 1.0
DeviceServiceDescription: string { read-only } 1.0
DeviceServiceVersion: int32 { read-only } 1.0
PhysicalDeviceDescription: string { read-only } 1.0
PhysicalDeviceName: string { read-only } 1.0
Usage Notes:
1.Used only with Devices that have Event Driven Input.
2.Used only with Asynchronous Output Devices.
UnifiedPOS Retail Peripheral Architecture Chapter 1
76 Common Properties, Methods, and Events
Methods (UML operations)

Name Version
open ( logicalDeviceName: string ): 1.0
void { raises-exception }
close ( ): 1.0
claima ( timeout: int32 ): 1.0
releasea ( ): 1.0
checkHealth ( level: int32 ): 1.0
clearInput ( ): 1.0
clearInputProperties ( ): 1.10
clearOutput ( ): 1.0
directIO ( command: int32, inout data: int32, inout obj: object ): 1.0
compareFirmwareVersion ( firmwareFileName: string, out result: int32 ): 1.9
resetStatistics ( statisticsBuffer: string ): 1.8
retrieveStatistics ( inout statisticsBuffer: string ): 1.8
updateFirmware ( firmwareFileName: string ): 1.9
updateStatistics ( statisticsBuffer: string ): 1.8
a. Note: In the OPOS environment starting with Release 1.5, the Claim and Release
methods are also defined as ClaimDevice and ReleaseDevice respectively
due to Release being a reserved method used by Microsoft’s Component
Object Model (COM).

Summary 77
Events (UML interfaces)

Usage
Notes
upos::events::DataEvent 1.0 1
Status: int32 { read-only }
upos::events::DirectIOEvent 1.0
EventNumber: int32 { read-only }
Data: int32 { read-write }
Obj: object { read-write }
upos::events::ErrorEvent 1.0
ErrorCode: int32 { read-only }
ErrorCodeExtended: int32 { read-only }
ErrorLocus: int32 { read-only }
ErrorResponse: int32 { read-write }
upos::events::OutputCompleteEvent 1.0 2
OutputID: int32 { read-only }
upos::events::StatusUpdateEvent 1.0
Usage Notes:

General Information
This section lists properties, methods, and events that are common to many of the
peripheral devices covered in this standard.
The summary section of each device category marks those common properties,
methods, and events that do not apply to that category as “Not Supported.” Items
identified in this fashion are not present in the Control’s class.
A good understanding of the features of the UnifiedPOS architecture model is
required. Please see “Device Behavior Models” on page 44 for additional
information.
Common PME Class Diagram Updated in Release 1.10

The following diagram shows the relationships between the Common classes.

General Information 79
<<Interface>>
BaseControl
(from upos)
<<capability>> CapCompareFirmwareVersion : boolean
<<capability>> CapPowerReporting : int32
<<capability>> CapStatisticsReporting : boolean
<<event>> <<capability>> CapUpdateFirmware : boolean
UposEvent <<capability>> CapUpdateStatistics : boolean
(from events) <<prop>> AutoDisable : boolean
fires <<prop>> CheckHealthText : string
<<prop>> Claimed : boolean
<<prop>> DataCount : int32
<<prop>> DataEventEnabled : boolean
<<prop>> DeviceEnabled : boolean
<<prop>> FreezeEvents : boolean
<<prop>> OutputID : int32
<<prop>> PowerNotify : int32
<<prop>> PowerState : int32
<<prop>> State : int32
<<prop>> DeviceControlDescription : string
<<prop>> DeviceControlVersion : int32
<<prop>> DeviceServiceDescription : string
<<prop>> DeviceServiceVersion : int32
<<prop>> PhysicalDeviceDescription : string
<<prop>> PhysicalDeviceName : string
open(logicalDeviceName : string) : void

close() : void
claim(timeout : int32) : void
compareFirmwareVersion(firmwareFileName : string, out result : int32) : void
release() : void
resetStatistics(statisticsBuffer : string) : void
checkHealth(level : int32) : void
clearInput() : void
clearInputProperties() : void
clearOutput() : void
directIO(command : int32, inout data : int32, inout obj : Object) : void
retrieveStatistics(inout statisticsBuffer : string) : void
updateFirmware(firmwareFileName : string) : void
<<uses>> updateStatistics(statisticsBuffer : string) : void
<<utility>>
UposConst <<sends>>
<<uses>> <<uses>>
(from upos) <<sends>>
<<uses>> <<exception>>
<<uses>> UposException
(from upos)
<<sends>>
<<sends>>
<<sends>>
<<Interface>> <<Interface>> <<Interface>> <<interface>>

BumpBarControl MSRControl POSPrinterControl <DevCat>Control
(from upos) (from upos) (from upos) (from upos)
<DevCat> == all UnifiedPOS device

category names e.g. CashDrawer,
POSPrinter, MICR, ...
Notes: AutoDisable, DataCount, and DataEventEnabled are used only with

Devices that have Event Driven Input.
OutputID is used only with Asynchronous Output Devices.


AutoDisable Property
Syntax AutoDisable: boolean { read-write }
Remarks If true, the UnifiedPOS Service will set DeviceEnabled to false after it receives
and enqueues data as a DataEvent. Before any additional input can be received,
the application must set DeviceEnabled to true.
If false, the UnifiedPOS Service does not automatically disable the device when
data is received.
This property provides the application with an additional option for controlling the
receipt of input data. If an application wants to receive and process only one input,
or only one input at a time, then this property should be set to true. This property
applies only to event-driven input devices.
This property is initialized to false by the open method.
Errors A UposException may be thrown when this property is accessed. For further
information, see “Errors” on page 52.
See Also “Device Input Model” on page 54.
CapCompareFirmwareVersion Property Added in Release 1.9

Syntax CapCompareFirmwareVersion: boolean { read-only, access after open }
Remarks If true, then the Service/device supports comparing the version of the firmware in
the physical device against that of a firmware file.
See Also compareFirmwareVersion Method.
CapPowerReporting Property Updated in Release 1.11

Syntax CapPowerReporting: int32 { read-only }
Remarks Identifies the reporting capabilities of the Device. It has one of the following
values:
Value Meaning
PR_NONE The UnifiedPOS Service cannot determine the state of
the device. Therefore, no power reporting is possible.
PR_STANDARD The UnifiedPOS Service can determine and report two
of the power states - OFF_OFFLINE (that is, off or
offline) and ONLINE.
PR_ADVANCED The UnifiedPOS Service can determine and report all
three power states - OFF, OFFLINE, and ONLINE.
This property is initialized by the open method.
See Also “Device Power Reporting Model” on page 58, PowerState Property,
PowerNotify Property.

Properties (UML attributes) 81
CapStatisticsReporting Property Added in Release 1.8
Syntax CapStatisticsReporting: boolean { read-only }

Remarks If true, the device accumulates and can provide various statistics regarding usage;
otherwise no usage statistics are accumulated. The information accumulated and
reported is device specific, and is retrieved using the retrieveStatistics method.
See Also retrieveStatistics Method.
CapUpdateFirmware Property Added in Release 1.9

Syntax CapUpdateFirmware: boolean { read-only, access after open }
Remarks If true, then the device’s firmware can be updated via the updateFirmware
method.
See Also updateFirmware Method.
CapUpdateStatistics Property Added in Release 1.8
Syntax CapUpdateStatistics: boolean { read-only }

Remarks If true, the device statistics, or some of the statistics, can be reset to zero using the
resetStatistics method, or updated using the updateStatistics method.
If CapStatisticsReporting is false, then CapUpdateStatistics is also false.
See Also CapStatisticsReporting Property, resetStatistics Method, updateStatistics
Method.
CheckHealthText Property
Syntax CheckHealthText: string { read-only }
Remarks Holds the results of the most recent call to the checkHealth method. The
following examples illustrate some possible diagnoses:
• “Internal HCheck: Successful”
• “External HCheck: Not Responding”
• “Interactive HCheck: Complete”
This property is empty (“”) before the first call to the checkHealth method.
information, see “Errors” on page 52
See Also checkHealth Method.

Claimed Property
Syntax Claimed: boolean { read-only }
Remarks If true, the device is claimed for exclusive access. If false, the device is released
for sharing with other applications.
Many devices must be claimed before the Control will allow access to many of its
methods and properties, and before it will deliver events to the application.
See Also “Device Initialization and Finalization” on page 46, “Device Sharing Model” on
page 50, claim Method, release Method.
DataCount Property
Syntax DataCount: int32 { read-only }
Remarks Holds the number of enqueued DataEvents.
The application may read this property to determine whether additional input is
enqueued from a device, but has not yet been delivered because of other
application processing, freezing of events, or other causes.
This property is initialized to zero by the open method.
See Also “Device Input Model” on page 54, DataEvent.
DataEventEnabled Property
Syntax DataEventEnabled: boolean { read-write }
Remarks If true, a DataEvent will be delivered as soon as input data is enqueued. If changed
to true and some input data is already queued, then a DataEvent is delivered
immediately. (Note that other conditions may delay “immediate” delivery: if
FreezeEvents is true or another event is already being processed at the
application, the DataEvent will remain queued at the UnifiedPOS Service until
the condition is corrected.)
If false, input data is enqueued for later delivery to the application. Also, if an input
error occurs, the ErrorEvent is not delivered while this property is false.
See Also “Events” on page 51, DataEvent.

DeviceControlDescription Property
Syntax DeviceControlDescription: string { read-only }
Remarks Holds an identifier for the UnifiedPOS Control and the company that produced it.
A sample returned string is:
“POS Printer UnifiedPOS Compatible Control, (C) 1998
Epson”
This property is always readable.
Errors None.
See Also DeviceControlVersion Property.
DeviceControlVersion Property
Syntax DeviceControlVersion: int32 { read-only }
Remarks Holds the UnifiedPOS Control version number.
Three version levels are specified, as follows:
Version Level Description
Major The “millions” place.

A change to the UnifiedPOS major version level for a
device class reflects significant interface enhancements,
and may remove support for obsolete interfaces from
previous major version levels.
Minor The “thousands” place.
A change to the UnifiedPOS minor version level for a
device class reflects minor interface enhancements, and
must provide a superset of previous interfaces at this
major version level.
Build The “units” place.
Internal level provided by the UnifiedPOS Control
developer. Updated when corrections are made to the
UnifiedPOS Control implementation.
A sample version number is:

1002038
This value may be displayed as version “1.2.38”, and interpreted as major

version 1, minor version 2, build 38 of the UnifiedPOS Control.
Errors None.
See Also “Version Handling” on page 68, DeviceControlDescription Property.

DeviceEnabled Property
Syntax DeviceEnabled: boolean { read-write }
Remarks If true, the device is in an operational state. If changed to true, then the device is
brought to an operational state.
If false, the device has been disabled. If changed to false, then the device is
physically disabled when possible, any subsequent input will be discarded, and
output operations are disallowed.
Changing this property usually does not physically affect output devices. For
consistency, however, the application must set this property to true before using
output devices.
The Device’s power state may be reported while DeviceEnabled is true; See
“Device Power Reporting Model” on page 58 for details.
This property is initialized to false by the open method. Note that an exclusive use
device must be claimed before the device may be enabled.
See Also “Device Initialization and Finalization” on page 46.
DeviceServiceDescription Property
Syntax DeviceServiceDescription: string { read-only }
Remarks Holds an identifier for the UnifiedPOS Service and the company that produced it.
“TM-U950 Printer UnifiedPOS Compatible Service Driver,
(C) 1998 Epson”


DeviceServiceVersion Property
Syntax DeviceServiceVersion: int32 { read-only }
Remarks Holds the UnifiedPOS Service version number.

A change to the UnifiedPOS major version level for a
A change to the UnifiedPOS minor version level for a
Internal level provided by the UnifiedPOS Service
developer. Updated when corrections are made to the
UnifiedPOS Service implementation.

1002038
This value may be displayed as version “1.2.38”, and interpreted as major version
1, minor version 2, build 38 of the UnifiedPOS Service.
See Also “Version Handling” on page 68, DeviceServiceDescription Property.

FreezeEvents Property Updated in Release 1.12

Syntax FreezeEvents: boolean { read-write }
Remarks If true, the UnifiedPOS Control will not deliver events. Events will be enqueued
until this property is set to false.
If false, the application allows events to be delivered. If some events have been
held while events were frozen and all other conditions are correct for delivering
the events, then changing this property to false will allow these events to be
delivered. An application may choose to freeze events for a specific sequence of
code where interruption by an event is not desirable.
regardless of the setting of this property.
OutputID Property
Syntax OutputID: int32 { read-only }
Remarks Holds the identifier of the most recently started asynchronous output.
When a method successfully initiates an asynchronous output, the Device assigns
an identifier to the request. When the output completes, an
OutputCompleteEvent will be enqueued with this output ID as a parameter.
The output ID numbers are assigned by the UnifiedPOS Service and are
guaranteed to be unique among the set of outstanding asynchronous outputs. No
other facts about the ID should be assumed.
See Also “Device Output Models” on page 57, OutputCompleteEvent.

PowerNotify Property
Syntax PowerNotify: int32 { read-write }
Remarks Contains the type of power notification selection made by the Application. It has
one of the following values:
Value Meaning
PN_DISABLED The UnifiedPOS Service will not provide any power

notifications to the application. No power notification
StatusUpdateEvents will be fired, and PowerState
may not be set.
PN_ENABLED The UnifiedPOS Service will fire power notification
StatusUpdateEvents and update PowerState,
beginning when DeviceEnabled is set to true. The level
of functionality depends upon CapPowerReporting.
PowerNotify may only be set while the device is disabled; that is, while
DeviceEnabled is false.
This property is initialized to PN_DISABLED by the open method. This value
provides compatibility with earlier releases.
Some possible values of the exception’s ErrorCode property are:
Value Meaning
E_ILLEGAL One of the following occurred:

• The device is already enabled.
• PowerNotify = PN_ENABLED but
CapPowerReporting = PR_NONE.
See Also “Device Power Reporting Model” on page 58, CapPowerReporting Property,
PowerState Property.

PowerState Property Updated in Release 1.11

Syntax PowerState: int32 { read-only }
Remarks Identifies the current power condition of the device, if it can be determined.
It has one of the following values:
Value Meaning
PS_UNKNOWN Cannot determine the device’s power state for one of the
following reasons:
CapPowerReporting = PR_NONE; the device does not

support power reporting.
PowerNotify = PN_DISABLED; power notifications

are disabled.
DeviceEnabled = false; Power state monitoring does

not occur until the device is enabled.
PS_ONLINE The device is powered on and ready for use. Can be
returned if CapPowerReporting = PR_STANDARD or
PR_ADVANCED.
PS_OFF The device is powered off or detached from the POS
terminal. Can only be returned if CapPowerReporting
= PR_ADVANCED.
PS_OFFLINE The device is powered on but is either not ready or not
able to respond to requests. Can only be returned if
CapPowerReporting = PR_ADVANCED.
PS_OFF_OFFLINE The device is either off or offline. Can only be returned
if CapPowerReporting = PR_STANDARD.
This property is initialized to PS_UNKNOWN by the open method. When
PowerNotify is set to enabled and DeviceEnabled is true, then this property is
updated as the UnifiedPOS Service detects power condition changes.
See Also “Device Power Reporting Model” on page 58, CapPowerReporting Property,
PowerNotify Property.

PhysicalDeviceDescription Property
Syntax PhysicalDeviceDescription: string { read-only }
Remarks Holds an identifier for the physical device.
“NCR 7192-0184 Printer, Japanese Version”

See Also PhysicalDeviceName Property.
PhysicalDeviceName Property
Syntax PhysicalDeviceName: string { read-only }
Remarks Holds a short name identifying the physical device. This is a short version of
PhysicalDeviceDescription and should be limited to 30 characters.
This property will typically be used to identify the device in an application
message box, where the full description is too verbose. A sample returned string is:
“IBM Model II Printer, Japanese”

See Also PhysicalDeviceDescription Property.

State Property
Syntax State: int32 { read-only }
Remarks Holds the current state of the Device. It has one of the following values:
Value Meaning
S_CLOSED The Device is closed.

S_IDLE The Device is in a good state and is not busy.
S_BUSY The Device is in a good state and is busy performing
output.
S_ERROR An error has been reported, and the application must
recover the Device to a good state before normal I/O can
resume.
Errors None.
See Also “Device Information Reporting Model” on page 62.

Methods (UML operations) 91
checkHealth Method
Syntax checkHealth ( level: int32 ):
The level parameter indicates the type of health check to be performed on the
device. The following values may be specified:
Value Meaning
CH_INTERNAL Perform a health check that does not physically change
the device. The device is tested by internal tests to the
extent possible.
CH_EXTERNAL Perform a more thorough test that may change the
device. For example, a pattern may be printed on the
printer.
CH_INTERACTIVE Perform an interactive test of the device. The supporting
UnifiedPOS Service will typically display a modal
dialog box to present test options and results.
Remarks Tests the state of a device.
A text description of the results of this method is placed in the
CheckHealthText property. The health of many devices can only be determined
by a visual inspection of these test results.
This method is always synchronous.
Errors A UposException may be thrown when this method is invoked. For further
Value Meaning
E_ILLEGAL The specified health check level is not supported by the
UnifiedPOS Service.
See Also CheckHealthText Property.

claim Method Updated in Release 1.11
Syntax claim ( timeout: int32 ):

The timeout parameter gives the maximum number of milliseconds to wait for
exclusive access to be satisfied. If zero, then immediately either returns (if
successful) or throws an appropriate exception. If FOREVER (-1), the method
waits as long as needed until exclusive access is satisfied.
Remarks Requests exclusive access to the device. Many devices require an application to
claim them before they can be used.
When successful, the Claimed property is changed to true.
Value Meaning
E_ILLEGAL This device cannot be claimed for exclusive access, or
an invalid timeout parameter was specified.
E_TIMEOUT Another application has exclusive access to the device,
and did not relinquish control before timeout
milliseconds expired.
See Also “Device Initialization and Finalization” on page 46, “Device Sharing Model” on
page 50, release Method.
clearInput Method
Syntax clearInput ( ):
Remarks Clears all device input that has been buffered.
Any data events or input error events that are enqueued – usually waiting for
DataEventEnabled to be set to true and FreezeEvents to be set to false – are also
cleared.

clearInputProperties Method Added in Release 1.10
Syntax clearInputProperties ( ):
Remarks Sets all data properties that were populated as a result of firing a DataEvent or
ErrorEvent back to their default values. This does not reset the DataCount or
State properties.
clearOutput Method Updated in Release 1.7

Syntax clearOutput ( ):
Remarks Clears all buffered output data, including all asynchronous output. Also, when
possible, halts outputs that are in progress.
Any output error events that are enqueued – usually waiting for FreezeEvents to
be set to false – are also cleared.
See Also “Device Output Models” on page 57.
close Method
Syntax close ( ):
Remarks Releases the device and its resources.
If the DeviceEnabled property is true, then the device is disabled.
If the Claimed property is true, then exclusive access to the device is released.
See Also “Device Initialization and Finalization” on page 46, open Method.

compareFirmwareVersion Method Added in Release 1.9

Syntax compareFirmwareVersion ( firmwareFileName: string, out result: int32 ):
void { raises-exception, use after open-claim-enable }
Parameter Description
firmwareFileName Specifies either the name of the file containing the
firmware or a file containing a set of firmware files
whose versions are to be compared against those of the
device.
result Location in which to return the result of the comparison.
Remarks This method determines whether the version of the firmware contained in the
specified file is newer than, older than, or the same as the version of the firmware
in the physical device.
The Service should check that the specified firmware file exists and that its
contents are valid for this device before attempting to perform the comparison
operation.
The result of the comparison is returned in the result parameter and will be one of
the following values:
Value Meaning
CFV_FIRMWARE_OLDER Indicates that the version of one or more of the
firmware files is older than the firmware in the
device and that none of the firmware files is
newer than the firmware in the device.
CFV_FIRMWARE_SAME Indicates that the versions of all of the firmware
files are the same as the firmware in the device.
CFV_FIRMWARE_NEWER Indicates that the version of one or more of the
firmware files is newer than the firmware in the
older than the firmware in the device.
CFV_FIRMWARE_DIFFERENT
Indicates that the version of one or more of the
firmware files is different than the firmware in
the device, but either:
• The chronological relationship cannot be
determined, or
• The relationship is inconsistent -- one or
more are older while one or more are newer.
CFV_FIRMWARE_UNKNOWN
Indicates that a relationship between the two
firmware versions could not be determined. A
possible reason for this result could be an
attempt to compare Japanese and US versions
of firmware.
If the firmwareFileName parameter specifies a file list, all of the component
firmware files should reside in the same directory as the firmware list file. This
will allow for distribution of the updated firmware without requiring a
modification to the firmware list file.

Value Meaning
E_ILLEGAL CapCompareFirmwareVersion is false.
E_NOEXIST The file specified by firmwareFileName does not exist
or, if firmwareFileName specifies a file list, one or more
of the component firmware files are missing.
E_EXTENDED ErrorCodeExtended = EFIRMWARE_BAD_FILE:
The specified firmware file or files exist, but one or
more are either not in the correct format or are corrupt.
See Also CapCompareFirmwareVersion Property.
directIO Method
Syntax directIO ( command: int32, inout data: int32, inout obj: object ):
command Command number whose specific values are assigned
by the UnifiedPOS Service.
data An array of one mutable integer whose specific values
or usage vary by command and UnifiedPOS Service.
obj Additional data whose usage varies by command and
UnifiedPOS Service.
Remarks Communicates directly with the UnifiedPOS Service.
This method provides a means for a UnifiedPOS Service to provide functionality
to the application that is not otherwise supported by the standard UnifiedPOS
Control for its device category. Depending upon the UnifiedPOS Service’s
definition of the command, this method may be asynchronous or synchronous.
Use of this method will make an application non-portable. The application may,
however, maintain portability by performing directIO calls within conditional
code. This code may be based upon the value of the DeviceServiceDescription,
PhysicalDeviceDescription, or PhysicalDeviceName property.
See Also DirectIOEvent.

open Method Updated in Release 1.7

Syntax open ( logicalDeviceName: string ):
The logicalDeviceName parameter specifies the device name to open.
Remarks Opens a device for subsequent I/O.
The device name specifies which of one or more devices supported by this
UnifiedPOS Control should be used. The logicalDeviceName must exist in the
operating system’s reference locator system (such as the JavaPOS Configurator/
Loader (JCL) or the Window’s Registry) for this device category so that its
relationship to the physical device can be determined. Entries in the reference
locator system are created by a setup or configuration utility.
The following sequence diagram shows the details of what needs to happen during
the open method call processing to allow the creation of the Service and its binding
to the Control.
NOTE: shows the details of what should happen at open() time. This diagram tries to be generic w/o reference to particular
platform. Note also, that some platform binding might have "easier" or "harder" API to accomplish the same task.
:ClientApp :<DevCat> :Config :Loader :<DevCat>

(registry of service properties) Service
NOTE1: we are assuming that the :Config object has or can obtain at runtime the configuration information for the
services that will be used. In particular the <DevCat> device is configured with logical name named "logicalName"
NOTE2: <DevCat> is a moniker for a generic control and DevCat == POSPrinter, Keylock, CashDrawer, ... all the
UnifiedPOS device categories
1: open(logicalName) 2: find properties of service with logicalName
3: pass loader properties and ask to create service
4: loader parses properties and loads the <DevCat>Service
5: create and/or bind to service
6: return service instance to control
The details of these steps might vary per platform and the
Config and Loader could be done by the same entity.
However, logically the actions above are happening on the
system.
When this method is successful, it initializes the properties Claimed,

DeviceEnabled, DataEventEnabled, and FreezeEvents, as well as descriptions
and version numbers of the UnifiedPOS software layers. Additional category-
specific properties may also be initialized.


Value Meaning
E_ILLEGAL The UnifiedPOS Control is already open.
E_NOEXIST The specified logicalDeviceName was not found.
E_NOSERVICE Could not establish a connection to the corresponding
UnifiedPOS Service.
See Also “Device Initialization and Finalization” on page 46, “Version Handling” on page
68, close Method.
release Method
Syntax release ( ):
Remarks Releases exclusive access to the device.
If the DeviceEnabled property is true, and the device is an exclusive-use device,
then the device is also disabled (this method does not change the device enabled
state of sharable devices).
Value Meaning
E_ILLEGAL The application does not have exclusive access to the
device.
See Also “Device Sharing Model” on page 50, claim Method.
resetStatistics Method Updated in Release 1.10

Syntax resetStatistics ( statisticsBuffer: string ):
statisticsBuffer The data buffer defining the statistics that are to be reset.
This is a comma-separated list of name(s), where an empty string (“”) means ALL
resettable statistics are to be reset, “U_” means all UnifiedPOS defined resettable
statistics are to be reset, “M_” means all manufacturer defined resettable statistics
are to be reset, and “actual_name1, actual_name2” (from the XML file definitions)
means that the specifically defined resettable statistic(s) are to be reset.
Remarks Resets the defined resettable statistics in a device to zero. All the requested
statistics must be successfully reset in order for this method to complete
successfully, otherwise an ErrorCode of E_EXTENDED is returned.
Both CapStatisticsReporting and CapUpdateStatistics must be true in order to
successfully use this method.
This method is always executed synchronously.

Value Meaning
E_ILLEGAL CapStatisticsReporting or CapUpdateStatistics is
false, or the named statistic is not defined/resettable.
E_EXTENDED ErrorCodeExtended = ESTATS_ERROR:
At least one of the specified statistics could not be reset.
ErrorCodeExtended = ESTATS_DEPENDENCY:
At least one other statistic is required to be reset in
addition to a requested statistic.
See Also CapStatisticsReporting Property, CapUpdateStatistics Property.
retrieveStatistics Method Added in Release 1.8

Syntax retrieveStatistics ( inout statisticsBuffer: string ):
statisticsBuffer The data buffer defining the statistics to be retrieved and
in which the retrieved statistics are placed.
statistics are to be retrieved, “U_” means all UnifiedPOS defined statistics are to
be retrieved, “M_” means all manufacturer defined statistics are to be retrieved,
and “actual_name1, actual_name2” (from the XML file definitions) means that the
specifically defined statistic(s) are to be retrieved.
Remarks Retrieves the requested statistics from a device.
CapStatisticsReporting must be true in order to successfully use this method.
All calls to retrieveStatistics will return the following XML as a minimum:
<Event>
<Parameter>
<Name>RequestedStatistic</Name>
<Value>1234</Value>
</Parameter>
</Event>
<Equipment>
</Equipment>
</UPOSStat>

If the application requests a statistic name that the device does not support, the
<Parameter> entry will be returned with an empty <Value>. e.g.,
<Parameter>
<Value></Value>
</Parameter>
All statistics that the device collects that are manufacturer specific (not defined in the
schema) will be returned in a <ManufacturerSpecific> tag instead of a <Parameter>
tag. e.g.,
<Name>TheAnswer</Name>
<Value>42</Value>
When an application requests all statistics from the device, the device will return a
<Parameter> entry for every defined statistic for the device category as defined by the
XML schema version specified by the version attribute in the <UPOSStat> tag. If the
device does not record any of the statistics, the <Value> tag will be empty.
The most up-to-date files defining the XML tag names and example schemas for the
statistics for all device categories can be downloaded from the NRF-ARTS web site at
http://www.nrf-arts.org.
Value Meaning
E_ILLEGAL CapStatisticsReporting is false or the named statistic is
not defined.
See Also CapStatisticsReporting Property.
updateFirmware Method Added in Release 1.9

Syntax updateFirmware ( firmwareFileName: string ):
firmware or a file containing a set of firmware files that
are to be downloaded into the device.
Remarks This method updates the firmware of a device with the version of the firmware
contained or defined in the file specified by the firmwareFileName parameter
regardless of whether that firmware’s version is newer than, older than, or the
same as the version of the firmware already in the device. If the firmwareFileName
parameter specifies a file list, all of the component firmware files should reside in
the same directory as the firmware list file. This will allow for distribution of the
updated firmware without requiring a modification to the firmware list file.
When this method is invoked, the Service should check that the specified firmware
file exists and that its contents are valid for this device. If so, this method should
return immediately and the remainder of the update firmware process should
continue asynchronously.

The Service should notify the application of the status of the update firmware
process by firing StatusUpdateEvents with values of SUE_UF_PROGRESS + an
integer between 1 and 100 indicating the completion percentage of the update
firmware process. For application convenience, the StatusUpdateEvent value
SUE_UF_COMPLETE is defined to be the same value as SUE_UF_PROGRESS
+ 100.
For consistency, the update firmware process is complete after the new firmware
has been downloaded into the physical device, any necessary physical device reset
has completed, and the Service and the physical device have been returned to the
state they were in before the update firmware process began.
For consistency, a Service must always fire at least one StatusUpdateEvent with
an incomplete progress completion percentage (i.e. a percentage between 1 and
99), even if the device cannot physically report the progress of the update firmware
process. If the update firmware process completes successfully, the Service must
fire a StatusUpdateEvent with a progress of 100 or use the special constant
SUE_UF_COMPLETE, which has the same value. These Service requirements
allow applications using this method to be designed to always expect some level
of progress notification.
If an error is detected during the asynchronous portion of a update firmware
process, one of the following StatusUpdateEvents will be fired:
Value Meaning
SUE_UF_FAILED_DEV_OK The update firmware process failed but the
device is still operational.
SUE_UF_FAILED_DEV_UNRECOVERABLE
The update firmware process failed and the
device is neither usable nor recoverable
through software. The device requires service
to be returned to an operational state.
SUE_UF_FAILED_DEV_NEEDS_FIRMWARE
device will not be operational until another
attempt to update the firmware is successful.
SUE_UF_FAILED_DEV_UNKNOWN
device is in an indeterminate state.
Value Meaning
E_ILLEGAL CapUpdateFirmware is false.
E_NOEXIST The file specified by firmwareFileName does not exist
E_EXTENDED ErrorCodeExtended = EFIRMWARE_BAD_FILE:
See Also CapUpdateFirmware Property.

updateStatistics Method Updated in Release 1.10
Syntax updateStatistics ( statisticsBuffer: string ):

statisticsBuffer The data buffer defining the statistics with values that
are to be updated.
This is a comma-separated list of name-value pair(s), where an empty string name
(““”=value1”) means ALL resettable statistics are to be set to the value “value1”,
“U_=value2” means all UnifiedPOS defined resettable statistics are to be set to the
value “value2”, “M_=value3” means all manufacturer defined resettable statistics
are to be set to the value “value3”, and “actual_name1=value4,
actual_name2=value5” (from the XML file definitions) means that the specifically
defined resettable statistic(s) are to be set to the specified value(s).
Remarks Updates the defined resettable statistics in a device. All the requested statistics
must be successfully updated in order for this method to complete successfully,
otherwise an ErrorCode of E_EXTENDED is returned.
Value Meaning
E_ILLEGAL CapStatisticsReporting or CapUpdateStatistics is
false, or the named statistic is not defined/updatable.
E_EXTENDED ErrorCodeExtended = ESTATS_ERROR:
At least one of the specified statistics could not be
updated.
ErrorCodeExtended = ESTATS_DEPENDENCY:
At least one other statistic is required to be updated in
addition to a requested statistic.

The UnifiedPOS standard utilizes a common UML base control structure to derive
a specific implementation case. The UML event base control model and interfaces
are shown below for the events.
upos::BaseControl
<<utility>>
UposConst
(from upos)
<<uses>>
<<event>> <<Interface>>
fires
UposEvent BaseControl
(from events) (from upos)
<<sends>>
<<exception>>
UposException
(from upos)

Events (UML interfaces) 103
upos::events interfaces
<<event>>
UposEvent
(from events)
<<event>> <<event>>
DataEvent OutputCompleteEvent
(from events) (from events)
<<prop>> Status : int32 <<prop>> OutputID : int32
<<event>> <<event>>
DirectIOEvent StatusUpdateEvent
(from events) (from events)
<<prop>> EventNumber : int32 <<prop>> Status : int32
<<prop>> Data : int32
<<prop>> Obj : object
<<event>>
ErrorEvent
(from events)
<<prop>> ErrorCode : int32
<<prop>> ErrorCodeExtended : int32
<<prop>> ErrorLocus : int32
<<prop>> ErrorResponse : int32

DataEvent
<<event>> upos::events::DataEvent
Description Notifies the application that input data is available from the device.
Attribute This event contains the following attribute:

Attribute Type Description
Status int32 The input status with its value dependent upon the
device category; it may describe the type or qualities of
the input data.
Remarks When this event is delivered to the application, the DataEventEnabled property
is changed to false, so that no further data events will be delivered until the
application sets DataEventEnabled back to true. The actual byte array input data
is placed in one or more device-specific properties.
If DataEventEnabled is false at the time that data is received, then the data is
enqueued in an internal buffer, the device-specific input data properties are not
updated, and the event is not delivered. When DataEventEnabled is subsequently
changed back to true, the event will be delivered immediately if input data is
enqueued and FreezeEvents is false.
See Also “Events” on page 51, “Device Input Model” on page 54, DataEventEnabled
Property, FreezeEvents Property.

DirectIOEvent Updated in Release 1.7
<<event>> upos::events::DirectIOEvent
Description Provides UnifiedPOS Service information directly to the application. This event
provides a means for a vendor-specific UnifiedPOS Service to provide events to
the application that are not otherwise supported by the UnifiedPOS Control.
Attributes This event contains the following attributes:
EventNumber int32 Event number whose specific values are assigned by the
UnifiedPOS Service.
Data int32 Additional numeric data. Specific values vary by the
EventNumber and the UnifiedPOS Service. This
attribute is settable.
Obj object Additional data whose usage varies by the EventNumber
and the UnifiedPOS Service. This attribute is settable.1
Remarks This event is to be used only for those types of vendor specific functions that are
not otherwise described as part of the UnifiedPOS standard. Use of this event may
restrict the application program from being used with other vendor’s devices
which may not have any knowledge of the UnifiedPOS Service’s need for this
event.
See Also “Events” on page 51, directIO Method.
1. In the OPOS environment, the format of this data depends upon the value of the
BinaryConversion property. See BinaryConversion property on page A-29.

ErrorEvent Updated in Release 1.12

<<event>> upos::events::ErrorEvent
Description Notifies the application that an error has been detected and a suitable response is
necessary to process the error condition.
ErrorCode int32 Error Code causing the error event. See the list of
ErrorCodes under “Error Codes” on page 52.
ErrorCodeExtended
int32 Extended Error Code causing the error event. These
values are device category specific.
ErrorLocus int32 Location of the error. See values below.
ErrorResponse int32 Error response, whose default value may be overridden
by the application (i.e., this attribute is settable). See
values below.
The ErrorLocus attribute has one of the following values:

Value Meaning
EL_OUTPUT Error occurred while processing asynchronous output.
EL_INPUT Error occurred while gathering or processing event-
driven input. No previously buffered input data is
available.
EL_INPUT_DATA Error occurred while gathering or processing event-
driven input, and some previously buffered data is
available.
The application’s error event handler can set the ErrorResponse attribute to one of
Value Meaning
ER_RETRY Retry the input or asynchronous output. The error state
is exited.
May be valid only when locus is EL_INPUT. Default
when locus is EL_OUTPUT.
ER_CLEAR Clear all buffered output data (including all
asynchronous output) or buffered input data. The error
state is exited. Default when locus is EL_INPUT.

ER_CONTINUEINPUT
Acknowledges the error and directs the Device to
continue input processing. The Device remains in the
error state and will deliver additional DataEvents as
input has been delivered and DataEventEnabled is
again set to true, then another ErrorEvent is delivered
with locus EL_INPUT.
Use only when locus is EL_INPUT_DATA. Default
when locus is EL_INPUT_DATA.
Remarks This event is enqueued when an error is detected and the Device’s State transitions
into the error state. Input error events are not delivered until DataEventEnabled
is true, so that proper application sequencing occurs.
See Also “Device Input Model” on page 54, “Device Information Reporting Model” on
page 62.
OutputCompleteEvent
<<event>> upos::events::OutputCompleteEvent
Description Notifies the application that the queued output request associated with the
OutputID attribute has completed successfully.
OutputID int32 The ID number of the asynchronous output request that
is complete.
Remarks This event is enqueued after the request’s data has been both sent and the
UnifiedPOS Service has confirmation that is was processed by the device
successfully.

StatusUpdateEvent Updated in Release 1.9

<<event>> upos::events::StatusUpdateEvent
Description Notifies the application when a device has detected an operation status change.

Status int32 Device category-specific status, describing the type of
status change.
Release 1.3 and later – Power State Reporting
Power State Reporting, added in Release 1.3, adds additional Status values of:
Value Meaning
SUE_POWER_ONLINE
The device is powered on and ready for use. Can be
returned if CapPowerReporting =
PR_STANDARD or PR_ADVANCED.
SUE_POWER_OFF The device is off or detached from the terminal. Can
only be returned if CapPowerReporting =
PR_ADVANCED.
SUE_POWER_OFFLINE
The device is powered on but is either not ready or not
CapPowerReporting = PR_ADVANCED.
SUE_POWER_OFF_OFFLINE
The device is either off or offline. Can only be returned
if CapPowerReporting = PR_STANDARD.
The common property PowerState is also maintained at the current power state of
the device.
Release 1.9 and later – Update Firmware Reporting

The Update Firmware capability, added in Release 1.9, adds the following Status
values for communicating the status/progress of an asynchronous update firmware
process:
Value Meaning
SUE_UF_PROGRESS + 1 to 100
The update firmware process has successfully
completed 1 to 100 percent of the total operation.
SUE_UF_COMPLETE The update firmware process has completed
successfully. The value of this constant is identical to
SUE_UF_PROGRESS + 100.

SUE_UF_COMPLETE_DEV_NOT_RESTORED
The update firmware process succeeded, however the
Service and/or the physical device cannot be returned to
the state they were in before the update firmware
process started. The Service has restored all properties
to their default initialization values.
To ensure consistent Service and physical device states,
the application needs to close the Service, then open,
claim, and enable again, and also restore all custom
application settings.
SUE_UF_FAILED_DEV_OK
The update firmware process failed but the device is still
operational.
The update firmware process failed and the device is
neither usable nor recoverable through software. The
device requires service to be returned to an operational
state.
The update firmware process failed and the device will
not be operational until another attempt to update the
firmware is successful.
The update firmware process failed and the device is in
an indeterminate state.
Remarks This event is enqueued when a Device needs to alert the application of a device
status change. Examples are a change in the cash drawer position (open vs. closed)
or a change in a POS printer sensor (form present vs. absent).
When a device is enabled, the Control may deliver this event to inform the
application of the device state. This behavior, however, is not required.
See Also “Events” on page 51, “Device Power Reporting Model” on page 58,
CapPowerReporting Property, CapUpdateFirmware Property, PowerNotify
Property.


C H A P T E R 2
Belt
This Chapter defines the Belt device category.
Summary
Common Type Mutability Version May Use After
AutoDisable: boolean { read-write } 1.12 Not Supported
CapCompareFirmwareVersion: boolean { read-only } 1.12 open
CapPowerReporting: int32 { read-only } 1.12 open
CapStatisticsReporting: boolean { read-only } 1.12 open
CapUpdateFirmware: boolean { read-only } 1.12 open
CapUpdateStatistics: boolean { read-only } 1.12 open
CheckHealthText: string { read-only } 1.12 open
Claimed: boolean { read-only } 1.12 open
DataCount: int32 { read-only } 1.12 Not Supported
DataEventEnabled: boolean { read-write } 1.12 Not Supported
DeviceEnabled: boolean { read-write } 1.12 open & claim
FreezeEvents: boolean { read-write } 1.12 open
OutputID: int32 { read-only } 1.12 Not Supported
PowerNotify: int32 { read-write } 1.12 open
PowerState: int32 { read-only } 1.12 open
State: int32 { read-only } 1.12 --
DeviceControlDescription: string { read-only } 1.12 --

DeviceControlVersion: int32 { read-only } 1.12 --
DeviceServiceDescription: string { read-only } 1.12 open
DeviceServiceVersion: int32 { read-only } 1.12 open
PhysicalDeviceDescription: string { read-only } 1.12 open
PhysicalDeviceName: string { read-only } 1.12 open
112 Belt
Properties (Continued)
Specific Type Mutability Version May Use After
CapAutoStopBackward: boolean { read-only } 1.12 open
CapAutoStopBackwardItemCount: boolean { read-only } 1.12 open
CapAutoStopForward: boolean { read-only } 1.12 open
CapAutoStopForwardItemCount: boolean { read-only } 1.12 open
CapLightBarrierBackward: boolean { read-only } 1.12 open
CapLightBarrierForward: boolean { read-only } 1.12 open
CapMoveBackward: boolean { read-only } 1.12 open
CapSecurityFlapBackward: boolean { read-only } 1.12 open
CapSecurityFlapForward: boolean { read-only } 1.12 open
CapSpeedStepsBackward: int32 { read-only } 1.12 open
CapSpeedStepsForward: int32 { read-only } 1.12 open
AutoStopBackward: boolean { read-write } 1.12 open

AutoStopBackwardDelayTime: int32 { read-write } 1.12 open
AutoStopBackwardItemCount: int32 { read-only } 1.12 open
AutoStopForward: boolean { read-write } 1.12 open
AutoStopForwardDelayTime: int32 { read-write } 1.12 open
AutoStopForwardItemCount: int32 { read-only } 1.12 open
LightBarrierBackwardInterrupted: boolean { read-only } 1.12 open, claim, & enable
LightBarrierForwardInterrupted: boolean { read-only } 1.12 open, claim, & enable
MotionStatus: int32 { read-only } 1.12 open, claim, & enable
SecurityFlapBackwardOpened: boolean { read-only } 1.12 open, claim, & enable
SecurityFlapForwardOpened: boolean { read-only } 1.12 open, claim, & enable

Common
Name Version
close ( ): 1.12
void { raises-exception, use after open }
claim ( timeout: int32 ): 1.12
release ( ): 1.12
void { raises-exception, use after open, claim }
void { raises-exception, use after open, enable }
clearInput ( ): Not
void { } supported

Summary 113
clearInputProperties ( ): Not
void { } supported
clearOutput ( ): Not
void { } supported
Specific
Name
adjustItemCount ( direction: int32, count: int32 ): 1.12
void { raises-exception, use after open, claim, enable }
moveBackward ( speed: int32 ): 1.12
moveForward ( speed: int32 ): 1.12
resetBelt ( ): 1.12
resetItemCount ( direction: int32 ): 1.12
stopBelt ( ): 1.12

114 Belt

upos::events::DataEvent Not Supported
upos::events::ErrorEvent Not Supported
upos::events::OutputCompleteEvent Not Supported

General Information
The Belt programmatic name is “Belt”.

This device category was added to Version 1.12 of the specification.
Capabilities
The Belt Control has the following capability:

• Supports a command to move the belt in forward direction.
• Supports commands to stop and reset the belt.
The Belt may have several additional capabilities, these are moving in backward
direction, moving with different speeds, light barriers, security flap, controlling an
automatic stop and emergency stop. See the Model section and the capabilities
properties for specific information.

116 Belt
Belt Class Diagram

The following diagram shows the relationships between the Belt classes.
«exception» «interface» «utility» «utility»

UposException «sends» BaseControl «uses» UposConst BeltConst
«sends» «uses»
«interface»
BeltControl
+CapAutoStopBackward : boolean
+CapAutoStopBackwardItemCount : boolean
+CapAutoStopForward : boolean
+CapAutoStopForwardItemCount : boolean
+CapLightBarrierBackward : boolean
+CapLightBarrierForward : boolean
+CapMoveBackward : boolean
+CapSecurityFlapBackward : boolean
+CapSecurityFlapForward : boolean
+CapSpeedStepsBackward : int32
+CapSpeedStepsForward : int32
+AutoStopBackward : boolean
+AutoStopBackwardDelayTime : int32
+AutoStopBackwardItemCount : int32
+AutoStopForward : boolean
+AutoStopForwardDelayTime : int32
+AutoStopForwardItemCount : int32
+LightBarrierBackwardInterrupted : boolean
+LightBarrierForwardInterrupted : boolean
+MotionStatus : int32
+SecurityFlapBackwardOpened : boolean
+SecurityFlapForwardOpened : boolean
+adjustItemCount(direction : int32, count : int32) : void

+moveBackward(speed : int32) : void
+moveForward(speed : int32) : void
+resetBelt() : void
+resetItemCount(direction : int32) : void
+stopBelt() : void
«fires» «fires»
«event» «event»
StatusUpdateEvent DirectIOEvent
+Status : int32 +EventNumber : int32
+Data : int32
+Obj : object

Belt Sequence Diagram

The following sequence diagram shows the typical usage of the Belt device during
an automatic stop scenario.
NOTE: We are assuming that the Application has already successfully opened and claimed the Belt Device
and is registered to receive events from the control. The belt should automatically stop after five items passing
the light barrier, that means CapAutoStopForward and CapAutoStopForwardItemCount are true.
Application Belt Control Belt Service Belt
1: setDeviceEnabled(true)
3: connect or somehow have
access to the hardware
4: adjustItemCount
(BELT_AIC_FORWARD, 5)
5: adjustItemCount
(BELT_AIC_FORWARD, 5)
6: setAutoStopForward(true)
7: setAutoStopForward(true)
8: moveForward(speed1)
10: moves the belt forward
Assume that five items passed the light barrier

and another one is detected. The belt stops.
11: update MotionStatus to BELT_MT_STOPPED

and deliver SUE
11: notify client of new event
Application event handling

code takes appropriate action

118 Belt
The following sequence diagram shows the typical usage of the Belt device during
an emergency stop scenario caused by an open security flap.
NOTE: We are assuming that the Application has already successfully opened and claimed the Belt Device
and is registered to receive events from the control. Emergency stop caused by an open security flap, that
means CapSecurityFlapForward is true.
Application Belt Control Belt Service Belt
access to the hardware
Assume that an item opens the security flap.

The belt stops due to an emergency condition.
7: update MotionStatus to BELT_MT_EMERGENCY

and deliver SUE
Application event handling code takes

appropriate action, calls for assistance
and the problem is finally fixed.
9: resetBelt()
10: resetBelt()
11: resets the belt

12: update MotionStatus to BELT_MT_STOPPED
and deliver SUE
Application goes on with

normal operation.

Model
The general model of a Belt is:

• After the belt is enabled an application can call moveForward and stopBelt
in order to control the motion.
• If CapMoveBackward is true, the application may also call moveBackward.
• Moving forward and backward may be available in different speeds defined
by CapSpeedStepsBackward and CapSpeedStepsForward.
• Due to safety regulations a belt is usually equipped with security flaps at the
end of the belt, at both ends if it can move backwards.
CapSecurityFlapBackward and CapSecurityFlapForward are defining
the availability of them.
• CapAutoStopBackward and CapAutoStopForward tell an application if
the belt supports an automatic stop. Whether the application wants to use this
feature can be controlled by setting AutoStopBackward and
AutoStopForward properties. The belt is stopped if an automatic stop
condition becomes true. Usually such a condition is controlled by light
barriers, but it can also correspond to an internal state of the device which is
not exposed. The condition is device specific and has to be explained in the
device documentation.
• Light barriers may be available for handling an automatic stop feature.
CapLightBarrierBackward and CapLightBarrierForward define the
availability of such barriers.
• If CapAutoStopForwardItemCount is true the application may control the
automatic stop feature depending on a number of items passing the light
barrier or any other item counting mechanism in forward direction by calling
adjustItemCount and resetItemCount. In this case the belt is automatically
stopped if AutoStopForwardItemCount is zero and an additional item is
detected. This feature may be also available for backward direction.
• If CapAutoStopForward is true, an application may also delay automatic
stop in forward direction by setting AutoStopForwardDelayTime. The delay
time starts when an automatic stop condition becomes true. The belt is stopped
when the delay time has expired. During delay time automatic stop is
cancelled if the automatic stop condition becomes false. This feature may be
also available for backward direction.
• The application will be informed about any status change with a
StatusUpdateEvent, also all corresponding status properties will be updated
before event delivery.
• An emergency stop will occur if one of the security flaps is open or the
operator presses an emergency button. In this case technical assistance is
needed and the application has to reset the belt by calling resetBelt. A security
stop will occur if the belt has been stopped due to safety requirement
regulations but no technical assistance is needed.

120 Belt
Device Sharing
Belt is an exclusive-use device. Its device sharing rules are:

• The application must claim the device before enabling it.
• The application must claim and enable the device before accessing some of the
properties and methods, or receiving events.
• See the “Summary” table for precise usage prerequisites.
Belt State Diagram

The following diagram illustrates the various state transitions within the Belt
device category.
open claim
Closed Opened Claimed
close release
)
ls e
e)
(tru
(fa
le d
led
ab
ab
close release
En
En
ice
ice
ev
ev
tD
tD
se
se
Enabled
moveForward motor fault

Forward
emergency sto
p Emergency
automatic stop
moveForward
Stop
fire
event done
done
fire
fire event event
stopBelt
Stopped Fire Events
done
moveBackward
automatic stop
done
fire
event fire
event
done
Motor Fault
moveBackward motor fault
Backward
emergency stop


AutoStopBackward Property
Syntax AutoStopBackward: boolean { read-write, access after open }
Remarks If true, the automatic stop feature in backward direction is enabled. If false, it is
disabled. The belt will automatically stop if an automatic stop condition becomes
true.
If CapAutoStopBackward is false, then this property is always false.
See Also CapAutoStopBackward Property.
AutoStopBackwardDelayTime Property
Syntax AutoStopBackwardDelayTime: int32 { read-write, access after open }
Remarks Specifies a delay time in milliseconds for an automatic stop in backward direction.
The delay time starts when an automatic stop condition becomes true. The delay
time counting stops and automatic stop is cancelled if the condition becomes false.
If CapAutoStopBackward is false, then this property has no meaning, setting this
property will be ignored.
This property is initialized to zero (0) by the open method.
See Also CapAutoStopBackward Property.
AutoStopBackwardItemCount Property
Syntax AutoStopBackwardItemCount: int32 { read-only, access after open }
Remarks Holds the actual item counter for an automatic stop in backward direction. If an
item is detected this property will be decreased. The automatic stop condition
becomes true if the item counter mechanism detects an additional item and the
counter is already zero.
This property can be increased or decreased by calling the adjustItemCount
method and can be reset to zero by calling the resetItemCount method.
If CapAutoStopBackward or CapAutoStopBackwardItemCount is false, then
this property has no meaning.

122 Belt

See Also CapAutoStopBackward Property, CapAutoStopBackwardItemCount
Property, adjustItemCount Method, resetItemCount Method.
AutoStopForward Property
Syntax AutoStopForward: boolean { read-write, access after open }
Remarks If true, the automatic stop feature in forward direction is enabled. If false, it is
disabled. The belt will automatically stop if an automatic stop condition becomes
true.
If CapAutoStopForward is false, then this property is always false.
See Also CapAutoStopForward Property.
AutoStopForwardDelayTime Property
Syntax AutoStopForwardDelayTime: int32 { read-write, access after open }
Remarks Specifies a delay time in milliseconds for an automatic stop in forward direction.
The delay time starts when an automatic stop condition becomes true. The delay
time counting stops and automatic stop is cancelled if the condition becomes false.
If CapAutoStopForward is false, then this property has no meaning, setting this
property will be ignored.
See Also CapAutoStopForward Property.
AutoStopForwardItemCount Property
Syntax AutoStopForwardItemCount: int32 { read-only, access after open }
Remarks Holds the actual item counter for an automatic stop in forward direction. If an item
is detected this property will be decreased. The automatic stop condition becomes
true if the item counter mechanism detects an additional item and the counter is
already zero.
This property can be increased or decreased by calling the adjustItemCount
method and can be reset to zero by calling the resetItemCount method.
If CapAutoStopForward or CapAutoStopForwardItemCount is false, then
this property has no meaning.

See Also CapAutoStopForward Property, CapAutoStopForwardItemCount Property,
adjustItemCount Method, resetItemCount Method.
CapAutoStopBackward Property
Syntax CapAutoStopBackward: boolean { read-only, access after open }
Remarks If true, the device supports an automatic motor stop when moving backward, based
on an automatic stop condition.
CapAutoStopBackwardItemCount Property
Syntax CapAutoStopBackwardItemCount: boolean { read-only, access after open }
Remarks If true, the device supports an automatic motor stop when moving backward
depending on the number of items specified by AutoStopBackwardItemCount.
See Also AutoStopBackwardItemCount Property.
CapAutoStopForward Property
Syntax CapAutoStopForward: boolean { read-only, access after open }
Remarks If true, the device supports an automatic motor stop when moving forward, based
on an automatic stop condition.
CapAutoStopForwardItemCount Property
Syntax CapAutoStopForwardItemCount: boolean { read-only, access after open }
Remarks If true, the device supports an automatic motor stop when moving forward
depending on the number of items specified by AutoStopForwardItemCount.
See Also AutoStopForwardItemCount Property.

124 Belt
CapLightBarrierBackward Property
Syntax CapLightBarrierBackward: boolean { read-only, access after open }
Remarks If true, the device has a backward light barrier and
LightBarrierBackwardInterrupted holds the actual state of the light barrier.
See Also LightBarrierBackwardInterrupted Property.
CapLightBarrierForward Property
Syntax CapLightBarrierForward: boolean { read-only, access after open }
Remarks If true, the device has a forward light barrier and
LightBarrierForwardInterrupted holds the actual state of the light barrier.
See Also LightBarrierForwardInterrupted Property.
CapMoveBackward Property
Syntax CapMoveBackward: boolean { read-only, access after open }
Remarks If true, the belt can move backward.
CapSecurityFlapBackward Property
Syntax CapSecurityFlapBackward: boolean { read-only, access after open }
Remarks If true, the device has a backward security flap and
SecurityFlapBackwardOpened holds the actual state of the flap.
See Also SecurityFlapBackwardOpened Property.

CapSecurityFlapForward Property
Syntax CapSecurityFlapForward: boolean { read-only, access after open }
Remarks If true, the device has a forward security flap and SecurityFlapForwardOpened
holds the actual state of the flap.
See Also SecurityFlapForwardOpened Property.
CapSpeedStepsBackward Property
Syntax CapSpeedStepsBackward: int32 { read-only, access after open }
Remarks Defines how many speed steps the belt motor supports in backward direction,
minimum is one (1). This property is only valid if CapMoveBackward is true. If
CapMoveBackward is false this property is initialized to zero (0).
See Also CapMoveBackward Property.
CapSpeedStepsForward Property
Syntax CapSpeedStepsForward: int32 { read-only, access after open }
Remarks Defines how many speed steps the belt motor supports in forward direction,
minimum is one (1).
LightBarrierBackwardInterrupted Property
Syntax LightBarrierBackwardInterrupted: boolean { read-only, access after open-
claim-enable }
Remarks If true, the light barrier in backward direction is interrupted, otherwise it is false.
An appropriate StatusUpdateEvent indicating a status change will be enqueued.
If CapLightBarrierBackward is false, then this property is always false.
This property is initialized and kept current while the device is enabled.
See Also CapLightBarrierBackward Property.

126 Belt
LightBarrierForwardInterrupted Property
Syntax LightBarrierForwardInterrupted: boolean { read-only, access after open-
claim-enable }
Remarks If true, the light barrier in forward direction is interrupted, otherwise it is false. An
appropriate StatusUpdateEvent indicating a status change will be enqueued.
If CapLightBarrierForward is false, then this property is always false.
See Also CapLightBarrierForward Property.
MotionStatus Property
Syntax MotionStatus: int32 { read-only, access after open-claim-enable }
Remarks Holds the current motion state of the device. It has one of the following values:
Value Meaning
BELT_MT_FORWARD The device is moving forward.
BELT_MT_BACKWARD The device is moving backward.
BELT_MT_STOPPED The device has stopped due to an automatic stop,
security stop or motor timeout stop.
BELT_MT_EMERGENCY Emergency stop, either a security flap is open or the
emergency button was pressed. Technical
assistance is needed in order to reactivate the belt
device.
BELT_MT_MOTOR_FAULT The device has stopped due to a motor failure like
overheating or a defective fuse. Technical
assistance may be needed in order to reactivate the
motor.

SecurityFlapBackwardOpened Property
Syntax SecurityFlapBackwardOpened: boolean { read-only, access after open-claim-
enable }
Remarks If true, the security flap in backward direction is open, otherwise it is closed. An
If CapSecurityFlapBackward is false, then this property is always false.
See Also CapSecurityFlapBackward Property.
SecurityFlapForwardOpened Property
Syntax SecurityFlapForwardOpened: boolean { read-only, access after open-claim-
enable }
Remarks If true, the security flap in forward direction is open, otherwise it is closed. An
If CapSecurityFlapForward is false, then this property is always false.
See Also CapSecurityFlapForward Property.

128 Belt
adjustItemCount Method
Syntax adjustItemCount ( direction: int32, count: int32 ):
direction Specifies the auto stop item count property to be
adjusted. May be either BELT_AIC_BACKWARD or
BELT_AIC_FORWARD.
count The count parameter contains the number of items to be
adjusted.
Remarks Depending on direction either AutoStopBackwardItemCount or
AutoStopForwardItemCount will be adjusted by count. It can be an increment
or decrement depending on whether count is positive or negative.
This method is only valid if at least one of the corresponding capabilities
CapAutoStopBackwardItemCount or CapAutoStopForwardItemCount is
true.
A possible value of the exception’s ErrorCode property is:
Value Meaning
E_ILLEGAL adjustItemCount is not supported or an invalid
direction was specified.
See Also CapAutoStopBackwardItemCount Property, AutoStopBackwardItemCount
Property, CapAutoStopForwardItemCount Property,
AutoStopForwardItemCount Property, resetItemCount Method.
moveBackward Method
Syntax moveBackward ( speed: int32 ):
speed Specifies the speed step. Valid speed steps are 1 through
CapSpeedStepsBackward.
Remarks Starts the belt motor to move backward with the specified speed.
This method is only valid if CapMoveBackward is true.
Subsequent calls to moveBackward will change the speed.


Value Meaning
E_ILLEGAL moveBackward is not supported or an invalid speed
step was specified.
See Also CapMoveBackward Property, CapSpeedStepsBackward Property.
moveForward Method
Syntax moveForward ( speed: int32 ):
speed Specifies the speed step. Valid speed steps are 1 through
CapSpeedStepsForward.
Remarks Starts the belt motor to move forward with the specified speed.
Subsequent calls to moveForward will change the speed.
See Also CapSpeedStepsForward Property.
resetBelt Method
Syntax resetBelt ( ):
Remarks Resets the belt after an emergency stop caused by an open security flap or a
pressed emergency button.

130 Belt
resetItemCount Method
Syntax resetItemCount ( direction: int32 ):
direction Specifies the auto stop item count property to be reset.
May be either BELT_RIC_BACKWARD or
BELT_RIC_FORWARD.
Remarks Depending on direction either AutoStopBackwardItemCount or
AutoStopForwardItemCount will be reset to zero (0).
This method is only valid if at least one of the corresponding capabilities
CapAutoStopBackwardItemCount or CapAutoStopForwardItemCount is
true.
Value Meaning
E_ILLEGAL resetItemCount is not supported or an invalid direction
was specified.
See Also CapAutoStopBackwardItemCount Property, AutoStopBackwardItemCount
Property, CapAutoStopForwardItemCount Property,
AutoStopForwardItemCount Property, adjustItemCount Method.
stopBelt Method
Syntax stopBelt ( ):
Remarks Stops the belt motor.

DirectIOEvent
<< event >> upos::events::DirectIOEvent
Description Provides Service information directly to the application. This event provides a
means for a vendor-specific Belt Service to provide events to the application that
are not otherwise supported by the Control.
Service.
EventNumber and the Service. This property is settable.
Obj Object Additional data whose usage varies by the EventNumber
and Service. This property is settable.
not otherwise described. Use of this event may restrict the application program
from being used with other vendor’s Belt devices which may not have any
knowledge of the Service’s need for this event.

132 Belt
StatusUpdateEvent
<< event >> upos::events::StatusUpdateEvent
Description Notifies the application when the status of the Belt changes.
Attributes This event contains the following attribute:

Status int32 The status reported from the Belt.
The Status attribute has one of the following values:
Value Description
BELT_SUE_AUTO_STOP
The belt has automatically stopped.
BELT_SUE_EMERGENCY_STOP
The belt has stopped caused by an emergency condition,
either a security flap is open or an emergency button has
been pressed. Technical assistance is needed.
BELT_SUE_SAFETY_STOP
The belt has stopped for safety reasons. Technical
assistance is not needed.
BELT_SUE_TIMEOUT_STOP
The belt has stopped due to a hardware timeout
protecting the motor against overheating.
BELT_SUE_MOTOR_OVERHEATING
The belt has stopped due to a motor overheating.
BELT_SUE_MOTOR_FUSE_DEFECT
The belt has stopped due to a defective fuse.
BELT_SUE_LIGHT_BARRIER_BACKWARD_INTERRUPTED
The light barrier in backward direction is interrupted.
BELT_SUE_LIGHT_BARRIER_BACKWARD_OK
The light barrier in backward direction is no longer
interrupted.
BELT_SUE_LIGHT_BARRIER_FORWARD_INTERRUPTED
The light barrier in forward direction is interrupted.
BELT_SUE_LIGHT_BARRIER_FORWARD_OK
The light barrier in forward direction is no longer
interrupted.
BELT_SUE_SECURITY_FLAP_BACKWARD_OPENED
The security flap in backward direction is open.
BELT_SUE_SECURITY_FLAP_BACKWARD_CLOSED
The security flap in backward direction is closed.
BELT_SUE_SECURITY_FLAP_FORWARD_OPENED

The security flap in forward direction is open.

BELT_SUE_SECURITY_FLAP_FORWARD_CLOSED
The security flap in forward direction is closed.
Note that Release 1.3 added Power State Reporting with
additional Power reporting StatusUpdateEvent values.
The Update Firmware capability, added in Release 1.9,
added additional Status values for communicating the
status/progress of an asynchronous update firmware
process.
See “StatusUpdateEvent” description on page 108.
Remarks This event applies for status changes of the belt. It depends on the capabilities of
the device which status changes can be reported.
See Also “Events” on page 51.

134 Belt

C H A P T E R 3
Bill Acceptor
This Chapter defines the Bill Acceptor device category.
Summary

AutoDisable: boolean {read-write} 1.11 Not Supported
CheckHealthText: string {read-only} 1.11 open
Claimed: boolean {read-only} 1.11 open
DataCount: int32 {read-only} 1.11 open
DataEventEnabled: boolean {read-write} 1.11 open
DeviceEnabled: boolean {read-write} 1.11 open & claim
FreezeEvents: boolean {read-write} 1.11 open
OutputID: int32 {read-only} 1.11 Not Supported
PowerNotify: int32 {read-write} 1.11 open
PowerState: int32 {read-only} 1.11 open
State: int32 {read-only} 1.11 --
DeviceControlDescription: string {read-only} 1.11 --

DeviceControlVersion: int32 {read-only} 1.11 --
DeviceServiceDescription: string {read-only} 1.11 open
DeviceServiceVersion: int32 {read-only} 1.11 open
PhysicalDeviceDescription: string {read-only} 1.11 open
PhysicalDeviceName: string {read-only} 1.11 open
136 Bill Acceptor
CapDiscrepancy: boolean {read-only} 1.11 open
CapFullSensor: boolean {read-only} 1.11 open
CapJamSensor: boolean {read-only} 1.11 open
CapNearFullSensor: boolean {read-only} 1.11 open
CapPauseDeposit: boolean {read-only} 1.11 open
CapRealTimeData: boolean {read-only} 1.11 open
CurrencyCode: string {read-write} 1.11 open

DepositAmount: int32 {read-only} 1.11 open
DepositCashList: string {read-only} 1.11 open
DepositCodeList: string {read-only} 1.11 open
DepositCounts: string {read-only} 1.11 open
DepositStatus: int32 {read-only} 1.11 open, claim, & enable
FullStatus: int32 {read-only} 1.11 open, claim, & enable
RealTimeDataEnabled: boolean {read-write} 1.11 open, claim & enable

Summary 137

Common
Name Version
close ( ): 1.11
release ( ): 1.11
clearInput ( ): 1.11
void { } supported
void { } supported
Specific
Name
adjustCashCounts ( cashCounts: string ): 1.11
beginDeposit ( ): 1.11
endDeposit ( success: int32 ): 1.11
fixDeposit ( ): 1.11
pauseDeposit ( control: int32 ): 1.11
readCashCounts ( inout cashCounts: string, inout discrepancy: boolean ): 1.11

138 Bill Acceptor

upos::events::DataEvent 1.11

General Information
The Bill Acceptor programmatic name is “BillAcceptor”.

Capabilities
The Bill Acceptor has the following capabilities:

• Reports the cash units and corresponding unit counts available in the Bill
Acceptor.
• Reports jam conditions within the device.
• Supports more than one currency.
The Bill Acceptor may also have the following additional capabilities:
• Reporting the levels of the Bill Acceptor’s cash units. Conditions which may
be indicated include full, and near full states.
• Reporting of a possible (or probable) cash count discrepancy in the data
reported by the readCashCounts method.
• The money (bills) which are deposited into the device between the start and
end of cash acceptance is reported to the application. The contents of the
report are cash units and cash counts.

140 Bill Acceptor
Bill Acceptor Class Diagram
The following diagram shows the relationships between the Bill Acceptor classes.
<<exception>> <<utility>>
UposException UposConst
(from upos)
(from upos)
<<sends>> <<utility>>
BillAcceptorConst
<<Int erface>> (from upos)
<<event>> BillAcceptorControl <<uses>>
DataEvent (from upos)
(from eve nts) <<capability>> CapDiscrepancy : boolean
<<capability>> CapFullSensor : boolean
<<capability>> CapJamSensor : Boolean
<<capability>> CapNearFullSensor : boolean
<<fires>> <<capability>> CapPauseDeposit : boolean
<<capability>> CapRealTimeData : Boolean
<<prop>> CurrencyCode : string
<<event>> <<prop>> DepositAmount : int32
DirectIOEvent <<prop>> DepositCashList : string
(from events)
<<prop>> DepositCodeList : string
<<prop>> DepositCounts : string
<<fires>> <<prop>> DepositStatus : int32
<<prop>> FullStatus : int32
<<prop>> RealTimeDataEnabled : boolean
<<event>> adjustCashCounts(cashCounts : string)

StatusUpdateEvent beginDeposit()
<<fires>>
(from events)
endDeposit(amount : int32)
fixDeposit()
pauseDeposit(control : int32)
readCashCounts(cashCounts : string, discrepancy : boolean)

Model
The general model of a Bill Acceptor is:

• Supports several bill denominations. The supported cash type for a particular
currency is noted by the list of cash units in the DepositCashList property.
• Consists of any combination of features to aid in the cash processing functions
such as a cash entry holding bin, a number of slots or bins which can hold the
cash, and cash exits.
• The removal of cash from the device (for example, to empty deposited cash)
is controlled by the adjustCashCounts method, unless the device can
determine the amount of cash on its own. The application can call
readCashCounts to retrieve the current unit count for each cash unit.
• Sets the cash slot (or cash bin) conditions in the FullStatus property to show
full and near full status. If there are one or more full cash slots, then
FullStatus is BACC_STATUS_FULL.
• Cash acceptance into the “cash acceptance mechanism” is started by invoking
the beginDeposit method. The previous values of the properties
DepositCounts and DepositAmount are initialized to zero.
• The total amount of cash placed into the device continues to be accumulated
until either the fixDeposit method or the pauseDeposit method is executed.
When the fixDeposit method is executed, the total amount of accumulated
cash is stored in the DepositCounts and DepositAmount properties. If the
pauseDeposit method is executed with a parameter value of
BACC_DEPOSIT_PAUSE, then the counting of the deposited cash is
suspended and the current amount of accumulated cash is also updated to the
DepositCounts and DepositAmount properties. When pauseDeposit
method is executed with a parameter value of BACC_DEPOSIT_RESTART,
counting of deposited cash is resumed and added to the accumulated totals.
When the fixDeposit method is executed, the current amount of accumulated
cash is updated in the DepositCounts and DepositAmount properties, and the
process remains static until the endDeposit method is invoked with a
BACC_DEPOSIT_COMPLETE parameter to complete the deposit.
• When the clearInput method is executed, the queued DataEvent associated
with the receipt of cash is cleared. The DepositCounts and DepositAmount
properties remain set and are not cleared.

142 Bill Acceptor
Bill Acceptor Sequence Diagram
NOTE: we are assuming that the :ClientApp already successfully open, Claimed and enabled the
Bill Acceptor device. This means that the Claimed, DeviceEnabled properties are == true
:ClientApp : BillAcceptorControl BillAcceptorService : DataEvent Human Actor
1: setRealTimeDataEvents(true)
2: setRealTimeDataEvents (true) Set so DepositAmount and

DepositCounts are updated for
each Data Event
3: beginDeposit( )
4: beginDeposit()
5: initialize Deposit Amount and DepositCount s
6: accept Cash
7: create Data Event
8: enqueue Data Event for delivery
9: update DepositAmount and Deposit Counts
10: deliver Data Event
11: notify ClientApp of event
12: fixDeposit( )
13: fixDeposit
14: updateDepositAmount and DepositCounts
15: endDeposit(int32)

Bill Acceptor State Diagram
open claim
close release
setDeviceEnabled( false )
release clearInput
close adjustCashCountssetDeviceEnabled( true )
clearInput ClearInput processing

Enabled
readCashCounts
entry/ empty data queue
endDeposit clearInput
beginDeposit
Fix Mode
entry/ sync DepostAmount and DepositCount
Cash Acceptance
fixDeposit fixDeposit
entry/ DepositAmount = 0
entry/ DepositCount = 0
Pause Mode
entry/ sync DepostAmount and DepositCount

pauseDeposit( BACC_DEPOSIT_RESTART )
has room
for cash
pauseDeposit( BACC_DEPOSIT_PAUSE )
jammed
adjustCashCounts / remove cash
near full
adjustCashCounts / removefull
cash
fire events
Device Sharing
The Bill Acceptor is an exclusive-use device, as follows:

properties, dispensing or collecting, or receiving events.

144 Bill Acceptor
CapDiscrepancy Property
Syntax CapDiscrepancy: boolean { read-only, access after open }
Remarks If true, the readCashCounts method can report effective discrepancy values.
See Also readCashCounts Method.
CapFullSensor Property
Syntax CapFullSensor: boolean { read-only, access after open }
Remarks If true, the Bill Acceptor can report the condition that some cash slots are full.
See Also FullStatus Property, StatusUpdateEvent.
CapJamSensor Property
Syntax CapJamSensor: boolean { read-only, access after open }
Remarks If true, the bill acceptor can report a mechanical jam or failure condition.
See Also StatusUpdateEvent.
CapNearFullSensor Property
Syntax CapNearFullSensor: boolean { read-only, access after open }
Remarks If true, the Bill Acceptor can report the condition that some cash slots are nearly
full.

CapPauseDeposit Property
Syntax CapPauseDeposit: boolean { read-only, access after open }
Remarks If true, the Bill Acceptor has the capability to suspend cash acceptance processing
temporarily.
See Also pauseDeposit Method.
CapRealTimeData Property
Syntax CapRealTimeData: boolean { read-only, access after open }
Remarks If true, the device is able to supply data as the money is being accepted (“real time”).

See Also RealTimeDataEnabled Property.
CurrencyCode Property
Syntax CurrencyCode: string { read-write, access after open }
Remarks Contains the active currency code to be used by Bill Acceptor operations.
This property is initialized to an appropriate value by the open method. This value
is guaranteed to be one of the set of currencies specified by the DepositCodeList
property.
Value Meaning
E_ILLEGAL A value was specified that is not within
DepositCodeList.
See Also DepositCodeList Property.

146 Bill Acceptor
DepositAmount Property
Syntax DepositAmount: int32 { read-only, access after open }
Remarks The total amount of deposited cash.
For example, if the currency is Japanese yen and DepositAmount is set to 18057,
after the call to the beginDeposit method, there would be 18,057 yen in the Bill
Acceptor.
See Also CurrencyCode Property.
DepositCashList Property
Syntax DepositCashList: string { read-only, access after open }
Remarks Holds the cash units supported in the Bill Acceptor for the currency represented
by the CurrencyCode property.
It consists of ASCII numeric comma delimited values which denote the ASCII
semicolon character (“;”) followed by ASCII numeric comma delimited values for
the bills that can be used with the Bill Acceptor. The semicolon (“;”) is present to
denote the start of bills when integrated within the bill dispenser
Below are sample DepositCashList values in Japan.
• “;1000,5000,10000” ---
1000, 5000, 10000 yen bill.
This property is initialized by the open method, and is updated when
CurrencyCode is set.
See Also CurrencyCode Property, DepositCodeList Property.
DepositCodeList Property
Syntax DepositCodeList: string { read-only, access after open }
Remarks Holds the currency code indicators for cash accepted.
It is a list of ASCII three-character ISO 4217 currency codes separated by commas.
For example, if the string is “JPY,USD”, then the Bill Acceptor supports both
Japanese and U.S. monetary units.
See Also CurrencyCode Property, DepositCashList Property.

DepositCounts Property Updated in Release 1.12

Syntax DepositCounts: string { read-only, access after open }
Remarks Holds the total of the cash accepted by the bill acceptor. Cash units inside the
string are the same as the DepositCashList property, and are in the same order.
For example if the currency is Japanese yen and string of the DepositCounts
property is set to:
“;1000:80,5000:77,10000:0”
After the call to the beginDeposit method, there would be 80 one thousand yen
bills and 77 five thousand yen bills in the Bill Acceptor.
This property is initialized to zero by the open method
DepositStatus Property
Syntax DepositStatus: int32 { read-only, access after open-claim-enable }
Remarks Holds the current status of the cash acceptance operation. It may be one of the
following values:
Value Meaning
BACC_STATUS_DEPOSIT_START
Cash acceptance started.
BACC_STATUS_DEPOSIT_END
Cash acceptance stopped.
BACC_STATUS_DEPOSIT_COUNT
Counting or repaying the deposited money.
BACC_STATUS_DEPOSIT_JAM
A mechanical fault has occurred.
This property is initialized and kept current while the device is enabled. This
property is set to BACC_STATUS_DEPOSIT_END after initialization.

148 Bill Acceptor
FullStatus Property
Syntax FullStatus: int32 { read-only, access after open }
Remarks Holds the current full status of the cash slots. It may be one of the following:
Value Meaning
BACC_STATUS_OK All cash slots are neither nearly full nor full.
BACC_STATUS_FULL Some cash slots are full.
BACC_STATUS_NEARFULL
Some cash slots are nearly full.
RealTimeDataEnabled Property
Syntax RealTimeDataEnabled: boolean {read-write, access after open-claim-enable}
Remarks If true and CapRealTimeData is true, each data event fired will update the
DepositAmount and DepositCounts properties. Otherwise, DepositAmount and
DepositCounts are updated with the value of the money collected when fixDeposit is
called. Setting RealTimeDataEnabled will not cause any change in system behavior
until a subsequent beginDeposit method is performed. This prevents confusion
regarding what would happen if it were modified between a beginDeposit -
endDeposit pairing.

Value Meaning
E_ILLEGAL Cannot be set true if CapRealTimeData is false.
See Also CapRealTimeData Property, DepositAmount Property, DepositCounts
Property, beginDeposit Method, endDeposit Method, fixDeposit Method.


adjustCashCounts Method Updated in Release 1.12
Syntax adjustCashCounts (cashCounts: string);
cashCounts The cashCounts parameter contains cash types and
amounts to be initialized.
Remarks This method is called to set the initial amounts in the Bill Acceptor after initial
setup, or to adjust cash counts after replenishment or removal, such as a paid in or
paid out operation. This method is called when needed for devices which cannot
determine the exact amount of cash in them automatically. If the device can
determine the exact amount, then this method call is ignored. The application
would first call readCashCounts to get the current counts, and adjust them to the
amount being replenished. Then the application will call this method to set the
amount currently in the acceptor.
To reset all cash counts to zero, set each denomination amount to zero.
For example if the currency is Japanese yen and string returned in cashCounts is
set to:
“;1000:80,5000:77,10000:0”
as a result of calling the adjustCashCounts method, then there would be 80 one
thousand yen bills and 77 five thousand yen bills in the Bill Acceptor.

150 Bill Acceptor
beginDeposit Method
Syntax beginDeposit ( ):
Remarks Cash acceptance is started.
The following property values are initialized by the call to this method:
• The value of each cash unit of the DepositCounts property is set to zero.
• The DepositAmount property is set to zero.
After calling this method, cash acceptance is reported by DataEvents until
fixDeposit is called while the deposit process is not paused.
Value Meaning
E_ILLEGAL The call sequence is not correct.
See Also DepositAmount Property, DepositCounts Property, endDeposit Method,
fixDeposit Method, pauseDeposit Method.
endDeposit Method
Syntax endDeposit ( success: int32 ):
The success parameter holds the value of how to deal with the cash that was
deposited. Contains one of the following values:
BACC_DEPOSIT_COMPLETE The deposit is accepted and the mode is
complete.
Remarks Cash acceptance is completed.
Before calling this method, the application must calculate the difference between
the amount of the deposit and the amount required.
The application must call the fixDeposit method before calling this method.
Value Meaning
E_ILLEGAL One of the following errors occurred:
• The call sequence is invalid. beginDeposit and
fixDeposit must be called in sequence before
calling this method.
See Also DepositAmount Property, DepositCounts Property, beginDeposit Method,

fixDeposit Method
Syntax fixDeposit ( ):
Remarks When this method is called, all property values are updated to reflect the current
values in the Bill Acceptor.
Value Meaning
• The call sequence is invalid. beginDeposit must be
called before calling this method.
endDeposit Method, pauseDeposit Method.
pauseDeposit Method
Syntax pauseDeposit ( control: int32 ):
The control parameter contains one of the following values:
BACC_DEPOSIT_PAUSE Cash acceptance is paused.
BACC_DEPOSIT_RESTART Cash acceptance is resumed.
Remarks Called to suspend or resume the process of depositing cash.
If control is BACC_DEPOSIT_PAUSE, the cash acceptance operation is paused.
The deposit process will remain paused until this method is called with control set
to BACC_DEPOSIT_RESTART. It is valid to call fixDeposit then endDeposit
while the deposit process is paused.
When the deposit process is paused, the DepositCounts and DepositAmount
properties are updated to reflect the current state of the Bill Acceptor. The property
values are not changed again until the deposit process is resumed.
If control is BACC_DEPOSIT_RESTART, the deposit process is resumed.
Value Meaning
• The deposit process is already paused and control is
set to BACC_DEPOSIT_PAUSE, or the deposit
process is not paused and control is set to
BACC_DEPOSIT_RESTART.
endDeposit Method, fixDeposit Method.

152 Bill Acceptor
readCashCounts Method Updated in Release 1.12
Syntax readCashCounts ( inout cashCounts: string, inout discrepancy: boolean ):

cashCounts The cash count data is placed into the string cashCounts.
discrepancy If discrepancy is set to true by this method, then there is
some cash which was not able to be included in the
counts reported in cashCounts; otherwise it is set false.
Remarks Each unit in cashCounts matches a unit in the DepositCashList property, and is
in the same order.
set to:
“;1000:80,5000:77,10000:0”
as a result of calling the readCashCounts method, then there would be 80 one
thousand yen bills and 77 five thousand yen bills in the Bill Acceptor.
Usually, the cash total calculated by cashCounts parameter is equal to the cash
total in a Bill Acceptor. There are some cases where a discrepancy may occur
because of existing uncountable cash in a Bill Acceptor. An example would be
when a cash slot is “overflowing” such that the device has lost its ability to
accurately detect and monitor the cash.
See Also DepositCashList Property.


DataEvent
<< event >> upos::events::DataEvent
Description Notifies the application when the Bill Acceptor has accepted a bill.
Attributes Type Description
Status int32 The Status parameter contains zero.
DirectIOEvent
means for a vendor-specific Bill Acceptor Service to provide events to the
application that are not otherwise supported by the Control.
Service.
from being used with other vendor’s Bill Acceptor devices which may not have
any knowledge of the Service’s need for this event.

154 Bill Acceptor
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of the Bill
Acceptor device.
Status int32 Indicates a change in the status of the unit. See values
below.
process.
The Status parameter contains the Bill Acceptor status condition:
Value Meaning
BACC_STATUS_FULL Some cash slots are full.
BACC_STATUS_NEARFULL Some cash slots are nearly full.
BACC_STATUS_FULLOK No cash slots are either full or nearly full.
BACC_STATUS_JAM A mechanical fault has occurred.
BACC_STATUS_JAMOK A mechanical fault has recovered.
Remarks Fired when the Bill Acceptor detects a status change.

For changes in the fullness levels, the Bill Acceptor is only able to fire
StatusUpdateEvents when the device has a sensor capable of detecting the full or
near full states and the corresponding capability properties for these states are set.
Jam conditions may be reported whenever this condition occurs.

C H A P T E R 4
Bill Dispenser
This Chapter defines the Bill Dispenser device category.
Summary

DataCount: int32 {read-only} 1.11 Not Supported
DataEventEnabled: boolean {read-write} 1.11 Not Supported

156 Bill Dispenser
CapEmptySensor: boolean {read-only} 1.11 open
CapNearEmptySensor: boolean {read-only} 1.11 open
AsyncMode: boolean {read-write} 1.11 open

AsyncResultCode: int32 {read-only} 1.11 open, claim, & enable
AsyncResultCodeExtended: int32 {read-only} 1.11 open, claim, & enable
CurrencyCashList: string {read-only} 1.11 open

CurrencyCodeList: string {read-only} 1.11 open
CurrentExit: int32 {read-write} 1.11 open
DeviceExits: int32 {read-only} 1.11 open
DeviceStatus: int32 {read-only} 1.11 open, claim, & enable
ExitCashList: string {read-only} 1.11 open

Summary 157

Common
Name Version
close ( ): 1.11
release ( ): 1.11
clearInput ( ): Not
void { raises-exception, use after open, claim } supported
void { } supported
void { } supported
Specific
Name
dispenseCash ( cashCounts: string ): 1.11

158 Bill Dispenser


General Information
The Bill Dispenser programmatic name is “BillDispenser”.

This device category was added in Version 1.11 of the specification.
Capabilities
The Bill Dispenser has the following capabilities:

• Reports the cash units and corresponding unit counts available in the Bill
Dispenser.
• Dispenses a specified number of cash units from the device in bills into a user-
specified exit.
The Bill Dispenser may also have the following additional capabilities:
• Reporting the fullness levels of the Bill Dispenser’s cash units. Conditions
which may be indicated include empty and near empty states.

160 Bill Dispenser
Bill Dispenser Class Diagram
The following diagram shows the relationships between the Bill Dispenser classes.
(f rom upos)
(f rom upos)
<<sends>>
<<Interface>>
BillDispenserControl <<utility>>
(f r om u pos ) BillDispenserConst
<<capabil ity>> CapDiscrepancy : b ool ean <<use s>> (f rom upos)
<<capabil ity>> CapEmptySens or : boolean
<<capabil ity>> CapJamSen sor : Boolean
<<capabil ity>> CapNearEm ptySensor : boole an
<<prop>> AsyncMod e : bool ean
<<prop>> AsyncRes ultCode : int32
<<prop>> AsyncRes ultCodeExtended : int32
<<event>> <<prop>> Curren cyCashList : string
DirectIOEvent <<prop>> Curren cyCode : s trin g
(f rom ev ents) <<prop>> Curren cyCodeList : string
<<prop>> Curren tExi t : int32
<<fires>> <<prop>> DeviceExits : int32
<<prop>> DeviceSta tus : int32
<<prop>> ExitCashList : stri ng
<<event>>
adjustCashC oun ts(cashCo unts : strin g)
StatusUpdateEvent
<<fire s>> beginDep osit()
(f rom ev ents)
dispenseCas h(cash Counts : string)
dispenseCha nge(amou nt : int32)
endDe posit(a mount : int32)
fixDeposit()
pause Deposi t(control : int32)
rea dCashCounts(cashCou nts : string , discre pancy : bo olean)

Model
The general model of a Bill Dispenser is:

• Supports several bill denominations. The supported bill denomination for a
particular currency is noted by the list of cash units in the CurrencyCashList
property.
such as a number of slots or bins which can hold the cash, and cash exits.
• This specification provides programmatic control only for the dispensing of
cash. The accepting of cash by the device (for example, to replenish cash) is
controlled by the adjustCashCounts method, unless the device can determine
the amount of cash on its own. The application can call readCashCounts to
retrieve the current unit count for each cash unit, but cannot control when or
how cash is added to the device.
• May have multiple exits. The number of exits is specified in the DeviceExits
property. The application chooses a dispensing exit by setting the
CurrentExit property. The cash units which may be dispensed to the current
exit are indicated by the ExitCashList property. When CurrentExit is 1, the
exit is considered the “primary exit” which is typically used during normal
processing for dispensing cash to a customer following a retail transaction.
When CurrentExit is greater than 1, the exit is considered an “auxiliary exit.”
An “auxiliary exit” typically is used for special purposes such as dispensing
quantities or types of cash not targeted for the “primary exit.”
• Dispenses cash into the exit specified by CurrentExit when dispenseCash is
called. With dispenseCash, the application specifies a count of each cash unit
to be dispensed.
• Dispenses cash either synchronously or asynchronously, depending on the
value of the AsyncMode property.
When AsyncMode is false, then the cash dispensing methods are performed
synchronously and the dispense method returns the completion status to the
application.
When AsyncMode is true and no exception is thrown by dispenseCash, then
the method is performed asynchronously and its completion is indicated by a
StatusUpdateEvent with its Data property set to BDSP_STATUS_ASYNC.
The request’s completion status is set in the AsyncResultCode and
AsyncResultCodeExtended properties.
The values of AsyncResultCode and AsyncResultCodeExtended are the
same as those for the ErrorCode and ErrorCodeExtended properties of a
UposException when an error occurs during synchronous dispensing.
Nesting of asynchronous Bill Dispenser operations is illegal; only one
asynchronous method can be processed at a time.
The readCashCounts method may not be called while an asynchronous
method is being performed since doing so could likely report incorrect cash
counts.

162 Bill Dispenser
• May support more than one currency. The CurrencyCode property may be
set to the currency, selecting from a currency in the list CurrencyCodeList.
CurrencyCashList, ExitCashList, dispenseCash, dispenseChange and
readCashCounts all act upon the current currency only.
• Sets the cash slot (or cash bin) conditions in the DeviceStatus property to
show empty and near empty status. If there are one or more empty cash slots,
then DeviceStatus is BDSP_STATUS_EMPTY.

Bill Dispenser Sequence Diagram
NOTE: We are assuming the clienApp has already successfully opened,

claimed and enabled the device
: :ClientApp : BillDispenserControl ::BillDispenserService : StatusUpdateEvent
1: dispenseCash(string)
2: dispenseCash(string)
Assume Bill
Dispenser is
getting low
3: update deviceStatus to BDSP_STATUS_NEAREMPTY (CapNearEmptySensor = true)
4: create new SUE Event
5: deliver SUE to control
6: notify ClientApp of new event

164 Bill Dispenser
Bill Dispenser State Diagram
Closed open Opened claim

Claimed
close release
release setDeviceEnabled( false )
close setDeviceEnabled( true )
Enabled
setAsync Mode( false )
setAsyncMode( true )
dispens eCashdispenseCash
setAsyncMode( false ) Has Bills Near Empt y Empty
setAsyncMode( trueSynchronous
) Synchronous
Asynchronous Asynchronous
adCashCounts
fires events
fire events
fire events
fire events done done
done fire events
done
done
jams
Fire Events
jams
Jammed
Device Sharing
The Bill Dispenser is an exclusive-use device, as follows:


AsyncMode Property
Syntax AsyncMode: boolean { read-write, access after open }
Remarks If true, the dispenseCash method will be performed asynchronously. If false, this
method will be performed synchronously.
See Also AsyncResultCode Property, AsyncResultCodeExtended Property,
dispenseCash Method.
AsyncResultCode Property
Syntax AsyncResultCode: int32 { read-only, access after open-claim-enable }
Remarks Holds the completion status of the last asynchronous dispense request (i.e., when
dispenseCash was called with AsyncMode true).
This property is set before a StatusUpdateEvent is delivered with a Status value
of BDSP_STATUS_ASYNC.
See Also AsyncMode Property, dispenseCash Method.
AsyncResultCodeExtended Property
Syntax AsyncResultCodeExtended: int32 { read-only, access after open-claim-
enable}
dispenseCash was called with AsyncMode true).
This property is set before a StatusUpdateEvent is delivered with a Status value
of BDSP_STATUS_ASYNC.
See Also AsyncMode Property, dispenseCash Method.

166 Bill Dispenser
CapEmptySensor Property
Syntax CapEmptySensor: boolean { read-only, access after open }
Remarks If true, the Bill Dispenser can report the condition that some cash slots are empty.
See Also DeviceStatus Property, StatusUpdateEvent.
Remarks If true, the Bill Dispenser can report the occurrence of a mechanical fault in the
Bill Dispenser.
CapNearEmptySensor Property
Syntax CapNearEmptySensor: boolean { read-only, access after open }
Remarks If true, the Bill Dispenser can report the condition that some cash slots are nearly
empty.

CurrencyCashList Property
Syntax CurrencyCashList: string { read-only, access after open }
Remarks Holds the cash units supported in the Bill Dispenser for the currency represented
The string consists of an ASCII semicolon character (“;”) followed by ASCII
numeric comma delimited units of bills that can be used with the Bill Dispenser.
The semicolon (“;”) is present to indicate the units are bills. This is used for
merging multiple device services into the Cash Changer.
Below are sample CurrencyCashList values in Japan.

• “;1000,5000,10000” ---
1000, 5000, 10000 yen bill.
Remarks Contains the active currency code to be used by Bill Dispenser operations. This
property is initialized to an appropriate value by the open method. This value is
guaranteed to be one of the set of currencies specified by the CurrencyCodeList
property.
Value Meaning
CurrencyCodeList.
See Also CurrencyCodeList Property.

168 Bill Dispenser
CurrencyCodeList Property
Syntax CurrencyCodeList: string { read-only, access after open }
Remarks Holds a list of ASCII three-character ISO 4217 currency codes separated by
commas. For example, if the string is “JPY,USD”, then the Bill Dispenser supports
both Japanese and U.S. monetary units.
CurrentExit Property
Syntax CurrentExit: int32 { read-write, access after open }
Remarks Holds the current cash dispensing exit. The value 1 represents the primary exit (or
normal exit), while values greater than 1 are considered auxiliary exits. Legal
values range from 1 to DeviceExits.
Below are examples of typical property value sets in Japan. CurrencyCode is
“JPY” and CurrencyCodeList is “JPY”.
• Bill Dispenser supports bills; an auxiliary exit is used for larger quantities
of bills:
CurrencyCashList = “;1000,5000,10000”
DeviceExits = 2
When CurrentExit = 1 : ExitCashList = “;1000,5000”
When CurrentExit = 2 : ExitCashList = “;1000,5000,10000”
This property is initialized to 1 by the open method.
Value Meaning
E_ILLEGAL An invalid CurrentExit value was specified.
See Also CurrencyCashList Property, DeviceExits Property, ExitCashList Property.
DeviceExits Property
Syntax DeviceExits: int32 { read-only, access after open }
Remarks The number of exits for dispensing cash.
See Also CurrentExit Property.

DeviceStatus Property
Syntax DeviceStatus: int32 { read-only, access after open-claim-enable }
Remarks Holds the current status of the Bill Dispenser. It may be one of the following:
Value Meaning
BDSP_STATUS_OK The current condition of the Bill Dispenser is
satisfactory.
BDSP_STATUS_EMPTY
Some cash slots are empty.
BDSP_STATUS_NEAREMPTY
Some cash slots are nearly empty.
BDSP_STATUS_JAM A mechanical fault has occurred.
This property is initialized and kept current while the device is enabled. If more
than one condition is present, then the order of precedence starting at the highest
is: fault, empty, and near empty.
ExitCashList Property
Syntax ExitCashList: string { read-only, access after open }
Remarks Holds the cash units which may be dispensed to the exit which is denoted by
CurrentExit property. The supported cash units are either the same as
CurrencyCashList, or a subset of it. The string format is identical to that of
CurrencyCashList.
CurrencyCode or CurrentExit is set.
See Also CurrencyCode Property, CurrencyCashList Property, CurrentExit Property.

170 Bill Dispenser

adjustCashCounts Method Updated in Release 1.12

Remarks This method is called to set the initial amounts in the Bill Dispenser after initial
amount currently in the changer.
set to:
“;1000:80,5000:77,10000:0”
thousand yen bills and 77 five thousand yen bills in the Bill Dispenser.
Value Meaning
E_BUSY Cash units and counts cannot be initialized because an
asynchronous method is outstanding.

dispenseCash Method
Syntax dispenseCash ( cashCounts: string ):
The cashCounts parameter contains the dispensing cash units and counts,
represented by the format of “;cash unit:cash counts, ...., cash unit:cash counts”.
Units must be preceded by “;” to represent bills.
Remarks Dispenses the cash from the Bill Dispenser into the exit specified by CurrentExit.
The cash dispensed is specified by pairs of cash units and counts.
This method is performed synchronously if AsyncMode is false, and
asynchronously if AsyncMode is true.
Some cashCounts examples, using Japanese yen as the currency, are shown below.
• “;1000:10”
Dispense 10 one thousand yen bills.
• “;1000:10,10000:5”
Dispense 10 one thousand yen bills and 5 ten thousand yen bills.
Value Meaning
E_BUSY Cash cannot be dispensed because an asynchronous
method is in progress.
• The cashCounts parameter value was illegal for the
current exit.
E_EXTENDED ErrorCodeExtended = EBDSP_OVERDISPENSE:
The specified cash cannot be dispensed because of a
cash shortage.
See Also AsyncMode Property, CurrentExit Property.

172 Bill Dispenser
readCashCounts Method Updated in Release 1.12

cashCounts The cash count data is placed into cashCounts.
Remarks The format of the string cashCounts is the same as cashCounts in the
dispenseCash method. Each unit in cashCounts matches a unit in the
CurrencyCashList property, and is in the same order.
set to:
“;1000:80,5000:77,10000:0”
thousand yen bills and 77 five thousand yen bills in the Bill Dispenser.
If CapDiscrepancy property is false, then discrepancy is always false.
total in a Bill Dispenser. There are some cases where a discrepancy may occur
because of existing uncountable cash in a Bill Dispenser. An example would be
when a bill dispenser has diverted unusable bill to a holding area.
Value Meaning
E_BUSY Cash units and counts cannot be read because an
asynchronous method is in process.
See Also CapDiscrepancy Property, CurrencyCashList Property, dispenseCash Method.


DirectIOEvent
means for a vendor-specific Bill Dispenser Service to provide events to the
Service.
from being used with other vendor’s Bill Dispenser devices which may not have

174 Bill Dispenser
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of the Bill
Dispenser device.
below.
process.
The Status parameter contains the Bill Dispenser status condition:
Value Meaning
BDSP_STATUS_EMPTY Some cash slots are empty.
BDSP_STATUS_NEAREMPTY Some cash slots are nearly empty.
BDSP_STATUS_EMPTYOK No cash slots are either empty or nearly
empty.
BDSP_STATUS_JAM A mechanical fault has occurred.
BDSP_STATUS_JAMOK A mechanical fault has recovered.
BDSP_STATUS_ASYNC Asynchronously performed method has
completed.
Remarks Fired when the Bill Dispenser detects a status change.
For changes in the fullness levels, the Bill Dispenser is only able to fire
StatusUpdateEvents when the device has a sensor capable of detecting the full,
near full, empty, and/or near empty states and the corresponding capability
properties for these states are set.
Jam conditions may be reported whenever this condition occurs; likewise for
asynchronous method completion.
The completion statuses of asynchronously performed methods are placed in the
AsyncResultCode and AsyncResultCodeExtended properties.
See Also AsyncResultCode Property, AsyncResultCodeExtended Property, “Events” on
page 51

C H A P T E R 5
Biometrics
This Chapter defines the Biometrics device category.
Summary

AutoDisable: boolean { read-write } 1.10 open
DataCount: int32 { read-only } 1.10 open
DataEventEnabled: boolean { read-write } 1.10 open

176 Biometrics
Specific: Type Mutability Version May Use After
Algorithm: int32 { read-write } 1.10 open & claim
AlgorithmList: string { read-only } 1.10 open
BIR: binary { read-only } 1.10 open & claim
CapPrematchData: boolean { read-only } 1.10 open
CapRawSensorData: boolean { read-only } 1.10 open
CapRealTimeData: boolean { read-only } 1.10 open
CapSensorColor: int32 { read-only } 1.10 open
CapSensorOrientation: int32 { read-only } 1.10 open
CapSensorType: int32 { read-only } 1.10 open
CapTemplateAdaptation: boolean { read-only } 1.10 open

RawSensorData: binary { read-only } 1.10 open & claim
RealTimeDataEnabled: boolean { read-write } 1.10 open
SensorBPP: int32 { read-only } 1.10 open
SensorColor: int32 { read-write } 1.10 open
SensorHeight: int32 { read-only } 1.10 open
SensorOrientation: int32 { read-write } 1.10 open, claim, & enable
SensorType: int32 { read-write } 1.10 open, claim, & enable
SensorWidth: int32 { read-only } 1.10 open

Summary 177

Common
Name Version
close ( ): 1.10
release ( ): 1.10
void { } supported
Specific Updated in Release 1.11

Name
beginEnrollCapture (referenceBIR: binary, payload: binary ): 1.10
beginVerifyCapture (): 1.10
endCapture ( ): 1.10
identify (maxFARRequested: int32, maxFRRRequested: int32, 1.11
FARPrecedence: boolean, referenceBIRPopulation: array of binary, inout
candidateRanking: int32 array, timeout: int32 ):

178 Biometrics
identifyMatch (maxFARRequested: int32, maxFRRRequested: int32, 1.11

FARPrecedence: boolean, sampleBIR: binary, referenceBIRPopulation:
array of binary, inout candidateRanking: int32 array ):
processPrematchData (capturedBIR: binary, prematchDataBIR: binary, 1.10
inout processedBIR: binary ):
verify (maxFARRequested: int32, maxFRRRequested: int32, 1.10
FARPrecedence: boolean, referenceBIR: binary, inout adaptedBIR: binary,
inout result: boolean, inout FARAchieved: int32, inout FRRAchieved:
int32, inout payload: binary, timeout: int32 ):
verifyMatch (maxFARRequested: int32, maxFRRRequested: int32, 1.10
FARPrecedence: boolean, sampleBIR: binary, referenceBIR: binary, inout
adaptedBIR: binary, inout result: boolean, inout FARAchieved: int32,
inout FRRAchieved: int32, inout payload: binary ):


General Information
The Biometrics programmatic name is “Biometrics”.
This device was introduced in Version 1.10 of this specification.
Capabilities
All Biometric devices have the following capabilities:

• The device captures biometrics data from a biometrics sensor. The biometrics
data is in the form of a Biometrics Information Record (BIR) containing one
or more Biometrics Data Blocks (BDB) which in turn contain one or more
biometric data samples or biometric templates.
This standard uses the term template (as adapted from the BioAPI1) to refer
to the biometric enrollment data for a user. The term biometric information
record (BIR) refers to any biometric data that is returned to the application;
including raw data, intermediate data, processed sample(s) ready for
verification or identification, as well as enrollment data. Typically, the only
data stored persistently by the application is the BIR generated for enrollment
(i.e., the template). The format of the Opaque Biometric Data Block (BDB) is
indicated by the Format field of the Header. This may be a standard or
proprietary format. The BDB may be encrypted. The digital signature is
optional, and may be used to ensure integrity of the data during transmission
and storage. When present, it is calculated on the Header + BDB. For
standardized BIR formats, the signature will take a standard form (to be
determined when the format is standardized). For proprietary BIR formats
(all that exists at the present time), the signature can take any form that suits
the Service. For this reason, there is no C structure definition of the signature.
The BIR Data Type indicates whether the BIR is signed and/or encrypted.
1.
BioAPI is defined by the BioAPI consortium (www.bioapi.org).

180 Biometrics
• The Device captures Biometric data for the purposes of enrollment. The
notion of enrollment requires a higher level of quality for the final BIR that is
created. Generally, the BIR will be the aggregation of series of biometric
captures.
• The Device captures Biometric data for the purposes of verification.
Verification does not require the same level of quality as enrollment.
• The Device has the ability to determine if two BIRs match within the degree
of error specified by the False Accept Rate (FAR) and False Reject Rate
(FRR). The FAR is the margin of percentage error acceptable that two non-
matching biometric samples will be falsely deemed to match. The FRR is the
margin of percentage error acceptable that two matching biometric samples
will be falsely deemed not to match.
• The Device has the ability to compare a BIR against a sample population of
BIRs and create a rank ordering of the population for identification purposes.
Some Biometrics Device may have the following additional capabilities:
• The Device Returns the raw biometric data in “real time” as it is captured by
the device. If this capability is true and has been enabled by application by
setting the RealTimeDataEnabled property to true, then a series of
StatusUpdateEvents are enqueued, each as a raw image defined by
SensorBPP, SensorColor, SensorHeight, and SensorWidth representing a
partial biometrics image capture.

Biometrics Class Diagram
The following diagram shows the relationships between the Biometrics classes.
«exception» «sends» «interface» «uses» «utility»

UposException BaseControl UposConst
«utility»
BiometricsConst
«sends» «uses»
«interface»
BiometricsControl
+Algorithm : int32
+AlgorithmList : string
+BIR : binary
+CapPrematchData : boolean
+CapRawSensorData : boolean
+CapRealTimeData : boolean
+CapSensorColor : int32
+CapSensorOrientation : int32
+CapSensorType : int32
+CapTemplateAdaption : boolean
+RawSensorData : binary
+RealTimeDataEnabled : boolean
+SensorBPP : int32
+SensorColor : int32
+SensorHeight : int32
+SensorOrientation : int32
+SensorType : int32
+SensorWidth : int32
+beginEnrollCapture() : void
+beginVerifyCapture() : void
+endCapture() : void
Note: Method parameters are
not listed due to space +identify() : void
limitations - refer to the +identifyMatch() : void
Methods section for details. +processPrematchData() : void
+verify() : void
+verifyMatch() : void
«fires»
«fires» «fires» «fires»
«event» «event» «event» «event»

DataEvent DirectIOEvent ErrorEvent StatusUpdateEvent
+Status : int32 +EventNumber : int32 +ErrorCode : int32 +Status : int32
+Data : int32 +ErrorCodeExtended : int32
+Obj : object +ErrorLocus : int32
+ErrorResponse : int32

182 Biometrics
Model
The Biometrics device usage model is:

• Open and claim the device.
• Enable the device and set the property DataEventEnabled to true.
• Begin capturing biometrics data by calling on of the following asynchronous
methods beginVerifyCapture or beginEnrollCapture. These methods
activate the biometrics sensor to begin acquiring the biometrics data in the
relevant manner for the particular biometrics device. The result biometric
data is stored in the BIR property. The BIR data can be provided to the
identifyMatch method and verifyMatch method for comparison and
matching purposes. The archival process of the BIR for future verification is
application dependent.
• Perform synchronous biometric verifications through the verify method or
synchronous biometric identifications through the identify method.
• If the device is capable of supplying biometrics data in real time as the
biometric sample is captured (CapRealTimeData is true), and if
RealTimeDataEnabled is true, the biometrics data is presented to the
application as a series of partial biometric data through the RawSensorData
property and notified to the application through StatusUpdateEvents until
the biometric sample is fully acquired. RawSensorData is not queued rather
it is up to the application to capture the data upon receiving the
StatusUpdateEvent.
The Biometrics Device follows the general “Device Input Model” for event-
driven input:
• When input is received by the Service, it enqueues a DataEvent.
• If AutoDisable is true, then the Device automatically disables itself when a
DataEvent is enqueued.
• A queued DataEvent can be delivered to the application when the property
DataEventEnabled is true and other event delivery requirements are met.
Just before delivering this event, data is copied into properties, and further
data events are disabled by setting DataEventEnabled to false. This causes
subsequent input data to be enqueued while the application processes the
current input and associated properties. When the application has finished
processing the current input and is ready for more data, it re-enables events
by setting DataEventEnabled to true.
• An ErrorEvent (or events) is enqueued if the an error occurs while gathering
or processing input, and is delivered to the application when
• The DataCount property may be read to obtain the number of queued
DataEvents.
• All enqueued input may be deleted by calling clearInput. See the clearInput
method description for more details.

Deviations from the general “Device Input Model” for event-driven input are:
• The capture of biometrics data begins when beginEnrollCapture or
beginVerifyCapture is called.
• If biometrics capture is terminated by calling endCapture, then no
DataEvent or ErrorEvent will be enqueued.
Device Sharing
The Biometrics is an exclusive-use device, as follows:

• The application must claim and enable the device before accessing many of
the Biometrics specific properties.
• The application must claim and enable the device before calling methods that
manipulate the device or before changing some writable properties.

184 Biometrics
Biometrics Sequence Diagrams

The following diagram illustrates the enrollment sequence for the Biometrics
device category.
NOTE: Assumes that the Applciation has already successfully opened, claimed and enabled the control and is registered to receive events from the control.
Application Biometrics Control Biometrics Service Hardware
1: setDataEventEnabled(true)
3: beginEnrollCapture()
4: beginEnrollCapture()
5: Enable hardware capture
6: Data captured and delivered
7: Create and fire a Data Event
8: Data Event delivered

9: getBIR()
10: getBIR()
11: BIR data returned
13: BIR data persisted

The following diagram illustrates the verify sequence for the Biometrics device
category.
3: beginVerifyCapture()

9: getBIR()
10: getBIR()
The application provides a set of enrollment BIRs from which a match is to be found.
13: verify()
14: verify()
15: Hardware compares each enrollment BIR against the verify BIR
16: Hardware returns match data
17: Return status and match data

186 Biometrics
The following diagram illustrates the verify - match sequence for the Biometrics
device category.

9: getBIR()
10: getBIR()
The application provides the enrollment BIR of the user to verify.
13: verifyMatch()
14: verifyMatch()
15: Hardware compares enrollment BIR against verify BIR
16: Hardware returns match data

Biometrics State Diagram
The following diagram illustrates the various state transitions within the
Biometrics device category.
/ close()
/ open() / claim()
Closed / close() Opened / release() Claimed
/ close() / release() / setDeviceEnabled(true)

/ setDeviceEnabled(false)
Enroll Capture
/ beginEnrollCapture()
/ endCapture() / beginVerifyCapture() Verify Capture
/ endCapture()
/ DataEvent fired
Enabled / DataEvent fired
/ identify()
/ verifyMatch()
/ identifyMatch() / processPrematchData() / verify()

Identify
Verify Matching
Identify Matching Preprocess Data Verify

188 Biometrics

Algorithm Property
Syntax Algorithm: int32 { read-write, access after open-claim }
Remarks Contains the biometric algorithm currently in use for generating the biometrics
template. The values can be set to index the values contained in AlgorithmList.
For example:
Value Meaning
0 Default value
1 First algorithm in AlgorithmList
2 Second algorithm in AlgorithmList, etc.
This property can only be updated when the device is opened and claimed, but not
enabled.
See Also AlgorithmList Property.
AlgorithmList Property
Syntax AlgorithmList: string { read-only, access after open }
Remarks Contains the comma-delimited list of algorithms that are supported by the device.
See Also Algorithm Property.
BIR Property 2
Syntax BIR: binary { read-only, access after open-claim-enable }3
Remarks This standard uses the term template to refer to the biometric enrollment data for
a user. The term biometric information record (BIR) refers to any biometric data
that is returned to the application; including raw data, intermediate data, processed
sample(s) ready for verification or identification, as well as enrollment data.
Typically, the only data stored persistently by the application is the BIR generated
for enrollment (i.e., the template). The format of the Opaque Biometric Data Block
(BDB) is indicated by the Format field of the Header. This may be a standard or
proprietary format. The BDB may be encrypted. The digital signature is optional,
and may be used to ensure integrity of the data during transmission and storage.
When present, it is calculated on the Header + BDB.
2.
Biometrics Information Record (BIR) was originally defined by the BioAPI
consortium (www.bioapi.org).

Properties (UML Attributes) 189
For standardized BIR formats, the signature will take a standard form (to be
determined when the format is standardized). For proprietary BIR formats (all that
exists at the present time), the signature can take any form that suits the Service.
For this reason, there is no C structure definition of the signature. The BIR Data
Type indicates whether the BIR is signed and/or encrypted.
Processed biometric data obtained through the methods beginEnrollCapture,
beginVerifyCapture, and verify are stored in this property upon successful
completion.
See Also beginEnrollCapture Method, beginVerifyCapture Method, verify Method.
CapPrematchData Property Updated in Release 1.11
Syntax CapPrematchData: boolean { read-only, access after open }
Remarks If true, the Service is capable of using MOC (Match-On-Card) SmartCard
technology to generate a processed BIR based on prematch data stored on a
SmartCard.
See Also processPrematchData Method.
CapRawSensorData Property Updated in Release 1.12
Syntax CapRawSensorData: boolean { read-only, access after open }
Remarks If true, the Service is able to return unprocessed raw data from the biometrics
sensor.
See Also RawSensorData Property.

190 Biometrics
CapRealTimeData Property Updated in Release 1.12

Remarks If true, the device is able to supply raw biometrics data as the biometrics
information is being captured (“real time”). This property value will be false if
CapRawSensorData is false, since real time data is only delivered via the
RawSensorData property which requires that CapRawSensorData is true.
See Also RawSensorData Property, SensorBPP Property, SensorColor Property,
SensorHeight Property, SensorWidth Property.
CapSensorColor Property
Syntax CapSensorColor: int32 { read-only, access after open }
Remarks This capability indicates if this device supports image formats other than bi-tonal.
CapSensorColor is a logical OR combination of any of the following values:
Value Meaning
BIO_CSC_MONO Bi-tonal ( B/W )
BIO_CSC_GRAYSCALE Gray scale
BIO_CSC_16 16 Colors
BIO_CSC_256 256 Colors
BIO_CSC_FULL Full colors
CapSensorOrientation Property
Syntax CapSensorOrientation: int32 { read-only, access after open }
Remarks This capability indicates the ability of the sensor image to be rotated prior to
processing. CapSensorOrientation is a logical OR combination of any of the
following values:
Value Meaning
BIO_CSO_NORMAL 0°
BIO_CSO_RIGHT 90°
BIO_CSO_INVERTED 180°
BIO_CSO_LEFT 270°

CapSensorType Property Updated in Release 1.11

Syntax CapSensorType: int32 { read-only, access after open-claim-enable }
Remarks This capability indicates the types of biometrics data that can be captured by the
attached sensor. CapSensorType is a logical OR combination of any of the
following values:
Value Meaning
BIO_CST_FACIAL_FEATURES Facial Features/Topography
BIO_CST_VOICE Voice
BIO_CST_FINGERPRINT Fingerprint
BIO_CST_IRIS Iris
BIO_CST_RETINA Retina
BIO_CST_HAND_GEOMETRY Hand Geometry
BIO_CST_SIGNATURE_DYNAMICS Signature
BIO_CST_KEYSTROKE_DYNAMICS Keystrokes
BIO_CST_LIP_MOVEMENT Lip Movement
BIO_CST_THERMAL_FACE_IMAGE Face Image
BIO_CST_THERMAL_HAND_IMAGE Hand Image
BIO_CST_GAIT Gait/Stride
BIO_CST_PASSWORD Password
See Also SensorType Property.
CapTemplateAdaptation Property
Syntax CapTemplateAdaptation: boolean { read-only, access after open }
Remarks If true, the Service is able to return an adapted BIR that is the result of updating a
reference BIR with information taken from a sample BIR or capture BIR. The
purpose of this adaptation is to keep the reference BIR current as biometric data
shifts over time.
This capability must be populated after open, claim, and enable because it is
dependent on the selected Algorithm.
See Also Algorithm Property, BIR Property, Verify Method, VerifyMatch Method.
RawSensorData Property Updated in Release 1.12
Syntax RawSensorData: binary { read-only, access after open-claim-enable }4
Remarks Holds the biometrics image data as raw pixel data scan lines from the top, left to
the bottom, right. SensorHeight and SensorWidth define the number of pixels.
SensorBPP defines the number of bits per pixel. SensorColor defines the
interpretation of the pixel data. If CapRawSensorData is false, then this property
contains no meaningful value.

192 Biometrics
See Also CapRawSensorData Property, CapRealTimeData Property,
RealTimeDataEnabled Property, SensorBPP Property, SensorColor Property,
RealTimeDataEnabled Property Updated in Release 1.12

Syntax RealTimeDataEnabled: boolean { read-write, access after open }
Remarks If true, then StatusUpdateEvents will be fired as updated partial biometric data is
captured until biometric capture is completed. Otherwise, the captured biometric
data is enqueued as a single DataEvent when biometric capture is completed.
Setting RealTimeDataEnabled will not cause any change in system behavior
until a subsequent beginEnrollCapture or beginVerifyCapture method is
performed. This prevents confusion regarding what would happen if it were
modified between a beginEnrollCapture - endCapture or beginVerifyCapture
- endCapture pairing.
Value Meaning
E_ILLEGAL Cannot set to true because CapRealTimeData
is false.
See Also CapRealTimeData Property, RawSensorData Property, SensorBPP Property,
SensorColor Property, SensorHeight Property, SensorWidth Property,
beginEnrollCapture Method, beginVerifyCapture Method, endCapture
Method.
SensorBPP Property
Syntax SensorBPP: int32 { read-only, access after open }
Remarks Holds the Bit Per Pixel (BPP) encoding of the RawSensorData.
SensorColor Property Updated in Release 1.11

Syntax SensorColor: int32 { read-write, access after open }
Remarks This property is used to select the image capture mode for subsequent biometric
capture operations. Certain SensorType devices may not work with all the
“colors” or color image type may not make sense. Changing the SensorColor
property will not affect any previously stored data currently residing in the
RawSensorData property or BIR property.
It may contain one of the following values:

Value Meaning
BIO_SC_MONO Bi-tonal (B/W)
BIO_SC_GRAYSCALE Gray scale
BIO_SC_16 16 Colors
BIO_SC_256 256 Colors
BIO_SC_FULL Full color
This property can only be set to a value if the value is defined in CapSensorColor.
Value Meaning
E_ILLEGAL Invalid sensor color specified. See
CapSensorColor.
See Also CapSensorColor Property, RawSensorData Property, SensorBPP Property,
SensorHeight Property
Syntax SensorHeight: int32 { read-only, access after open }
Remarks Holds the height of the RawSensorData in pixels.
SensorOrientation Property Updated in Release 1.11

Syntax SensorOrientation: int32 { read-write, access after open-claim }
Remarks Holds the requested orientation adjustment to the received sensor data prior to BIR
creation.
Value Meaning
BIO_SO_NORMAL 0°
BIO_SO_RIGHT 90°
BIO_SO_INVERTED 180°
BIO_SO_LEFT 270°
This property can only be updated when the device is opened and claimed, but not
enabled.
This property can only be set to a value if the value is defined in
CapSensorOrientation.
Value Meaning
E_ILLEGAL Invalid sensor orientation specified. See
CapSensorOrientation.
See Also CapSensorOrientation Property.

194 Biometrics
SensorType Property Updated in Release 1.11

Syntax SensorType: int32 { read-write, access after open-claim-enable }
Remarks Holds the type of biometrics sensor being accessed.
Value Meaning
BIO_ST_FACIAL_FEATURES Facial Topography
BIO_ST_VOICE Voice
BIO_ST_FINGERPRINT Fingerprint
BIO_ST_IRIS Iris
BIO_ST_RETINA Retina
BIO_ST_HAND_GEOMETRY Hand Geometry
BIO_ST_SIGNATURE_DYNAMICS Signature
BIO_ST_KEYSTROKE_DYNAMICS Keystrokes
BIO_ST_LIP_MOVEMENT Lip Movement
BIO_ST_THERMAL_FACE_IMAGE Thermal Face Image
BIO_ST_THERMAL_HAND_IMAGE Thermal Hand Image
BIO_ST_GAIT Gait/Stride
BIO_ST_PASSWORD Password
This property can only be set to a value if the value is defined in CapSensorType.
Value Meaning
E_ILLEGAL Invalid sensor type specified. See
CapSensorType.
See Also CapSensorType Property.
SensorWidth Property
Syntax SensorWidth: int32 { read-only, access after open }
Remarks Holds the width of the RawSensorData in pixels.
See Also RawSensorData Property.


beginEnrollCapture Method Updated in Release 1.11
Syntax beginEnrollCapture ( referenceBIR: binary, payload: binary ):
referenceBIR5 Optional BIR to be adapted (updated). This parameter is
ignored, if EMPTY.
payload5 Data that will be stored by the BSP. This parameter is
ignored, if EMPTY.
Remarks Starts capturing biometrics data for purposes of enrollment. Although not
required, enrollment captures customarily result in a series of biometrics data
captures whose aggregation form the final BIR. Optionally if
CapTemplateAdaptation is true, a referenceBIR can be provided for adaptation
with the enrollment. If a payload is provided that data is added into the resulting
BIR.
Value Meaning
E_FAILURE referenceBIR could not be adapted.
E_ILLEGAL Biometrics capture is already in progress.
See Also BIR Property, CapTemplateAdaptation Property, endCapture Method.
beginVerifyCapture Method Updated in Release 1.11

Syntax beginVerifyCapture ( ):
Remarks Starts capturing biometrics data for the purposes of verification. The resulting
processed data is stored in the BIR.
Value Meaning
E_ILLEGAL Biometrics capture is already in progress.
See Also BIR Property, endCapture Method.
5.
In the OPOS environment, the format of referenceBIR and payload depends upon
the value of the BinaryConversion property. See BinaryConversion property on
page A-29.

196 Biometrics
endCapture Method
Syntax endCapture( ):
Remarks Stops (terminates) capturing biometrics data.
If RealTimeDataEnabled is false and biometrics data was captured, then it is
placed in the properties BIR and RawSensorData. If no biometrics data was
captured, then BIR and RawSensorData are EMPTY.
If RealTimeDataEnabled is true and there is biometric data remaining which
have not been delivered to the application by a StatusUpdateEvent, then the
remaining biometric data is placed into the properties BIR and RawSensorData.
If no biometrics data was captured or all biometric data has been delivered to the
application, then BIR and RawSensorData are EMPTY.
Value Meaning
E_ILLEGAL Biometrics capture was not in progress.
See Also BIR Property, RawSensorData Property, RealTimeDataEnabled Property,
beginEnrollCapture Method, beginVerifyCapture Method, DataEvent.
identify Method Updated in Release 1.12

Syntax identify (maxFARRequested: int32, maxFRRRequested: int32,
FARPrecedence: boolean, referenceBIRPopulation: array of binary, inout
candidateRanking: int32 array, timeout: int32 ):
maxFARRequested The requested FAR criterion for successful verification,
as defined in the BioAPI specification.
maxFRRRequested The requested FRR criterion for successful verification,
as defined in the BioAPI specification. If zero, then this
criterion is not provided.
FARPrecedence If both criteria are provided, this parameter indicates
which takes precedence. BIO_FAR_PRECEDENCE
(TRUE) indicates that maxFARRequested takes
precedence, BIO_FRR_PRECEDENCE (FALSE)
indicates that maxFRRRequested takes precedence.
referenceBIRPopulation6
An array of BIRs against which the Identify match is
performed.
candidateRanking Array of BIR indices from the referenceBIRPopulation
listed in rank order. The indices are zero-based.
6.
In the OPOS environment, the format of referenceBIRPopulation depends upon the
value of the BinaryConversion property. See BinaryConversion property on page
A-29.

timeout Maximum number of milliseconds to attempt a

successful biometric capture before failing.
Remarks This function captures biometric data from the attached device within the allotted
timeout, and compares it against a set of referenceBIRPopulation. It then returns a
rank ordered array of referenceBIRPopulation indices in candidateRanking. If
nothing matches, an array with zero elements is returned.
Value Meaning
E_ILLEGAL maxFARRequested, or maxFRRRequested, or
referenceBIRPopulation was not valid or Biometrics
capture is in progress.
E_TIMEOUT The specified timeout has elapsed before biometric data
was captured.
identifyMatch Method Updated in Release 1.12

Syntax identifyMatch (maxFARRequested: int32, maxFRRRequested: int32,
FARPrecedence: boolean, sampleBIR: binary, referenceBIRPopulation:
array of binary, inout candidateRanking: int32 array ):
sampleBIR7 The BIR to be identified
referenceBIRPopulation 7
An array of BIRs against which the Identify match is
performed.
candidateRanking Array of BIR indices from the referenceBIRPopulation
listed in rank order. The indices are zero-based.
Remarks This function accepts a sampleBIR, and compares it against a set of
referenceBIRPopulation. It then returns a rank ordered array of
referenceBIRPopulation indices in candidateRanking. If nothing matches, an
array with zero elements is returned.
7.
In the OPOS environment, the format of sampleBIR and referenceBIRPopulation
depends upon the value of the BinaryConversion property. See BinaryConversion
property on page A-29.

198 Biometrics
Value Meaning
referenceBIRPopulation was not valid or Biometrics
capture is in progress.
processPrematchData Method Updated in Release 1.11

Syntax processPrematchData (sampleBIR: binary, prematchDataBIR: binary, inout
processedBIR: binary)
void { raises-exception, use after open-claim-enable}
sampleBIR8 BIR to be processed
prematchDataBIR 8 BIR containing prematch data previously emitted by the
associated MOC Library.
processedBIR 8 The newly constructed processed BIR
Remarks This function creates processed biometric samples suitable for Match-on-Card
(MOC). It enables MOC implementations that require the retrieval of “prematch”
data from the card prior to the subsequent matching operation. Since smart cards
generally do not have the capability to capture and process biometric samples, the
on-card MOC functionality needs a host to perform off-card operations such as
sample acquisition and feature extraction. In this case, the card needs the host to
perform an operation based on prematch data that is retrieved from the card.
Value Meaning
E_ILLEGAL sampleBIR was not valid, Biometrics capture is in
progress, or CapPrematchData is false.
See Also CapPrematchData Property.
8. In the OPOS environment, the format of sampleBIR, prematchDataBIR, and

processedBIR depends upon the value of the BinaryConversion property. See
BinaryConversion property on page A-29.

verify Method Updated in Release 1.12

Syntax verify( maxFARRequested: int32, maxFRRRequested: int32,
FARPrecedence: boolean, referenceBIR: binary, inout adaptedBIR: binary,
inout result: boolean, inout FARAchieved: int32, inout FRRAchieved: int32,
inout payload: binary, timeout: int32 ):
referenceBIR9 The BIR to be verified against.
adaptedBIR 9 A pointer to the handle of the adapted BIR. This
parameter can be EMPTY (0x00) if an adapted BIR is
not desired.
result A boolean value of true for a successful match or false
for a failed match.
FARAchieved FAR Value indicating the closeness of the match.
FRRAchieved FRR Value indicating the closeness of the match.
payload 9 If a payload is associated with the referenceBIR, it is
returned in an allocated binary if a successful match was
made.
timeout Maximum number of milliseconds to attempt a
successful biometric capture before failing.
Remarks This function captures biometric data from the attached device within the allotted
timeout, and compares it against the referenceBIR. If the match is successful as
indicated by a positive result and an adaptedBIR handle was provided, the Service
will attempt to adapt the referenceBIR from information take form the captured
BIR.
Value Meaning
referenceBIR was not valid or Biometrics capture is in
progress.
E_TIMEOUT The specified timeout has elapsed before biometric data
was captured.
See Also BIR Property, CapTemplateAdaptation Property.
9.
In the OPOS environment, the format of referenceBIR, adaptedBIR, and payload

200 Biometrics
verifyMatch Method Updated in Release 1.12

Syntax verifyMatch (maxFARRequested: int32, maxFRRRequested: int32,
FARPrecedence: boolean, sampleBIR: binary, referenceBIR: binary, inout
adaptedBIR: binary, inout result: boolean, inout FARAchieved: int32, inout
FRRAchieved: int32, inout payload: binary):
sampleBIR10 The BIR to be identified.
referenceBIR10 The BIR to be verified against.
adaptedBIR 10 A pointer to the handle of the adapted BIR. This
parameter can be EMPTY (0x00) if an adapted BIR is
not desired.
result A boolean value of true for a successful match or false
for a failed match.
FARAchieved FAR Value indicating the closeness of the match.
FRRAchieved FRR Value indicating the closeness of the match.
payload 10 If a payload is associated with the referenceBIR, it is
returned in an allocated binary if a successful match was
made.
Remarks This function compares a sampleBIR against the referenceBIR. If the match is
successful as indicated by a positive result and an adaptedBIR handle was
provided, the Service will attempt to adapt the referenceBIR from information
taken from the captured BIR.
Value Meaning
referenceBIR was not valid or Biometrics capture is in
progress.
10. In
the OPOS environment, the format of sampleBIR, referenceBIR, adaptedBIR,
and payload depends upon the value of the BinaryConversion property. See
BinaryConversion property on page A-29.

Events (UML Interfaces) 201

DataEvent
Description Notifies the application that input data is available.
Status int32 BIO_DATA_ENROLL if enroll capture is completed.
BIO_DATA_VERIFY if verify capture is completed.
Remarks The properties BIR and RawSensorData are set to appropriate values prior to a
DataEvent being delivered to the application.
See Also “Events” on page 51, BIR Property, RawSensorData Property,
beginEnrollCapture Method, beginVerifyCapture Method, endCapture
Method.
DirectIOEvent
means for a vendor-specific Biometrics Capture Service to provide events to the
Service.
from being used with other vendors’ Biometric devices which may not have any

202 Biometrics

<< event >> upos::events::ErrorEvent
Description Notifies the application that a Biometrics device error has been detected and a
suitable response by the application is necessary to process the error condition.
ErrorCode int32 Error code causing the error event. See a list of Error
Codes on page 52.
ErrorCodeExtended
int32 Extended Error code causing the error event. It may
contain a Service-specific value.
by the application. (i.e., this property is settable). See
values below.
The ErrorLocus property may be one of the following:

Value Meaning
available.
available. (Very unlikely - see Remarks.)
The contents of the ErrorResponse property are preset to a default value, based on
the ErrorLocus. The application’s error processing may change ErrorResponse to
Value Meaning
ER_CLEAR Clear all buffered input data. The error state is exited.
Default when locus is EL_INPUT.
ER_CONTINUEINPUT
Used only when locus is EL_INPUT_DATA.
Acknowledges the error and directs the Service to
continue processing. The Service remains in the error
state and will deliver additional DataEvents as directed
by the DataEventEnabled property. When all input has
been delivered and DataEventEnabled is again set to
true, then another ErrorEvent is delivered with locus
EL_INPUT. Default when locus isEL_INPUT_DATA.

Remarks Enqueued when an error is detected while trying to read biometric capture data.
This event is not delivered until DataEventEnabled is set to true and other event
delivery requirements are met, so that proper application sequencing occurs.
With proper programming, an ErrorEvent with locus EL_INPUT_DATA will
not occur. This is because each biometrics capture requires an explicit
beginXxxxxxCapture method, which can generate at most one DataEvent. The
application would need to defer the DataEvent by setting DataEventEnabled to
false and request another capture before an EL_INPUT_DATA would be possible.
page 62, “Events” on page 51.

Description Notifies the application that there is a change in the power status of a Biometric
Capture device.
Status int32 Reports a change in the power state of a Biometrics
device or reports a requested user interaction with the
Biometrics sensor to complete the capture. In the case of
the latter, the following directives can be issued:
Value Meaning
BIO_SUE_RAW_DATA Raw image data is available.
BIO_SUE_MOVE_LEFT The position was too far to the right.
BIO_SUE_MOVE_RIGHT The position was too far to the left.
BIO_SUE_MOVE_DOWN The position was too high.
BIO_SUE_MOVE_UP The position was too low.
BIO_SUE_MOVE_CLOSER The position was too far away.
BIO_SUE_MOVE_AWAY The position was too near (close).
BIO_SUE_MOVE_BACKWARD The position was too far forward.
BIO_SUE_MOVE_FORWARD The position was too far backward.
BIO_SUE_MOVE_SLOWER The motion was too fast, move slower.
BIO_SUE_MOVE_FASTER The motion was too slow, move faster.
BIO_SUE_SENSOR_DIRTY The sensor is dirty and requires cleaning.
BIO_SUE_FAILED_READ Unable to capture data from the sensor,
please retry the operation.
Remarks Enqueued when the Biometric Capture device detects a power state change or user
interaction.

204 Biometrics

C H A P T E R 6
Bump Bar
This Chapter defines the Bump Bar device category.
Summary

OutputID: int32 { read-only } 1.3 open

206 Bump Bar
AsyncMode: boolean { read-write } 1.3 open, claim, & enable
AutoToneDuration: int32 { read-write } 1.3 open, claim, & enable
AutoToneFrequency: int32 { read-write } 1.3 open, claim, & enable
BumpBarDataCount: int32 { read-only } 1.3 open, claim, & enable
CapTone: boolean { read-only } 1.3 open, claim, & enable
CurrentUnitID: int32 { read-write } 1.3 open, claim, & enable
ErrorString: string { read-only } 1.3 open
ErrorUnits: int32 { read-only } 1.3 open
EventString: string { read-only } 1.3 open & claim
EventUnitID: int32 { read-only } 1.3 open & claim
EventUnits: int32 { read-only } 1.3 open & claim
Keys: int32 { read-only } 1.3 open, claim, & enable
Timeout: int32 { read-write } 1.3 open
UnitsOnline: int32 { read-only } 1.3 open, claim, & enable

Summary 207

Common
Name Version
close ( ): 1.3
release ( ): 1.3
clearInput ( ): 1.3
void { raises-exception, use after open, claim } supporteda
Specific
Name
bumpBarSound ( units: int32, frequency: int32, duration: int32, 1.3
numberOfCycles: int32, interSoundWait: int32 ):
setKeyTranslation ( units: int32, scanCodes: int32, logicalKey: int32 ): 1.3
a. No sensitive information is generated or stored.

208 Bump Bar

ErrorResponse int32 { read-write }
upos::events::OutputCompleteEvent 1.3

General Information
The Bump Bar programmatic name is “BumpBar”.
Capabilities
The Bump Bar Control has the following minimal set of capabilities:
• Supports broadcast methods that can communicate with one, a range, or all
bump bar units online.
• Supports bump bar input (keys 0-255).
The Bump Bar Control may also have the following additional capabilities:
• Supports bump bar enunciator output with frequency and duration.
• Supports tactile feedback via an automatic tone when a bump bar key is
pressed.

210 Bump Bar
Bump Bar Class Diagram
The following diagram shows the relationships between the Bump Bar classes.
<<event>> <<utility>> <<utility>> <<Interface>>

DataEvent <<uses>>
BumpBarConst UposConst BaseControl
(from events) (from upos) (from upos) (from upos)
<<uses>>
<<uses>>
<<sends>>
<<exception>>
fires
<<event>> UposException
DirectIOEvent (from upos)
(from events)
<<sends>>
fires
<<Interface>>
BumpBarControl
(from upos)
<<capability>> CapTone : boolean
<<prop>> AsyncMode : boolean
<<prop>> Timeout : int32
<<prop>> UnitsOnline : int32
<<prop>> CurrentUnitID : int32
<<prop>> AutoToneDuration : int32
<<prop>> AutoToneFrequency : int32
<<prop>> BumpBarDataCount : int32
<<prop>> Keys : int32
<<prop>> ErrorUnits : int32
<<prop>> ErrorString : string
<<prop>> EventUnitID : int32
<<prop>> EventUnits : int32
<<prop>> EventString : string
bumpBarSound(units : int32, frequency : int32, duration : int32, numCycles : int32) : void

setKeyTranslation(units : int32, scanCodes : int32, logicalKey : int32) : void
fires fires fires
<<event>> <<event>> <<event>>

ErrorEvent StatusUpdateEvent OutputCompleteEvent
(from events) (from events) (from events)

Model
The general model of a bump bar is:

• The bump bar device class is a subsystem of bump bar units. The initial
targeted environment is food service, to control the display of order
preparation and fulfillment information. Bump bars typically are used in
conjunction with remote order displays.
The subsystem can support up to 32 bump bar units.
One application on one workstation or POS Terminal will typically manage
and control the entire subsystem of bump bars. If applications on the same or
other workstations and POS Terminals will need to access the subsystem, then
this application must act as a subsystem server and expose interfaces to other
applications.
• All specific methods are broadcast methods. This means that the method can
apply to one unit, a selection of units or all online units. The units parameter
is an int32, with each bit identifying an individual bump bar unit. (One or more
of the constants BB_UID_1 through BB_UID_32 are bitwise ORed to form
the bitmask.) The Service will attempt to satisfy the method for all unit(s)
indicated in the units parameter. If an error is received from one or more units,
the ErrorUnits property is updated with the appropriate units in error. The
ErrorString property is updated with a description of the error or errors
received. The method will then notify the application of the error condition. In
the case where two or more units encounter different errors, the Service should
determine the most severe error to report.
• The common methods checkHealth, clearInput, and clearOutput are not
broadcast methods and use the unit ID indicated in the CurrentUnitID
property. (One of the constants BB_UID_1 through BB_UID_32 are
selected.) See the description of these common methods to understand how
the current unit ID property is used.
• When the current unit ID property is set by the application, all the
corresponding properties are updated to reflect the settings for that unit.
If the CurrentUnitID property is set to a unit ID that is not online, the depen-
dent properties will contain non-initialized values.
The CurrentUnitID uniquely represents a single bump bar unit. The defini-
tions range from BB_UID_1 to BB_UID_32. These definitions are also used
to create the bitwise parameter, units, used in the broadcast methods.

212 Bump Bar
Input – Bump Bar

The Bump Bar follows the general “Device Input Model” for event-driven input
with some differences:
• When input is received, a DataEvent is enqueued.
• This device does not support the AutoDisable property, so the device will not
automatically disable itself when a DataEvent is enqueued.
• An enqueued DataEvent can be delivered to the application when the
DataEventEnabled property is true and other event delivery requirements are
met. Just before delivering this event, data is copied into corresponding
properties, and further data events are disabled by setting the
DataEventEnabled property to false. This causes subsequent input data to be
enqueued while the application processes the current input and associated
properties. When the application has finished the current input and is ready for
more data, it reenables events by setting DataEventEnabled to true.
• An ErrorEvent or events are enqueued if an error is encountered while
gathering or processing input, and are delivered to the application when the
met.
• The BumpBarDataCount property may be read to obtain the number of
bump bar DataEvents for a specific unit ID enqueued. The DataCount
property can be read to obtain the total number of data events enqueued.
• Queued input may be deleted by calling the clearInput method. See
clearInput method description for more details.
The Bump Bar Service provider must supply a mechanism for translating its inter-
nal key scan codes into user-defined codes which are returned by the data event.
Note that this translation must be end-user configurable. The default translated key
value is the scan code value.

Output – Tone Updated in Release 1.7

The bump bar follows the general “Device Output Model,” with some enhance-
ments:
• The bumpBarSound method is performed either synchronously or
asynchronously, depending on the value of the AsyncMode property.
• When AsyncMode is false, then this method operates synchronously and the
Device returns to the application after completion. When operating
synchronously, the application is notified of an error if the method could not
complete successfully.
• When AsyncMode is true, then this method operates as follows:
• The Device buffers the request in program memory, for delivery to the
Physical Device as soon as the Physical Device can receive and process
it, sets the OutputID property to an identifier for this request, and returns
as soon as possible. When the device completes the request successfully,
the EventUnits property is updated and an OutputCompleteEvent is
enqueued. A property of this event contains the output ID of the
completed request.
• If an error occurs while performing an asynchronous request, an
ErrorEvent is enqueued. The EventUnits property is set to the unit or
units in error. The EventString property is also set.
Note: ErrorEvent updates EventUnits and EventString. If an error is
reported by a broadcast method, then ErrorUnits and ErrorString are
set instead.
The event handler may call synchronous bump bar methods (but not asynchronous
methods), then can either retry the outstanding output or clear it.
• Asynchronous output is performed on a first-in first-out basis.
• All output buffered may be deleted by setting the CurrentUnitID
property and calling the clearOutput method. An
OutputCompleteEvent will not be enqueued for cleared output. This
method also stops any output that may be in progress (when possible).
Device Sharing
The bump bar is an exclusive-use device, as follows:

• The application must claim and enable the device before accessing many
bump bar specific properties.
manipulate the device.
• When a claim method is called again, settable device characteristics are
restored to their condition at release.

214 Bump Bar
Bump Bar State Diagram
/open
Closed
Opened
/close
/ claim
/close /release
/release
/close
Claimed
/setDeviceEnabled(false)
Enabled
/setDeviceEnabled(true)
[AsyncMode == true]/bumpBarSound
Normal Busy
[async requests done]

[async request I/O error or bump bar input error]
[bump bar input error]

[error event done and async requests]
[error event done and no async requests]
Error

AsyncMode Property
Syntax AsyncMode: boolean { read-write, access after open-claim-enable }
Remarks If true, then the bumpBarSound method will be performed asynchronously.
If false, tones are generated synchronously.
See Also bumpBarSound Method, “Device Output Models” on page 57.
AutoToneDuration Property
Syntax AutoToneDuration: int32 { read-write, access after open-claim-enable }
Remarks Holds the duration (in milliseconds) of the automatic tone for the bump bar unit
specified by the CurrentUnitID property.
This property is initialized to the default value for each online bump bar unit when
the device is first enabled following the open method.
See Also CurrentUnitID Property.
AutoToneFrequency Property
Syntax AutoToneFrequency: int32 { read-write, access after open-claim-enable }
Remarks Holds the frequency (in Hertz) of the automatic tone for the bump bar unit
specified by the CurrentUnitID property.
This property is initialized to the default value for each online bump bar unit when

216 Bump Bar
BumpBarDataCount Property
Syntax BumpBarDataCount: int32 { read-only, access after open-claim-enable }
Remarks Holds the number of DataEvents enqueued for the bump bar unit specified by the
CurrentUnitID property.
enqueued from a bump bar unit, but has not yet been delivered because of other
See Also CurrentUnitID Property, DataEvent.
CapTone Property
Syntax CapTone: boolean { read-only, access after open-claim-enable }
Remarks If true, the bump bar unit specified by the CurrentUnitID property supports an
enunciator.
This property is initialized when the device is first enabled following the open
method.

CurrentUnitID Property
Syntax CurrentUnitID: int32 { read-write, access after open-claim-enable }
Remarks Holds the current bump bar unit ID. Up to 32 units are allowed for one bump bar
device. The unit ID definitions range from BB_UID_1 to BB_UID_32.
Setting this property will update other properties to the current values that apply to
the specified unit.The following properties and methods apply only to the selected
bump bar unit ID:
• Properties: AutoToneDuration, AutoToneFrequency, BumpBarDataCount,
CapTone, and Keys.
• Methods: checkHealth, clearInput, clearOutput.
This property is initialized to BB_UID_1 when the device is first enabled
following the open method.
DataCount Property
Syntax DataCount: int32 { read-only, access after open }
Remarks Holds the total number of DataEvents enqueued. All units online are included in
this value. The number of enqueued events for a specific unit ID is stored in the
BumpBarDataCount property.
enqueued, but has not yet been delivered because of other application processing,
freezing of events, or other causes.
See Also BumpBarDataCount Property, DataEvent Event, “Device Input Model” on
page 54.

218 Bump Bar
ErrorString Property
Syntax ErrorString: string { read-only, access after open }
Remarks Holds a description of the error which occurred on the unit(s) specified by the
ErrorUnits property, when an error occurs for any method that acts on a bitwise
set of bump bar units.
If an error occurs during processing of an asynchronous request, the ErrorEvent
updates the property EventString instead.
This property is initialized to an empty string by the open method.
See Also ErrorUnits Property.
ErrorUnits Property
Syntax ErrorUnits: int32 { read-only, access after open }
Remarks Holds a bitwise mask of the unit(s) that encountered an error, when an error occurs
for any method that acts on a bitwise set of bump bar units.
updates the property EventUnits instead.
See Also ErrorString Property.
EventString Property
Syntax EventString: string { read-only, access after open-claim }
Remarks Holds a description of the error which occurred to the unit(s) specified by the
EventUnits property, when an ErrorEvent is delivered.
See Also EventUnits Property, ErrorEvent.

EventUnitID Property
Syntax EventUnitID: int32 { read-only, access after open-claim }
Remarks Holds the bump bar unit ID causing a DataEvent. This property is set just before
a DataEvent is delivered. The unit ID definitions range from BB_UID_1 to
BB_UID_32.
See Also DataEvent.
EventUnits Property
Syntax EventUnits: int32 { read-only, access after open-claim }
Remarks Holds a bitwise mask of the unit(s) when an OutputCompleteEvent,
ErrorEvent, or StatusUpdateEvent is delivered.
See Also OutputCompleteEvent, ErrorEvent, StatusUpdateEvent.
Keys Property
Syntax Keys: int32 { read-only, access after open-claim-enable }
Remarks Holds the number of keys on the bump bar unit specified by the CurrentUnitID
property.
method.

220 Bump Bar
Timeout Property
Syntax Timeout: int32 { read-write, access after open }
Remarks Holds the timeout value in milliseconds used by the bump bar device to complete
all output methods supported. If the device cannot successfully complete an output
method within the timeout value, then the method notifies the application of the
error.
This property is initialized to a Service dependent timeout following the open
method.
See Also AsyncMode Property, ErrorString Property, bumpBarSound Method.
UnitsOnline Property
Syntax UnitsOnline: int32 { read-only, access after open-claim-enable }
Remarks Bitwise mask indicating the bump bar units online, where zero or more of the unit
constants BB_UID_1 (bit 0 on) through BB_UID_32 (bit 31 on) are bitwise ORed.
32 units are supported.
method. This property is updated as changes are detected, such as before a
StatusUpdateEvent is enqueued and during the checkHealth method.
See Also checkHealth Method, StatusUpdateEvent.


bumpBarSound Method
Syntax bumpBarSound ( units: int32, frequency: int32, duration: int32,
units Bitwise mask indicating which bump bar unit(s) to

operate on.
frequency Tone frequency in Hertz.
duration Tone duration in milliseconds.
numberOfCycles If FOREVER, then start bump bar sounding and, repeat
continuously. Else perform the specified number of
cycles.
interSoundWait When numberOfCycles is not one, then pause for
interSoundWait milliseconds before repeating the tone
cycle (before playing the tone again)
Remarks Sounds the bump bar enunciator for the bump bar(s) specified by the units
parameter.
The duration of a tone cycle is:
duration parameter + interSoundWait parameter (except on the last tone cycle)
After the bump bar has started an asynchronous sound, then the sound may be
stopped by using the clearOutput method. (When a numberOfCycles value of
FOREVER was used to start the sound, then the application must use clearOutput
to stop the continuous sounding of tones.)

222 Bump Bar
Value Meaning

numberOfCycles is neither a positive, non-zero value
nor FOREVER.
numberOfCycles is FOREVER when AsyncMode is
false.
A negative interSoundWait was specified.
units is zero or a non-existent unit was specified.
A unit in units does not support the CapTone capability.
The ErrorUnits and ErrorString properties may be
updated before the exception is thrown.
E_FAILURE An error occurred while communicating with one of the
bump bar units specified by the units parameter. The
ErrorUnits and ErrorString properties are updated
before the exception is thrown. (Can only occur if
AsyncMode is false.)
See Also AsyncMode Property, ErrorUnits Property, ErrorString Property, CapTone
Property, clearOutput Method.

checkHealth Method (Common)

Value Meaning

extent possible.
device.
CH_INTERACTIVE Perform an interactive test of the device. The Service
will typically display a modal dialog box to present test
options and results.
Remarks When CH_INTERNAL or CH_EXTERNAL level is requested, the method will
check the health of the bump bar unit specified by the CurrentUnitID property.
When the current unit ID property is set to a unit that is not currently online, the
device will attempt to check the health of the bump bar unit and report a
communication error if necessary. The CH_INTERACTIVE health check
operation is up to the Service designer.
A text description of the results of this method is placed in the CheckHealthText
property.
The UnitsOnline property will be updated with any changes before returning to
the application.
Value Meaning
E_FAILURE An error occurred while communicating with the bump

bar unit specified by the CurrentUnitID property.
See Also CurrentUnitID Property, UnitsOnline Property.

224 Bump Bar
clearInput Method (Common)

void { raises-exception, use after open-claim }
Remarks Clears the device input that has been buffered for the unit specified by the
Any data events that are enqueued – usually waiting for DataEventEnabled to be
set to true and FreezeEvents to be set to false – are also cleared.
See Also CurrentUnitID Property, “Device Input Model” on page 54.
clearOutput Method (Common) Updated in Release 1.7

Remarks Clears the tone outputs that have been buffered, including all asynchronous output,
for the unit specified by the CurrentUnitID property.
Any output complete and output error events that are enqueued – usually waiting
for DataEventEnabled to be set to true and FreezeEvents to be set to false – are
also cleared.
See Also CurrentUnitID Property, “Device Output Models” on page 57.

setKeyTranslation Method
Syntax setKeyTranslation ( units: int32, scanCode: int32, logicalKey: int32 ):
units Bitwise mask indicating which bump bar unit(s) to set

key translation for.
scanCode The bump bar generated key scan code. Valid values 0-
255.
logicalKey The translated logical key value. Valid values 0-255.
Remarks Assigns a logical key value to a device-specific key scan code for the bump bar
unit(s) specified by the units parameter. The logical key value is used during
translation during the DataEvent.
Value Meaning

scanCode or logicalKey are out of range.
units is zero or a non-existent unit was specified.
The ErrorUnits and ErrorString properties are
updated prior to notifying the application of the error.
See Also ErrorUnits Property, ErrorString Property, DataEvent.

226 Bump Bar
DataEvent
Status: int32 {read-only }
Description Notifies the application when status from the bump bar is available.
Status int32 See below.

The Status property is divided into four bytes. Depending on the Event Type,
located in the low word, the remaining 2 bytes will contain additional data. The
diagram below indicates how the Status property is divided:
High Word Low Word (Event Type)

High Byte Low Byte
Unused. Always zero. LogicalKeyCode BB_DE_KEY
Remarks Enqueued to present input data from a bump bar unit to the application. The low
word contains the Event Type. The high word contains additional data depending
on the Event Type. When the Event Type is BB_DE_KEY, the low byte of the
high word contains the LogicalKeyCode for the key pressed on the bump bar unit.
The LogicalKeyCode value is device independent. It has been translated by the
Service from its original hardware specific value. Valid ranges are 0-255.
The EventUnitID property is updated before delivering the event.
See Also “Device Input Model” on page 54, EventUnitID Property, DataEventEnabled

DirectIOEvent
means for a vendor-specific Bump Bar Service to provide events to the application
that are not otherwise supported by the Control.
Service.
from being used with other vendor’s Bump Bar devices which may not have any

228 Bump Bar

Description Notifies the application that a Bump Bar error has been detected and a suitable
response by the application is necessary to process the error condition.
Codes on page 52.
ErrorCodeExtended
int32 Extended Error code causing the error event. If
ErrorCode is E_EXTENDED, then see values below.
Otherwise, it may contain a Service-specific value.
by the application (i.e., this property is settable). See
values below.
Value Meaning

available.
available.

the ErrorLocus. The application’s error event listener may change ErrorResponse
to one of the following values:
Value Meaning
ER_RETRY Use only when locus is EL_OUTPUT.

Retry the asynchronous output. The error state is exited.
Default when locus is EL_OUTPUT.
state is exited.
ER_CONTINUEINPUT
Use only when locus is EL_INPUT_DATA.
continue processing. The Device remains in the error
state, and will deliver additional DataEvents as directed
been delivered and the DataEventEnabled property is
Default when locus is EL_INPUT_DATA.
Remarks Enqueued when an error is detected while gathering data from or processing
asynchronous output for the bump bar.
Input error events are not delivered until the DataEventEnabled property is true,
so that proper application sequencing occurs.
The EventUnits and EventString properties are updated before the event is
delivered.
See Also “Device Output Models” on page 57, “Device Information Reporting Model” on
page 62, DataEventEnabled Property, EventUnits Property, EventString
Property.

230 Bump Bar
OutputCompleteEvent
<< event >> upos::events::OutputCompleteEvent

is complete. The EventUnits property is updated before
delivering.
Remarks Enqueued when a previously started asynchronous output request completes
successfully.
See Also EventUnits Property, “Device Output Models” on page 57.
StatusUpdateEvent
Description Notifies the application that the bump bar has had an operation status change.
Status int32 Reports a change in the power state of a bump bar unit.
process.
Remarks Enqueued when the bump bar device detects a power state change.
Deviation from the standard StatusUpdateEvent (See “StatusUpdateEvent”
description on page 108)
• Before delivering the event, the EventUnits property is set to the units for
which the new power state applies.
• When the bump bar device is enabled, then a StatusUpdateEvent is enqueued
to specify the bitmask of online units.
• While the bump bar device is enabled, a StatusUpdateEvent is enqueued
when the power state of one or more units change. If more than one unit
changes state at the same time, the Service may choose to either enqueue
multiple events or to coalesce the information into a minimal number of events
applying to EventUnits.
See Also EventUnits Property.

C H A P T E R 7
Cash Changer
This Chapter defines the Cash Changer device category.
Summary


232 Cash Changer
CapDeposit: boolean {read-only} 1.5 open
CapDepositDataEvent: boolean {read-only} 1.5 open
CapEmptySensor: boolean {read-only} 1.2 open
CapNearEmptySensor: boolean {read-only} 1.2 open
CapRepayDeposit: boolean {read-only} 1.5 open

AsyncResultCode: int32 {read-only} 1.2 open, claim, & enable
AsyncResultCodeExtended: int32 {read-only} 1.2 open, claim, & enable
CurrencyCashList: string {read-only} 1.2 open

CurrencyCodeList: string {read-only} 1.2 open
CurrentExit: int32 {read-write} 1.2 open
CurrentService: int32 {read-write} 1.11 open
DeviceExits: int32 {read-only} 1.2 open
DeviceStatus: int32 {read-only} 1.2 open, claim, & enable
ExitCashList: string {read-only} 1.2 open
RealTimeDataEnabled: boolean {read-write} 1.11 open, claim & enable
ServiceCount: int32 {read-only} 1.11 open
ServiceIndex: int32 {read-only} 1.11 open

Summary 233

Common
Name Version
close ( ): 1.2
release ( ): 1.2
clearInput ( ): 1.5
void { } supported
void { } supported
Specific
Name
dispenseCash ( cashCounts: string ): 1.2
dispenseChange ( amount: int32 ): 1.2
fixDeposit ( ): 1.5

234 Cash Changer



General Information
The Cash Changer programmatic name is “CashChanger”.
Capabilities Updated in Release 1.11
The Cash Changer has the following capabilities:

• Reports the cash units and corresponding unit counts available in the Cash
Changer.
• Dispenses a specified amount of cash from the device in either bills, coins, or
both into a user-specified exit.
• Dispenses a specified number of cash units from the device in either bills,
coins, or both into a user-specified exit.
The Cash Changer may also have the following additional capabilities:
• Reporting the fullness levels of the Cash Changer’s cash units. Conditions
which may be indicated include empty, near empty, full, and near full states.
Release 1.5 and later – Support for the cash acceptance is added
as an option.
• The money (bills and coins) which is deposited into the device between the
start and end of cash acceptance is reported to the application. The contents of
the report are cash units and cash counts.
Release 1.11 and later – Support for the use of cash device sub-
services
• The service can use sub-services for other cash devices to create a full-
function cash changer service. Properties are added for the extraction of
information from the sub-services.

236 Cash Changer
CashChanger Class Diagram Updated in Release 1.11
The following diagram shows the relationships between the CashChanger classes.
(from upos) (from upos)
<<sends>>
<<Interface>>
CashChangerControl
(from upos)
<<capability>> CapDeposit : boolean <<utility>>
<<capability>> CapDepositDataEvent : boolean CashChangerConst
<<event>> <<capability>> CapDiscrepancy : boolean (from upos)
DataEvent <<capability>> CapEmptySensor : boolean
(from events)
<<capability>> CapFullSensor : boolean
<<capability>> CapJamSensor : Boolean
fires <<capability>> CapNearEmptySensor : boolean <<uses>>
<<capability>> CapPauseDeposit : boolean
<<capability>> CapRealTimeData : Boolean
<<event>> <<capability>> CapRepayDeposit : boolean
DirectIOEvent <<prop>> AsyncMode : boolean
(from events) fires <<prop>> AsyncResultCode : int32
<<prop>> AsyncResultCodeExtended : int32
<<prop>> CurrencyCashList : string
<<prop>> CurrencyCodeList : string
<<prop>> CurrentExit : int32
<<event>> fires <<prop>> CurrentService : int32
StatusUpdateEvent <<prop>> DepositAmount : int32
(from events) <<prop>> DepositCashList : string
<<prop>> DepositCodeList : string
<<prop>> DepositCounts : string
fires <<prop>> DepositStatus : int32
<<prop>> DeviceExits : int32
<<event>> <<prop>> DeviceStatus : int32
ErrorEvent <<prop>> ExitCashList : string
(from events) <<prop>> FullStatus : int32
<<prop>> ServiceCount : int32
<<prop>> ServiceIndex : int32
adjustCashCounts(cashCounts : string)
beginDeposit()
dispenseCash(cashCounts : string)
dispenseChange(amount : int32)
endDeposit(amount : int32)
fixDeposit()
pauseDeposit(control : int32)
readCashCounts(cashCounts : string, discrepancy : boolean)

Model Updated in Release 1.11
The general model of a Cash Changer is:

• Supports several cash types such as coins, bills, and combinations of coins and
bills. The supported cash type for a particular currency is noted by the list of
cash units in the CurrencyCashList property.
such as a cash entry holding bin, a number of slots or bins which can hold the
cash, and cash exits.
• Prior to Release 1.5 this specification provides programmatic control only for
the dispensing of cash. The accepting or removing of cash by the device (for
example, to replenish cash) is controlled by the adjustCashCounts method,
unless the device can determine the amount of cash on its own. The
application can call readCashCounts to retrieve the current unit count for
each cash unit, but cannot control when or how cash is added to the device.
• May have multiple exits. The number of exits is specified in the DeviceExits
property. The application chooses a dispensing exit by setting the
CurrentExit property. The cash units which may be dispensed to the current
exit are indicated by the ExitCashList property. When CurrentExit is 1, the
exit is considered the “primary exit” which is typically used during normal
processing for dispensing cash to a customer following a retail transaction.
When CurrentExit is greater than 1, the exit is considered an “auxiliary exit.”
An “auxiliary exit” typically is used for special purposes such as dispensing
quantities or types of cash not targeted for the “primary exit.”
• Dispenses cash into the exit specified by CurrentExit when either
dispenseChange or dispenseCash is called. With dispenseChange, the
application specifies a total amount to be dispensed, and it is the responsibility
of the Cash Changer device or the Control to dispense the proper amount of
cash from the various slots or bins. With dispenseCash, the application
specifies a count of each cash unit to be dispensed.
• Dispenses cash either synchronously or asynchronously, depending on the
value of the AsyncMode property.
When AsyncMode is false, then the cash dispensing methods are performed
synchronously and the dispense method returns the completion status to the
application.
When AsyncMode is true and no exception is thrown by either
dispenseChange or dispenseCash, then the method is performed
asynchronously and its completion is indicated by a StatusUpdateEvent with
its Data property set to CHAN_STATUS_ASYNC. The request’s completion
status is set in the AsyncResultCode and AsyncResultCodeExtended
properties.
The values of AsyncResultCode and AsyncResultCodeExtended are the
same as those for the ErrorCode and ErrorCodeExtended properties of a
UposException when an error occurs during synchronous dispensing.
Nesting of asynchronous Cash Changer operations is illegal; only one
asynchronous method can be processed at a time.

238 Cash Changer
The readCashCounts method may not be called while an asynchronous

method is being performed since doing so could likely report incorrect cash
counts.
set to the currency, selecting from a currency in the list CurrencyCodeList.
CurrencyCashList, ExitCashList, dispenseCash, dispenseChange and
readCashCounts all act upon the current currency only.
• Sets the cash slot (or cash bin) conditions in the DeviceStatus property to
show empty and near empty status, and in the FullStatus property to show full
and near full status. If there are one or more empty cash slots, then
DeviceStatus is CHAN_STATUS_EMPTY, and if there are one or more full
cash slots, then FullStatus is CHAN_STATUS_FULL.
• After Release 1.5 — Support for cash acceptance is added as an
option.
• The cash acceptance model is as follows:
• Note that the AsyncMode property has no affect on methods that have been
added for cash acceptance, since these are treated as input methods.
• The dispensing of change function of this device is not dependent upon the
availability of a “cash acceptance” function option. Dispensing of change and
collection of money are two independent functions.
• Receipt of cash (cash acceptance function) is an option that may be provided
by the Cash Changer device. Cash acceptance into the “cash acceptance
mechanism” is started by invoking the beginDeposit method. The previous
values of the properties DepositCounts and DepositAmount are initialized to
zero.
cash is stored in the DepositCounts and DepositAmount properties. If the
CapDepositDataEvent capability was previously set to true, then a
DataEvent is generated to inform the application that cash has been collected.
If the pauseDeposit method is executed with a parameter value of
CHAN_DEPOSIT_PAUSE, then the counting of the deposited cash is
method is executed with a parameter value of CHAN_DEPOSIT_RESTART,
process remains static until an endDeposit method is executed. At this point
the “cash acceptance” mechanism is notified to stop accepting cash. If
endDeposit method receives a CHAN_DEPOSIT_CHANGE parameter, then
the mechanism will dispense cash change back to the user. If endDeposit is
invoked with a CHAN_DEPOSIT_NOCHANGE parameter, then the
mechanism will not dispense cash change back to the user. Finally, if
endDeposit is invoked with a CHAN_DEPOSIT_REPAY parameter, then all
collected cash is returned back to the user by the mechanism.
• Two types of Cash Changer mechanisms are covered by this standard. In one
case where CapRepayDeposit is true, the bins that are used for collecting the
cash are the same bins that are used for dispensing the cash as change. In the

other case where CapRepayDeposit is false, the bins that are used for
collecting the cash are different from the bins that are used for dispensing the
change. In the first case, if a transaction is aborted for any reason, the same
cash the user input to the mechanism will be returned to the user. In the second
case, it is up to the application to dispense an equivalent amount of cash (not
the same physical cash collected) back to the user for an aborted transaction.
• The Cash Changer mechanisms can only be used in one mode at a time. While
the mechanism is collecting deposited cash, it cannot dispense change at the
same time. Therefore, while beginDeposit method is being executed, no
payment of change can occur. Only after an endDeposit method call can the
proper amount of change be determined (either by the application or by a
“smart” Cash Changer) and dispensed to the user. Each Cash Changer
manufacturer must determine the amount of time it takes to process the
received cash and place in storage bins before it completes the endDeposit
method.
• After Release 1.11 — Support for the use of cash device sub-
services.
• The cash device sub-service model is as follows:
• Cash Changer service can utilize other cash device sub-services, such as coin
dispensers, coin acceptors, bill dispenser, bill acceptors and other cash
changers to access device hardware, creating a full function cash changer
service. Each call to the cash changer service will invoke the corresponding
call to the sub-services. Therefore, an open call will call the open method of
all of the sub-services, claim will call claim, and so forth. The same can be said
for the cash changer properties. Some properties are available for dispensers,
while others are available only for acceptors. It is up to the aggregating cash
changer service to analyze and interpret the results of its communications to
the sub-services and report to the application. For example, if the open call
fails for one of the sub services, the exception should be passed up to the
application. The mapping of the properties and methods from service to sub-
service is as follows:
Cash Coin Bill Coin Bill

Changer Dispenser Dispenser Acceptor Acceptor
CapDeposit
CapDepositDataEvent
CapDiscrepancy X X X X
CapEmptySensor X X
CapJamSensor X X X X
CapFullSensor X X
CapNearEmptySensor X X
CapNearFullSensor X X
CapPauseDeposit X X
CapRealTimeData X X
CapRepayDeposit
AsyncMode X
AsyncResultCode X

240 Cash Changer
Cash Coin Bill Coin Bill

Changer Dispenser Dispenser Acceptor Acceptor
AsyncResultCodeExtended X
CurrencyCashList X
CurrencyCode X X X
CurrencyCodeList X
CurrentExit X
CurrentService
DepositAmount X X
DepositCashList X X
DepositCodeList X X
DepositCounts X X
DepositStatus X X
DeviceExits X
DeviceStatus DispenserStatus X
ExitCashList X
FullStatus X X
ServiceCount
ServiceIndex
RealTimeDataEnabled X X
beginDeposit() X X
dispenseCash() X
dispenseChange( ) X
endDeposit() X X
fixDeposit( ) X X
pauseDeposit() X X
readCashCounts() X X X X
• ServiceCount lists the number of sub-services used by the cash changer.

• ServiceIndex is a byte segmented property containing the index for each sub-
service.
• If access to sub-service property and method information is desired, setting the
CurrentService property to the desired index will allow the application to
request property information of the specified sub-service.
Coin Cash Changer Service
<<Interface>> CashChangerService
POS
CashChangerControl
Application Bill Acceptor
(f rom up os)
Service
Bill Dispenser
Example of a Cash Changer Service using a coin cash changer Service
service, a bill acceptor service and a bill dispenser service.

Cash Changer Sequence Diagram Added in Release 1.7
CashChanger device. This means that the Claimed, DeviceEnabled properties are == true
:ClientApp :CashChanger :CashChangerService :Human Actor
register to receive DataEvent with Control
setDataEventEnabled(true)
beginDeposit() DepositCounts and DepositAmount

beginDeposit()
property values are initialized
accepting cash
DepositCounts and DepositAmount

property values are Updated
deliver DataEvent
deliver DataEvent
pauseDeposit(Pause)
pauseDeposit(Pause)
while check amount accepted

is < amount of sale
pauseDeposit(Restart)
pauseDeposit(Restart)
accepting cash
DepositCounts and DepositAmount

property values are Updated
deliver DataEvent
deliver DataEvent
end loop
fixDeposit() DepositCounts and DepositAmount
fixDeposit() property values are finalized
endDeposit(Change/
endDeposit(Change/
Nochange/Repayment)
Nochange/Repayment)
if there is change
dispenseChange() or
dispenseChange() or
dispenseCash()
dispenseCash()
change
end if

242 Cash Changer
Cash Changer State Diagram Updated in Release 1.8
close()
Closed open() Opened claim() Claimed

close()
release()
release() clearInput()
close()
DepositCount == 0 setDeviceEnabled( true )
DepositAmount == 0
clearInput() ClearInput Processing
Enabled
beginDeposit() entry/ empty data queue
ReceiptMoney
Wait endDeposit() endDeposit()
pauseDeposit( CHAN_DEPOSIT_RESTART )
clearInput()
clearInput()
done pauseDeposit( CHAN_DEPOSIT_PAUSE )
PauseMode
FixMode
entry/ sync DepositCounts and DepositAmount

dispenseChange(), dispenseCash()
Pay Money
done
[asyncMode == false] [asyncMode == true] Fire Events
Synchronous Pay Async
fire event entry/ enqueue StatusUpdateEvents
Device Sharing
The Cash Changer is an exclusive-use device, as follows:


AsyncMode Property
Remarks If true, the dispenseCash and dispenseChange methods will be performed
asynchronously. If false, these methods will be performed synchronously.
This property is initialized to false by the Open method.
See Also AsyncResultCode Property, AsyncResultCodeExtended Property,
dispenseChange Method, dispenseCash Method.
AsyncResultCode Property
Syntax AsyncResultCode: int32 { read-only, access after open-claim-enable }
dispenseCash or dispenseChange was called with AsyncMode true).
This property is set before a StatusUpdateEvent event is delivered with a Status
value of CHAN_STATUS_ASYNC.
See Also AsyncMode Property, dispenseCash Method, dispenseChange Method.
AsyncResultCodeExtended Property
Syntax AsyncResultCodeExtended: int32 { read-only, access after open-claim-
enable}
dispenseCash or dispenseChange was called with AsyncMode true).
This property is set before a StatusUpdateEvent event is delivered with a Status
value of CHAN_STATUS_ASYNC.
See Also AsyncMode Property, dispenseCash Method, dispenseChange Method.

244 Cash Changer
CapDeposit Property Added in Release 1.5

Syntax CapDeposit: boolean { read-only, access after open }
Remarks If true, the Cash Changer supports cash acceptance.
See Also beginDeposit Method, endDeposit Method, fixDeposit Method, pauseDeposit
Method.
CapDepositDataEvent Property Added in Release 1.5

Syntax CapDepositDataEvent: boolean { read-only, access after open }
Remarks If true, the Cash Changer can report a cash acceptance event.
See Also beginDeposit Method, endDeposit Method, fixDeposit Method, pauseDeposit
Method.
Remarks If true, the Cash Changer can report the condition that some cash slots are empty.

Remarks If true, the Cash Changer can report the condition that some cash slots are full.
CapJamSensor Property Added in Release 1.11

Remarks If true, the Cash Changer can report a mechanical jam or failure condition.
Remarks If true, the Cash Changer can report the condition that some cash slots are nearly
empty.
Remarks If true, the Cash Changer can report the condition that some cash slots are nearly
full.

246 Cash Changer
CapPauseDeposit Property Added in Release 1.5

Remarks If true, the Cash Changer has the capability to suspend cash acceptance processing
temporarily.
CapRealTimeData Property Added in Release 1.11

Remarks If true, the device is able to supply data as the money is being accepted (“real
time”).
See Also RealTimeDataEnabled property.
CapRepayDeposit Property Added in Release 1.5

Syntax CapRepayDeposit: boolean { read-only, access after open }
Remarks If true, the Cash Changer has the capability to return money that was deposited.
See Also endDeposit Method.
CurrencyCashList Property
Syntax CurrencyCashList: string { read-only, access after open }
Remarks Holds the cash dispensing units supported in the Cash Changer for the currency
represented by the CurrencyCode Property.
The string consists of ASCII numeric comma delimited values which denote the
units of coins, then the ASCII semicolon character (“;”) followed by ASCII
numeric comma delimited units of bills that can be used with the Cash Changer. If
a semicolon (“;”) is absent, then all units represent coins.
Below are sample CurrencyCashList values in Japan.

• “1,5,10,50,100,500” ---
1, 5, 10, 50, 100, 500 yen coin.
• “1,5,10,50,100,500;1000,5000,10000” ---
1, 5, 10, 50, 100, 500 yen coin and 1000, 5000, 10000 yen bill.
• “;1000,5000,10000” ---
1000, 5000, 10000 yen bill.
Remarks Contains the active currency code to be used by Cash Changer operations. This
property is initialized to an appropriate value by the open method. This value is
guaranteed to be one of the set of currencies specified by the CurrencyCodeList
property.
Value Meaning
CurrencyCodeList.
See Also CurrencyCodeList Property.
CurrencyCodeList Property
Syntax CurrencyCodeList: string { read-only, access after open }
Remarks Holds a list of ASCII three-character ISO 4217 currency codes separated by
commas. For example, if the string is “JPY,USD”, then the Cash Changer supports


248 Cash Changer
CurrentExit Property
Syntax CurrentExit: int32 { read-write, access after open }
Remarks Holds the current cash dispensing exit. The value 1 represents the primary exit (or
normal exit), while values greater then 1 are considered auxiliary exits. Legal
values range from 1 to DeviceExits.
Below are examples of typical property value sets in Japan. CurrencyCode is

“JPY” and CurrencyCodeList is “JPY”.
• Cash Changer supports coins; only one exit supported:
CurrencyCashList = “1,5,10,50,100,500”
DeviceExits = 1
CurrentExit = 1 : ExitCashList = “1,5,10,50,100,500”
• Cash Changer supports both coins and bills; an auxiliary exit is used for
larger quantities of bills:
CurrencyCashList = “1,5,10,50,100,500;1000,5000,10000”
DeviceExits = 2
When CurrentExit = 1 : ExitCashList =
“1,5,10,50,100,500;1000,5000”
• Cash Changer supports bills; an auxiliary exit is used for larger quantities
of bills:
CurrencyCashList = “;1000,5000,10000”
DeviceExits = 2
When CurrentExit = 1 : ExitCashList = “;1000,5000”
Value Meaning
E_ILLEGAL An invalid CurrentExit value was specified.
See Also CurrencyCashList Property, DeviceExits Property, ExitCashList Property.

CurrentService Property Added in Release 1.11

Syntax CurrentService: int32 { read-write, access after open }
Remarks Holds the current service. The value 0 represents the primary service, while values
greater than 0 and less than or equal to ServiceCount are used to request
information from the integrated services. Legal values range from 0 to
ServiceCount. The readCashCounts method and all of the properties, common
and specific, are accessible when the CurrentService is greater than 0.
CurrentService, ServiceCount and ServiceIndex will always reflect the primary
service.
Below are examples of a cash changer service using services for separate Coin
Acceptor and Dispenser and a bills only cash changer. A StatusUpdateEvent
indicting a jam has been received by the application. Only the bill changer and the
coin dispenser can detect a jam.
• Checking the values of the primary service:
CurrentService = 0
ServiceCount = 3
ServiceIndex = 50528769 (X’03030201’)
DeviceStatus = CHAN_STATUS_JAM
DeviceServiceDescription = “Integrated Cash Changer Service 1.11.05”
• Changing the service to get information about the coin dispenser:
CurrentService = 2
ServiceCount = 3
ServiceIndex = 50528769 (X’03030201’)
DeviceStatus = CHAN_STATUS_OK
DeviceServiceDescription = “Pennybrite Coin Dispenser Service”
• The coin dispenser looks ok. Check the bill changer:
CurrentService = 3
ServiceCount = 3
ServiceIndex = 50528769 (X’03030201’)
DeviceStatus = CHAN_STATUS_JAM
DeviceServiceDescription = “Benjamin Bill Changer Service”
Value Meaning
E_ILLEGAL An invalid CurrentService value was specified.
See Also ServiceCount Property, ServiceIndex Property.

250 Cash Changer
DepositAmount Property Added in Release 1.5

after the call to the beginDeposit method, there would be 18,057 yen in the Cash
Changer.
DepositCashList Property Added in Release 1.5

Remarks Holds the cash units supported in the Cash Changer for the currency represented
by the CurrencyCode property. It is set to an empty string when the cash
acceptance process is not supported.
It consists of ASCII numeric comma delimited values which denote the units of
coins, then the ASCII semicolon character (“;”) followed by ASCII numeric
comma delimited values for the bills that can be used with the Cash Changer. If
the semicolon (“;”) is absent, then all units represent coins.

• “1,5,10,50,100,500” ---
1, 5, 10, 50, 100, 500 yen coin.
• “1,5,10,50,100,500;1000,5000,10000” ---
1, 5, 10, 50, 100, 500 yen coin and 1000, 5000, 10000 yen bill.
• “;1000,5000,10000” ---
1000, 5000, 10000 yen bill.

DepositCodeList Property Added in Release 1.5

Remarks Holds the currency code indicators for cash accepted. It is set to an empty string
when the cash acceptance process is not supported.
It is a list of ASCII three-character ISO 4217 currency codes separated by com-
mas. For example, if the string is “JPY,USD”, then the Cash Changer supports
DepositCounts Property Added in Release 1.5

Remarks Holds the total of the cash accepted by the cash units. The format of the string is
the same as cashCounts in the dispenseCash method. Cash units inside the string
are the same as the DepositCashList property, and are in the same order. It is set
to an empty string when the cash acceptance function is not supported.
property is set to
1:80,5:77,10:0,50:54,100:0,500:87
After the call to the beginDeposit method, there would be 80 one yen coins, 77
five yen coins, 54 fifty yen coins, and 87 five hundred yen coins in the Cash
Changer.
This property is initialized by the open method
.

252 Cash Changer
DepositStatus Property Added in Release 1.5

Remarks Holds the current status of the cash acceptance operation. It may be one of the
following values:
Value Meaning
CHAN_STATUS_DEPOSIT_START
CHAN_STATUS_DEPOSIT_END
CHAN_STATUS_DEPOSIT_NONE
Cash acceptance not supported.
CHAN_STATUS_DEPOSIT_COUNT
CHAN_STATUS_DEPOSIT_JAM
property is set to CHAN_STATUS_DEPOSIT_END after initialization, or to
CHAN_STATUS_DEPOSIT_NONE if the device does not support cash
acceptance.
DeviceExits Property
Syntax DeviceExits: int32 { read-only, access after open }
Remarks The number of exits for dispensing cash.
See Also CurrentExit Property.

DeviceStatus Property
Syntax DeviceStatus: int32 { read-only, access after open-claim-enable }
Remarks Holds the current status of the Cash Changer. It may be one of the following:
Value Meaning
CHAN_STATUS_OK The current condition of the Cash Changer is
satisfactory.
CHAN_STATUS_EMPTY
Some cash slots are empty.
CHAN_STATUS_NEAREMPTY
Some cash slots are nearly empty.
CHAN_STATUS_JAM A mechanical fault has occurred.
ExitCashList Property
Syntax ExitCashList: string { read-only, access after open }
Remarks Holds the cash units which may be dispensed to the exit which is denoted by
CurrentExit property. The supported cash units are either the same as
CurrencyCashList, or a subset of it. The string format is identical to that of
CurrencyCashList.
CurrencyCode or CurrentExit is set.
See Also CurrencyCode Property, CurrencyCashList Property, CurrentExit Property.
FullStatus Property
Value Meaning
CHAN_STATUS_OK All cash slots are neither nearly full nor full.
CHAN_STATUS_FULL Some cash slots are full.
CHAN_STATUS_NEARFULL

254 Cash Changer
RealTimeDataEnabled Property Added in Release 1.11

Remarks If true and CapRealTimeData is true, each data event fired will update the
DepositAmount and DepositCounts properties. Otherwise, DepositAmount and
DepositCounts are updated with the value of the money collected when fixDeposit is
called. Setting RealTimeDataEnabled will not cause any change in system behavior
until a subsequent beginDeposit method is performed. This prevents confusion
regarding what would happen if it were modified between a beginDeposit -
endDeposit pairing.
Value Meaning
See Also CapRealTimeData property, DepositAmount property, DepositCounts
property, beginDeposit Method, endDeposit Method, fixDeposit Method.
ServiceCount Property Added in Release 1.11

Syntax ServiceCount: int32 { read-only, access after open-claim-enable }
Remarks The number of integrated services used by the cash changer service. If the service
does not utilize other services, this value will be zero.
See Also CurrentService Property, ServiceIndex Property.
ServiceIndex Property Added in Release 1.11

Syntax ServiceIndex: int32 { read-only, access after open-claim-enable }
Remarks The value is divided into four bytes indicating the service index for each of the
integrated service types.The diagram below indicates how the property is divided:
A value of zero means that no integrated services are utilized.
High Word Low Word

High Byte Low Byte High Byte Low Byte
Bill Dispenser Bill Acceptor Coin Dispenser Coin Acceptor

See Also CurrentService Property, ServiceCount Property.


adjustCashCounts Method Added in Release 1.11
Remarks This method is called to set the initial amounts in the cash changer after initial
amount currently in the changer.
For example if the currency is Japanese yen and the cashCounts parameter is set
to .1:80,5:77,50:54,100:0,500:87. as a result of calling the adjustCashCounts
method, then there would be eighty one yen coins, seventy-seven five yen coins,
fifty-four fifty yen coins, zero one hundred yen coins, and eighty-seven five-
hundred yen coins in the Cash Changer.
Value Meaning

256 Cash Changer
beginDeposit Method Added in Release 1.5

After calling this method, if CapDepositDataEvent is true, cash acceptance is
reported by DataEvents until fixDeposit is called while the deposit process is not
paused.
Value Meaning
E_ILLEGAL Either the Cash Changer does not support cash
acceptance, or the call sequence is not correct.
See Also CapDepositDataEvent Property, DepositAmount Property, DepositCounts
Property, endDeposit Method, fixDeposit Method, pauseDeposit Method.

dispenseCash Method
Syntax dispenseCash ( cashCounts: string ):
The cashCounts parameter contains the dispensing cash units and counts,
represented by the format of “cash unit:cash counts, ..;.., cash unit:cash counts”.
Units before “;” represent coins, and units after “;” represent bills. If “;” is absent,
then all units represent coins.
Remarks Dispenses the cash from the Cash Changer into the exit specified by CurrentExit.
The cash dispensed is specified by pairs of cash units and counts.

Some cashCounts examples, using Japanese yen as the currency, are shown below.
• “10:5,50:1,100:3,500:1”
Dispense 5 ten yen coins, 1 fifty yen coins, 3 one hundred yen coins, 1 five
hundred yen coins.
• “10:5,100:3;1000:10”
Dispense 5 ten yen coins, 3 one hundred yen coins, and 10 one thousand
yen bills.
• “;1000:10,10000:5”
Dispense 10 one thousand yen bills and 5 ten thousand yen bills.
Value Meaning
E_BUSY Cash cannot be dispensed because an asynchronous
• The cashCounts parameter value was illegal for the
current exit.
• Cash could not be dispensed because cash
acceptance was in progress.
E_EXTENDED ErrorCodeExtended = ECHAN_OVERDISPENSE:
The specified cash cannot be dispensed because of a
cash shortage.

258 Cash Changer
dispenseChange Method
Syntax dispenseChange ( amount: int32 ):
The amount parameter contains the amount of change to be dispensed. It is up to
the Cash Changer to determine what combination of bills and coins will satisfy the
tender requirements from its available supply of cash.
Remarks Dispenses the specified amount of cash from the Cash Changer into the exit
represented by CurrentExit.
Value Meaning
E_BUSY The specified change cannot be dispensed because an
asynchronous method is in progress.
• A negative or zero amount was specified.
• The amount could not be dispensed based on the
values specified in ExitCashList for the current
exit.
• Change could not be dispensed because cash
acceptance was in progress.
E_EXTENDED ErrorCodeExtended = ECHAN_OVERDISPENSE:
The specified change cannot be dispensed because of a
cash shortage.

endDeposit Method Added in Release 1.5

CHAN_DEPOSIT_CHANGE The deposit is accepted and the deposited
amount is greater than the amount required.
CHAN_DEPOSIT_NOCHANGE The deposit is accepted and the deposited
amount is equal to or less than the amount
required.
CHAN_DEPOSIT_REPAY The deposit is to be repaid through the cash
deposit exit or the cash payment exit.
If the deposited amount is greater than the amount required then success is set to
CHAN_DEPOSIT_CHANGE. If the deposited amount is equal to or less than the
amount required then success is set to CHAN_DEPOSIT_NOCHANGE.
If success is set to CHAN_DEPOSIT_REPAY then the deposit is repaid through
either the cash deposit exit or the cash payment exit without storing the actual
deposited cash.
When the deposit is repaid, it is repaid in the exact cash unit quantities that were
deposited. Depending on the actual device, the cash repaid may be the exact same
bills and coins that were deposited, or it may not.
Value Meaning
• Cash acceptance is not supported.
See Also CapDepositDataEvent Property, DepositAmount Property, DepositCounts
Property, beginDeposit Method, fixDeposit Method, pauseDeposit Method.

260 Cash Changer
fixDeposit Method Added in Release 1.5

values in the Cash Changer.
Value Meaning

pauseDeposit Method Added in Release 1.5

CHAN_DEPOSIT_PAUSE Cash acceptance is paused.
CHAN_DEPOSIT_RESTART Cash acceptance is resumed.
If control is CHAN_DEPOSIT_PAUSE, the cash acceptance operation is paused.
to CHAN_DEPOSIT_RESTART. It is valid to call fixDeposit then endDeposit
When the deposit process is paused, the depositCounts and depositAmount
properties are updated to reflect the current state of the Cash Changer. The
property values are not changed again until the deposit process is resumed.
If control is CHAN_DEPOSIT_RESTART, the deposit process is resumed.
Value Meaning
set to CHAN_DEPOSIT_PAUSE, or the deposit
CHAN_DEPOSIT_RESTART.
See Also CapDepositDataEvent Property, CapPauseDeposit Property, DepositAmount
Property, DepositCounts Property, beginDeposit Method, endDeposit Method,
fixDeposit Method.

262 Cash Changer
readCashCounts Method
Remarks The format of the string cashCounts is the same as cashCounts in the
dispenseCash method. Each unit in cashCounts matches a unit in the
CurrencyCashList property, and is in the same order.
set to:
1:80,5:77,10:0,50:54,100:0,500:87
yen coins, 77 five yen coins, 54 fifty yen coins, and 87 five hundred yen coins in
the Cash Changer.
If CapDiscrepancy property is false, then discrepancy is always false.
total in a Cash Changer. There are some cases where a discrepancy may occur
because of existing uncountable cash in a Cash Changer. An example would be
Value Meaning
See Also CapDiscrepancy Property, CurrencyCashList Property, dispenseCash Method.


DataEvent Updated in Release 1.11
Description Notifies the application when the Cash Changer has accepted cash.
DirectIOEvent
means for a vendor-specific Cash Changer Service to provide events to the
Service.
from being used with other vendor’s Cash Changer devices which may not have

264 Cash Changer
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of the Cash
Changer device.
below.
process.
The Status parameter contains the Cash Changer status condition:
Value Meaning
CHAN_STATUS_EMPTY Some cash slots are empty.
CHAN_STATUS_NEAREMPTY Some cash slots are nearly empty.
CHAN_STATUS_EMPTYOK No cash slots are either empty or nearly
empty.
CHAN_STATUS_FULL Some cash slots are full.
CHAN_STATUS_NEARFULL Some cash slots are nearly full.
CHAN_STATUS_FULLOK No cash slots are either full or nearly full.
CHAN_STATUS_JAM A mechanical fault has occurred.
CHAN_STATUS_JAMOK A mechanical fault has recovered.
CHAN_STATUS_ASYNC Asynchronously performed method has
completed.
Remarks Fired when the Cash Changer detects a status change.
For changes in the fullness levels, the Cash Changer is only able to fire
StatusUpdateEvents when the device has a sensor capable of detecting the full,
near full, empty, and/or near empty states and the corresponding capability
properties for these states are set.
Jam conditions may be reported whenever this condition occurs; likewise for
asynchronous method completion.
The completion statuses of asynchronously performed methods are placed in the
AsyncResultCode and AsyncResultCodeExtended properties.
See Also AsyncResultCode Property, AsyncResultCodeExtended Property, “Events” on
page 51.

C H A P T E R 8
Cash Drawer
This Chapter defines the Cash Drawer device category.
Summary

DeviceEnabled: boolean { read-write } 1.0 open

266 Cash Drawer
CapStatus: boolean { read-only } 1.0 open
CapStatusMultiDrawerDetect: boolean { read-only } 1.5 open
DrawerOpened: boolean { read-only } 1.0 open & enable

Common
Name Version
open ( logicalDeviceName: string ):
1.0
close ( ): 1.0
claim ( timeout: int32 ):
void { raises-exception, use after open } 1.0
release ( ): 1.0
checkHealth ( level: int32 ):
void { raises-exception, use after open, enable } Note 1.0
clearInput ( ): Not
void { } supported
void { } supported
void { } supported
Specific
Name
openDrawer ( ):
void { raises-exception, use after open, enable } Note 1.0
waitForDrawerClose ( beepTimeout: int32, beepFrequency: int32,

beepDuration: int32, beepDelay: int32 ): 1.0
void { raises-exception, use after open, enable } Note
Note: Also requires that no other application has claimed the cash drawer.

Summary 267


268 Cash Drawer
General Information
The Cash Drawer programmatic name is “CashDrawer”.
Capabilities
The Cash Drawer Control has the following capability:
• Supports a command to “open” the cash drawer.
The cash drawer may have the following additional capability:

• Drawer status reporting of such a nature that the service can determine
whether a particular drawer is open or closed in environments where the
drawer is the only drawer accessible via a hardware port.
• Drawer unique status reporting of such a nature that the service can determine
whether a particular drawer is open or closed in environments where more
than one drawer is accessible via the same hardware port.
Cash Drawer Class Diagram Updated in Release 1.8

The following diagram shows the relationships between the Cash Drawer classes.
<<exception>> <<Interface>> <<utility>> <<utility>>

<<uses>>
UposException BaseControl UposConst CashDrawerConst
<<sends>>
<<uses>>
<<sends>>
<<Interface>>
CashDrawerControl
(from upos)
<<capability>> CapStatus : boolean
<<capability>> CapStatusMulti DrawerDetect : boolean
<<prop>> DrawerOpened : boolean
openDrawer() : void
waitForDrawerClose(beepTimeout : int32, beepFrequency : int32, beepDuration : int32, beepDelay : int32) : void
fires fires
<<event>>
<<event>> DirectIOEvent
StatusUpdateEvent
(from events)
(from events)
<<prop>> EventNumber : int32
<<prop>> Status : int32 <<prop>> Data : int32

Cash Drawer Sequence Diagram Updated in Release 1.12

The following sequence diagram show the typical usage of a Cash Drawer open()
Æ setDeviceEnabled(true) Æ getDrawerOpened() Æ openDrawer(); as well as
showing the unique sharing model of the Cash Drawer device when used with
multiple control instances open on the same physical device but by different
applications.
NOTE: we are assuming that the :ClientApp(s) already successfully opened the controls. T his
means that the platform specific loading/configuration/creation code executed successfully.
:ClientApp0 :ClientApp1 cd0:CashDrawe cd1:CashDrawer :StatusUpdateEvent : :CashDrawer :CashDrawer Physical CD

r StatusUpdateEvent Service0 Service1 Device
1: setDeviceEnabled(true) 2: setDeviceEnabled(true)
3: connect or somehow have access to the hardware
Service returns
current state of
4: openDrawer() cash drawer
5: openDrawer()
6: send command to open physical CD
If the command to open the physical CD CashDrawer

is successful then this will result in device is
StatusUpdateEvent delivered to any assumed open
registered listeners. This is not shown in successfully and
this diagram for simplicity. DrawerOpened
property is now
7: setDeviceEnabled(true) true
9: might communicate with
device (e.g. get current drawer
state)
10: openDrawer() CashDrawer is now

open by call to cd1.
Assume that some
human actor closes
11: openDrawer() after open
12: send command to open drawer
Assume the CashDrawer

is successfully claimed
at this point by
13: claim(timeout) :ClientApp1
14: claim(timeout)
This call results in a

15: openDrawer()
UposException since
the CashDrawer device
16: openDrawer()
is claimed by the cd1
instance that is used by
:ClientApp1
17: throw UposException
Assume that both

This call is
:ClientApp0 and :ClientApp1
successful and
registered to receive events
CashDrawer device
-- not shown.
18: openDrawer() is open since cd1
claimed the device
19: openDrawer() successfully
20: new
21: send command to open CD
23: deliver event to all registered handlers
StatusUpdateEvent is delivered
24: notify client of new event to all registered handlers, even
though, in the situation above,
25: new only :ClientApp1 is allowed to
call openDrawer() - since it
successfully claimed the CD.
27: deliver event to all registered handlers Service0 also detects the cash drawer is
opened, either via a message from
28: notify client of new event Service1, a StatusUpdateEvent from
Service 1, or from a lower level interface

270 Cash Drawer
Device Sharing
The cash drawer is a sharable device. Its device sharing rules are:
• After opening and enabling the device, the application may access all
properties and methods and will receive status update events.
• If more than one application has opened and enabled the device, each of these
applications may access its properties and methods. Status update events are
delivered to all of these applications.
• If one application claims the cash drawer, then only that application may call
openDrawer and waitForDrawerClose. This feature provides a degree of
security, such that these methods may effectively be restricted to the main
application if that application claims the device at startup.


CapStatus Property
Syntax CapStatus: boolean { read-only, access after open }
Remarks If true, the drawer can report status. If false, the Service is not able to determine
whether the cash drawer is open or closed.
CapStatusMultiDrawerDetect Property Added in Release 1.5

Syntax CapStatusMultiDrawerDetect: boolean { read-only, access after open }
Remarks If true, the status unique to each drawer in a multiple cash drawer configuration1
can be reported.
If false, the following possibilities exist:
DrawerOpened: value of false indicates that there are no drawers open.
DrawerOpened: value of true indicates that at least one drawer is open and it
might be the particular drawer in question. This case can occur in multiple cash
drawer configurations where only one status is reported indicating either a) all
drawers are closed, or b) one or more drawers are open.
Note: A multiple cash drawer configuration is defined as one where a terminal or
printer supports opening more than one cash drawer independently via the same
channel or hardware port. A typical example is a configuration where a “Y” cable,
connected to a single hardware printer port, has separate drawer open signal lines
but the drawer open status from each of the drawers is “wired-or” together. It is not
possible to determine which drawer is open.
This property is only meaningful if CapStatus is true.
See Also CapStatus Property, DrawerOpened Property.
1. Multiple cash drawer configuration -- A hardware configuration where a printer or

terminal controls more than one cash drawer independently via the same channel or
hardware port. A typical example is a configuration with a “Y” cable connected to a
single hardware port that controls two cash drawers.

272 Cash Drawer
DrawerOpened Property
Syntax DrawerOpened: boolean { read-only, access after open }
Remarks If true, the drawer is open. If false, the drawer is closed.
If the capability CapStatus is false, then the device does not support status
reporting, and this property is always false.
Note: If the capability CapStatusMultiDrawerDetect is false, then a
DrawerOpened value of true indicates at least one drawer is open, and it might be
the particular drawer in question in a multiple cash drawer configuration. See
CapStatusMultiDrawerDetect for further clarification.
See Also CapStatus Property, CapStatusMultiDrawerDetect Property.


openDrawer Method
Syntax openDrawer ( ):
void { raises-exception, use after open-enable }
Remarks Opens the drawer.

waitForDrawerClose Method
Syntax waitForDrawerClose ( beepTimeout: int32, beepFrequency: int32,
beepDuration: int32, beepDelay: int32 ):
beepTimeout Number of milliseconds to wait before starting an alert

beeper.
beepFrequency Audio frequency of the alert beeper in hertz.
beepDuration Number of milliseconds that the beep tone will be
sounded.
beepDelay Number of milliseconds between the sounding of beeper
tones.
Remarks Waits until the cash drawer is closed. If the drawer is still open after beepTimeout
milliseconds, then the system alert beeper is started.
Not all POS implementations may support the typical PC speaker system alert
beeper. However, by setting these parameters the application will insure that the
system alert beeper will be utilized if it is present.
Unless a UposException is thrown, this method will not return to the application
while the drawer is open. In addition, in a multiple cash drawer configuration
where the CapStatusMultiDrawerDetect property is false, this method will not
return to the application while any of the drawers are open. When all drawers are
closed, the beeper is turned off.
If CapStatus is false, then the device does not support status reporting, and this
method will return immediately.
See Also CapStatus Property, CapStatusMultiDrawerDetect Property.

274 Cash Drawer
DirectIOEvent
means for a vendor-specific Cash Drawer Service to provide events to the
Service.
from being used with other vendor’s Cash Drawer devices which may not have any

StatusUpdateEvent
Description Notifies the application when the status of the Cash Drawer changes.
Status int32 The status reported from the Cash Drawer.

The Status property has one of the following values:
Value Meaning
CASH_SUE_DRAWERCLOSED The drawer is closed.

CASH_SUE_DRAWEROPEN The drawer is open.
process.
Remarks If CapStatus is false, then the device does not support status reporting, and this
event will never be delivered to report status changes.
If CapStatusMultiDrawerDetect is false, then a CASH_SUE_DRAWEROPEN

value indicates that at least one cash drawer is open and it might be the particular
drawer in question for multiple cash drawer configurations.
See Also “Events” on page 51, CapStatus Property, CapStatusMultiDrawerDetect
Property.

276 Cash Drawer

C H A P T E R 9
CAT - Credit Authorization Terminal

This Chapter defines the Credit Authorization Terminal device category.
Summary


278 CAT - Credit Authorization Terminal
AccountNumber: string { read-only } 1.4 open
AdditionalSecurityInformation: string { read-write } 1.4 open
ApprovalCode: string { read-only } 1.4 open
AsyncMode: boolean { read-write } 1.4 open
Balance: currency { read-only } 1.9 open
CapAdditionalSecurityInformation: boolean { read-only } 1.4 open
CapAuthorizeCompletion: boolean { read-only } 1.4 open
CapAuthorizePreSales: boolean { read-only } 1.4 open
CapAuthorizeRefund: boolean { read-only } 1.4 open
CapAuthorizeVoid: boolean { read-only } 1.4 open
CapAuthorizeVoidPreSales: boolean { read-only } 1.4 open
CapCashDeposit: boolean { read-only } 1.9 open
CapCenterResultCode: boolean { read-only } 1.4 open
CapCheckCard: boolean { read-only } 1.4 open
CapDailyLog: int32 { read-only } 1.4 open
CapInstallments: boolean { read-only } 1.4 open
CapLockTerminal: boolean { read-only } 1.9 open
CapLogStatus: boolean { read-only } 1.9 open
CapPaymentDetail: boolean { read-only } 1.4 open
CapTaxOthers: boolean { read-only } 1.4 open
CapTransactionNumber: boolean { read-only } 1.4 open
CapTrainingMode: boolean { read-only } 1.4 open
CapUnlockTerminal: boolean { read-only } 1.9 open
CardCompanyID: string { read-only } 1.4 open
CenterResultCode: string { read-only } 1.4 open
DailyLog: string { read-only } 1.4 open
LogStatus: int32 { read-only } 1.9 open
PaymentCondition: int32 { read-only } 1.4 open
PaymentDetail: string { read-only } 1.4 open
PaymentMedia: int32 { read-write } 1.5 open
SequenceNumber: int32 { read-only } 1.4 open
SettledAmount: currency { read-only } 1.9 open
SlipNumber: string { read-only } 1.4 open
TrainingMode: boolean { read-write } 1.4 open
TransactionNumber: string { read-only } 1.4 open
TransactionType: int32 { read-only } 1.4 open

Summary 279

Common
Name Version
close ( ): 1.4
release ( ): 1.4
clearInput ( ): Not
void { } supported
void { } supported
Specific
Name
accessDailyLog ( sequenceNumber: int32, type: int32, timeout: int32 ): 1.4
authorizeCompletion ( sequenceNumber: int32, amount: currency, 1.4
taxOthers: currency, timeout: int32 ):
authorizePreSales ( sequenceNumber: int32, amount: currency, 1.4
authorizeRefund ( sequenceNumber: int32, amount: currency, taxOthers: 1.4
currency, timeout: int32 ):

authorizeSales ( sequenceNumber: int32, amount: currency, taxOthers: 1.4

authorizeVoid ( sequenceNumber: int32, amount: currency, taxOthers: 1.4
authorizeVoidPreSales ( sequenceNumber: int32, amount: currency, 1.4
cashDeposit ( sequenceNumber: int32, amount: currency, timeout: int32 ): 1.9
checkCard ( sequenceNumber: int32, timeout: int32 ): 1.4
lockTerminal ( ): 1.9
unlockTerminal ( ): 1.9

upos::events::DataEvent Not supported

General Information
The CAT programmatic name is “CAT”.
Description of terms
• Authorization method
Methods defined by this device class that have the Authorize prefix in their
name. These methods require communication with an approval agency.
• Authorization operation
The period from the invocation of an authorization method until the
authorization is completed. This period differs depending upon whether
operating in synchronous or asynchronous mode.
• Credit Authorization Terminal (CAT) Device
A CAT device typically consists of a display, keyboard, magnetic stripe card
reader, receipt printing device, and a communications device. CAT devices
are predominantly used in Japan where they are required by law. Essentially a
CAT device can be considered a device that shields the encryption, message
formatting, and communication functions of an electronic funds transfer
(EFT) operation from an application.
• Purchase
The transaction that allows credit card or debit card payment at the POS. It is
independent of payment methods (for example, lump-sum payment, payment
in installments, revolving payment, etc.).
• Cancel Purchase
The transaction to request voiding a purchase on the date of purchase.
• Refund Purchase
The transaction to request voiding a purchase after the date of purchase. This
differs from cancel purchase in that a cancel purchase operation can often be
handled by updating the daily log at the CAT device, while the refund
purchase operation typically requires interaction with the approval agency.
• Authorization Completion
The state of a purchase when the response from the approval agency is
“suspended”. The purchase is later completed after a voice approval is
received from the card company.
• Pre-Authorization
The transaction to reserve an estimated amount in advance of the actual
purchase with customer's credit card presentation and card entry at CAT.
• Cancel Pre-Authorization
The transaction to request canceling pre-authorization.

• Card Check
The transaction to perform a negative card file validation of the card presented
by the customer. Typically negative card files contain card numbers that are
known to fail approval. Therefore the Card Check operation removes the need
for communication to the approval agency in some instances.
• Daily log
The daily log of card transactions that have been approved by the card
companies.
• Payment condition
Condition of payment such as lump-sum payment, payment by bonus,
payment in installments, revolving payment, and the combination of those
payments. Debit payment is also available. See the PaymentCondition,
PaymentMedia, and PaymentDetail properties for details.
• Approval agency
The agency to decide whether or not to approve the purchase based on the card
information, the amount of purchase, and payment type. The approval agency
is generally the card company.
Capabilities
The CAT control is capable of the following general mode of operation:

• This standard defines the application interface with the CAT control and does
not depend on the CAT device hardware implementation. Therefore, the
hardware implementation of a CAT device may be as follows:
• Separate type (POS interlock)
The dedicated CAT device is externally connected to the POS (for
instance, via an RS-232 connection).
• Built-in type
The hardware structure is the same as the separate type but is installed
within the POS housing.
• The CAT device receives each authorization request containing a purchase
amount and tax from CAT control.
• The CAT device generally requests the user to swipe a magnetic card when it
receives an authorization request from CAT control.
• Once a magnetic card is swiped at the CAT device, the device sends the
purchase amount and tax to the approval agency using the communications
device.
• The CAT device returns the result from the approval agency to the CAT
control. The returned data will be stored in the authorization properties by the
CAT control for access by applications.

Electronic Money Device: Added in Release 1.9

The CAT Device Category is extended to support an Electronic Money Device that
has the following attributes.
• A CAT device typically consists of a display, keyboard, magnetic stripe
reader, receipt printing device, and a communications device. CAT devices
are predominanly used in Japan where they are required by law. Essentially, a
CAT device can be considered a device that shields the encryption message
formatting and communications functions of an Electronic Funds Transfer
(EFT) operation from an application.
• The Electronic Money Device receives the tendering information (amount of
tender, tax, and other transaction based information) from CAT control, and
then starts the authorization processing.
• When the Electronic Money Device is required, a Credit Card swipe on the
CAT device is generally required for authorization.
• When a Card [Contact Type / Contactless Type] is input by the Electronic
Money Device, it is formatted into the authorization format with the
transaction information and then communicated for authorization.
• When the authorization is completed, the Electronic Money Device sends the
settlement result to CAT control. The settlement result is stored by the CAT
control and passed back to the calling application.
• The Electronic Money Device may save settlement result as DealingLog in
the memory of the device. The device may also send DealingLog to the Center
by settlement processing.

CAT Class Diagram Updated in Release 1.9

<<utility>> <<exception>>
UposConst UposException
<<sends>>
<<event>> <<uses>>
<<Interface>>
ErrorEvent CATControl
<<prop>> AccountNumber : string
<<prop>> AdditionalSecurityInformation : string
<<prop>> ApprovalCode : string
<<event>> fires <<prop>> Balance : currency
OutputCompleteEvent <<capability>> CapAdditionalSecurityInformation : boolean
(from events) <<capability>> CapAuthorizeCompletion : boolean
<<capability>> CapAuthorizePreSales : boolean
<<capability>> CapAuthorizeRefund : boolean
<<capability>> CapAuthorizeVoid : boolean
fires <<capability>> CapAuthorizeVoidPreSales : boolean
<<event>>
StatusUpdateEvent <<capability>> CapCashDeposit : boolean
(from events) <<capability>> CapCenterResultCode : boolean
<<capability>> CapCheckCard : boolean
fires <<capability>> CapDailyLog : int32
<<capability>> CapInstallments : boolean
<<capability>> CapLockTerminal : boolean
<<capability>> CapLogStatus : boolean
<<event>> <<capability>> CapPaymentDetail : boolean
DirectIOEvent fires <<capability>> CapTaxOthers : boolean
(from events)
<<capability>> CapTransactionNumber : boolean
<<capability>> CapTrainingMode : boolean
<<capability>> CapUnlockTerminal : boolean
<<prop>> CardCompanyID : string
<<prop>> CenterResultCode : string
<<prop>> DailyLog : string
<<prop>> LogStatus : int32
<<prop>> PaymentCondition : int32
<<prop>> PaymentDetail : string
<<prop>> PaymentMedia : int32
<<prop>> SequenceNumber : int32
<<prop>> SettledAmount : currency
<<prop>> SlipNumber : string
<<prop>> TrainingMode : boolean
<<prop>> TransactionNumber : string
<<prop>> TransactionType : int32
accessdailyLog()
authorizeCompletion()
authorizePreSales()
authorizeRefund()
authorizeSales()
authorizeVoid()
authorizeVoidPreSales()
cashDeposit()
checkCard()
lockTerminal()
unlockTerminal()

Model
The general models for the CAT control are shown below:
• The CAT control basically follows the output device model. However,
multiple methods cannot be issued for asynchronous output; only one
outstanding asynchronous request is allowed.
• The CAT control issues requests to the CAT device for different types of
authorization by invoking the following methods.
Function Method name Corresponding Cap property
Purchase authorizeSales None
Cancel Purchase authorizeVoid CapAuthorizeVoid
Refund Purchase authorizeRefund CapAuthorizeRefund
Authorization Completion authorizeCompletion CapAuthorizeCompletion
Pre-Authorization authorizePreSales CapAuthorizePreSales
Cancel Pre-Authorization authorizeVoidPreSales CapAuthorizeVoidPreSales
• The CAT control issues requests to the CAT device for special processing
local to the CAT device by invoking the following methods.
Card Check checkCard CapCheckCard
Daily log accessDailyLog CapDailyLog
• The CAT control stores the authorization results in the following properties
when an authorization operation successfully completes:
Description Property Name Corresponding Cap Property
Credit Account number AccountNumber None
Additional information AdditionalSecurityInformation CapAdditionalSecurityInformation
Approval code ApprovalCode None
Card company ID CardCompanyID None
Code from the approval
CenterResultCode CapCenterResultCode
agency
Payment condition PaymentCondition None
Payment detail PaymentDetail CapPaymentDetail
Sequence number SequenceNumber None
Slip number SlipNumber None
Center transaction number TransactionNumber CapTransactionNumber
Transaction type TransactionType None

• The accessDailyLog method sets the following property

Daily log DailyLog CapDailyLog
Electronic Money Device: Added in Release 1.9

• The CAT Control requires the Electronic Money Device to track each
settlement and closing in the DealingLog.
Settlement authorizeSales None
Charge cashDeposit CapCashDeposit
Inquiry for the balances checkCard CapCheckCard
Closing DealingLog accessDailyLog CapDailyLog
Setting security lock lockTerminal CapLockTerminal
Releasing security lock unlockTerminal CapUnlockTerminal
• When the CAT Control receives the settlement results from the Electronic
Money Device it stores these results in the following properties:

Card ID AccountNumber None
Additional information AdditionalSecurityInformation CapAdditionalSecurityInformation
Approval code ApprovalCode None
Settled amount SettledAmount None
Balance Balance None
Sequence number SequenceNumber None
Transaction type TransactionType None
• The accessDailyLog method sets the following property

DealingLog DailyLog CapDailyLog
• Sequence numbers are used to validate that the properties set at completion of
a method are indeed associated with the completed method. An incoming
SequenceNumber argument for each method is compared with the resulting
SequenceNumber property after the operation associated with the method
has completed. If the numbers do not match, or if an application fails to
identify the number, there is no guarantee that the values of the properties
listed in the two tables correspond to the completed method.
• The AsyncMode property determines if methods are run synchronously or
asynchronously.

• When AsyncMode is false, methods will be executed synchronously and their

corresponding properties will contain data when the method returns.
• When AsyncMode is true, methods will return immediately to the application.
When the operation associated with the method completes, each
corresponding property will be updated by the CAT control prior to an
OutputCompleteEvent. When AsyncMode is true, methods cannot be
issued immediately after issuing a prior method; only one outstanding
asynchronous method is allowed at a time. However, clearOutput is an
exception because its purpose is to cancel an outstanding asynchronous
method.
The methods supported and their corresponding properties vary depending on
the CAT control implementation. Applications should verify that particular
Cap properties are supported before utilizing the capability dependent
methods and properties.
• Results of synchronous calls to methods and writable properties will be stored
in ErrorCode. Results of asynchronous processing will be indicated by an
OutputCompleteEvent or returned in the Errorcode argument of an
ErrorEvent. If ErrorCode or the ErrorCode argument is E_EXTENDED,
detailed device specific information may be stored to ErrorCodeExtended in
synchronous mode and stored to ErrorEvent argument ErrorCodeExtended
in asynchronous mode. The error code from the approval agency will be stored
in CenterResultCode in either mode.
• Training mode occurs continually when TrainingMode is true. To
discontinue training mode, set TrainingMode to false.
• An outstanding asynchronous method can be canceled via the clearOutput
method.
• The Daily log can be collected by the accessDailyLog method. Collection will
be run either synchronously or asynchronously according to the value of
AsyncMode.

• Following is the general usage sequence of the CAT control.

Synchronous Mode:
- open
- claim
- setDeviceEnabled (true)
- Definition of the argument SequenceNumber
- Set PaymentMedia Added in Version 1.5
- authorizeSales()
- Check UposException of the authorizeSales method
- Verify that the SequenceNumber property matches the value of the
authorizeSales() sequenceNumber argument
- Access the properties set by authorizeSales()
- setDeviceEnabled (false)
- release
- Close
Asynchronous Mode:
- open
- claim
- setDeviceEnabled (true)
- setAsyncMode (true)
- Definition of the argument SequenceNumber
- Set PaymentMedia Added in Version 1.5
- authorizeSales()
- Check UposException of the authorizeSales method
- Wait for OutputCompleteEvent
- Check the argument ErrorCode
- Verify that the SequenceNumber property matches the value of the
authorizeSales() SequenceNumber argument
- Access the properties set by authorizeSales()
- setDeviceEnabled (false)
- release
- close

Device Sharing
The CAT is an exclusive-use device, as follows:

• After opening the device, properties are readable.

CAT Sequence Diagram Added in Release 1.7

This sequence diagram shows the typical synchronous usage of the
AuthorizeSales process of the CAT device.
:Client App :CAT :CAT Service :CAT Hardware

open(logicalName)
open(logicalName)
claim(timeout)
claim(timeout)
setDeviceEnabled(true)
setPaymentMedia(mediaType)
setPaymentMedia()
Definition of the argument
SequenceNumber
AuthorizeSales(sequenceNumber, amount, tax, timeout)
AuthorizeSales(sequenceNumber, amount, tax, timeout)
send commands to
physical CAT
After human actor swipes the card,

the device sends the purchase amount
and tax to approval agency using the
communications device.
Set properties on
return from successful
Check properties authorization.
on successful return.

CAT State Diagram
The following diagram depicts the CAT states.
close()
open() claim()
close() release()
release()
/set DeviceEnabled (false) clearOutput()

close()
/set DeviceEnabled (true)
Logging Enabled
Processing
accessDailyLog() Clear Output

Processing
Method processing
Done delivering event authorizeXyz(),

checkCard()
authorizeXyz(),
Synchronous checkCard() Async Mode
Mode
ErrorEvent OutputCompleteEvent
Processing Processing


AccountNumber Property Updated in Release 1.9
Syntax AccountNumber: string { read-only, access after open }
Remarks This property is initialized to an empty string by the open method and is updated
when an authorization operation successfully completes.
Electronic Money Device: Credit Card number of the settled account.
AdditionalSecurityInformation Property Updated in Release 1.7
Syntax AdditionalSecurityInformation: string { read-write, access after open }1
Remarks An application can send data to the CAT device by setting this property before
issuing an authorization method. Also, data obtained from the CAT device and not
stored in any other property as the result of an authorization operation (for
example, the account code for a loyalty program) can be provided to an application
by storing it in this property. Since the data stored here is device specific, this
should not be used for any development that requires portability.
See Also CapAdditionalSecurityInformation Property.
ApprovalCode Property Updated in Release 1.9

Syntax ApprovalCode: string { read-only, access after open }
Remarks This property is initialized to an empty string by the open method and is updated
Electronic Money Device: Approval Code for the settled account.
AsyncMode Property
Remarks If true, the authorization methods will run asynchronously.
If false, the authorization methods will run synchronously.
See Also Authorization Methods.

Balance Property Added in Release 1.9

Syntax Balance: currency { read-only, access after open }
Remarks Electronic Money Device: The balance of Credit Card.
CapAdditionalSecurityInformation Property
Syntax CapAdditionalSecurityInformation: boolean { read-only, access after open }
Remarks If true, the AdditionalSecurityInformation property may be utilized; otherwise
it is false.
This property is initialized by open method.
See Also AdditionalSecurityInformation Property.
CapAuthorizeCompletion Property
Syntax CapAuthorizeCompletion: boolean { read-only, access after open }
Remarks If true, the authorizeCompletion method has been implemented; otherwise it is
false.
See Also authorizeCompletion Method.
CapAuthorizePreSales Property
Syntax CapAuthorizePreSales: boolean { read-only, access after open }
Remarks If true, the authorizePreSales method has been implemented; otherwise it is false.
See Also authorizePreSales Method.
CapAuthorizeRefund Property
Syntax CapAuthorizeRefund: boolean { read-only, access after open }
Remarks If true, the authorizeRefund method has been implemented; otherwise it is false.
See Also authorizeRefund Method.

CapAuthorizeVoid Property
Syntax CapAuthorizeVoid: boolean { read-only, access after open }
Remarks If true, the authorizeVoid method has been implemented; otherwise it is false.
See Also authorizeVoid Method.
CapAuthorizeVoidPreSales Property
Syntax CapAuthorizeVoidPreSales: boolean { read-only, access after open }
Remarks If true, the authorizeVoidPreSales method has been implemented; otherwise it is
false.
See Also authorizeVoidPreSales Method.
CapCashDeposit Property Added in Release 1.9

Syntax CapCashDeposit: boolean { read-only, access after open }
Remarks Electronic Money Device: Show the device has charged method by cashDeposit
method or not. If true, the cashDeposit method is implemented, otherwise false.
See Also cashDeposit Method.
CapCenterResultCode Property
Syntax CapCenterResultCode: boolean { read-only, access after open }
Remarks If true, the CenterResultCode property has been implemented; otherwise it is
false.
See Also CenterResultCode Property.
CapCheckCard Property
Syntax CapCheckCard: boolean { read-only, access after open }
Remarks If true, the checkCard method has been implemented; otherwise it is false.
See Also checkCard Method.

CapDailyLog Property
Syntax CapDailyLog: int32 { read-only, access after open }
Remarks Shows the daily log ability of the device.
Value Meaning
CAT_DL_NONE The CAT device does not have the daily log functions.
CAT_DL_REPORTING The CAT device only has an intermediate total function
which reads the daily log but does not erase the log.
CAT_DL_SETTLEMENT The CAT device only has the “final total” and “erase
daily log” functions.
CAT_DL_REPORTING_SETTLEMENT
The CAT device has both the intermediate total function
and the final total and erase daily log function.
See Also DailyLog Property, accessDailyLog Method.
CapInstallments Property
Syntax CapInstallments: boolean { read-only, access after open }
Remarks If true, the item “Installments” which is stored in the DailyLog property as the
result of accessDailyLog will be provided; otherwise it is false.
See Also DailyLog Property.
CapLockTerminal Property Added in Release 1.9
Syntax CapLockTerminal: boolean { read-only, access after open }
Remarks Electronic Money Device: If true, the device has a security lock and the device
can set the lock using the lockTerminal method, otherwise false.
See Also lockTerminal Method.
CapLogStatus Property Added in Release 1.9
Syntax CapLogStatus: boolean { read-only, access after open }
Remarks Electronic Money Device: If true, the device can notify the condition of the log
by the LogStatus property, otherwise false.
See Also LogStatus Property.

CapPaymentDetail Property
Syntax CapPaymentDetail: boolean { read-only, access after open }
Remarks If true, the PaymentDetail property has been implemented; otherwise it is false.
This property is initialized by open method.
See Also PaymentDetail Property.
CapTaxOthers Property
Syntax CapTaxOthers: boolean { read-only, access after open }
Remarks If true, the item “TaxOthers” which is stored in the DailyLog property as the result
of access DailyLog will be provided; otherwise it is false.
Note that this property is not related to the “TaxOthers” argument used with the
authorization methods.
See Also DailyLog Property.
CapTransactionNumber Property
Syntax CapTransactionNumber: boolean { read-only, access after open }
Remarks If true, the TransactionNumber property has been implemented; otherwise it is
false.
See Also TransactionNumber Property.
CapTrainingMode Property
Syntax CapTrainingMode: boolean { read-only, access after open }
Remarks If true, the TrainingMode property has been implemented; otherwise it is false.
See Also TrainingMode Property.

CapUnlockTerminal Property Added in Release 1.9

Syntax CapUnlockTerminal: boolean { read-only, access after open }
Remarks Electronic Money Device: If true, the device has a security lock and the device
can release the lock using the unlockTerminal method, otherwise false.
See Also unlockTerminal Method.
CardCompanyID Property
Syntax CardCompanyID: string { read-only, access after open }
Remarks This property is updated when an authorization operation successfully completes.
It shows credit card company ID.
The length of the ID string varies depending upon the CAT device.
This property is initialized to an empty string by the open method
CenterResultCode Property
Syntax CenterResultCode: string { read-only, access after open }
Remarks Contains the code from the approval agency. Check the approval agency for the
actual codes to be stored.
This property is initialized to an empty string by the open method and is updated
when an authorization operation successfully completes

DailyLog Property
Syntax DailyLog: string { read-only, access after open }
Remarks Stores the result of the accessDailyLog method. The data is delimited by CR(13
decimal)+LF(10 decimal) for each transaction and is stored in ASCII code. The
detailed data of each transaction is comma separated [i.e., delimited by “,” (44)].
The details of one transaction are shown as follows:
No Item Property Corresponding Cap Property

1 Card company ID CardCompanyID None
2 Transaction type TransactionType None
3 Transaction date None None
Note 1)
4 Transaction number TransactionNumber CapTransactionNumber
Note 3)
5 Payment condition PaymentCondition None
6 Slip number SlipNumber None
7 Approval code ApprovalCode None
8 Purchase date None None
Note 5)
9 Account number AccountNumber None
10 Amount The argument Amount of the None
Note 4) authorization method or the
amount actually approved.
11 Tax/others The argument TaxOthers of the CapTaxOthers
Note 3) authorization method.
12 Installments None CapInstallments
Note 3)
13 Additional data AdditionalSecurityInformation CapAdditionalSecurityInfor-
Note 2) mation
Notes from the previous table:

1) Format
Item Format
Transaction date YYYYMMDDHHMMSS
Purchase date MMDD
Some CAT devices may not support seconds by the internal clock. In that
case, the seconds field of the transaction date is filled with “00”
2) Additional data
The area where the CAT device stores the vendor specific data. This enables
an application to receive data other than that defined in this specification. The
data stored here is vendor specific and should not be used for development
which places an importance on portability.

3) If the corresponding Cap property is false

Cap property is set to false if the CAT device provides no corresponding data.
In such instances, the item cannot be displayed so the next comma delimiter
immediately follows. For example, if “Amount” is 1234 yen and “Tax/others”
is missing and “Installments” is 2, the description will be “1234,,2”. This
makes the description independent of Cap property and makes the position of
each data item consistent.
4) Amount
Amount always includes “Tax/others” even if item 11 is present.
5) Purchase date
The date manually entered for the purchase transaction after approval.
Example An example of daily log content is shown below.
Item Description Meaning

Card company ID 102 JCB
Transaction type CAT_TRANSACTION_SALES Purchase
Transaction date 19980116134530 1/16/199813:45:30
Transaction number 123456 123456
Payment condition CAT_PAYMENT_INSTALLME Installment 1
NT_1
Slip number 12345 12345
Approval code 0123456 0123456
Purchase date None None
Account number 1234123412341234 1234-1234-1234-1234
Amount 12345 12345JPY
Tax/others None None
Number of payments 2 2
Additional data 12345678 Specific information
The actual data stored in DailyLog will be as follows:
102,10,19980116134530,123456,61,12345,0123456,,12341234123
41234,12345,,2,12345678[CR][LF]
Electronic Money Device: Setting DealingLog which is a result of the Electronic

Money Device which does not have the communication module for closing
processing done closing processing. It may be the device which is enciphered
DealingLog to everything except for Center.
See Also CapDailyLog Property, accessDailyLog Method.

LogStatus Property Added in Release 1.9

Syntax LogStatus: int32 { read-only, access after open }
Remarks Electronic Money Device: This property shows the status of the DealingLog of
the device.
Value Meaning
CAT_LOGSTATUS_OK DealingLog has enough capacity.
CAT_LOGSTATUS_NEARFULL DealingLog is nearly full.
CAT_LOGSTATUS_FULL DealingLog is full.
This property is initialized by the open method and kept current while the device
is enabled.
If DealingLog becomes full, depending on the device, the settlement processing
may not be able to operate.
See Also StatusUpdateEvent Event.
PaymentCondition Property Updated in Release 1.9
Syntax PaymentCondition: int32 { read-only, access after open }
Remarks Holds the payment condition of the most recent successful authorization
operation.
This property will be set to one of the following values. See PaymentDetail for
the detailed payment string that correlates to the following PaymentCondition
values.
Value Meaning
CAT_PAYMENT_LUMP Lump-sum
CAT_PAYMENT_BONUS_1 Bonus 1
CAT_PAYMENT_INSTALLMENT_1 Installment 1
CAT_PAYMENT_BONUS_COMBINATION_1
Bonus combination payments 1
CAT_PAYMENT_ REVOLVING Revolving
CAT_PAYMENT_DEBIT Debit card
CAT_PAYMENT_ELECTRONIC_MONEY
Electronic Money
See Also PaymentDetail Property.

PaymentDetail Property Updated in Release 1.9

Syntax PaymentDetail: string { read-only, access after open }
Remarks Contains payment condition details as the result of an authorization operation.
Payment details vary depending on the value of PaymentCondition. The data will
be stored as comma separated ASCII code. An empty string means that no data is
stored and represents a string with zero length data.
PaymentCondition PaymentDetail
CAT_PAYMENT_LUMP An empty string
CAT_PAYMENT_BONUS_1 An empty string
CAT_PAYMENT_BONUS_2 Number of bonus payments
CAT_PAYMENT_BONUS_3 1st bonus month
CAT_PAYMENT_BONUS_4* Number of bonus payments, 1st bonus month, 2nd bo-
nus month, 3rd bonus month, 4th bonus month, 5th bo-
nus month, 6th bonus month
CAT_PAYMENT_BONUS_5* Number of bonus payments, 1st bonus month, 1st bo-
nus amount, 2nd bonus month, 2nd bonus amount, 3rd
bonus month, 3rd bonus amount, 4th bonus month, 4th
bonus amount, 5th bonus month, 5th bonus amount, 6th
bonus month, 6th bonus amount
CAT_PAYMENT_INSTALLMENT_1 1st billing month, Number of payments
CAT_PAYMENT_INSTALLMENT_2* 1st billing month, Number of payments, 1st amount,
2nd amount, 3rd amount, 4th amount, 5th amount, 6th
amount
CAT_PAYMENT_INSTALLMENT_3 1st billing month, Number of payments, 1st amount
CAT_PAYMENT_BONUS_COMBINATION_1 1st billing month, Number of payments
CAT_PAYMENT_BONUS_COMBINATION_2 1st billing month, Number of payments, bonus amount
CAT_PAYMENT_BONUS_COMBINATION_3* 1st billing month, Number of payments, number of bo-
nus payments, 1st bonus month, 2nd bonus month, 3rd
bonus month, 4th bonus month, 5th bonus month, 6th
bonus month
CAT_PAYMENT_BONUS_COMBINATION_4* 1st billing month, Number of payments, number of bo-
nus payments, 1st bonus month, 1st bonus amount, 2nd
bonus month, 2nd bonus amount, 3rd bonus month, 3rd
bonus amount, 4th bonus month, 4th bonus amount, 5th
bonus month, 5th bonus amount, 6th bonus month, 6th
bonus amount
CAT_PAYMENT_REVOLVING An empty string
CAT_PAYMENT_DEBIT An empty string
CAT_PAYMENT_ELECTRONIC_MONEY An empty string
*Maximum 6 installments

The payment types and names vary depending on the CAT device. The following
are the payment types and terms available for CAT devices. Note that there are
some differences between UnifiedPOS terms and those used by the CAT devices.
The goal of this table is to synchronize these terms.
CAT CAT G-CAT JET-S SG-CAT Master-T

General Payment Category
PaymentCondition Value
Name (Old CAT)

Credit Not Not JCB VISA MASTER
Card specified specified
UnifiedPOS
Entry item
Card Company Terms

Term
Lump- (None) 10 Lump-sum Lump-sum Lump-sum Lump-sum Lump-sum Lump-sum

sum
Bonus (None) 21 Bonus 1 Bonus 1 Bonus 1 Bonus 1 Bonus 1 Bonus 1
Number of 22 Bonus 2 Bonus 2 Bonus 2 Bonus 2 Bonus 2 Bonus 2
bonus
payments
Bonus 23 Bonus 3 Bonus 3 Does not ex- Does not ex- Bonus 3 Bonus 3
month(s) ist. ist.
Number of 24 Bonus 4 Bonus 4 Bonus 3 Bonus 3 Bonus 4 Bonus 4

bonus (Up to two
payments entries for
bonus
Bonus month)
month (1)
Bonus
month (2)
Bonus
month (3)
Bonus
month (4)
Bonus
month (5)
Bonus
month (6)

Number of 25 Bonus 5 Bonus 5 Does not Does not Does not Bonus 5
bonus exist. exist. exist.
payments
Bonus
month (1)
Bonus
amount
(1)
Bonus
month (2)
Bonus
amount(2)
Bonus
month (3)
Bonus
amount(3)
Bonus
month (4)
Bonus
amount(4)
Bonus
month (5)
Bonus
amount(5)
Bonus
month (6)
Bonus
amount(6)
Installm Payment 61 Installment 1 Installment 1 Installment 1 Installment 1 Installment 1 Installment 1
ent start
month
Number of
payments

Payment 62 Installment 2 Installment 2 Does not Does not Does not Does not
start exist. exist. exist. exist.
month
Number of
payments
Install-
ment
amount(1)
Install-
ment
amount(2)
Install-
ment
amount(3)
Install-
ment
amount(4)
Install-
ment
amount(5)
Install-
ment
amount(6)
Payment 63 Installment 3 Installment 3 Installment 2 Installment 2 Does not Installment 2
start exist.
month
Number of
payments
Initial
amount
Combi- Payment 31 Bonus Com- Bonus Com- Bonus Com- Bonus Com- Bonus Com- Bonus Com-
nation start bination 1 bination 1 bination 1 bination 1 bination 1 bination 1
month
Number of
payments
Payment 32 Bonus Com- Bonus Com- Does not Does not Bonus Com- Bonus Com-
start bination 2 bination 2 exist. exist. bination 2 bination 2
month
Number of
payments
Bonus
amount

Payment 33 Bonus Com- Bonus Com- Does not Does not Bonus Com- Bonus Com-
start bination 3 bination 3 exist. exist. bination 3 bination 3
month (Up to two
entries for
Number of bonus
payments
month)
Number of
bonus
payments
Bonus
month (1)
Bonus
month (2)
Bonus
month (3)
Bonus
month (4)
Bonus
month (5)
Bonus
month (6)

Payment 34 Bonus Com- Bonus Com- Bonus Com- Bonus Com- Bonus Com- Bonus Com-
start bination 4 bination 4 bination 2 bination 2 bination 4 bination 4
month (Up to two
entries for
Number of bonus month
payments
and amount)
Number of
bonus
payments
Bonus
month (1)
Bonus
amount(1)
Bonus
month (2)
Bonus
amount(2)
Bonus
month (3)
Bonus
amount(3)
Bonus
month (4)
Bonus
amount(4)
Bonus
month (5)
Bonus
amount(5)
Bonus
month (6)
Bonus
amount(6)
Revolvi (None) 80 Revolving Revolving Revolving Revolving Revolving Revolving
ng
Debit (None) 110 Debit (Support (Support (Support (Support (Support
depends on depends on depends on depends on depends on
the actual the actual the actual the actual the actual
device) device) device) device) device)
See Also CapPaymentDetail Property.

PaymentMedia Property Updated in Release 1.9

Syntax PaymentMedia: int32 { read-write, access after open }
Remarks Holds the payment media type that the approval method should approve.
The application sets this property to one of the following values before issuing an
approval method call. “None specified” means that payment media will be
determined by the CAT device, not by the POS application.
Value Meaning
CAT_MEDIA_UNSPECIFIED None specified.
CAT_MEDIA_CREDIT Credit card.
CAT_MEDIA_DEBIT Debit card.
CAT_MEDIA_ELECTRONIC_MONEY
Electronic Money.
This property is initialized to CAT_MEDIA_UNSPECIFIED by the open method.
SequenceNumber Property
Syntax SequenceNumber: int32 { read-only, access after open }
Remarks Stores a “sequence number” as the result of each method call. This number needs
to be checked by an application to see if it matches with the argument
sequenceNumber of the originating method.
If the “sequence number” returned from the CAT device is not numeric, the CAT
control set this property to zero.
This property is initialized to zero by the open method and is updated when an
authorization operation successfully completes.
SettledAmount Property Added in Release 1.9
Syntax SettledAmount: currency { read-only, access after open }
Remarks Electronic Money Device: Setting real amount of the settlement.
See Also authorizeSales Method, cashDeposit Method.
SlipNumber Property Updated in Release 1.7
Syntax SlipNumber: string { read-only, access after open }
Remarks Stores a “slip number” as the result of each authorization operation.

TrainingMode Property
Syntax TrainingMode: boolean { read-write, access after open }
Remarks If true, each operation will be run in training mode; otherwise each operation will
be run in normal mode.
TrainingMode needs to be explicitly set to false by an application to exit from
training mode, because it will not automatically be set to false after the completion
of an operation.
This property will be initialized to false by the open method.
Value Meaning
E_ILLEGAL CapTrainingMode is false.
TransactionNumber Property
Syntax TransactionNumber: string { read-only, access after open }
Remarks Stores a “transaction number” as the result of each authorization operation.
TransactionType Property Updated in Release 1.10
Syntax TransactionType: int32 { read-only, access after open }
Remarks Stores a “transaction type” as the result of each authorization operation.
This property is initialized to zero by the open method and is updated when an
authorization operation successfully completes.
This property will be set to one of the following values.
Value Meaning
CAT_TRANSACTION_SALES Sales
CAT_TRANSACTION_VOID Cancellation
CAT_TRANSACTION_REFUND Refund purchase
CAT_TRANSACTION_COMPLETION Purchase after approval
CAT_TRANSACTION_PRESALES Pre-authorization
CAT_TRANSACTION_CHECKCARD Card Check
CAT_TRANSACTION_VOIDPRESALES Cancel pre-authorization approval
CAT_TRANSACTION_CASHDEPOSIT Charge


accessDailyLog Method Updated in Release 1.9
Syntax accessDailyLog ( sequenceNumber: int32, type: int32, timeout: int32 ):
sequenceNumber The sequence number to get daily log.

type Specify whether the daily log is intermediate total or
final total and erase.
timeout The maximum waiting time (in milliseconds) until the
response is received from the CAT device. FOREVER
(-1), 0 and positive values can be specified.
Remarks Gets daily log from CAT.
Daily log will be retrieved and stored in DailyLog as specified by
sequenceNumber.
When timeout is FOREVER (-1), timeout never occurs and the device waits until
it receives response from the CAT.
Application must specify one of the following values for type for daily log type
(either intermediate total or adjustment). Legal values depend upon the
CapDailyLog value.
Electronic Money Device: Gets the DealingLog from the Electronic Money
Device to send to the Center. If the Electronic Money Device has communication
capabilities, the DealingLog will be sent from the Electronic Money Device to the
Center and nothing is stored in the DailyLog. Otherwise, the DealingLog is stored
in the DailyLog Property.
Value Meaning
CAT_DL_REPORTING Intermediate total.
CAT_DL_SETTLEMENT Final total and erase.
Electronic Money Device: Closing DealingLog of
the Electronic Money device.
Some possible values of the exception's ErrorCode property are:
Value Meaning
E_ILLEGAL Invalid or unsupported type or timeout parameter was
specified, or CapDailyLog is false.
E_TIMEOUT No response was received from CAT during the
specified timeout time in milliseconds.
E_EXTENDED The detail code has been stored in ErrorCodeExtended.
E_BUSY The CAT device cannot accept any commands now.
See Also CapDailyLog Property, DailyLog Property.

authorizeCompletion Method
Syntax authorizeCompletion ( sequenceNumber: int32, amount: currency,
sequenceNumber Sequence number for approval.

amount Purchase amount for approval.
taxOthers Tax and other amounts for approval.
Remarks Purchase after approval is intended.
Sales after approval for amount and taxOthers is intended as the approval specified
by sequenceNumber.
Value Meaning
E_ILLEGAL Invalid timeout parameter was specified, or

CapAuthorizeCompletion is false.
See Also CapAuthorizeCompletion Property.

authorizePreSales Method
Syntax authorizePreSales ( sequenceNumber: int32, amount: currency, taxOthers:

Remarks Makes a pre-authorization.
Pre-authorization for amount and taxOthers is made as the approval specified by
sequenceNumber.
Value Meaning

CapAuthorizePreSales is false.
See Also CapAuthorizePreSales Property.

authorizeRefund Method
Syntax authorizeRefund ( sequenceNumber: int32, amount: currency, taxOthers:

Remarks Refund purchase approval is intended.
Refund purchase approval for amount and taxOthers is intended as the approval
specified by sequenceNumber.
Value Meaning

CapAuthorizeRefund is false.
See Also CapAuthorizeRefund Property.

authorizeSales Method
Syntax authorizeSales ( sequenceNumber: int32, amount: currency, taxOthers:

Remarks Normal purchase approval is intended.
Normal purchase approval for amount and taxOthers is intended as the approval
Value Meaning
E_ILLEGAL Invalid timeout parameter was specified.


authorizeVoid Method
Syntax authorizeVoid ( sequenceNumber: int32, amount: currency, taxOthers:

Remarks Purchase cancellation approval is intended.
Cancellation approval for amount and taxOthers is intended as the approval
Value Meaning

CapAuthorizeVoid is false.
See Also CapAuthorizeVoid Property.

authorizeVoidPreSales Method
Syntax authorizeVoidPreSales ( sequenceNumber: int32, amount: currency,

Remarks Pre-authorization cancellation approval is intended.
Pre-authorization cancellation approval for amount and taxOthers is intended as
the approval specified by sequenceNumber.
Normal cancellation could be used for CAT control and CAT devices which have
not implemented the pre-authorization approval cancellation. Refer to the
documentation supplied with CAT device and / or CAT control.
Value Meaning

CapAuthorizeVoidPreSales is false.
See Also CapAuthorizeVoidPreSales Property.

cashDeposit Method Added in Release 1.9

Syntax cashDeposit ( sequenceNumber: int32, amount: currency, timeout: int32):
sequenceNumber Sequence number for charge.
amount Amount of money for charge.
Remarks Chargings.
The amount is stored on the Electronic Money Device.
If timeout is FOREVER(-1), a timeout will not occur and the process will wait
forever until the Electronic Money Device responds.
Value Meaning
CapCashDeposit is false.
See Also CapCashDeposit Property.

checkCard Method Updated in Release 1.9

Syntax checkCard ( sequenceNumber: int32, timeout: int32 ):
Remarks Card Check is intended.
Card Check will be made as specified by sequenceNumber.
Electronic Money Device:
The check of the Balance will be done by the specified sequenceNumber. The
Balance will be stored in the Balance
Value Meaning
CapCheckCard is false.
See Also Balance Property, CapCheckCard Property.

lockTerminal Method Added in Release 1.9

Syntax lockTerminal ( ):
Remarks Sets the security lock. When locked, the Electronic Money Device cannot accept
any commands.
AdditionalSecurityInformation property is used when key information is
required.
Value Meaning
E_ILLEGAL The Electronic Money Device does not have a security
lock function.
See Also CapLockTerminal Property.
unlockTerminal Method Added in Release 1.9

Syntax unlockTerminal ( ):
Remarks Releases the security lock.

AdditionalSecurityInformation property is used when key information is
required.
Value Meaning
E_ILLEGAL The Electronic Money Device does not have a security
lock function.
See Also CapUnlockTerminal Property.

DirectIOEvent
<<event>> upos::events::DirectIOEvent
means for a vendor-specific CAT Service to provide events to the application that
Service.
EventNumber and the Service. This attribute is settable.
and the Service. This attribute is settable.
from being used with other vendor’s CAT devices which may not have any
See Also “Events” on page 51, directIO Method

Description Notifies the application that a CAT error has been detected and suitable response
by the application is necessary to process the error condition.
ErrorCode int32 The code which caused the error event. See
ErrorCode for the values.
ErrorCodeExtended int32 The extended code which caused the error
event. See ErrorCodeExtended below for
values.
ErrorLocus int32 EL_OUTPUT is specified. An error occurred
during asynchronous action.
ErrorResponse int32 Pointer to the error event response. See
ErrorResponse below for values.

If ErrorCode is E_EXTENDED, ErrorCodeExtended will be set to one of the

following values:
Value Meaning
ECAT_CENTERERROR
An error was returned from the approval agency. The
detail error code is defined in CenterResultCode.
ECAT_COMMANDERROR
The command sent to CAT is wrong. This error is never
returned so long as CAT control is working correctly.
ECAT_RESET CAT was stopped during processing by CAT reset key
(stop key) and so on.
ECAT_COMMUNICATIONERROR
Communication error has occurred between the
approval agency and CAT.
ECAT_DAILYLOGOVERFLOW
Daily log was too big to be stored. Keeping daily log has
been stopped and the value of DailyLog property is
uncertain.
A failure will occur if the DealingLog on the device is
full and the device is attempting to be closed.
ECAT_DEFICIENT Electronic Money Device:
Because the balance is insufficient, it cannot close
settlement.
ECAT_OVERDEPOSIT
A failure will occur if a settlement amount is attempted
that is over the chargeable amount of the charge account.
The content of the position specified by ErrorResponse will be preset to the default
value of ER_RETRY. An application may set one of the following values.
Value Meaning
ER_RETRY Retries the asynchronous processing. The error state is

exited.
ER_CLEAR Clear the asynchronous processing. The error state is
exited.
Remarks Fired when an error is detected while processing an asynchronous authorize group
method or the accessDailyLog method. The control's State transitions into the
error state.
See Also “Device Output Models” on page 57, Device Information Reporting Model on
page 62.

OutputCompleteEvent
<<event>> upos::events::OutputCompleteEvent
is complete.
Remarks This event is enqueued after the request’s data has been both sent and the Service
has confirmation that is was processed by the device successfully.

Description Notifies the application that there is a change in the power status of the CAT
device.
Notifies the application that there is a change in the DealingLog status of the
Electronic Money Device.
Status int32 Indicates a change in the power status of the unit.
process.
The Status parameter contains the DealingLog status condition.
Value Meaning
CAT_LOGSTATUS_OK DealingLog is enough capacity.
CAT_LOGSTATUS_NEARFULL
DealingLog is nearly full.
CAT_LOGSTATUS_FULL DealingLog is full.
Remarks Enqueued when the CAT device detects a power state change.


C H A P T E R 1 0
Check Scanner
This Chapter defines the Check Scanner device category.
Summary


324 Check Scanner
CapAutoContrast: boolean { read-only } 1.9 open
CapAutoGenerateFileID: boolean { read-only } 1.7 open
CapAutoGenerateImageTagData: boolean { read-only } 1.7 open
CapAutoSize: boolean { read-only } 1.7 open
CapColor: int32 { read-only } 1.7 open
CapConcurrentMICR: boolean { read-only } 1.7 open
CapContrast: boolean { read-only } 1.9 open
CapDefineCropArea: boolean { read-only } 1.7 open
CapImageFormat: int32 { read-only } 1.7 open
CapImageTagData: boolean { read-only } 1.7 open
CapMICRDevice: boolean { read-only } 1.7 open
CapStoreImageFiles: boolean { read-only } 1.7 open
CapValidationDevice: boolean { read-only } 1.7 open
Color: int32 { read-write } 1.7 open

ConcurrentMICR: boolean { read-write } 1.7 open
Contrast: int32 { read-write } 1.9 open & enable
CropAreaCount: int32 { read-only } 1.7 open
DocumentHeight: int32 { read-write } 1.7 open
DocumentWidth: int32 { read-write } 1.7 open
FileID: string { read-write } 1.7 open
FileIndex: int32 { read-write } 1.7 open
ImageData: binary { read-only } 1.7 open
ImageFormat: int32 { read-write } 1.7 open
ImageMemoryStatus: int32 { read-only } 1.7 open & claim
ImageTagData string { read-write } 1.7 open
MapMode: int32 { read-write } 1.7 open
MaxCropAreas: int32 { read-only } 1.7 open
Quality: int32 { read-write } 1.7 open
QualityList: string { read-only } 1.7 open
RemainingImagesEstimate: int32 { read-only } 1.7 open

Summary 325

Common
Name Version
close ( ): 1.7
release ( ): 1.7
clearInput ( ): 1.7
clearOutput ( ): Not supported
void { }
compareFirmwareVersion(firmwareFileName: string,out result: int32):1.9
Specific
beginInsertion ( timeout: int32 ): 1.7
beginRemoval ( timeout: int32 ): 1.7
clearImage (by: int32): 1.7
defineCropArea ( cropAreaID: int32, x: int32, y: int32, 1.7
cx: int32, cy: int32 ):
endInsertion ( ): 1.7
endRemoval ( ): 1.7
retrieveImage (cropAreaID: int32 ): 1.7
retrieveMemory( by: int32 ): 1.7
void {raises-exception, use after open, claim, enable }
storeImage ( cropAreaID: int32 ): 1.7

326 Check Scanner

Data:
Obj: int32 { read-write }
object { read-write }
ErrorCodeExtended:
ErrorResponse: int32 { read-only }
int32 { read-write }

General Information
The Check Scanner programmatic name is “CheckScanner”.
Capabilities
The primary purpose of this device is to capture the image of a personal or business
check for Electronic Check Conversion. However, other documents (vouchers,
signature receipts, etc.) may be scanned if they fall within the capture size
parameters of the Check Scanner. Therefore, in the description used in this
standard the overall term “document” may be used to indicate the multiplicity of
uses of which the device may be capable. When the term “check” is used, it should
be viewed as a special form of a “document” as an example.
The Check Scanner Control has the following minimal set of capabilities:
• Reads image data from a Check Scanner device.
• Has programmatic control of check insertion, reading, and removal. For some
Check Scanner devices, this will require no processing in the Control since the
device may automate many of these functions.
The Check Scanner Control may have the following additional capabilities:
• The Check Scanner may store successive check images in its hardware
memory.
• Cropping of areas of interest within the check image may be supported by the
Check Scanner to aid in the reduction of the memory needed to transmit or
store the check image data.
• The retrieveImage data is deposited in the ImageData property in binary
form.
• The Check Scanner may allow for retrieval of images stored in its hardware
memory.
• The Check Scanner may support Image tag data information to identify the
check image.
• The application reads the contents of ImageData property when it wants to
further process the check image.
• The Check Scanner device may be physically attached to or incorporated into
a check validation print device and/or a MICR device. If this is the case, once
a check is inserted via Check Scanner Control methods, the check can still be
used by the Printer and MICR Control prior to check removal.

328 Check Scanner
Check Scanner Class Diagram Updated in Release 1.9
The following diagram shows the relationships between the Check Scanner
classes.
<<sends>>
<<exception>> <<Interface>> <<utility>> <<utility>>
<<uses>>
UposException BaseControl UposConst CheckScannerConst
<<uses>>
<<sends>>
DataEvent CheckScannerControl
<<prop>> Status : int32 <<capability>> CapAutoContrast : boolean
<<capability>> CapAutoGenerateFileID : boolean
<<capability>> CapAutoGenerateImageTagData : boolean
<<fires>> <<capability>> CapAutoSize : boolean
<<capability>> CapColor : int32
<<capability>> CapConcurrentMICR : boolean
<<capability>> CapContrast : boolean
<<event>> <<capability>> CapDefineCropArea : boolean
DirectIOEvent <<capability>> CapImageFormat : int32
(from events) <<capability>> CapImageTagData : boolean
<<prop>> EventNumber : int32 <<capability>> CapMICRDevice : boolean
<<fires>>
<<prop>> Data : int32 <<capability>> CapStoreImageFiles : boolean
<<prop>> Obj : object <<capability>> CapValidationDevice : boolean
<<prop>> Color : int32
<<prop>> ConcurrentMICR : boolean
<<prop>> Contrast : int32
<<prop>> CropAreaCount : int32
<<prop>> DocumentHeight : int32
<<prop>> DocumentWidth : int32
<<fires>> <<prop>> FileID : string
<<event>> <<prop>> FileIndex : int32
ErrorEvent <<prop>> ImageData : binary
(from events) <<prop>> ImageFormat : int32
<<prop>> ErrorCode : int32 <<prop>> ImageMemoryStatus : int32
<<prop>> ErrorCodeExtended : int32 <<prop>> ImageTagData : string
<<prop>> ErrorLocus : int32 <<prop>> MapMode : int32
<<prop>> ErrorResponse : int32 <<prop>> MaxCropAreas : int32
<<prop>> Quality : int32
<<prop>> QualityList : string
<<fires>> <<prop>> Remaining ImagesEstimate : int32
beginInsertion(timeout : int32) : void

beginRemoval(timeout : int32) : void
clearImage(by : int32) : void
defineCropArea(cropAreaID : int32, x : int32, y : int32, cx : int32, cy : int32) : void
<<event>> endInsertion() : void
StatusUpdateEvent endRemoval() : void
(from events)
retrieveImage(cropAreaID : int32) : void
<<prop>> Status : int32 retrieveMemory(by : int32) : void
storeImage(cropAreaID : int32) : void


The Check Scanner Control follows the general “Input Model”. One point of
difference is that the Check Scanner Control requires the execution of methods to
insert and remove the check for processing. Therefore, this Control requires more
than simply setting the DataEventEnabled property to true in order to receive
data. The basic model is as follows:
• The Check Scanner Control is opened, claimed, and enabled.
• Starting with Version 1.9, the application has the ability to adjust the darkness
of the scanned image for devices that have the ability to adjust the scan
mechanism so that it can darken or lighten the image. The CapContrast
property controls whether the device supports this feature.
• When the beginInsertion method is called, the Check Scanner is ready to read
the check within the specified time as indicated by the time-out value. If the
check is not inserted before the time-out value expires, a UposException is
raised.
• In the event of a time-out, the Check Scanner device will remain in a state that
allows a check to be inserted. The application may provide an operator prompt
which requests that a check be inserted. Following this prompt, the application
would then reissue the beginInsertion method and wait for the check to be
inserted.
• Once a check is inserted, the beginInsertion method returns and the
application calls the endInsertion method, which results in the Check
Scanner device exiting the check insertion mode and causes the check image
to be captured.
• Following the endInsertion method, the scan image data is stored in a
working buffer memory area and a StatusUpdateEvent will occur to
indicate that a successful scan image process has taken place. No
DataEvent is enqueued since data has not been transferred to the
ImageData property at this point.
• The application must use the retrieveImage method to retrieve the
current scan image data. However, if the check image was not
successfully captured by the device, the Control enqueues a ErrorEvent
to indicate the capture was not successful.
• If the AutoDisable property is true, then the device is automatically
disabled when the image is successfully captured.
DataEventEnabled property is true and other event delivery
requirements are met. Just before delivering this event, the Control copies
data into specific properties, and disables further data events by setting the
DataEventEnabled property to false. This causes subsequent input data
to be enqueued by the Control while the application processes the current
input and associated properties. When the application has finished the
current input and is ready for more data, it reenables events by setting
• If the CapAutoSize property is true, when the DataEvent is delivered,
the height and width of the of entire captured image are automatically
stored in the corresponding DocumentHeight and DocumentWidth
properties. If the CapAutoSize property is false, the application must
manually set the DocumentHeight and the DocumentWidth property
values prior to the beginInsertion method being invoked.

330 Check Scanner
• If the application needs to retrieve the entire or a cropped portion of the

captured image, the retrieveImage method is called. The image data is
sent from the device to the service and stored in the ImageData property.
When the corresponding DataEvent is delivered, the current image or
cropped image may be accessed by the application reading the image file
contained in the ImageData property.
• If the CapStoreImageFiles property is true, then the current image, or
cropped image, can be stored in the memory by using the storeImage
method.
• Any previously stored image may be retrieved by using the
retrieveMemory method. The stored image may be identified using the
“by” parameter and requesting that the image be located by FileID,
FileIndex, or ImageTagData.
• If CapDefineCropArea is true, then the application can use the
defineCropArea method to define crop areas in the captured image.
• An ErrorEvent (or events) is (are) enqueued if the Control encounters an
error while reading the check, and is delivered to the application when the
DataEventEnabled property is true and other event delivery
requirements are met.
• All input data enqueued by the Control may be deleted by calling the
clearInput method.
• All data properties that are populated as a result of firing a DataEvent or
ErrorEvent can be set back to their default values by calling the
clearInputProperties method.
• After processing the endInsertion DataEvent, the application may query the
CapMICRDevice property to determine if the device supports Magnetic Ink
Character Recognition. If CapMICRDevice property is true, then a MICR
read function may be performed in a “single pass” or “multiple pass” cycle but
prior to the check being removed from the device. If CapConcurrentMICR
property is true, then the device is capable of supporting a “single pass” MICR
read during an image scan. If CapConcurrentMICR property is true and
ConcurrentMICR property is true, then the MICR data would be read and
calling the MICR's beginInsertion and endInsertion methods would not be
needed to reposition the check for MICR reading.
• Additionally, after processing a DataEvent, the application should query the
CapValidationDevice property to determine if validation printing can be
performed on the check prior to check removal. If this property is true, the
application may call the Printer Control's beginInsertion and endInsertion
methods. This positions the check for validation printing. The Printer
Control's validation printing methods can then be used to perform validation
printing.
• If the CapImageTagData property is true, then an identifying name, for
example the transaction number, date and time, or some other naming
element, could be used to identify the image data. The format of the data must
be conformant to ARTS XML and reside in ImageTagData property.
• Once the check is no longer needed in the device, the application must call
beginRemoval of the Check Scanner, the MICR (if CapMICRDevice is
true), or the POS Printer (if CapValidationDevice is true), also specifying a
timeout value. This method will raise a UposException if the check is not

removed within the timeout period. In this case, the application may perform
any additional prompting prior to calling the method again. Once the check is
removed, the application should call the same device’s endRemoval method
to take the device out of removal mode.
• In order to accommodate many different Check Scanning devices, the
application should follow the above sequence of method calls even though the
device may not physically require one or more of the methods. An example
may be a Check Scanner that is “auto armed” and is capable of detecting a
check present and initiating a Check Scan and MICR read cycle automatically.
In this case the beginInsertion, endInsertion, beginRemoval, and
endRemoval method calls may actually do no more than return from the
Service.
• The model assumes that the device has a work area that can be used in the
following ways:
• When a document is scanned its image will be loaded as raw data into this
work area. When the retrieveImage method is invoked the data from the
work area may be modified by a previously defined crop area, as specified
by the cropAreaID parameter, and loaded into the ImageData property.
The work area will still contain the original scanned image data.
Additional retrieveImage method calls using different crop area criteria
can then be accomplished to load the ImageData property.
• The work area contains image data either from a recently scanned image
or as a result of a retrieveMemory method. Prior to invoking the
storeImage method, the FileIndex property is set to the correct index
number (as maintained by the service) and if used, the FileID and/or
ImageTagData properties are set. When the storeImage method is
invoked the data from the work area may be modified by a previously
defined crop area, as specified by the cropAreaID parameter, and stored
in the device memory. The work area will still contain the original
scanned image data. Additional storeImage method calls using different
crop area criteria can then be accomplished to store the image data in the
device’s memory. The RemainingImagesEstimate property is adjusted
to reflect the approximate number additional images that may be stored in
the device memory based upon the file size history of previously stored
images.
• When the retrieveMemory method is invoked, the work area is loaded
with an image data file that was previously stored in the device memory.
Either the FileIndex, FileID, or ImageTagData may be used to locate the
previously stored image. The ImageData property is also loaded with the
retrieved image data.
• In order to accommodate the various storage and retrieval architectures that
are in use for the Check Scanner device class, the model has been designed to
allow for three different addressing ways to locate previously stored image
data: FileIndex, FileID, and ImageTagData.
• The FileIndex is an addressing scheme that is automatically provided by
the service to physically store and retrieve the file data. The definition of
file data in this case includes any and/or all of the following: image data,
tag data information (that is appended and included with the image data
file), and a file identification (a file name associated with the image data

332 Check Scanner
file). The FileIndex is only used by the service to save and retrieve the
scan data and its associated data elements.
• The FileID is a “file name” that may be provided automatically by the
hardware device or the service. It also may be populated by the
application prior to a storeImage method being called. Once created it
remains with the ImageData and can be used to randomly locate a
specific file for uploading to the POS system and post processing
applications.
• The ImageTagData property contains a set of information about the
image that has been scanned. It is required that the format of the data be
XML and compliant to the ARTS Data Dictionary and ARTS XML
standards to ensure interoperability. Typically, it contains information
about when the image was captured, e.g., Date and Time, Store number,
Lane Number, Clerk identification, etc. This data may be pre- or post-
appended to the ImageData and remains a part of the combined data file
as a record of the origin of the data.
Device Sharing
The Check Scanner is an exclusive-use device, and adheres to the following

constraints:
• The application must claim and enable the device before the device begins
reading input, or before calling methods that manipulate the device.

Check Scanner Sequence Diagram

The following sequence diagram shows the typical usage of the Check Scanner
device.
Note: we are assuming that the :ClientApp already successfully opened, claimed and enabled the device. This
means that the platform specific loading/configuration/creation code executed successfully. We also assume
that the application already registered some event handlers with the controls.
:ClientApp :CheckScanner :DataEvent StatusUpdateEvent CheckScanner

Service
3: setMapMode(CHK_MM_ENGLISH)
4: setMapMode(CHK_MM_ENGLISH)
5: defineCropArea(1,0,0,1500,1000)
6: defineCropArea(1,0,0,1500,1000)
7: defineCropArea(1,0,2000,CHK_CROP_AREA_BOTTOM,CHK_CROP_AREA_RIGHT)
8: defineCropArea(1,0,2000,CHK_CROP_AREA_BOTTOM,CHK_CROP_AREA_RIGHT)
9: beginInsertion(timeout) 10: beginInsertion(timeout)
Detect check
insertion and
scan check
11: endInsertion()
12: endInsertion()
13: new
14: set status update event status
15: enqueue StatusUpdateEvent to service's internal queue
16: deliver StatusUpdateEvent [FreezeEvents == false]

retrieve the
image within the
second crop
19: retrieveImage(2) area defined
20: retrieveImage(2)
21: new
22: copy data to new DataEvent
23: enqueue DataEvent to service's internal queue
24: set Check Scanner properties and deliver DataEvent

[DataEventEnabled == true && FreezeEvents == false]

27: storeImage(1) 28: storeImage(1)
29: beginRemoval(timeout) 30: beginRemoval(timeout)
31: indicate user to start removing check
32: endRemoval() 33: endRemoval()

334 Check Scanner
Check Scanner State Diagram
The following diagram depicts the Check Scanner control device model.
[ Opened && [ Closed ||
Claimed && Released || Begin

Disabled ] Removal
Begin Enabled ]
Insertion /beginRemoval
/beginInsertion
[ Failed ] [ Failed ]
[ Success ]
/endRemoval
Removal
Insertion Idle
[ Success ]
/endRemoval
/endInsertion /endInsertion
End End
/defineCropArea /clearImage
Insertion Removal
/storeImage /retrieveImage
/retrieveMemory
Define
Retrieve
CropArea Store Image Retrieve Memory Clear Image
Image

CapAutoContrast Property Added in Release 1.9

Syntax CapAutoContrast: boolean { read-only, access after open }
Remarks This capability indicates that the device has the ability to automatically adjust the
darkness of the image to provide the best contrast for the image.
If true, then when Contrast is set to CHK_AUTOMATIC_CONTRAST, the device
attempts to automatically adjust the contrast.
See Also CapContrast Property, Contrast Property.
CapAutoGenerateFileID Property
Syntax CapAutoGenerateFileID: boolean { read-only, access after open }
Remarks This capability indicates the ability of the device to automatically generate a file name
that can be used to reference the file containing the captured image.
If CapAutoGenerateFileID is true, then the device can automatically create a file

name for the captured image file.
See Also FileID Property.
CapAutoGenerateImageTagData Property
Syntax CapAutoGenerateImageTagData: boolean { read-only, access after open }
Remarks This capability indicates the ability of the device to automatically generate tag data
used in reference to the image file for the captured image.
If CapAutoGenerateImageTagData is true, then the device can automatically

create image tag data which can be appended to the image file to provide
information about the captured image.
See Also ImageTagData Property.

336 Check Scanner
CapAutoSize Property
Syntax CapAutoSize: boolean { read-only, access after open }
Remarks This capability indicates the ability of the device to determine the height and width of
the document automatically.
If CapAutoSize is true, then the height and width of the scanned document will be
automatically placed in the DocumentHeight and DocumentWidth properties
when the image is captured.
If CapAutoSize is false, the height and width of the document can be manually set
in the DocumentHeight and DocumentWidth properties by the application prior to
scanning an image.
See Also DocumentHeight Property, DocumentWidth Property.
CapColor Property
Syntax CapColor: int32 { read-only, access after open }
Remarks This capability indicates if this device supports image formats other than bi-tonal.
CapColor is a logical OR combination of any of the following values:
Value Meaning
CHK_CCL_MONO Bi-tonal ( B/W )
CHK_CCL_GRAYSCALE Gray scale
CHK_CCL_16 16 Colors
CHK_CCL_256 256 Colors
CHK_CCL_FULL Full colors
See Also Color Property.

CapConcurrentMICR Property
Syntax CapConcurrentMICR: boolean { read-only, access after open }
Remarks This capability indicates if this device supports a Magnetic Ink Character
Recognition read during the image scanning process.
If CapConcurrentMICR is true, a check's MICR data can be captured during a
check scanning cycle (single pass scanning). For devices that are both a Check
Scanner device and a MICR reader device, following a check scan the device will
automatically pass the MICR data to the MICR Service. The check will not need
to be re-read during the MICR beginInsertion and endInsertion methods.
If CapConcurrentMICR is false, then it would be necessary to read the MICR
data (if the device supports MICR reading) by using the MICR beginInsertion
and endInsertion methods. Usually the MICR read is performed prior to the
Check Scanning process.
This property has no meaning if the CapMICRDevice property is false.
See Also CapMICRDevice Property, ConcurrentMICR Property.
CapContrast Property Added in Release 1.9

Syntax CapContrast: boolean { read-only, access after open }
Remarks This capability indicates the ability of the device to lighten or darken the scanned
image. This affects the image regardless of the value of the CapColor property.
If true then the darkness of the image can be adjusted using the Contrast property. If
false then the application cannot adjust the darkness of the image.
information see “Errors” on page 52.
See Also CapAutoContrast Property, Contrast Property.
CapDefineCropArea Property
Syntax CapDefineCropArea: boolean { read-only, access after open }
Remarks This capability indicates if this device supports a feature that allows cropping of
areas of interest within the scan image area defined by the DocumentHeight and
DocumentWidth properties.
If CapDefineCropArea is true, one or more cropping areas are allowed;
otherwise it is set to be false.
See Also CropAreaCount Property, MaxCropAreas Property, defineCropArea Method.

338 Check Scanner
CapImageFormat Property
Syntax CapImageFormat: int32 { read-only, access after open }
Remarks This capability indicates the image file formats that this device supports. The
image data is stored in the ImageData property using one of the following formats
supported by the CapImageFormat Property:
CapImageFormat is a logical OR combination of any of the following values:
Value Meaning
CHK_CIF_NATIVE Hardware native format
CHK_CIF_TIFF TIFF format
CHK_CIF_BMP BMP format
CHK_CIF_JPEG JPEG format
CHK_CIF_GIF GIF format
See Also ImageFormat Property.
CapImageTagData Property Updated in Release 1.11

Syntax CapImageTagData: boolean { read-only, access after open }
Remarks This capability indicates if this device has the ability to utilize ARTS XML
compliant tag names to identify its scanned images.
If CapImageTagData is true, then the device can set tag data, as defined by the
ImageTagData property, to the image data file stored in the ImageData property.
See Also ImageTagData Property, retrieveImage Method, storeImage Method.

CapMICRDevice Property
Syntax CapMICRDevice: boolean { read-only, access after open }
Remarks This capability indicates if this device supports a check MICR read function.
If CapMICRDevice is true, then the device supports a MICR read function in
addition to check scanning.
If CapConcurrentMICR is true, a check's MICR data can be captured during a
check scanning cycle (single pass scanning). For devices that are both a Check
Scanner device and a MICR reader device, following a check scan the device will
automatically pass the MICR data to the MICR service. The check will not need
If CapConcurrentMICR property is false, then it would be necessary to read the
MICR data by using the MICR beginInsertion and endInsertion methods. In this
case the MICR read is usually performed prior to the Check Scanning process.
See Also CapConcurrentMICR Property, ConcurrentMICR Property.
CapStoreImageFiles Property
Syntax CapStoreImageFiles: boolean { read-only, access after open }
Remarks This capability indicates if this device has the ability to store check images in its
hardware memory.
If CapStoreImageFiles is true, one or more images can be stored in the memory
provided by the device by using the storeImage method.
See Also retrieveImage Method, storeImage Method.

340 Check Scanner
CapValidationDevice Property
Syntax CapValidationDevice: boolean { read-only, access after open }
Remarks This capability indicates if this device has the ability to perform a validation print
function on the check using a print station.
If CapValidationDevice is true, a check does not have to be removed from the
Check Scanner device prior to performing validation printing. For devices that are
both a Check Scanner device as well as a POS Printer, the device will
automatically position the check for validation printing after successfully
performing a Check Scanner read. Either the Check Scanner Control’s or the POS
Printer Control’s beginRemoval and endRemoval methods may be called to
remove the check once the process is complete.
Color Property
Syntax Color: int32 { read-write, access after open }
Remarks This property is used to select the image scan mode for subsequent document scan
operations. The available options may be affected by the current file type as
specified by the ImageFormat property. Certain file types may not work with all
the “colors” that the device may support. It is up to the application to insure that
the proper Color and ImageFormat properties are compatible. Changing the
Color property will not affect any previously stored data currently residing in the
ImageData property.
It may contain one of the following values:
Value Meaning
CHK_CL_MONO Bi-tonal (B/W)
CHK_CL_GRAYSCALE Gray scale
CHK_CL_16 16 Colors
CHK_CL_256 256 Colors
CHK_CL_FULL Full color
See Also CapColor Property, ImageFormat Property.

ConcurrentMICR Property
Syntax ConcurrentMICR: boolean { read-write, access after open }
Remarks This property indicates whether a MICR read should be performed at the same
time the check image is captured (single pass operation).
This property has no meaning if the CapMICRDevice is false.
If ConcurrentMICR is true, a check's MICR data is captured during a check
scanning cycle (single pass scanning). For devices that are both a Check Scanner
device and a MICR reader device, following a check scan the device will
automatically pass the MICR data to the MICR Service. The check will not need
If ConcurrentMICR is false and MICR data is required, then it is necessary to
read MICR data by using the MICR beginInsertion and endInsertion method
calls. In this case the MICR read is usually performed prior to the Check Scanning
process.
See Also CapConcurrentMICR Property, CapMICRDevice Property.
Contrast Property Added in Release 1.9

Syntax Contrast: int32 { read-write, access after enable }
Remarks This property allows the application to adjust the darkness of the image. The
property is valid only if the CapContrast property is true.
A value of 0 sets or indicates that the device will generate the lightest image possible.
A value of 100 sets or indicates that the device will generate the darkest image possi-
ble. All values between 0 and 100 produce images with varying degrees of darkness.
A value of 50 should produce an image that is the optimal brightness for the best
image under normal circumstances.
If the CapAutoContrast property is true then this property can be set to
CHK_AUTOMATIC_CONTRAST to allow the device to automatically adjust the
darkness of the image based on sensing of the paper to produce the optimal brightness
for the best image under normal circumstances.
If CapAutoContrast is false, then attempting to set this property to
CHK_AUTOMATIC_CONTRAST is illegal.
If CapAutoContrast is true, then this property is initialized to
CHK_AUTOMATIC_CONTRAST when the device is enabled. If CapAutoContrast
is false, this property is initialized either to 50 or to a user configured value when the
device is enabled.
information see “Errors” on page 52.
See Also CapAutoContrast Property, CapContrast Property.

342 Check Scanner
CropAreaCount Property
Syntax CropAreaCount: int32 { read-only, access after open }
Remarks This property indicates the number of Crop areas that have been defined which
may be applied to the captured image.
If CapDefineCropArea is false, then this property is always zero.
See Also CapDefineCropArea Property, MaxCropAreas Property, defineCropArea
Method.
DocumentHeight Property
Syntax DocumentHeight: int32 { read-write, access after open}
Remarks This property is used to define the height of the document scanned or the height of
a document to scan. It is expressed in the unit of measure as defined by the
MapMode property.
If CapAutoSize is true, then the height of the scanned document will be
automatically placed in the DocumentHeight property when the image is
captured.
If CapAutoSize is false, the height of the document can be manually set in the
DocumentHeight property by the application prior to scanning a document.
This property is initialized to the maximum height supported by the device by the
open method.
See Also CapAutoSize Property, MapMode Property.
DocumentWidth Property
Syntax DocumentWidth: int32 { read-write, access after open}
Remarks This property is used to define the width of the document scanned or the width of
a document to scan. It is expressed in the unit of measure as defined by the
MapMode property.
If CapAutoSize is true, then the width of the scanned document will be
automatically placed in the DocumentWidth property when the image is
captured.
If CapAutoSize is false, the width of the document can be manually set in the
DocumentWidth property by the application prior to scanning an image.
This property is initialized to the maximum width supported by the device by the
open method.
See Also CapAutoSize Property, MapMode Property.

FileID Property
Syntax FileID: string { read-write, access after open }
Remarks This property is used to store a “file name” associated with the image data file. If
the application chooses to create the data for this property, it must set the FileID
property prior to calling the storeImage method.
After a retrieveMemory method call the FileID property will be set to the image
data file name if available, otherwise it will be set to an empty string. Its value is
set prior to a DataEvent being delivered to the application.
If the CapAutoGenerateFileID property is true then the FileID will
automatically be generated by the hardware device or the service when the image
is scanned.
See Also CapAutoGenerateFileID Property, retrieveImage Method, retrieveMemory
Method, storeImage Method.
FileIndex Property
Syntax FileIndex: int32 { read-write, access after open }
Remarks This property is used to store a file location reference to the image data file when
either the storeImage or retrieveMemory methods are called. Its value is set prior
to a DataEvent being delivered to the application.
The FileIndex property is used only by the service in conjunction with the device
to store and locate an image data file.
See Also clearImage Method, retrieveImage Method, retrieveMemory Method
storeImage Method.

344 Check Scanner
ImageData Property
Syntax ImageData: binary { read-only, access after open }1
Remarks This property is used to store the image data after the retrieveImage or
retrieveMemory methods are called. If no image data was available, the
ImageData property will be set to zero length (or empty). Its value is set prior to
a DataEvent being delivered to the application.
This property is initialized to zero length by the open method.
See Also retrieveImage Method, DataEvent.
ImageFormat Property
Syntax ImageFormat: int32 { read-write, access after open }
Remarks This property is used to define the data format of the image file that the device will
use when it captures an image. The availability of acceptable file types is specified
in the CapImageFormat property.
The ImageFormat property must be set before a document is scanned. Any
previously stored data in the ImageData property will not be affected by changing
the value of the ImageFormat property.
If the device provides support, it may be one of the following values:
Value Meaning
CHK_IF_NATIVE Hardware native format
CHK_IF_TIFF TIFF format
CHK_IF_BMP BMP format
CHK_IF_JPEG JPEG format
CHK_IF_GIF GIF format
The default value of this property is CHK_IF_TIFF.
See Also CapImageFormat Property, Color Property, DataEvent.

ImageMemoryStatus Property
Syntax ImageMemoryStatus: int32 { read-only, access after open-claim }
Remarks This property is used to indicate the current memory availability status if the
device has the ability to store multiple image files. The ImageMemoryStatus
value is only valid if the CapStoreImageFiles is true.
The following values are supported.
Value Meaning
CHK_IMS_EMPTY The image memory is empty.
CHK_IMS_OK The image memory is has storage available.
CHK_IMS_FULL The image memory is full.
See Also CapStoreImageFiles Property, storeImage Method.
ImageTagData Property Updated in Release 1.11

Syntax ImageTagData: string { read-write, access after open }
Remarks This property is used to define a string that specifies the ARTS XML compliant
tag name for the captured image data. It may be specified by the application or
auto-generated by the Check Scanner device. Information contained in the data
may refer to the date, time, lane number, location, clerk, or other information of
interest associated with the image at the time of capture.
If the application chooses to create the data for this property, it must set the
ImageTagData property prior to calling the storeImage method. After a
retrieveMemory method call, the ImageTagData property will be set if
available, otherwise it will be set to an empty string. Its value is set prior to a
If the CapAutoGenerateImageTagData property is true, the ImageTagData
will automatically be generated by the hardware device or the service when the
image is scanned.
All ImageTagData information must be formatted using XML that is conformant
to the ARTS Data Model and XML Dictionary. It is the responsibility of the
Application and/or Service to encode or parse the XML data.
See Also CapAutoGenerateImageTagData Property, retrieveImage Method,
retrieveMemory Method, storeImage Method.

346 Check Scanner
MapMode Property
Syntax MapMode: int32 { read-write, access after open }
Remarks This property is used to specify the units of measure that are currently valid for the
Check Scanner.
The mapping mode defines the unit of measure used by other properties, such as
the DocumentHeight and DocumentWidth properties.
The following units of measure may be selected for storing the image:
Value Meaning
CHK_MM_DOTS The scanner’s dot width.
CHK_MM_TWIPS 1/1440 of an inch.
CHK_MM_ENGLISH 0.001 inch.
CHK_MM_METRIC 0.01 millimeter.
The value of MapMode is initialized to CHK_MM_ENGLISH when the device is
first enabled following the open method.
See Also DocumentHeight Property, DocumentWidth Property, defineCropArea
Method.
MaxCropAreas Property
Syntax MaxCropAreas: int32 { read-only, access after open }
Remarks This property is used to specify the maximum number of crop areas that the device
can support.
See Also CapDefineCropArea Property, CropAreaCount Property, defineCropArea
Method.

Quality Property
Syntax Quality: int32 { read-write, access after open }
Remarks This property is used to set the resolution of the device when a scan image is to
take place. It is defined as a dpi (dots per inch) value.
Any previously stored data in ImageData property will not be affected when the
Quality property value is changed.
See Also QualityList Property.
QualityList Property
Syntax QualityList: string { read-only, access after open }
Remarks This property is used to define the resolutions that the Check Scanner is capable
of supporting.
The string data consists of comma separated values that indicate the available
scanning resolutions that the device supports measured in dots per inch (dpi). An
empty string indicates that resolution is not selectable.
An example might be “160,320”, which indicates that the device supports 160 dpi
and 320 dpi.
See Also Quality Property.

348 Check Scanner
RemainingImagesEstimate Property
Syntax RemainingImagesEstimate: int32 { read-only, access after open }
Remarks This property is used to provide a “best guess” estimate of the remaining number
of images that can be stored. It is updated after every new image is stored or
cleared from the device’s available memory. The RemainingImagesEstimate
along with the ImageMemoryStatus properties are intended to be used by the
application to monitor the amount of available image storage.
This property is initialized to a “best guess” estimate of the total number of image
files that can be stored in the device’s memory by the open method.
See Also ImageMemoryStatus Property.

beginInsertion Method
Syntax beginInsertion ( timeout: int32 ):
void { raises exception, use after open-claim-enable }
The timeout parameter gives the number of milliseconds before failing the method.
If zero, the method tries to begin insertion mode, then returns immediately if
successful. otherwise a UposException is raised. If FOREVER (-1), the method
tries to begin insertion mode, then waits as long as needed until either the check is
inserted or an error occurs.
Remarks Called to initiate the document insertion process.
When called, the Check Scanner is made ready to receive a check by opening the
Check Scanner’s check handling “jaws” or activating a Check Scanner’s check
insertion mode. This method is paired with the endInsertion method for
controlling the check insertion. Although some Check Scanner devices do not
require this sort of processing, the application should still use these methods to
ensure application portability across different Check Scanner devices.
If the Check Scanner device cannot be placed into insertion mode, a
UposException is raised. Otherwise, check insertion is monitored until either:
• The check is successfully inserted.
• The check is not inserted before timeout milliseconds have elapsed, or an error
is reported by the Check Scanner device. In this case, a UposException is
raised, The Check Scanner device remains in check insertion mode. This
allows an application to perform some user interaction and reissue the
beginInsertion method without altering the Check Scanner check handling
mechanism.
Value Meaning
E_BUSY If the Check Scanner is a combination device, the peer
device may be busy.
E_ILLEGAL An invalid timeout parameter was specified.
E_TIMEOUT The specified time has elapsed without the check being
properly inserted.
See Also beginRemoval Method, endInsertion Method, endRemoval Method.

350 Check Scanner
beginRemoval Method
Syntax beginRemoval ( timeout: int32 ):
If zero, the method tries to begin removal mode, then returns immediately if
successful. otherwise a UposException is raised. If FOREVER (-1), the method
tries to begin removal mode, then waits as long as needed until either the check is
removed or an error occurs.
Remarks Called to initiate the check removal processing.
When called, the Check Scanner is made ready to remove a check by opening the
Check Scanner’s check handling “jaws” or activating a Check Scanner’s check
ejection mode. This method is paired with the endRemoval method for controlling
check removal. Although some Check Scanner devices do not require this sort of
processing, the application should still use these methods to ensure application
portability across different Check Scanner devices.
If the Check Scanner device cannot be placed into removal or ejection mode, a
UposException is raised. Otherwise, check removal is monitored until either:
• The check is successfully removed.
• The check is not removed before timeout milliseconds have elapsed, or an
error is reported by the Check Scanner device. In this case, a UposException
is raised, The Check Scanner device remains in check removal mode. This
beginRemoval method without altering the Check Scanner check handling
mechanism.
Value Meaning
E_BUSY If the Check Scanner is a combination device, the peer
device may be busy.
properly removed.
See Also beginInsertion Method, endInsertion Method, endRemoval Method.

clearImage Method
Syntax clearImage ( by : int32):
by Indicates how the image file is to be located so that it can
be removed from the storage.
Remarks Called to clear a specific image or all the images in the device memory.
The following values may be selected for by to initiate clearing of the memory:
Value Meaning
CHK_CLR_ALL All images in the device are cleared
CHK_CLR_BY_FILEID Locate file to be cleared using the FileID property.
CHK_CLR_BY_FILEINDEX
Locate file to be cleared using the FileIndex property.
CHK_CLR_BY_IMAGETAGDATA
Locate file to be cleared using the ImageTagData
property.
Return A UposException may be thrown when this method is invoked. For further
Value Meaning
• Device does not support stored images
• Device does not support clearing one image
E_NOEXIST Image was not found.
See Also CapStoreImageFiles Property, FileID Property, FileIndex Property,

ImageTagData Property.

352 Check Scanner
defineCropArea Method
Syntax defineCropArea (cropAreaID: int32, x: int32, y: int32, cx: int32, cy: int32 ):
cropAreaID The numeric identifier for the defined crop area.
x The starting X-coordinate of the cropping area.
y The starting Y-coordinate of the cropping area.
cx The value added to the “X-coordinate” in order to
determine the “X” endpoint for the cropping area.
cy The value added to the “Y-coordinate” in order to
determine the “Y” endpoint for the cropping area.
If the cropAreaID parameter is set to CHK_CROP_AREA_RESET_ALL, then all
the crop area definitions allowed (as specified by the MaxCropAreas property)
will reset their (x,y) and (cx,cy) values to (0,0) and
(DocumentWidth, DocumentHeight) respectively.
If the cropAreaID parameter is set to CHK_CROP_AREA_ENTIRE_IMAGE,
then the crop area is equal to the entire area of the scanned image.
If cx is set to the parameter CHK_CROP_AREA_RIGHT, then the “X” endpoint
value will be set to the value of the DocumentWidth property.
If cy is set to the parameter CHK_CROP_AREA_BOTTOM, then the “Y”
endpoint value will be set to the value of the DocumentHeight property.
Remarks This method is used to establish one or more cropping areas that may be applied
to a scanned image. The values are in MapMode units and use the top left corner
of the scanned document as the origin (0,0). All values are positive.
The defineCropArea method specifies an area of interest that is contained within
a crop box and given an index number for reference. Only the data defined by
defineCropArea index number will be sent when the retrieveImage method is
called.
The crop areas should be set before the retrieveImage method is called and will
be in effect until changed.
A crop box cannot contain an area larger than that defined by the current
DocumentHeight and DocumentWidth properties. If the resultant value for the
endpoint (x+cx) is greater than the DocumentWidth value, then the “X” endpoint
value will be set to DocumentWidth. If the resultant value for endpoint (y+cy) is
greater than the DocumentHeight value, then the “Y” endpoint value will be set
to DocumentHeight.
See Also CapDefineCropArea Property, CropAreaCount Property, DocumentHeight
Property, DocumentWidth Property, MapMode Property, MaxCropAreas
Property.

endInsertion Method
Syntax endInsertion ( ):
Remarks Ends the document insertion processing. If this method call is successful, the
device will place the captured image in a working buffer memory area. A
StatusUpdateEvent will occur to indicate that a successful scan image process
has taken place. No DataEvent is enqueued since data has not been transferred to
the ImageData property at this point. The application must invoke retrieveImage
in order to populate the ImageData property with the scan image data.
When called, the Check Scanner is taken out of the check insertion mode. If a
check is not detected in the device, a UposException is raised with an extended
error code of ECHK_NOCHECK. This allows an application to prompt the user
prior to calling this method to ensure that the form is correctly positioned.
This method is paired with the beginInsertion method for controlling check
insertion. Although some Check Scanner devices do not require this sort of
Value Meaning
E_ILLEGAL The device is not in check insertion mode.
E_EXTENDED ErrorCodeExtended = ECHK_NOCHECK:
The device was taken out of insertion mode without a
check being inserted.
See Also beginInsertion Method, beginRemoval Method, endRemoval Method,

retrieveImage Method.

354 Check Scanner
endRemoval Method
Syntax endRemoval ( ):
Remarks Ends the document removal processing.
When called, the Check Scanner is taken out of check removal or ejection mode.
If a check is detected in the device, a UposException is raised with an extended
error code of ECHK_CHECK .
This method is paired with the beginRemoval method for controlling check
removal. Although some Check Scanner devices do not require this sort of
Value Meaning
E_ILLEGAL The device is not in check removal mode.
E_EXTENDED ErrorCodeExtended = ECHK_CHECK:
The device was taken out of removal mode while a
check is still present.
See Also beginInsertion Method, beginRemoval Method, endInsertion Method.

retrieveImage Method Updated in Release 1.11

Syntax retrieveImage ( cropAreaID: int32 ):
cropAreaID Identifier to specify the storage location of the crop area
parameters to be applied to the most recently scanned
image held in the working area memory of the device. If
the value is CHK_CROP_AREA_ENTIRE_IMAGE
then the entire area of the most recently scanned image
is retrieved.
Remarks Called to retrieve the most recently scanned image which is resident in the work
area memory to the ImageData property. If this method call is successful, the
device will deliver either a DataEvent or an ErrorEvent at a later time.
If the CapImageTagData property is true, then the ImageTagData property is set
to the ARTS XML compliant tag data associated with the image data file.
If a file name has been created for the image data by the device, then the FileID
property will be set to the file name; if none is available then the FileID property
will be set to an empty string.
Many models of Check Scanner devices do not require any check handling
processing from the application. Such devices may always be capable of receiving
a check, scanning the image into their working memory area, and require no
commands to actually read and eject the check. For these type of Check Scanner
devices, the beginInsertion, endInsertion, beginRemoval and endRemoval
methods simply return, and the Control will enqueue the data until the
DataEventEnabled property is set to true. However, applications should still use
these methods to ensure application portability across different Check Scanner
devices.
The retrieveImage method cannot be called after a retrieveMemory method has
been called until a new document has been scanned.
Value Meaning
E_ILLEGAL The following error has occurred:
• Cropped area that is specified by cropAreaID
parameter is invalid.
See Also CapImageTagData Property, FileID Property, ImageData Property,

ImageTagData Property, beginInsertion Method, beginRemoval Method,
endInsertion Method, endRemoval Method.

356 Check Scanner
retrieveMemory Method Updated in Release 1.11

Syntax retrieveMemory ( by: int32 ):
by Indicates how the image file is to be located so that it can
be retrieved from the device memory storage.
Remarks Called to retrieve an image that was previously stored in memory to the work area
and the ImageData property. If this method call is successful, the device will
deliver either a DataEvent or an ErrorEvent at a later time.
The following values may be selected for by:
Value Meaning
CHK_LOCATE_BY_FILEID
Locate image file using the FileID property.
CHK_LOCATE_BY_FILEINDEX
Locate image file using the FileIndex property.
CHK_LOCATE_BY_IMAGETAGDATA
Locate image file using the ARTS XML compliant
ImageTagData property.
The FileID, FileIndex, and ImageTagData properties will all be updated to
reflect their respective values associated with the image data file after this method
is called. A value for FileIndex will always be available. The FileID and
ImageTagData properties will be set to empty strings if the image file does not
have respective data to be retrieved for these properties.
The retrieveImage method cannot be called after a retrieveMemory method has
been called until a new document has been scanned.
Value Meaning
• by parameter is invalid.
• The image data file could not be located due to an
invalid value stored in either the FileID, FileIndex,
or ImageTagData properties that was being used
with the by value.
See Also FileID Property, FileIndex Property, ImageData Property, ImageTagData

Property.

storeImage Method
Syntax storeImage ( cropAreaID: int32 ):
cropAreaID Identifier to specify the storage location of the crop area
parameters to be applied to image data file currently in
the buffer memory area of the device. If the value is
CHK_CROP_AREA_ENTIRE_IMAGE, then an exact
image of the buffer memory is stored in the device
memory (no cropping is applied).
Remarks Called to store an image or a cropped area of the image in the memory of the
device.
The RemainingImagesEstimate property is adjusted to reflect the approximate
number additional images that may be stored in the device memory based upon the
file size history of previously stored images.
The ImageMemoryStatus property indicates whether or not the device memory
is full and is adjusted as a result of this method.
The FileID, FileIndex, and ImageTagData properties must all be updated to
reflect their respective values associated with the image data file before this
method is called. A value for FileIndex will always be available and is supplied
by the service. The FileID and/or ImageTagData properties will be set to empty
strings if the device does not support the respective property.
Return A UposException may be thrown when this method is invoked. For further
Value Meaning
E_EXIST Image already exists in the store location specified by
the FileIndex property.
• Device does not support storing images
• Cropped area that is specified by cropAreaID
E_FAILURE Internal error storing image.
E_EXTENDED ErrorCodeExtended = ECHK_NOROOM:
There is no more room for the image in memory.
See Also CapStoreImageFiles Property, FileID Property, FileIndex Property,

ImageMemoryStatus Property, ImageTagData Property,
RemainingImagesEstimate Property.

358 Check Scanner
DataEvent
Description Notifies the application when data from the Check Scanner device is available to be
read.
Status int32 Set to 0.
Remarks Before this event is delivered, the scanned check image is placed into ImageData.
See Also ImageData Property, endInsertion Method, retrieveImage Method, storeImage
Method.
DirectIOEvent
means for a vendor-specific Check Scanner Service to provide events to the
Service.
from being used with other vendor’s Check Scanner devices which may not have

ErrorEvent
Description Notifies the application that an error has been detected at the Check Scanner
device and a suitable response by the application is necessary to process the error
condition.
Codes on page 52.
ErrorCodeExtended
values below.
Value Meaning
available.
available.
Value Meaning
ER_CLEAR Clear the buffered input data. The error state is exited.
ER_CONTINUEINPUT Use only when locus is EL_INPUT_DATA.

360 Check Scanner
Remarks This event is not delivered until DataEventEnabled is true and other event
See Also “Device Input Model” on page 18, “Device States” on page 26.
StatusUpdateEvent
Description Notifies the application that there is a change in the status of the Check Scanner
device.
Status int32 Indicates a change in the status of the Check Scanner
device.
The Status parameter has one of the following values:
Value Meaning
CHK_SUE_SCANCOMPLETE
The process of scanning a document image has been
successfully completed.
process.
Remarks Enqueued after the endInsertion method has been called and the Check Scanner
device has successfully completed the process of scanning a new image into a
working buffer memory area. Also enqueued when the Check Scanner device
detects a power state change.

C H A P T E R 1 1
Coin Acceptor
This Chapter defines the Coin Acceptor device category.
Summary


362 Coin Acceptor

RealTimeDataEnabled: boolean {read-only} 1.11 open, claim & enable

Summary 363

Common
Name Version
close ( ): 1.11
release ( ): 1.11
void { } supported
void { } supported
Specific
Name
fixDeposit ( ): 1.11

364 Coin Acceptor


General Information
The Coin Acceptor programmatic name is “CoinAcceptor”.

Capabilities
The Coin Acceptor has the following capabilities:

• Reports the cash units and corresponding unit counts available in the Coin
Acceptor.
• The coins which are deposited into the device between the start and end of
cash acceptance are reported to the application. The contents of the report are
cash units and cash counts.
The Coin Acceptor may also have the following additional capabilities:
• Reporting the fullness levels of the Coin Acceptor’s cash units. Conditions
which may be indicated include full, and near full states.

366 Coin Acceptor
Coin Acceptor Class Diagram
The following diagram shows the relationships between the Coin Acceptor
classes.
<<exception>>
<<utility>>
UposException
(from upos)
UposConst
(from upos)
<<sends>>
<<Interface>> <<utility>>
<<event>> CoinAcceptorControl CoinAcceptorConst
(f ro m up os) (from upos)
DataEvent <<uses>>
(from events) <<capability>> CapFullSensor : boolean
<<capability>> CapJamSensor : B oolean
<<capability>> CapPauseDeposit : boolean
<<capability>> CapRealTimeData : B oolean
<<fires>>
<<prop>> DepositAmount : int32
<<event>> <<prop>> DepositCashList : s tring
DirectIOEvent <<prop>> DepositCodeList : s tring
(from events) <<prop>> DepositCounts : string
<<prop>> DepositStatus : int32
<<fires>> <<prop>> FullS tatus : int32
adjustCashCounts(cashCounts : s tring)
<<event>> beginDeposit()
StatusUpdateEvent <<fires>> endDeposit(amount : int32)
(f ro m event s) fixDeposit()
pauseDeposit(control : int 32)
readCashCounts (cashCounts : string, disc repanc y : boolean)

Model
The general model of a Coin Acceptor is:

• Supports several coin denominations. The supported cash type for a particular
currency is noted by the list of cash units in the DepositCashList property.
• This specification provides programmatic control only for the accepting of
cash. The removal of cash from the device (for example, to remove deposited
cash) is controlled by the adjustCashCounts method, unless the device can
determine the amount of cash on its own. The application can call
readCashCounts to retrieve the current unit count for each cash unit, but
cannot control when or how cash is removed from the device.
set to the currency, selecting from a currency in the list DepositCodeList.
DepositCashList and readCashCounts all act upon the current currency
only.
• Sets the cash slot (or cash bin) conditions in the FullStatus property to show
full and near full status. If there are one or more full cash slots, then
FullStatus is CACC_STATUS_FULL.
• Coin acceptance into the “coin acceptance mechanism” is started by invoking
the beginDeposit method. The previous values of the properties
DepositCounts and DepositAmount are initialized to zero.
cash is stored in the DepositCounts and DepositAmount properties.
If the pauseDeposit method is executed with a parameter value of
CACC_DEPOSIT_PAUSE, then the counting of the deposited cash is
method is executed with a parameter value of CACC_DEPOSIT_RESTART,
process remains static until the endDeposit method is invoked with a
CACC_DEPOSIT_COMPLETE parameter to complete the deposit.

368 Coin Acceptor
Coin Acceptor Sequence Diagram
CoinAcceptor
Bill Acceptordevice.
device.This
Thismeans
meansthat
thatthe
theClaimed,
Claimed,DeviceEnabled
DeviceEnabledproperties
propertiesare
are==
==true
true
:ClientApp : CoinAcceptorControl CoinAcceptorService : DataEvent Human Actor
1: setRealTimeDataEvents(true)
2: setRealTimeDataEvents (true) Set so Deposit Amount and

DepositCount s are updat ed for
each Data Event
3: beginDeposit( )
4: beginDeposit()
5: initialize Deposit Amount and DepositCount s
6: accept Cash
7: create Data Event
8: enqueue Data Event for delivery
9: update DepositAmount and Deposit Counts
10: deliver Data Event
11: notify ClientApp of event
12: fixDeposit( )
13: fixDeposit
14: updateDepositAmount and DepositCounts

Coin Acceptor State Diagram
Closed open Opened claim Claimed
close release
s etDeviceEnabled( true )
release
close setDeviceEnabled( false )
Enabled clearInput ClearInputProcessing

readCashCounts
entry/ empty data queue
beginDeposit
Coin Acceptance endDepos it clearInput
entry/ DepositAmount = 0 Fix Mode

entry/ DepositCounts = 0
fixDeposit entry/ s ync DepositAmount and DepositCounts
has room
for coins
fix Deposit
adjustCas hCounts / remove coins jammed
near full pauseDeposit( CACC_DEPOSIT_PAUSE )
Pause Mode
adustCashCounts / remove coins
pauseDeposit( CACC_DEPOSIT_RESTART ) DepositAmount and DepositCounts
entry / sync
full
fire Event s
Device Sharing
The Coin Acceptor is an exclusive-use device, as follows:


370 Coin Acceptor

Remarks If true, the Coin Acceptor can report the condition that some cash slots are full.
Remarks If true, the coin acceptor can report a mechanical jam or failure condition.
Remarks If true, the Coin Acceptor can report the condition that some cash slots are nearly
full.

CapPauseDeposit Property
Remarks If true, the Coin Acceptor has the capability to suspend cash acceptance processing
temporarily.
Remarks If true, the device is able to supply data as the money is being accepted (“real time”).

See Also RealTimeDataEnabled property.
Remarks Contains the active currency code to be used by Coin Acceptor operations.
This property is initialized to an appropriate value by the open method. This value
is guaranteed to be one of the set of currencies specified by the DepositCodeList
property.
Value Meaning
DepositCodeList.
See Also DepositCodeList Property.

372 Coin Acceptor
DepositAmount Property
after the call to the beginDeposit method, there would be 18,057 yen in the Coin
Acceptor.
DepositCashList Property
Remarks Holds the cash units supported in the Coin Acceptor for the currency represented
It consists of ASCII numeric comma delimited values which denote the units of
the coins, then the ASCII semicolon character (“;”).

• “1,5,10,50,100,500” ---
1, 5, 10, 50, 100, and 500 yen coin.
DepositCodeList Property
Remarks Holds the currency code indicators for cash accepted.
It is a list of ASCII three-character ISO 4217 currency codes separated by commas.
For example, if the string is “JPY,USD”, then the Coin Acceptor supports both
Japanese and U.S. monetary units.

DepositCounts Property
Remarks Holds the total of the cash accepted by the cash units. Cash units inside the string
are the same as the DepositCashList property, and are in the same order.
property is set to
1:80,5:77,10:0,50:54,100:0,500:87
After the call to the beginDeposit method, there would be 80 one yen coins, 77
five yen coins, 54 fifty yen coins, and 87 five hundred yen coins in the Coin
Acceptor.
DepositStatus Property
Remarks Holds the current status of the coin acceptance operation. It may be one of the
following values:
Value Meaning
CACC_STATUS_DEPOSIT_START
CACC_STATUS_DEPOSIT_END
CACC_STATUS_DEPOSIT_COUNT
CACC_STATUS_DEPOSIT_JAM
property is set to CACC_STATUS_DEPOSIT_END after initialization.

374 Coin Acceptor
FullStatus Property
Value Meaning
CACC_STATUS_OK All cash slots are neither nearly full nor full.
CACC_STATUS_FULL Some cash slots are full.
CACC_STATUS_NEARFULL
Remarks If true, each data event fired will update the DepositAmount and DepositCounts
properties. Otherwise, DepositAmount and DepositCounts are updated with the
value of the money collected when fixDeposit is called. Setting
RealTimeDataEnabled will not cause any change in system behavior until a
subsequent beginDeposit method is performed. This prevents confusion regarding
what would happen if it were modified between a beginDeposit - endDeposit pairing.

Value Meaning
See Also CapRealTimeData Property, DepositAmount Property, DepositCounts
Property, beginDeposit Method, endDeposit Method, fixDeposit Method.


adjustCashCounts Method
Remarks This method is called to set the initial amounts in the Coin Acceptor after initial
amount currently in the acceptor.
hundred yen coins in the Coin Acceptor.

376 Coin Acceptor
beginDeposit Method
After calling this method, cash acceptance is reported by DataEvents until
fixDeposit is called while the deposit process is not paused.
Value Meaning
E_ILLEGAL The call sequence is not correct.
See Also DepositAmount Property, DepositCounts Property, endDeposit Method,
endDeposit Method
CACC_DEPOSIT_COMPLETE The deposit is accepted and the deposited
amount is equal to or less than the amount
required.
Value Meaning

fixDeposit Method
values in the Coin Acceptor.
Value Meaning
pauseDeposit Method
CACC_DEPOSIT_PAUSE Cash acceptance is paused.
CACC_DEPOSIT_RESTART Cash acceptance is resumed.
If control is CACC_DEPOSIT_PAUSE, the cash acceptance operation is paused.
to CACC_DEPOSIT_RESTART. It is valid to call fixDeposit then endDeposit
When the deposit process is paused, the DepositCounts and DepositAmount
properties are updated to reflect the current state of the Coin Acceptor. The
property values are not changed again until the deposit process is resumed.
If control is CACC_DEPOSIT_RESTART, the deposit process is resumed.
Value Meaning
set to CACC_DEPOSIT_PAUSE, or the deposit
CACC_DEPOSIT_RESTART.
See Also CapPauseDeposit Property, DepositAmount Property, DepositCounts Property,
beginDeposit Method, endDeposit Method, fixDeposit Method.

378 Coin Acceptor
readCashCounts Method
Remarks Each unit in cashCounts matches a unit in the DepositCashList property, and is
in the same order.
set to:
1:80,5:77,10:0,50:54,100:0,500:87
yen coins, 77 five yen coins, 54 fifty yen coins, and 87 five hundred yen coins in
the Coin Acceptor.
total in a Coin Acceptor. There are some cases where a discrepancy may occur
because of existing uncountable cash in a Coin Acceptor. An example would be
See Also DepositCashList Property.


DataEvent
Description Notifies the application when a one or more coins have been accepted.
DirectIOEvent
means for a vendor-specific Coin Acceptor Service to provide events to the
Service.
from being used with other vendor’s Coin Acceptor devices which may not have

380 Coin Acceptor
StatusUpdateEvent
Description Notifies the application that there is a change in the status of the Coin Acceptor
device.
below.
process.
The Status parameter contains the Coin Acceptor status condition:
Value Meaning
CACC_STATUS_FULL Some cash slots are full.
CACC_STATUS_NEARFULL Some cash slots are nearly full.
CACC_STATUS_FULLOK No cash slots are either full or nearly full.
CACC_STATUS_JAM A mechanical fault has occurred.
CACC_STATUS_JAMOK A mechanical fault has recovered.
Remarks Fired when the Coin Acceptor detects a status change.

For changes in the fullness levels, the Coin Acceptor is only able to fire
StatusUpdateEvents when the device has a sensor capable of detecting the full or
near full states and the corresponding capability properties for these states are set.
Jam conditions may be reported whenever this condition occurs.

C H A P T E R 1 2
Coin Dispenser
This Chapter defines the Coin Dispenser device category.
Summary

382 Coin Dispenser
CapEmptySensor: boolean { read-only } 1.0 open
CapJamSensor: boolean { read-only } 1.0 open
CapNearEmptySensor: boolean { read-only } 1.0 open
DispenserStatus: int32 { read-only } 1.0 open, claim, & enable

Common
Name Version
close ( ): 1.0
release ( ): 1.0
clearInput ( ): Not
void { } supported
void { } supported
void { } supported

Summary 383
Methods (UML operations) - continued

Specific
Name
dispenseChange ( amount: int32 ): 1.0

upos::events::StatusUpdateEvent
Status: int32 { read-only } 1.0

384 Coin Dispenser
General Information
The Coin Dispenser programmatic name is “CoinDispenser”.
The coin dispenser has the following capability:

• Supports a method that allows a specified amount of change to be dispensed
from the device.
The coin dispenser may have the following additional capabilities:

• Status reporting, which indicates empty coin slot conditions, near empty coin
slot conditions, and coin slot jamming conditions.
• Starting with Release 1.11, reporting of a possible (or probable) cash count
discrepancy in the data reported by the readCashCounts method.

Coin Dispenser Class Diagram Updated in Release 1.11
The following diagram shows the relationships between the Coin Dispenser
classes.
<<Interface>>
BaseControl
(from upos)
open()
c lose()
c laim()
c ompareFirmwareVersion() <<utility>>
release() <<uses>> UposConst
reset Stat ist ics() (from upos)
<<sends>> c heckHealth()
<<exception>>
UposException c learInput()
(f rom up os) c learInputPropert ies()
c learOutput ()
directIO()
retrieveSt atistics()
updateFirmware()
<<utility>>
updateSt atist ics()
CoinDispenserConst
(f rom upo s)
<<sends>>
<<uses>>
DirectIOEvent CoinDispenserControl
(from events) (f ro m up os)
fires
<<prop>> EventNumber : int32 <<capability>> CapEmptyS ensor : boolean
<<prop>> Data : int32 <<capability>> CapJamSensor : boolean
<<prop>> Obj : object <<capability>> CapNearEmptySensor : boolean
<<capability>> DispenserSt atus : int32
adjustCashCount s(cas hCounts : st ring) : void

dispens eChange(amount : int 32) : void
fires
readCashCounts(cashCount s : string, discrepancy : boolean) : void
<<event>>
StatusUpdateEvent
(from events)
<<prop>> Status : int32

386 Coin Dispenser
Coin Dispenser Sequence Diagram Added in Release 1.7

The following sequence diagram shows the typical usage of the Coin Dispenser
device, showing coin dispensing and the firing of a StatusUpdateEvent due to
coin status getting low.
NOTE: we are assuming that the :ClientApp already successfully registered handlers for events and opened, claimed
and enabled the CoinDispenser device. This means that the Claimed, DeviceEnabled properties are == true
:ClientApp :CoinDispenser :StatusUpdateEvent :CoinDispenserService
1: dispenseChange(amount1)
Assume that after this

point the CoinDispenser
change is getting low
5: update DispenserStatus to COIN_STATUS_NEAR_EMPTY [CapNearEmptyStatus == true]

At this point the
:ClientApp event 6: create new SUE event
handling code executes
and takes appropriate
action (like informing
user) 7: deliver SUE event to control
8: deliver StatusUpdateEvent to all registered handlers


Coin Dispenser State Diagram Updated in Release 1.11
The following diagram illustrates the various state transitions within the Coin
Dispenser device category.
open claim
clos e release
release setDeviceEnabled( true )

close
Enabled
dispenseChange
dispenseChange
Has Coins Near Empty

Empty
adjustCashCounts / add coins
readCashCounts adjustCashCounts / coins added
done done
jams
jams fire event fire event
done
Jammed Fire Events
fire event

388 Coin Dispenser
The general model of a coin dispenser is:

• Consists of a number of coin slots which hold the coinage to be dispensed. The
application using the Coin Dispenser Service is not concerned with
controlling the individual slots of coinage, but rather calls a method with the
amount of change to be dispensed. It is the responsibility of the coin dispenser
device or the Service to dispense the proper amount of change from the
various slots.
Starting with Release 1.11:

• Sets cash in the device programatically by adding amount to counts when cash
is added.
• Reads cash counts from device, either directly from the hardware, or from the
service, by tracking what is dispensed and what has been added to the device.
Device Sharing
The coin dispenser is an exclusive-use device, as follows:

properties, dispensing change, or receiving status update events.


Remarks If true, the coin dispenser can report an out-of-coinage condition.
Remarks If true, the coin dispenser can report a mechanical jam or failure condition.
Remarks If true, the coin dispenser can report when it is almost out of coinage.
DispenserStatus Property
Syntax DispenserStatus: int32 { read-only, access after open-claim-enable }
Remarks Holds the current status of the dispenser. It has one of the following values:
Value Meaning
COIN_STATUS_OK Ready to dispense coinage. This value is also set when
the dispenser is unable to detect an error condition.
COIN_STATUS_EMPTY
Cannot dispense coinage because the dispenser is
empty.
COIN_STATUS_NEAREMPTY
Can still dispense coinage, but the dispenser is nearly
empty.
COIN_STATUS_JAM A mechanical fault has occurred.
property is synonymous to the DeviceStatus in the Cash Changer.

390 Coin Dispenser
adjustCashCounts Method Added in Release 1.11

Remarks This method is called to set the initial amounts in the Coin Dispenser after initial
amount currently in the dispenser.
hundred yen coins in the Coin Dispenser.
dispenseChange Method
Syntax dispenseChange ( amount: int32 ):
The amount parameter contains the amount of change to be dispensed.
Remarks Dispenses change. The value represented by the amount parameter is a count of
the currency units to dispense (such as cents or yen).
Value Meaning
E_ILLEGAL An amount parameter value of zero was specified, or the
amount parameter contained a negative value or a value
greater than the device can dispense.

readCashCounts Method Added in Release 1.11

cashCounts The cash count data is placed into cashCounts.

Remarks The format of the string cashCounts is an ASCII string. The string has a set of
comma separated units. Each unit in cashCounts indicates a denomination of a unit
as well as a count of those units, separated by a colon (“:”).
set to:
1:80,5:77,10:0,50:54,100:0
yen coins, 77 five yen coins, and 54 fifty yen coins in the Coin Dispenser.

392 Coin Dispenser
DirectIOEvent
means for a vendor-specific Coin Dispenser Service to provide events to the
Service.
from being used with other vendor’s Coin Dispenser devices which may not have

StatusUpdateEvent
Description Notifies the application of a sensor status change.
Status int32 The status reported from the Coin Dispenser.
Value Meaning
COIN_STATUS_OK Ready to dispense coinage. This value is also set when
the dispenser is unable to detect an error condition.
COIN_STATUS_EMPTY
Cannot dispense coinage because the dispenser is
empty.
COIN_STATUS_NEAREMPTY
Can still dispense coinage, but the dispenser is nearly
empty.
COIN_STATUS_JAM A mechanical fault has occurred.
process.
Remarks This event applies for status changes of the sensor types supported, as indicated by
the capability properties. It also applies if Power State Reporting is enabled.

394 Coin Dispenser

C H A P T E R 1 3
Electronic Journal
This Chapter defines the Electronic Journal device category.
Summary

396 Electronic Journal
CapAddMarker: boolean {read-only} 1.10 open
CapErasableMedium: boolean {read-only} 1.10 open
CapInitializeMedium: boolean {read-only} 1.10 open
CapMediumIsAvailable: boolean {read-only} 1.10 open
CapPrintContent: boolean {read-only} 1.10 open
CapPrintContentFile: boolean {read-only} 1.10 open
CapRetrieveCurrentMarker: boolean {read-only} 1.10 open
CapRetrieveMarker: boolean {read-only} 1.10 open
CapRetrieveMarkerByDateTime: boolean {read-only} 1.10 open
CapRetrieveMarkersDateTime: boolean {read-only} 1.10 open
CapStation: int32 {read-only} 1.10 open
CapStorageEnabled: boolean {read-only} 1.10 open
CapSuspendPrintContent: boolean {read-only} 1.10 open
CapSuspendQueryContent: boolean {read-only} 1.10 open
CapWaterMark: boolean {read-only} 1.10 open
FlagWhenIdle: boolean {read-write} 1.10 open
MediumFreeSpace: currency {read-only} 1.10 open, claim & enable
MediumID: string {read-only} 1.10 open, claim & enable
MediumIsAvailable: boolean {read-only} 1.10 open, claim & enable
MediumSize: currency {read-only} 1.10 open, claim & enable
Station: int32 {read-write} 1.10 open
StorageEnabled: boolean {read-write} 1.10 open, claim & enable
Suspended: boolean {read-only} 1.10 open
WaterMark: boolean {read-write} 1.10 open

Summary 397

Common
Name Version
close ( ): 1.10
release ( ): 1.10
void { } supported
Specific
Name
addMarker ( marker: string ): 1.10
cancelPrintContent ( ): 1.10
cancelQueryContent ( ): 1.10
eraseMedium ( ): 1.10
initializeMedium ( mediumID: string ): 1.10
printContent ( fromMarker: string, toMarker: string ): 1.10

printContentFile ( fileName: string ): 1.10

queryContent ( fileName: string, fromMarker: string, toMarker: string ): 1.10
resumePrintContent ( ): 1.10
resumeQueryContent ( ): 1.10
retrieveCurrentMarker ( markerType: int32, out marker: string ): 1.10
retrieveMarker ( markerType: int32, sessionNumber: int32, document- 1.10
Number: int32, out marker: string ):
retrieveMarkerByDateTime ( markerType: int32, dateTime: string, mark- 1.10
erNumber: string, out marker: string ):
retrieveMarkersDateTime ( marker: string, out dateTime: string ): 1.10
suspendPrintContent ( ): 1.10
suspendQueryContent ( ): 1.10


General Information
The Electronic Journal programmatic name is “ElectronicJournal”.
Capabilities
The Electronic Journal device stores records of transactions into digital media as
electronic data. If the recording function of the Electronic Journal device is
enabled, then it starts storing all print data that is output to the POSPrinter or
FiscalPrinter device. In the case of the FiscalPrinter device, the Fiscal Printing
output is stored at all times.
The Electronic Journal has the following capabilities.

• Stores transaction data.
• Transfers stored data.
The Electronic Journal may also have the following additional capabilities.
• Prints stored data on the attached POSPrinter or FiscalPrinter.
• Erases stored data.
• Initializes recording medium.
The Electronic Journal may also have the following special capabilities in fiscal
environments.
• Provides the ability to re-print entire fiscal documents and tickets specifying
a range of ticket numbers or ticket dates and times.

Electronic Journal Class Diagram
The following diagram shows the relationships between the Electronic Journal
device classes.
<<Interface>> <<utility>>
BaseControl ElectronicJournalConst
<<sends>> <<uses>>
<<uses>>
<<sends>>
<<event>>
DataEvent
(from events) <<Interface>>
<<prop>> Status : int32 ElectronicJournalControl
(from upos)
fires <<capability>> CapInitializeMedium : boolean
<<capability>> CapErasableMedium : boolean
<<capability>> CapPrintContent : boolean
<<capability>> CapPrintContentFile : boolean
<<event>> <<capability>> CapStation : int32
ErrorEvent <<capability>> CapSuspendPrintContent : boolean
(from events) <<capability>> CapSuspendQueryContent : boolean
<<prop>> ErrorCode : int32 <<capability>> CapWaterMark : boolean
<<prop>> ErrorCodeExtended : int32 <<capability>> CapMediumIsAvailable : boolean
<<prop>> ErrorLocus : int32 <<capability>> CapRetrieveMarker : boolean
fires <<capability>> CapRetrieveMarkerByDateTime : boolean
<<capability>> CapRetrieveCurrentMarker : boolean
<<capability>> CapRetrieveMarkersDateTime : boolean
<<capability>> CapAddMarker : boolean
<<capability>> CapStorageEnabled : boolean
<<prop>> FlagWhenIdle : boolean
<<prop>> MediumID : string
<<prop>> MediumSize : currency
<<event>> <<prop>> MediumFreeSpace : currency
OutputCompleteEvent fires <<prop>> MediumIsAvailable : boolean
(from events) <<prop>> StorageEnabled : boolean
<<prop>> OutputID : int32 <<prop>> Station : int32
<<prop>> Suspended : boolean
<<prop>> WaterMark : boolean
addMarker(marker : string) : void

fires cancelPrintContent () : void
cancelQueryContent () : void
<<event>> initializeMedium (mediumID : string) : void
StatusUpdateEvent eraseMedium () : void
(from events) printContent (fromMarker : string, toMarker : string) : void
<<prop>> Status : int32 printContentFile (fileName : string) : void
queryContent (fileName : string, fromMarker : string, toMarker : string) : void
resumePrintContent () : void
resumeQueryContent () : void
suspendPrintContent () : void
suspendQueryContent () : void
retrieveMarker(markerType : int32, sessionNumber : int32, documentNumber : int32, out marker : string) : void
retrieveMarkerByDateTime(markerType : int32, dateTime : string, markerNumber : string, out marker : string) : void
retrieveCurrentMarker(markerType : int32, out marker : string) : void
retrieveMarkersDateTime(marker : string, out dateTime : string) : void

Model
The Electronic Journal writing process is started implicitly when a printing

method for the POSPrinter or FiscalPrinter is performed. All output is performed
on a first-in first-out basis. Therefore, an ErrorEvent is delivered if the writing
process fails.
The writing process of the POSPrinter or FiscalPrinter may result in a failure, in

this case an ErrorEvent is delivered.
• The following methods are always performed synchronously: addMarker,
retrieveCurrentMarker, retrieveMarker, retrieveMarkerByDateTime,
retrieveMarkersDateTime, and checkHealth. These methods will fail if
output to the POSPrinter or FiscalPrinter is outstanding.
• The suspendPrintContent and suspendQueryContent methods are also
always performed synchronously.
These methods attempt to stop printing (that is, at the very next printer
operation). They may be called when asynchronous output is outstanding.
These methods are primarily intended for use in exception conditions when
asynchronous output is outstanding.
• The following methods are performed either synchronously or asynchronously,
depending on the value of the AsyncMode property: eraseMedium,
initializeMedium, printContent, printContentFile, and queryContent.
When AsyncMode is false, then these methods are performed synchronously.
A marker can be placed where to store data and it can be used as an index. It can
be added at the beginning and end of data to indicate the data range when getting
or printing stored data.
During asynchronous data printing or transfer process, it can be suspended by
interrupt methods.
In fiscal environments the markers are set implicitly by the FiscalPrinter device.
The stored data is organized in sessions that correspond to the fiscal days. These
sessions contain documents that correspond to fiscal tickets. Sessions and
documents can be queried by the application indirectly using the
retrieveMarker, retrieveMarkerByDateTime, and retrieveCurrentMarker
methods. The returned markers are intended to be used with the printContent
and queryContent methods. The content and format of the markers are
implementation specific and need not be known or analyzed by the application.
An Electronic Journal device combines both the properties of an input device
(query) and an output device (store and print).
The data stored on the electronic journal medium are the printing lines that have
been issued to the attached POSPrinter or FiscalPrinter device. The data format of
the stored information depends upon the physical device model. The data should
be stored in nonvolatile storage; e.g., flash cards, memory cards, CD-RW, and
HDD can be used as the physical media. There is no need to distinguish the
differences between the physical media.

If the recording medium can be removed from or inserted into the device, a
StatusUpdateEvent is delivered when the medium status is changed.
Additionally, the medium status can be checked and it can be initialized if
necessary.
The primary responsibility is storing transaction data as it is, so there are no
functions to convert or reprocess the data.
Device Sharing
The Electronic Journal is an exclusive-use device, as follows:

the Electronic Journal specific properties.

Electronic Journal Sequence Diagrams

Various sequence diagrams are used to illustrate how the Electronic Journal API
can be used. These scenarios are designed to show the rationale and key concepts
behind the structure of the API.
: Application : ElectronicJournalControl : POSPrinterControl
open()
claim()
setStorageEnabled(true)
addMarker(1)
printNormal(PTR_S_RECEIPT, "Receipt #1")
write data
addMarker(2)
printNormal(PTR_S_RECEIPT, "Receipt #2")
write data
queryContent("data.bin", 1, 2)
notify of DataEvent
close()

The following sequence diagram shows how markers are intended to be used in
the fiscal environment. The querying of the FiscalPrinter device for the needed
markers is processed implicitly and therefore not shown below.
: Application : ElectronicJournalConst
retrieveMarker(EJ_MT_SESSION_BEG, 1, 0, marker1)
maker1
retrieveMarker(EJ_MT_SESSION_END, 1, 0, marker2)
marker2
printContent(marker1, marker2)
queryContent("data.bin", marker1, marker2)

Electronic Journal State Diagram
The following diagram illustrates the various state transitions within the
Electronic Journal device.
printContent(), printContentFile(), queryContent()
NormalMode SuspendMode
suspendPrintContent(),
suspendQueryContent()
resumePrintContent(), cancelPrintContent(),
resumeQueryContent(), cancelQueryContent()


AsyncMode Property
Remarks If true, then the print methods will be performed asynchronously.
If false, they will be performed synchronously.
CapAddMarker Property
Syntax CapAddMarker: boolean {read-only, access after open}
Remarks If true, the application can use the addMarker method. Usually this property is
false for fiscal EJ devices.
See Also addMarker Method.
CapErasableMedium Property
Syntax CapErasableMedium: boolean {read-only, access after open}
Remarks If true, the storage medium can be erased. If false, it is impossible.
CapInitializeMedium Property
Syntax CapInitializeMedium: boolean { read-only, access after open }
Remarks If true, the application can initialize the medium.
CapMediumIsAvailable Property Updated in Release 1.11

Syntax CapMediumIsAvailable: boolean { read-only, access after open }
Remarks If true, the application can check whether a recording medium is available or not.
See Also MediumIsAvailable Property.

CapPrintContent Property Updated in Release 1.11

Syntax CapPrintContent: boolean { read-only, access after open }
Remarks If true, the device is able to reprint stored journal documents directly on a
connected printing device.
See Also printContent Method.
CapPrintContentFile Property Updated in Release 1.11

Syntax CapPrintContentFile: boolean { read-only, access after open }
Remarks If true, the device is able to print journal documents extracted from the storage
medium on a connected printing device.
See Also printContentFile Method.
CapRetrieveCurrentMarker Property
Syntax CapRetrieveCurrentMarker: boolean {read-only, access after open}
Remarks If true, the application can use the retrieveCurrentMarker method. Usually this
property is true for fiscal EJ devices.
See Also retrieveCurrentMarker Method.
CapRetrieveMarker Property
Syntax CapRetrieveMarker: boolean {read-only, access after open}
Remarks If true, the application can use the retrieveMarker method. Usually this property
is true for fiscal EJ devices.
See Also retrieveMarker Method.

CapRetrieveMarkerByDateTime Property
Syntax CapRetrieveMarkerByDateTime: boolean {read-only, access after open}
Remarks If true, the application can use the retrieveMarkerByDateTime method. Usually
this property is true for fiscal EJ devices.
See Also retrieveMarkerByDateTime Method.
CapRetrieveMarkersDateTime Property
Syntax CapRetrieveMarkersDateTime: boolean {read-only, access after open}
Remarks If true, the application can use the retrieveMarkersDateTime method. Usually
this property is true for fiscal EJ devices.
See Also retrieveMarkersDateTime Method.
CapStation Property
Syntax CapStation: int32 { read-only, access after open }
Remarks This capability indicates the availability of data capturing.
CapStation property is a logical OR combination of any of the following values:
Value Meaning
EJ_S_RECEIPT Captures data output into receipt station and stores it
into the medium.
EJ_S_SLIP Captures data output into slip station and stores it into
the medium.
EJ_S_JOURNAL Captures data output into journal station and stores it
into the medium.
CapStorageEnabled Property
Syntax CapStorageEnabled: boolean { read-only, access after open }
Remarks This property indicates whether the recording of print data can be controlled by the
StorageEnabled property, i.e., can be changed. If false, StorageEnabled is
always set to true.
See Also StorageEnabled Property.

CapSuspendPrintContent Property
Syntax CapSuspendPrintContent: boolean { read-only, access after open }
Remarks If true, the printing process can be suspended.
See Also Suspended Property.
CapSuspendQueryContent Property
Syntax CapSuspendQueryContent: boolean { read-only, access after open }
Remarks If true, the data acquiring process can be suspended.
CapWaterMark Property
Syntax CapWaterMark: boolean { read-only, access after open }
Remarks If true, the device is able to print specific predefined background when reprinting
journal documents.
FlagWhenIdle Property
Syntax FlagWhenIdle: boolean { read-write, access after open }
Remarks If true, a StatusUpdateEvent will be enqueued when the device is in the idle state.
This property is automatically reset to false when the status event is delivered.
The main use of idle status event that is controlled by this property is to give the
application control when all outstanding asynchronous outputs have been
processed. The event will be enqueued if the outputs were completed successfully
or if they were cleared by the clearOutput method or by an ErrorEvent handler.
If the State is already set to S_IDLE when this property is set to true, then a
StatusUpdateEvent is enqueued immediately. The application can therefore
depend upon the event, with no race condition between the starting of its last
asynchronous output and the setting of this flag.
See Also State Property, clearOutput Method.

MediumFreeSpace Property
Syntax MediumFreeSpace: currency { read-only, access after open-claim-enable }
Remarks Holds the size of the remained free space on the storage medium in bytes. After
each storing process caused by printing with POSPrinter or FiscalPrinter device,
this value is decreased. It notifies StatusUpdateEvent when free space is near
empty or empty.
MediumID Property
Syntax MediumID: string { read-only, access after open-claim-enable }
Remarks This property indicates identification of the currently plugged medium. It holds a
value from the physical medium, so is initialized when enabled.
If it is not possible to obtain any information from the physical medium, then this
property is initialized to an empty string.
MediumIsAvailable Property Updated in Release 1.11

Syntax MediumIsAvailable: boolean { read-only, access after open-claim-enable }
Remarks Indicates whether a recording medium is attached or not. This information is only
available if CapMediumIsAvailable is true.
If true, a recording medium is attached. If false, it is not attached.
If the storage medium is not exchangeable, this property is always set true.
See Also CapMediumIsAvailable Property.
MediumSize Property
Syntax MediumSize: currency { read-only, access after open-claim-enable }
Remarks Holds the size of the storage medium in bytes.
Station Property
Syntax Station: int32 { read-write, access after open }
Remarks Set the station for subsequent data storing into the medium. Station is a logical OR
combination of any of the following values.
Value Meaning
EJ_S_RECEIPT Captures data output into receipt station of POSPrinter
or FiscalPrinter and stores it into the medium.

EJ_S_SLIP Captures data output into slip station of POSPrinter or

FiscalPrinter and stores it into the medium.
EJ_S_JOURNAL Captures data output into journal station of POSPrinter
or FiscalPrinter and stores it into the medium.
This property is initialized to EJ_S_RECEIPT by the open method.
StorageEnabled Property Updated in Release 1.11

Syntax StorageEnabled: boolean { read-write, access after open-claim-enable }
Remarks If true, the device is in a recordable state. Data output to the POSPrinter or
FiscalPrinter is stored on the medium as electronic information sequentially. The
Station property must be specified in advance to specify what station is available
to record.
If false, the device has been disabled to record data.
Value Meaning
E_FAILURE The device cannot move to the recordable state.
See Also Station Property.
Suspended Property
Syntax Suspended: boolean { read-only, access after open }
Remarks If true, the printing or data acquiring process is being suspended.
When both CapSuspendPrintContent and CapSuspendQueryContent are
false, there is no application to suspend a process. Then this property is always set
to false.
See Also CapSuspendPrintContent Property, CapSuspendQueryContent Property.
WaterMark Property
Syntax WaterMark: boolean { read-write, access after open }
Remarks This property specifies whether a specific predefined background should be
printed or not with journal documents. If true, the background is printed and it is
clear that the output is a reprint of the stored data.


addMarker Method
Syntax addMarker (marker: string):
marker Marker identifier.
Remarks Adds a marker at the end of the data stored on the recording medium.
Specifies index numbers as arguments to specify the data range when acquiring
data as a file or printing data on the connected POSPrinter or FiscalPrinter system.
Value Meaning
E_ILLEGAL Characters that cannot be used as marker are included,
or the character string is too long to be used as the
marker.
E_BUSY Request cannot be performed while output is in
progress. (This includes when the POSPrinter or
FiscalPrinter is busy printing.)
E_EXTENDED ErrorCodeExtended = EEJ_EXISTING:
The marker name is already specified in current
medium.
ErrorCodeExtended = EEJ_MEDIUM_FULL:
There is not enough free space to add a marker in current
medium.
cancelPrintContent Method
Syntax cancelPrintContent ():
Remarks Cancels the suspended data printing process.
If this method is performed successfully, remaining data is not printed.
cancelQueryContent Method
Syntax cancelQueryContent ( ):
Remarks Cancel the suspended data transfer process.
If this method is performed, no file to store data is created.

eraseMedium Method
Syntax eraseMedium ( ):
Remarks All the data in this medium is erased. Marker information is erased too.
When performed asynchronously, the results are notified with an event. If the
method succeeds and OutputCompleteEvent is delivered, otherwise an
ErrorEvent will be delivered.
Value Meaning
E_FAILURE Failed to erase data.
See Also AsyncMode Property.
initializeMedium Method
Syntax initializeMedium (mediumID: string ):
mediumID medium identifier.
Remarks Initializes the recording medium. At this time the application can give the medium
a name expressed as character string.
If the medium is not namable, the MediumID property is set to an empty string.
Value Meaning
E_BUSY Cannot perform while output is in progress. (This
includes when the POSPrinter or FiscalPrinter is busy
printing.)
See Also AsyncMode Property, MediumID Property.

printContent Method Updated in Release 1.11

Syntax printContent (fromMarker: string, toMarker: string):
fromMarker Marker identifier that indicates start position of the data.
Specifying an empty string means specifying the data at
the beginning of the recording medium.
toMarker Marker identifier that indicates end position of the data.
the end of the recording medium.
Remarks Prints the current journal document stored in the recording medium onto the
connected printer. This method is only supported if CapPrintContent is true.
Specifying an empty string for the fromMarker means specifying the data at the
beginning of the recording medium. Specifying an empty string for the toMarker
means specifying the data at the end of the recording medium.
See Also AsyncMode Property, CapPrintContent Property.
printContentFile Method Updated in Release 1.11

Syntax printContentFile (fileName: string):
fileName Name of the file that contains printing data.
Remarks Prints the journal document included in the file acquired from the recording
medium onto the connected printer system. The whole data included in the file is
printed. This method is only supported if CapPrintContentFile is true.
Value Meaning
E_ILLEGAL fileName contains invalid characters.
E_NOEXIST fileName was not found.
See Also AsyncMode Property, CapPrintContentFile Property.

queryContent Method Updated in Release 1.11

Syntax queryContent (fileName: string, fromMarker: string, toMarker: string):
fileName Name of the file that stores acquired data.
fromMarker Marker identifier that indicates start position of the data.
the beginning of the recording medium.
toMarker Marker identifier that indicates end position of the data.
the end of the recording medium.
Remarks Retrieves the data that has been stored on the electronic journal medium and
transfers it to the file fileName.
If AsyncMode is false, then queryContent operates synchronously.
If AsyncMode is true, the content querying process is performed asynchronously.
The method will initiate the querying and then return immediately. Once the
storing of the queried content data is successfully completed, a DataEvent is
delivered to the application. If the method fails, an ErrorEvent is delivered.
Specifying an empty string for the fromMarker means specifying the data at the
beginning of the recording medium. Specifying an empty string for the toMarker
means specifying the data at the end of the recording medium.
Value Meaning
E_BUSY Cannot perform while output is in progress. (This
includes when the POSPrinter or FiscalPrinter is busy
printing.)
E_EXISTS The file defined in fileName already exists.
E_ILLEGAL fileName contains invalid characters.
resumePrintContent Method
Syntax resumePrintContent ( ):
Remarks Resumes the suspended data printing process.
resumeQueryContent Method
Syntax resumeQueryContent ( ):
Remarks Resume the suspended data transfer process.

retrieveCurrentMarker Method
Syntax retrieveCurrentMarker (markerType: int32, out marker: string):
markerType specifies the type of the queried current marker, see
values below.
marker contains the return value, the implementation specific
marker.
The parameter markerType controls which type of stored marker is returned:
Value Meaning
EJ_MT_SESSION_BEG The marker for the last completed begin of a session is
returned.
EJ_MT_SESSION_END The marker for the last completed end of a session is
returned.
EJ_MT_DOCUMENT The marker for the last completed document or ticket is
returned.
EJ_MT_HEAD The first implicitly stored marker on the EJ medium is
returned.
EJ_MT_TAIL The last implicitly stored marker on the EJ medium is
returned.
Remarks Returns the last implicitly stored marker. The queried marker is specified by the
parameter markerType. The marker is returned in the parameter marker. The
format and content of the string representing a marker is implementation specific
and has not to be known or analyzed by the application. The returned marker can
be used as an input parameter for the printContent and queryContent methods.
The values EJ_MT_HEAD and EJ_MT_TAIL are intended to address the entire
contents of the EJ medium.
This method is only supported if CapRetrieveCurrentMarker is true.
This method is usually used for fiscal EJ devices.
Value Meaning
E_ILLEGAL The parameter markerType contains an invalid value.
E_NOEXIST A marker does not exist for the specified marker type.
See Also CapRetrieveCurrentMarker Property, printContent Method, queryContent
Method.

retrieveMarker Method
Syntax retrieveMarker (markerType: int32, sessionNumber: int32,
documentNumber: int32, out marker: string):
markerType specifies the type of the queried marker, see values
below.
sessionNumber contains the number of the session the marker is queried
for. If a session concept is not supported by the device
then this parameter has to be set to an invalid value less
than zero.
documentNumber contains the number of the document the marker is
queried for. If markerType is EJ_MT_SESSION_BEG
or EJ_MT_SESSION_END, then this parameter is
ignored.
marker.
Value Meaning
EJ_MT_SESSION_BEG A marker for begin of a session is queried.
EJ_MT_SESSION_END A marker for end of a session is queried.
EJ_MT_DOCUMENT A marker for a document or ticket is queried.
Remarks Returns a marker implicitly stored on the record medium. The queried marker is
specified by the parameters markerType, sessionNumber, and documentNumber.
The marker is returned in the parameter marker. The format and content of the
string representing a marker is implementation specific and has not to be known
or analyzed by the application. The returned marker is intended to be used as an
input parameter for the printContent and queryContent methods.
TIn case of a fiscal EJ device, the sessionNumber corresponds to a fiscal day
counter number returned by the FiscalPrinter device (see the getData parameter
value FPTR_GD_Z_REPORT). In the same way the documentNumber
corresponds to a fiscal ticket number.
This method is only supported if CapRetrieveMarker is true.
Value Meaning
E_ILLEGAL One of the parameters is invalid. Either the value in
markerType does not exist.
E_NOEXIST A marker does not exist for the specified parameter
values.
See Also CapRetrieveMarker Property, printContent Method, queryContent Method,
and the getData Method of the FiscalPrinter device category.

retrieveMarkerByDateTime Method
Syntax retrieveMarkerByDateTime (markerType: int32, dateTime: string,
markerNumber: string, out marker: string):
markerType specifies the type of the queried marker, see values
below.
dateTime The date-time period the marker is queried for. The
format of dateTime is ‘YYYYMMDDhhmmss’. If the
application is not able to specify the hours, minutes, and/
or seconds, then these fields can be omitted.
markerNumber If more than one marker exists of the requested type for
the time period given by the dateTime parameter, then
this parameter specifies the number of the marker which
has to be queried. Starts at 1 and is continuously
incremented by one for each marker.
marker.
Value Meaning
EJ_MT_SESSION_BEG The marker for the begin of a session is queried.
EJ_MT_SESSION_END The marker for the end of a session is queried.
EJ_MT_DOCUMENT The marker for a document is queried.
Remarks Returns a marker implicitly stored on the record medium. The queried marker is
specified by the parameters markerType, dateTime, and markerNumber. The
marker is returned in the parameter marker. The format and content of the string
representing a marker is implementation specific and has not to be known or
analyzed by the application. The returned marker can be used as an input
parameter for the printContent and queryContent methods.
This method is only supported if CapRetrieveMarkerByDateTime is true.
Value Meaning
E_ILLEGAL One of the parameters is invalid. The value in
markerType does not exist, dateTime is invalid, or the
markerNumber does not exist for the specified time
period.
E_NOEXIST A marker does not exist for the specified time period.
E_EXTENDED ErrorCodeExtended = EEJ_MULTIPLE_MARKER:
More than one marker exists for the specified time
period.
See Also CapRetrieveMarkerByDateTime Property, printContent Method,
queryContent Method.

retrieveMarkersDateTime Method
Syntax retrieveMarkersDateTime (marker: string, out dateTime: string):
marker specifies the marker for which the time has to be
determined.
dateTime contains the return value, the date and time string of the
given marker.
Remarks Returns the date and time of the given marker. The marker has either to be
instantiated by the application using addMarker, or it has to be queried by the
application using retrieveMarker or retrieveCurrentMarker. The determined
date-time is returned as a string in the marker parameter with the format
YYYYMMDDhhmmss. If the hours, minutes, and/or seconds can not be determined
then they are filled with question marks (?).
This method is only supported if CapRetrieveMarkersByDateTime is true.
Value Meaning
E_ILLEGAL The parameter marker contains an invalid marker.
See Also CapRetrieveMarkersByDateTime Property, addMarker Method,
retrieveCurrentMarker Method, retrieveMarker Method.
suspendPrintContent Method
Syntax suspendPrintContent ( ):
Remarks This suspends data transfer from the device, then move to suspended state. It must
be called when asynchronous output is outstanding. This method is primarily
intended for use in exception conditions when asynchronous output is outstanding,
such as within an error event handler.
After that, Suspended property changes into true, then a StatusUpdateEvent is
delivered.
Value Meaning
E_ILLEGAL It’s not in the printing cycle.

suspendQueryContent Method
Syntax suspendQueryContent ( ):
Remarks This method suspends data transfer from the device, then move to suspended state.
This method is primarily intended for use in exception conditions when
asynchronous output is outstanding, such as within an error event handler.
After that, Suspended property changes into true, then a StatusUpdateEvent is
notified.


DataEvent
Description Notifies the application that the storing of the queried Electronic Journal content
to a host file is completed.

Remarks This event is delivered after an asynchronous queryContent method call, when
DataEventEnabled is set true.
DirectIOEvent
means for a vendor-specific Electronic Journal Service to provide events to the
Service.
from being used with other vendors’ Electronic Journal devices which may not
have any knowledge of the Service’s need for this event.

ErrorEvent

Description Notifies the application that an Electronic Journal device error has been detected
and that a suitable response by the application is necessary to process the error
condition.
Concrete ErrorEvent notifications are delivered under the following conditions:
• When the POSPrinter or FiscalPrinter device asynchronously performs
printing jobs which include writing to the Electronic Journal media and this
writing fails.
• When the queryContent method fails in asynchronous mode
• When one of the methods - initializeMedium, eraseMedium,
printContent, printContentFile - is performed in asynchronous mode and
fails.
Codes on page 52.
ErrorCodeExtended
Otherwise it may contain a Service-specific value.
values below.
Value Meaning
available.
available.
If ErrorCode is E_EXTENDED, then ErrorCodeExtended has one of the
following values:
Value Meaning
EEJ_UNINITIALIZED_MEDIUM The medium is not initialized

EEJ_CORRUPTED_MEDIUM The medium or data on the media is

corrupted and can not be used.
EEJ_UNKNOWN_DATAFORMAT The medium has an unknown or
unsupported format.
EEJ_NOT_ENOUGH_SPACE There is not enough free space in the
medium to store data.
EEJ_MULTIPLE_MARKERS More than one marker has been requested,
but only one can be returned.
Value Meaning
ER_CLEAR Clear all buffered output data including all
asynchronous output. (The effect is the same as calling
clearInput.) The error state is exited. Default when
locus is EL_INPUT.
ER_CONTINUEINPUT
Acknowledges the error and directs the Control to
continue processing. The Control remains in the error
been delivered and the DataEventEnabled
property is again set to true, then another ErrorEvent is
delivered with locus EL_INPUT. Default when locus is
EL_INPUT_DATA.
ER_RETRY Typically valid only when locus is EL_OUTPUT.
May be valid when locus is EL_INPUT.
Remarks Input error events are generated when errors occur while reading the data from
the Electronic Journal device. Such events are not delivered until the
DataEventEnabled property is set to true so as to allow proper application
sequencing. All error information is placed into the applicable properties before
Output error events are generated and delivered when an error occurs during
asynchronous output processing. All error information is placed into the
applicable properties before the event is delivered.

OutputCompleteEvent
Concrete OutputCompleteEvent notifications are delivered under the following
conditions:
• When one of the methods - initializeMedium, eraseMedium,
printContent, printContentFile - is performed in asynchronous mode
and succeeds.
is complete.
has confirmation that it was processed by the device successfully.

Description Notifies the application that there is a change in the status of the Electronic Journal
device.
Status int32 Indicates a change in the status of the Electronic Journal
device.
The Status attribute may be one of the following values:
Value Meaning
EJ_SUE_MEDIUM_NEAR_FULL The medium is nearly full (that is, its free
space is low.
EJ_SUE_MEDIUM_FULL Storage medium is full.
EJ_SUE_MEDIUM_REMOVED Medium was removed from the device.
EJ_SUE_MEDIUM_INSERTED Medium was inserted into the device.
EJ_SUE_SUSPENDED Data printing or transfer was suspended.
EJ_SUE_IDLE All asynchronous output has finished,
either successfully or because output has
been cleared. The Electric Journal State is
now S_IDLE. The FlagWhenIdle property
must be true for this event to be delivered,
and is automatically reset to false just
before the event is delivered.
Remarks Fired when the status of an Electronic Journal changes.

C H A P T E R 1 4
Electronic Value Reader / Writer

This Chapter defines the Electronic Value Reader / Writer device category.
Summary

426 Electronic Value Reader / Writer

CapActivateService: boolean { read-only } 1.12 open
CapAddValue: boolean { read-only } 1.12 open
CapCancelValue: boolean { read-only } 1.12 open
CapCardSensor: int32 { read-only } 1.12 open
CapDetectionControl: int32 { read-only } 1.12 open
CapElectronicMoney: boolean { read-only } 1.12 open
CapEnumerateCardServices: boolean { read-only } 1.12 open
CapIndirectTransactionLog: boolean { read-only } 1.12 open
CapLockTerminal: boolean { read-only } 1.12 open
CapLogStatus: boolean { read-only } 1.12 open
CapMediumID: boolean { read-only } 1.12 open
CapPoint: boolean { read-only } 1.12 open
CapSubtractValue: boolean { read-only } 1.12 open
CapTransaction: boolean { read-only } 1.12 open
CapTransactionLog: boolean { read-only } 1.12 open
CapUnlockTerminal: boolean { read-only } 1.12 open
CapUpdateKey: boolean { read-only } 1.12 open
CapVoucher: boolean { read-only } 1.12 open
CapWriteValue: boolean { read-only } 1.12 open

AdditionalSecurityInformation: string { read-write } 1.12 open
Amount: currency { read-write } 1.12 open
ApprovalCode: string { read-write } 1.12 open
Balance: currency { read-only } 1.12 open
BalanceOfPoint: currency { read-only } 1.12 open
CardServiceList: string { read-only } 1.12 open
CurrentService: string { read-write } 1.12 open
DetectionControl: boolean { read-write } 1.12 open
DetectionStatus: int32 { read-only } 1.12 open
ExpirationDate: string { read-only } 1.12 open
LastUsedDate: string { read-only } 1.12 open
LogStatus: int32 { read-only } 1.12 open
MediumID: string { read-write } 1.12 open
Point: currency { read-write } 1.12 open
ReaderWriterServiceList: string { read-only } 1.12 open
SequenceNumber: int32 { read-only } 1.12 open

Summary 427
SettledAmount: currency { read-only } 1.12 open

SettledPoint: currency { read-only } 1.12 open
TransactionLog: string { read-only } 1.12 open
VoucherID: string { read-write } 1.12 open
VoucherIDList: string { read-write } 1.12 open

Common
Name Version
close ( ): 1.12
release ( ): 1.12
void { }
void { }
void { }
Specific
Name
accessLog ( sequenceNumber: int32, type: int32, timeout: int32 ): 1.12

activateService ( inout data: int32, inout obj: object ): 1.12

addValue ( sequenceNumber: int32, timeout: int32 ): 1.12
beginDetection ( type: int32, timeout: int32 ): 1.12
cancelValue ( sequenceNumber: int32, timeout: int32 ): 1.12
captureCard ( ): 1.12
endDetection ( ): 1.12
endRemoval ( ): 1.12
enumerateCardServices ( ): 1.12
lockTerminal ( ): 1.12
readValue ( sequenceNumber: int32, timeout: int32 ): 1.12
subtractValue ( sequenceNumber: int32, timeout: int32 ): 1.12
transactionAccess ( control: int32 ): 1.12
unlockTerminal ( ): 1.12
updateKey ( inout data: int32, inout obj: object ): 1.12
writeValue ( sequenceNumber: int32, timeout: int32 ): 1.12

Summary 429


General Information
The Electronic Value Reader / Writer programmatic name is

“ElectronicValueRW”.
This device was introduced in Version 1.12 of the specification.
Electronic value is defined as a collection of services such as electronic money,
points, and voucher/ticket, maintained on a contact-less or contact IC card (this is
referred to as ‘card’ in the following sections). The Electronic Value Reader /
Writer device is a device that offers the capability to hold the settlement addition,
subtraction, setting, and reading electronically.
The electronic money service supports the post-paid type electronic money
settlement, pre-paid type electronic money settlement, the credit card settlement,
and the debit card settlement.
The point service maintains (can add or subtract) points directly on the card.
Alternatively, the points may be stored in another location and only a reference is
maintained on the card.
The voucher/ticket service maintains two or more identifiers that validate the card
holder. The card holder can receive and exchange the value at any time. The
service provider can provide value to the card holder at its discretion.
Capabilities
The Electronic Value R/W has the following set of capabilities:

• Access the card for the settlement.
• Read/write the content of electronic value that can be used for the settlement
from the card.
• Execute the settlement service using electronic value.
• Accumulate the result of the settlement in the device as a log.

Electronic Value R / W Class Diagram

The following diagram shows the relationships between the Electronic Value R/W
classes.
<<utility>> <<Interface>>
UposConst EVRWControl
<<uses>> (from upos)
(from upos)
<<capability>> CapActivateService: boolean

<<capability>> CapAddValue: boolean
<<capability>> CapCancelValue: boolean
<<capability>> CapCardSensor: int32
<<exception>> <<capability>> CapDetectionControl: int32
UposException
<<sends>! <<capability>> CapElectronicMoney: boolean
(from upos) <<capability>> CapEnumerateCardServices: boolean
<<capability>> CapIndirectTransactionLog: boolean
<<capability>> CapLockTerminal: boolean
<<capability>> CapLogStatus: boolean
<<capability>> CapMediumID: boolean
<<capability>> CapPoint: boolean
<<capability>> CapSubtractValue: boolean
<<capability>> CapTransaction: boolean
<<capability>> CapTransactionLog: boolean
<<capability>> CapUnlockTerminal: boolean
<<capability>> CapUpdateKey: boolean
<<event>> <<capability>> CapVoucher: boolean
DataEvent <<capability>> CapWriteValue: boolean
fires
(from upos) <<prop>> AccountNumber: string
<<prop>> AdditionalSecurityInformation: string
<<prop>> Amount: currency
<<prop>> ApprovalCode: string
<<prop>> AsyncMode: boolean
<<prop>> Balance: currency
<<event>>
<<prop>> BalanceOfPoint: currency
DirectIOEvent <<prop>> CardServiceList: string
fires
(from upos) <<prop>> CurrentService: string
<<prop>> DetectionControl: boolean
<<prop>> DetectionStatus: int32
<<prop>> ExpirationDate: string
<<prop>> LastUsedDate: string
<<event>> <<prop>> LogStatus: int32
ErrorEvent <<prop>> MediumID: string
fires <<prop>> Point: currency
(from upos)
<<prop>> ReaderWriterServiceList: string
<<prop>> SequenceNumber: int32
<<prop>> SettledAmount: currency
<<prop>> SettledPoint: currency
<<prop>> TransactionLog: string
<<event>> <<prop>> VoucherID: string
OutputCompleteEvent fires <<prop>> VoucherIDList: string
(from upos)
accessLog ( sequenceNumber: int32, type: int32, timeout: int32 ):void
activateService ( inout data: int32, inout obj: object ):void
addValue ( sequenceNumber: int32, timeout: int32 ):void
beginDetection ( type: int32, timeout: int32 ):void
beginRemoval ( timeout: int32 ):void
<<event>> cancelValue ( sequenceNumber: int32, timeout: int32 ):void
StatusUpdateEvent captureCard ( ):void
fires endDetection ( ):void
(from upos) endRemoval ( ):void
enumerateCardServices ( ):void
lockTerminal ( ):void
readValue ( sequenceNumber: int32, timeout: int32 ):void
subtractValue ( sequenceNumber: int32, timeout: int32 ):void
transactionAccess ( control: int32 ):void
unlockTerminal ( ):void
updateKey ( inout data: int32, inout obj: object ):void
writeValue ( sequenceNumber: int32, timeout: int32 ):void

Model
The Electronic Value Reader Writer supports the following services and methods.
Service
Services Corresponding methods
capabilities
Electronic Balance inquiry readValue method
money Balance property
Payment subtractValue method
Amount property
SettledAmount property
Deposit addValue method
Amount property
SettledAmount property
Cancel cancelValue method
ApprovalCode property
Point Inquiry readValue method

BalanceOfPoint property
Deposit addValue method
Point property
SettledPoint property
Redeem subtractValue method
Point property
SettledPoint property
Updating writeValue method
Point property
Voucher/ Inquiry / readValue method

Ticket Enumeration VoucherID property
VoucherIDList property
Issue addValue method
VoucherID property
Redeem subtractValue method
VoucherID property

The general model of the Electronic Value Reader / Writer is as follows:
Input Model
The readValue method follows the UnifiedPOS Input model.
When the application is ready to receive the data from the Electronic Value Reader
Writer, the readValue method is called. Then, when input data is received, a
DataEvent event is enqueued. When the application sets the DataEventEnabled
property to true, the DataEvent event will be delivered to the application.
If an error occurs while reading the data, an ErrorEvent is enqueued instead of
the DataEvent. When the application sets the DataEventEnabled property to
true, the ErrorEvent event will be delivered to the application.
The application can obtain the number of enqueued data events by reading the
DataCount property.
If AutoDisable is true, then the device is automatically disabled when a
All input data that is queued can be cleared by executing the clearInput method.
Output Model
The accessLog, addValue, cancelValue, subtractValue, transactionAccess,
and writeValue methods can be executed asynchronously or synchronously
depending on the value of the AsyncMode property as defined by the UnifiedPOS
output model.
When AsyncMode is true, methods cannot be issued immediately after issuing a
prior method; only one outstanding asynchronous method is allowed at a time.
However, clearOutput is an exception because its purpose is to cancel an
outstanding asynchronous method.
When asynchronous processing completes, an OutputCompleteEvent is
delivered to the application.
Support of sub-service use
When one Electronic Value Reader Writer provides two or more electronic value
services, and an Electronic Value Reader Writer Service corresponding to each
service provider exists, then they can be used as sub-service.
If the open method is executed, the open method of all sub-services is called, and
the sub-service is enumerated by the ReaderWriterServiceList property. The
close, claim, and release methods operate in the same manner on all the sub-
services.
The application selects the sub-service to be used by setting the CurrentService
property. All method and property operations thereafter effect that sub-service.

Transaction Mode Support

Transaction mode is comprised of multiple method calls and property accesses.
Operations that can be included in the batch processing is a invocation of the
writeValue, addValue, subtractValue, and cancelValue methods and all
properties. When these methods are executed in transaction mode, their validation
is confirmed first. If it is valid, the operation is added to the transaction mode
buffer prior to execution. No update has yet been performed to the card.
Executing the transactionAccess method with a control value of
EVRW_TA_NORMAL will cause all buffered commands to be processed.
The AsyncMode property also influences the execution of the transaction mode.
If the transaction is processed synchronously and an exception is not raised, then
the entire transaction process was successful. If the transaction is processed
asynchronously, then the asynchronous process rules listed above are followed. If
an error occurs and the Error Event handler causes a retry, the entire transaction is
retried.
Device Sharing
The Electronic Value Reader / Writer is an exclusive-use device, as follows:

See the “Summary” table for precise usage prerequisites.

Electronic Value Reader / Writer Sequence Diagram

The following sequence diagram shows the typical usage of the Electronic Value
Reader / Writer device.
Application Device IC chip
open(logicalName)
Initialization. claim(timeout)
getCapDetectionControl()
Confirmation of
device
capability. DETECTION
REMOVAL
APPLICATIONCONTROL
getReaderWriterServiceList()
“ElectronicMoney, Point, Coupon”
setDetectionControl(true)
setAsyncMode(true)
beginDetection
Detection of IC chip
Card detection.
StatusUpdateEvent
DETECTED
endDetection
Confirmation of getCardServiceList()
card’s services.
Selection of
service. “ElectronicMoney, Point”
setCurrentService(“ElectronicMoney”)

The following sequence diagram shows the continuation of the typical usage of the
Electronic Value Reader / Writer device.
Getting readValue
remainder.
Reading the data
DataEvent
getBalance
5000
Starting
transaction transactionAccess(EVRW_TA_TRANSACTION)
access.
setCurrentService(“ElectronicMoney”)
Requesting
settlement.
setAmount(1000)
subtractValue()
setCurrentService(“Point”)
Requesting
add points.
setPoint(10)
addValue()
transactionAccess(EVRW_TA_NORMAL)
Executing
transaction 1000 is settled
access.
10 points are added.
OutputCompleteEvent

The following sequence diagram shows the continuation of the typical usage of the
Electronic Value Reader / Writer device.
beginRemoval
Card IC chip not detected
removal
StatusUpdateEvent
NOCARD
endRemoval
setDeviceEnabled(false)
Terminating. release(timeout)
close()

Electronic Value Reader / Writer State Diagram

The following state diagram depicts the Electronic Value Reader / Writer device
model.

Closed
Detection
open() close()
close()

beginDetection() endDetection() Opened
Removal
claim() release()
beginRemoval() endRemoval()
Claimed

setDeviceEnabled(true) setDeviceEnabled(false)
Enabled
writeValue writeValue
addValue addValue readValue
subtractValue subtractValue
cancelValue cancelValue
accessLog accessLog Done delivering Done delivering
transactionLog transactionAccess
activateService
updateKey
enumerateCardServices
lockTerminal Output Async Mode Input Async Mode
unlockTerminal
captureCard ErrorEvent OutputComplete ErrorEvent DataEvent
processing Event processing processing
Synchronous processing
Mode


AccountNumber Property
Remarks Information for the service provider like the card number, the member number,
etc., to specify the user (owner) is set from the information on the card.
This property is initialized to an empty string (“”) by the open method.
AdditionalSecurityInformation Property
Syntax AdditionalSecurityInformation: string { read-write, access after open }1
Remarks An application can send data to the ElectronicValue R/W device by setting this
property before issuing an authorization method. Also, data obtained from the
ElectronicValue R/W device and not stored in any other property as the result of
an authorization operation can be provided to an application by storing it in this
property. Since the data stored here is device specific, this should not be used for
any development that requires portability.
Amount Property
Syntax Amount: currency { read-write, access after open }
Remarks Holds the payment amount on the electronic money service.
ApprovalCode Property
Syntax ApprovalCode: string { read-write, access after open }
Remarks Holds the payment approval code.
The content of the approval code depends on implementation the device. When a
unique number is issued to the processing done with the device, the information is
set.
This property is set to specify the cancellation of the payment when the device
supports cancellation of the payment and the cancelValue method is executed.

AsyncMode Property
Remarks If true, the writeValue, addValue, subtractValue, cancelValue, accessLog, and
transactionAccess methods will be performed asynchronously.
If false, these methods will be performed synchronously.
Balance Property
Syntax Balance: currency { read-only, access after open }
Remarks Holds the balance on the electronic money service.
BalanceOfPoint Property
Syntax BalanceOfPoint: currency { read-only, access after open }
Remarks Holds the point balance on the point service.
CapActivateService Property
Syntax CapActivateService: boolean { read-only, access after open }
Remarks If true, the activation processing is supported; otherwise it is false.
CapAddValue Property
Syntax CapAddValue: boolean { read-only, access after open }
Remarks If true, the addition of electronic value is supported; otherwise it is false.

CapCancelValue Property
Syntax CapCancelValue: boolean { read-only, access after open }
Remarks If true, the cancellation of the operation to the electronic value is supported;
otherwise it is false.
CapCardSensor Property
Syntax CapCardSensor: int32 { read-only, access after open }
Remarks Contains a bitmask indicating the types of card detection supported. When the
sensor exists, the detection is set to the DetectionStatus property and a
StatusUpdateEvent is delivered.
This property is set to the logical OR of one or more of the following values:
Value Meaning
EVRW_CCS_ENTRY There is an insertion slot sensor.
EVRW_CCS_DETECT There is a card detection sensor.
EVRW_CCS_CAPTURE There is a stock space sensor.
See Also DetectionStatus Property, StatusUpdateEvent.
CapDetectionControl Property
Syntax CapDetectionControl: int32 { read-only, access after open }
Remarks It is shown whether the detection processing of the card, the ejection processing of
the card, the storing processing of the card and these processing can be controlled
from the application or the reader writer.
This property is set to the logical OR of one or more of the following values:
Value Meaning
EVRW_CDC_RWCONTROL Control is possible by the ElectronicValue
R/W device.
EVRW_CDC_APPLICATIONCONTROL
Control is possible by the application.
See Also DetectionControl Property, DetectionStatus Property.

CapElectronicMoney Property
Syntax CapElectronicMoney: boolean { read-only, access after open }
Remarks If true, the electronic money service is supported; otherwise it is false.
CapEnumerateCardServices Property
Syntax CapEnumerateCardServices: boolean { read-only, access after open }
Remarks If true, the enumeration of service in the card is supported; otherwise it is false.
CapIndirectTransactionLog Property
Syntax CapIndirectTransactionLog: boolean { read-only, access after open }
Remarks If true, the transaction log is accessed as a file; otherwise it is false.
CapLockTerminal Property
Syntax CapLockTerminal: boolean { read-only, access after open }
Remarks If true, the security lock setting is supported; otherwise it is false.
See Also lockTerminal Method.
CapLogStatus Property
Syntax CapLogStatus: boolean { read-only, access after open }
Remarks If true, the reporting of the status of the transaction log is supported; otherwise it
is false.

CapMediumID Property
Syntax CapMediumID: boolean { read-only, access after open }
Remarks If true, the specification of the medium identifier is supported; otherwise it is false.
CapPoint Property
Syntax CapPoint: boolean { read-only, access after open }
Remarks If true, the point service is supported otherwise it is false.
CapSubtractValue Property
Syntax CapSubtractValue: boolean { read-only, access after open }
Remarks If true, the subtraction of electronic value is supported; otherwise it is false.
CapTransaction Property
Syntax CapTransaction: boolean { read-only, access after open }
Remarks If true, the transaction mode is supported; otherwise it is false.
CapTransactionLog Property
Syntax CapTransactionLog: boolean { read-only, access after open }
Remarks If true, the transaction log is supported; otherwise it is false.

CapUnlockTerminal Property
Syntax CapUnlockTerminal: boolean { read-only, access after open }
Remarks If true, releasing of the security lock is supported; otherwise it is false.
See Also unlockTerminal Method.
CapUpdateKey Property
Syntax CapUpdateKey: boolean { read-only, access after open }
Remarks If true, the update of key information is supported; otherwise it is false.
CapVoucher Property
Syntax CapVoucher: boolean { read-only, access after open }
Remarks If true, the voucher/ticket service is supported; otherwise it is false.
CapWriteValue Property
Syntax CapWriteValue: boolean { read-only, access after open }
Remarks If true, the writing of electronic value is supported; otherwise it is false.
CardServiceList Property
Syntax CardServiceList: string { read-only, access after open }
Remarks Holds the comma-separated (CSV) list of services supported by the card. This list
is populated by the enumerateCardServices method.
For example, when the character string that identifies A electronic money service
is “MoneyA” and the character string that identifies B electronic point service is
“PointB”, the CardServiceList property becomes “MoneyA,PointB”.
See Also enumerateCardServices Method.

CurrentService Property
Syntax CurrentService: string { read-write, access after open }
Remarks Holds the character string that identifies the currently selected service. This value
is guaranteed to be one of the set of services specified by the
ReaderWriterServiceList property.
The character string being enumerated by the ReaderWriterServiceList property
can be set.
If an empty string (“”) is set, it enters the state that no service has been selected. In
this state, depending on the device, an application can operate directly to the
device.
When a valid string is set, the service is selected and started.
If the service supports the sub-service, the execution of the method and the setting
of property are done to the sub-service of the service that property shows. And
only the event fires from the sub-service which is selected by this property.
See Also ReaderWriterServiceList Property.
DetectionControl Property
Syntax DetectionControl: boolean { read-write, access after open }
Remarks If true, the detection processing of the card by the beginDetection/endDetection
methods and the card ejection processing by the beginRemoval/endRemoval
methods are controlled by the application.
This property can only be set true by the application when CapDetectionControl
is set to EVRW_CDC_APPLICATIONCONTROL.
If false, neither detection nor the ejection processing of the card are controlled
from the application. Invocation of the beginDetection/endDetection methods
and the beginRemoval/endRemoval methods from the application is invalid.
When EVRW_CDC_RWCONTROL is specified for the CapDetectionControl
property, it is possible to set it.
See Also CapDetectionControl Property, beginDetection Method, beginRemoval
Method, endDetection Method, endRemoval Method.

DetectionStatus Property
Syntax DetectionStatus: int32 { read-only, access after open }
Remarks Holds the state of card detection.
Value Meaning
EVRW_DS_NOCARD No card. The card detection sensor does not
detect a card.
EVRW_DS_DETECTED There is a card in the device. The card
detection sensor detects the card.
EVRW_DS_ENTERED Card remaining at the insertion slot. The
insertion slot sensor detects the card.
EVRW_DS_CAPTURED The card is in the stock space. The stock
space sensor detects the card.
This property is initialized to EVRW_DS_NOCARD by the open method.
ExpirationDate Property
Syntax ExpirationDate: string { read-only, access after open }
Remarks Holds the expiration date in the format “YYYYMMDD”.
LastUsedDate Property
Syntax LastUsedDate: string { read-only, access after open }
Remarks Holds the last used date in the format “YYYYMMDDHHMMSS”.
LogStatus Property
Syntax LogStatus: int32 { read-only, access after open }
Remarks Holds the state of transaction log.
Value Meaning
EVRW_LS_OK Transaction Log has enough capacity.
EVRW_LS_NEARFULL Transaction Log is nearly full.
EVRW_LS_FULL Transaction Log is full.
If transaction log becomes full, depending on the device, the settlement processing
may not be able to operate.
After this property is initialized, it is kept current as long as the device is enabled.

MediumID Property
Syntax MediumID: string { read-write, access after open }
Remarks Holds the medium identifier of the card.
The medium identifier is information (manufacturer’s serial number, etc.) to
specify the card uniquely, and its content depends on implementation for the card.
The following methods are processed to the card with the medium identifier
specified by this property:
• addValue
• beginDetection
• cancelValue
• readValue
• subtractValue
• writeValue
The application can specify the card to be operated on by setting the medium
identifier to this property before the method call is issued. Setting an empty string
(“”) for this property means the operation can be performed with any card.
The medium identifier of the card is set when the method that have relation to the
card succeeds.
See Also addValue Method, beginDetection Method, cancelValue Method, readValue
Method, subtractValue Method, writeValue Method.
Point Property
Syntax Point: currency { read-write, access after open }
Remarks Holds the settlement point on the point service.
ReaderWriterServiceList Property
Syntax ReaderWriterServiceList: string { read-only, access after open }
Remarks Holds the comma-separated list of services that are supported by the
ElectronicValue R/W device.
For example, when the character string that identifies ‘A’ electronic money service
is “MoneyA” and the character string that identifies ‘B’ electronic point service is
“PointB”, the ReaderWriterServiceList property becomes “MoneyA,PointB”.
If the service supports the sub-service, the open method succeeds, the service that
all the sub-services provides is enumerated.
If the ElectronicValue R/W service does not support the sub-service and an
ElectronicValue R/W service supports many services, those services are
enumerated by this property.
This property is initialized by the open method. The initialization value depends
on what services are supported; e.g., if the ElectronicValue R/W device supports
“MoneyA” and “PointB” services, this property is initialized to “MoneyA,
PointB”.

SequenceNumber Property
Syntax SequenceNumber: int32 { read-only, access after open }
Remarks Holds a “sequence number” as the result of each method call. This number needs
to be checked by an application to see if it matches with the argument
sequenceNumber of the originating method.
SettledAmount Property
Syntax SettledAmount: currency { read-only, access after open }
Remarks Sets the real amount of the settlement on the electronic money service.
SettledPoint Property
Syntax SettledPoint: currency { read-only, access after open }
Remarks Sets the settlement point on the point service.
TransactionLog Property
Syntax TransactionLog: string { read-only, access after open }
Remarks Stores the result of the accessLog method.
If the CapIndirectTransactionLog property is true, the TransactionLog
property shows URL that shows the position such as files where the transaction log
is stored.
The content of the transaction log depends on the device and service.
See Also CapIndirectTransactionLog Property, TransactionLog property, accessLog
method.

VoucherID Property
Syntax VoucherID: string { read-write, access after open }
Remarks Sets the ID of voucher/ticket on the voucher/ticket service.
It consists of pairs of the identifier and the number which validate the card holder.
For example, six tickets of identifier “001” are shown by the character string
“001:6”. The “:” is a separator between the identifier and the number of sheets.
VoucherIDList Property
Syntax VoucherIDList: string { read-write, access after open }
Remarks Sets the IDs of voucher/ticket are enumerated on the voucher/ticket service.
If six tickets of identifier “001”, one ticket of identifier “002”, two tickets of
identifier “034” are maintained, this is expressed by the CSV character string in
the format “001:6,002:1,034:2”. The “,” is a separator when two or more rights are
maintained.


accessLog Method
Syntax accessLog ( sequenceNumber: int32, type: int32, timeout: int32 ):
sequenceNumber The sequence number to get transaction log.
type Specifies whether the transaction log is intermediate
total or the last total. (see values below)
response is received from the device. FOREVER(-1), 0,
and positive values can be specified.
Remarks Gets transaction log from device.
Gets transaction log on demand by sequenceNumber, and it is stored in the
TransactionLog property.
When timeout is FOREVER(-1), a timeout never occurs and it waits indefinitely
until it receives a response from the device.
If ElectronicValue R/W device needs the last total processing of a transaction, it
performs this method.
The last total processing might be cleared in the transaction log, this depends on
the implementation. However, the intermediate total must not be cleared in the
transaction log.
It depends on the implementation if the transaction log will be passed to the service
center directly and not to the application.
The application must specify one of the following values for type of transaction
(either intermediate total or the last total).
Value Meaning
EVRW_AL_REPORTING
Gets transaction log as an intermediate total.
EVRW_AL_SETTLEMENT
The transaction log for the device is fixed and erased.
(Whether it is erased or not depends on the
implementation.)
Value Meaning
E_ILLEGAL Invalid type or timeout parameter was specified. Or
transaction log function is unsupported.
E_TIMEOUT No response was received from device during the
specified timeout (in milliseconds).
E_BUSY The device can not accept any commands while
asynchronously processing.
See Also TransactionLog Property.

activateService Method
Syntax activateService ( inout data: int32, inout obj: object ):
Remarks Executes the device activation process.
If the device has the activation process function, it is supported.
The activation process is initialization or installation of device. The details of
process contents and parameters depend on implementation.
Value Meaning
E_ILLEGAL The device does not have the activation.
E_BUSY The device can not accept any commands now.
See Also CapActivateService Property.
addValue Method
Syntax addValue ( sequenceNumber: int32, timeout: int32 ):
sequenceNumber Sequence number
Remarks Electronic value is added to the card as specified by sequenceNumber on demand.
When timeout is FOREVER(-1), timeout never occurs and it waits indefinitely
Value Meaning
E_ILLEGAL Invalid or unsupported parameter was specified.
specified Timeout in milliseconds.
See Also CapAddValue Property, cancelValue Method, readValue Method,
subtractValue Method, writeValue Method.

beginDetection Method
Syntax beginDetection ( type: int32, timeout: int32 ):
Executes the card detection process.
If the timeout parameter value is zero, the method initiates the detection mode
immediately. If a value is set (in milliseconds), the card detection process will wait
for this time period if necessary. If a value of FOREVER(-1) is specified, the
method initiates the card detection process and then waits as long as necessary
until either the card is detected or an error occurs.
The type parameter specifies the type of the detected card. The value that can be
specified is as follows:
Value Meaning
EVRW_BD_ANY The content of the detected card can be anything.
EVRW_BD_SPECIFIC When this method is called, only the card that
corresponds to the identifier in the MediumID property
can be detected.
Remarks Starts the card detection process in the device slot.
Supports the both contactless and contact IC card devices.
When called, the device starts a card detection process, and initiates the card
detection in the device. This method is called together with the endDetection
method that ends the card detection process.
If the device cannot be set to the detection process, an error exception will be fired
such as E_TIMEOUT. However, the device stays in the detection mode until the
endDetection method is called.
Value Meaning
E_BUSY Can not execute while asynchronous processing.
E_TIMEOUT The specified timeout has elapsed without the card being
properly detected.
See Also MediumID Property, endDetection Method.

beginRemoval Method
Executes the removal process
If the timeout parameter value is zero, the method initiated the detection mode
immediately. If its value is set (milliseconds), the card detection process will be
wait until time is due. If its value is FOREVER(-1), the method initiates the card
removal process and then waits as long as necessary until either the card is
Remarks Starts the card ejection process.
If the device is a contactless IC card device, when this method is called, device
starts the card ejection process and ejects the card and this method ends
successfully at any time.
If the device is a contact IC card device with card detection sensor, this method
completes when card ejection was detected.
If the device is a contact IC card device without card detection sensor, this method
completes when this method is executed.
This method is called together with the endRemoval method that ends the card
ejection process.
If the device cannot be set to the card ejection mode, an error exception will be
fired, e.g., E_TIMEOUT. However, the device will remain in card ejection mode
until endRemoval method is called.
Value Meaning
E_BUSY Can not execute while asynchronous processing.
E_TIMEOUT The specified timeout has elapsed without the card being
properly removed.
See Also endRemoval Method.

cancelValue Method
Syntax cancelValue ( sequenceNumber: int32, timeout: int32 ):
Remarks Cancels the Electronic value related operation specified by sequenceNumber on
demand. The targeted cancellation operation is identified by the settlement number
that is contained in the ApprovalCode property.
Value Meaning
specified timeout in milliseconds.
See Also ApprovalCode Property, CapCancelValue Property, addValue Method,
readValue Method, subtractValue Method, writeValue Method.
captureCard Method
Syntax captureCard ( ):
Remarks The card left in the slot is removed.
This method is effective, if the device is equipped with a card detection sensor.
When the card insertion slot sensor detects the card, since the card ejection process
was executed, application may call this method to keep and maintain the card.
Value Meaning
E_FAILURE The device can not capture the card.
See Also DetectionStatus Property.

endDetection Method
Syntax endDetection ( ):
Remarks Ends the card detection process.
When called, the device ends card detection mode. If the card is correctly detected
in the device control is returned to the application. If the card cannot be detected
an exception is delivered with its ErrorCodeExtended property set to
EVRW_NOCARD.
This method is called together with the beginDetection method.
Value Meaning
E_ILLEGAL The device is not in card detection mode.
E_EXTENDED ErrorCodeExtended=EVRW_NOCARD:
No card has been detected.
See Also beginDetection Method.
endRemoval Method
Remarks Ends the card removal process.
When called, the device ends the card removal mode. If the card is not detected in
the device, control is returned to the application. If the card remains in the device,
an exception is delivered with its ErrorCodeExtended property set to
EVRW_RELEASE. If the device is contactless IC card, it is not necessary to
implement this and control is always returned to the application without any
exceptions.
This method is called together with the beginRemoval method for the card
removal processing.
Value Meaning
E_ILLEGAL The device is not in card removal mode.
E_EXTENDED ErrorCodeExtended=EVRW_RELEASE:
The card remains in the device.
See Also beginRemoval Method.

enumerateCardServices Method
Syntax enumerateCardServices ( ):
Remarks Enumerates the services which are used in the card and sets the CardServiceList
property.
See Also CardServiceList Property.
lockTerminal Method
Syntax lockTerminal ( ):
Remarks Sets the security lock. If the device is locked, the device cannot accept any
commands.
AdditionalSecurityInformation property is set if key information is required to
lock for the authentication.
Value Meaning
E_ILLEGAL The device does not have a security lock function.
CapLockTerminal is false.
See Also AdditionalSecurityInformation Property, CapLockTerminal Property.
readValue Method
Syntax readValue ( sequenceNumber: int32, timeout: int32 ):
Remarks Reads the electronic value from the card.
Electronic value is read from the card specified by sequenceNumber on demand.
When timeout is FOREVER(-1), a timeout never occurs and the Service waits
indefinitely until it receives a response from the device.

Value Meaning
specified Timeout in milliseconds.
See Also addValue Method, cancelValue Method, subtractValue Method, writeValue
Method.
subtractValue Method
Syntax subtractValue ( sequenceNumber: int32, timeout: int32 ):
Remarks Subtracts the electronic value from the card.
Electronic value is subtracted from the card specified by sequenceNumber on
demand.
When timeout is FOREVER(-1), timeout never occurs and the Service waits
indefinitely until it receives a response from the device.
Value Meaning
See Also CapSubtractValue Property, addValue Method, cancelValue Method,
readValue Method, writeValue Method.
transactionAccess Method
Syntax transactionAccess ( control: int32 ):
control The transaction control, can be set to one of the
following values:

Value Meaning
EVRW_TA_TRANSACTION Begin a transaction
EVRW_TA_NORMAL End the transaction mode by executing the
buffer operation.
Remarks Enters or exits transaction mode.
If control is EVRW_TA_TRANSACTION, then transaction mode is entered.
Subsequent calls to readValue, writeValue, addValue, subtractValue, and
cancelValue will buffer the data until transactionAccess is called with the control
parameter set to EVRW_TA_NORMAL. It depends on the implementation if
buffering is done in the ElectronicValue R/W device or buffering is done within
the Service.
If control is EVRW_TA_NORMAL, then transaction mode is exited. If some
requests were buffered by calls to the methods readValue, writeValue,
addValue, subtractValue, and cancelValue, then the buffered requests will be
executed.
The entire transaction requests are treated as one message. This method is
performed synchronously if AsyncMode is false, and asynchronously if
AsyncMode is true.
Calling the clearOutput method cancels transaction mode. Any buffered print
lines are also cleared.
See Also AsyncMode Property, CapTransaction Property, addValue Method,
cancelValue Method, readValue Method, subtractValue Method, writeValue
Method.
unlockTerminal Method
Syntax unlockTerminal ( ):
Remarks Releases the security lock.
When the device has a security lock function, it is supported.
AdditionalSecurityInformation property is set when key information is required
to release the lock.
Value Meaning
E_ILLEGAL The device does not have a security lock function.
CapUnlockTerminal is false.
See Also AdditionalSecurityInformation Property, CapUnlockTerminal Property.

updateKey Method
Syntax updateKey ( inout data: int32, inout obj: object ):
Remarks Updates the key information in the device.
If the device has the function to the key information, it is supported.
The content of processing and the content of the parameter depend on the
implementation.
Value Meaning
E_ILLEGAL The device does not have the update function of key
information.
See Also ...
writeValue Method
Syntax writeValue ( sequenceNumber: int32, timeout: int32 ):
Remarks Writes the electronic value in the card.
Electronic value is written in the card specified by sequenceNumber on demand.
Value Meaning
See Also CapWriteValue Property, addValue Method, cancelValue Method, readValue
Method, subtractValue Method.


DataEvent
Description Notifies the application about the available input data from the device.
Remarks Before this event is delivered, the data is set into the appropriate property.
DirectIOEvent
means for a vendor-specific Electronic Value Reader / Writer Service to provide
events to the application that are not otherwise supported by the Control.
Service.
from being used with other vendor’s Electronic Value Reader / Writer devices
which may not have any knowledge of the Service’s need for this event.

ErrorEvent
Description Notifies the application that an ElectronicValue R/W error has been detected and
a suitable response by the application is necessary to process the error condition.
Codes on page 52.
ErrorCodeExtended
values below.
following values:
Value Meaning
EVRW_CENTERERROR
An error was returned from the approval agency.
EVRW_COMMANDERROR
The command sent to the device is wrong. This error is
never returned so long as device control is working
correctly.
EVRW_RESET The device was stopped during processing by device
reset key (stop key) and so on.
EVRW_COMMUNICATIONERROR
Communication error has occurred between the
approval agency (center) and device.
EVRW_LOGOVERFLOW
Transaction log was too big to be stored. Getting
transaction log has been stopped and the value of
TransactionLog is uncertain.
EVRW_DAILYLOGOVERFLOW
Try to processing, a failure will occur if the transaction
log on the device is full and cannot be settle.
EVRW_DEFICIENT Because the balance is insufficient, it cannot be
subtracted.
EVRW_OVERDEPOSIT
Because the amount that was able to be charged was
exceeded, it cannot be added.


Value Meaning
available.
available.
Value Meaning
ER_CONTINUEINPUT
EL_INPUT_DATA.
Remarks Notifies when the error is detected when a method is asynchronously executed,
and the state of the control moves to the error state.
Input error events are generated when errors occur while reading the data from a
card, directed by readValue method. These error events are not delivered until
the DataEventEnabled property is set to true so as to allow proper application
this event is delivered.
Output error events are generated and delivered when errors occur during
asynchronous output processing. The errors are placed into the applicable
properties before the events are delivered.

OutputCompleteEvent
Description Notifies the application that the queued asynchronous output request associated
with the OutputID attribute has completed successfully.
is complete.

StatusUpdateEvent
Description Notifies the application when the device detects a status change.

Status int32 The status condition of the Electronic Value Reader /
Writer.
Value Description
EVRW_SUE_LS_OK The transaction log has enough capacity.
EVRW_SUE_LS_NEARFULL
The transaction log is nearly full.
EVRW_SUE_LS_FULL The transaction log is full.
EVRW_SUE_DS_NOCARD
The card detection sensor does not detect the card.
EVRW_SUE_DS_DETECTED
The card detection sensor detected the card.
EVRW_SUE_DS_ENTERED
The insertion slot sensor detected the card.
EVRW_SUE_DS_CAPTURED
The stock space sensor detected the card.

process.
Remarks This event is enqueued when a Electronic Value Reader / Writer detection
undergoes a change or if Power State Reporting is enabled and a change in the
power state is detected.
The state of the transaction log is reported only if CapLogStatus is true.
See Also CapLogStatus Property, LogStatus Property, “Events” on page 51.

C H A P T E R 1 5
Fiscal Printer
This Chapter defines the Fiscal Printer device category.
Summary


466 Fiscal Printer
CapAdditionalHeader: boolean { read-only } 1.6 open
CapAdditionalLines: boolean { read-only } 1.3 open
CapAdditionalTrailer: boolean { read-only } 1.6 open
CapAmountAdjustment: boolean { read-only } 1.3 open
CapAmountNotPaid: boolean { read-only } 1.3 Deprecated v1.11
CapChangeDue: boolean { read-only } 1.6 open
CapCheckTotal: boolean { read-only } 1.3 open
CapCoverSensor: (1) boolean { read-only } 1.3 open
CapDoubleWidth: boolean { read-only } 1.3 open
CapDuplicateReceipt: boolean { read-only } 1.3 open
CapEmptyReceiptIsVoidable: boolean { read-only } 1.6 open
CapFiscalReceiptStation: boolean { read-only } 1.6 open
CapFiscalReceiptType: boolean { read-only } 1.6 open
CapFixedOutput: boolean { read-only } 1.3 open
CapHasVatTable: boolean { read-only } 1.3 open
CapIndependentHeader: boolean { read-only } 1.3 open
CapItemList: boolean { read-only } 1.3 open
CapJrnEmptySensor: (1) boolean { read-only } 1.3 open

CapJrnNearEndSensor: (1) boolean { read-only } 1.3 open
CapJrnPresent: (1) boolean { read-only } 1.3 open
CapMultiContractor: boolean { read-only } 1.6 open

CapNonFiscalMode: boolean { read-only } 1.3 open
CapOnlyVoidLastItem: boolean { read-only } 1.6 open
CapOrderAdjustmentFirst: boolean { read-only } 1.3 open
CapPackageAdjustment: boolean { read-only } 1.6 open
CapPercentAdjustment: boolean { read-only } 1.3 open
CapPositiveAdjustment: boolean { read-only } 1.3 open
CapPositiveSubtotalAdjustment boolean { read-only } 1.11 open
CapPostPreLine: boolean { read-only } 1.6 open
CapPowerLossReport: boolean { read-only } 1.3 open
CapPredefinedPaymentLines: boolean { read-only } 1.3 open
CapReceiptNotPaid: boolean { read-only } 1.3 open
CapRecEmptySensor: (1) boolean { read-only } 1.3 open

CapRecNearEndSensor: (1) boolean { read-only } 1.3 open
CapRecPresent: (1) boolean { read-only } 1.3 open

Summary 467
Specific (continued) Type Mutability Version May Use After
CapRemainingFiscalMemory: boolean { read-only } 1.3 open
CapReservedWord: boolean { read-only } 1.3 open
CapSetCurrency: boolean { read-only } 1.6 open
CapSetHeader: boolean { read-only } 1.3 open
CapSetPOSID: boolean { read-only } 1.3 open
CapSetStoreFiscalID: boolean { read-only } 1.3 open
CapSetTrailer: boolean { read-only } 1.3 open
CapSetVatTable: boolean { read-only } 1.3 open
CapSlpEmptySensor: (1) boolean { read-only } 1.3 open

CapSlpFiscalDocument: boolean { read-only } 1.3 open
CapSlpFullSlip: (1) boolean { read-only } 1.3 open
CapSlpNearEndSensor: (1) boolean { read-only } 1.3 open
CapSlpPresent: (1) boolean { read-only } 1.3 open
CapSlpValidation: boolean { read-only } 1.3 open
CapSubAmountAdjustment: boolean { read-only } 1.3 open
CapSubPercentAdjustment: boolean { read-only } 1.3 open
CapSubtotal: boolean { read-only } 1.3 open
CapTotalizerType: boolean { read-only } 1.6 open
CapTrainingMode: boolean { read-only } 1.3 open
CapValidateJournal: boolean { read-only } 1.3 open
CapXReport: boolean { read-only } 1.3 open
ActualCurrency: int32 { read-only } 1.6 open, claim, & enable

AdditionalHeader: string { read-write } 1.6 open, claim, & enable
AdditionalTrailer: string { read-write } 1.6 open, claim, & enable
AmountDecimalPlaces: int32 { read-only } 1.3 open, claim, & enable
ChangeDue: string { read-write } 1.6 open
CheckTotal: boolean { read-write } 1.3 open
ContractorId: int32 { read-write } 1.6 open, claim, & enable
CountryCode: int32 { read-only } 1.3 open, claim, & enable
CoverOpen: (1) boolean { read-only } 1.3 open, claim, & enable
DateType: int32 { read-write } 1.6 open, claim, & enable
DayOpened: boolean { read-only } 1.3 open, claim, & enable
DescriptionLength: int32 { read-only } 1.3 open
DuplicateReceipt: boolean { read-write } 1.3 open
ErrorLevel: int32 { read-only } 1.3 open

468 Fiscal Printer
ErrorOutID: int32 { read-only } 1.3 open, claim, & enable
ErrorState: int32 { read-only } 1.3 open
ErrorStation: int32 { read-only } 1.3 open
FiscalReceiptStation: int32 { read-write } 1.6 open, claim, & enable
FiscalReceiptType: int32 { read-write } 1.6 open, claim, & enable
FlagWhenIdle: (1) boolean { read-write } 1.3 open
JrnEmpty: boolean { read-only } 1.3 open, claim, & enable

JrnNearEnd: boolean { read-only } 1.3 open, claim, & enable
MessageLength: int32 { read-only } 1.3 open

MessageType: int32 { read-write } 1.6 open
NumHeaderLines: int32 { read-only } 1.3 open
NumTrailerLines: int32 { read-only } 1.3 open
NumVatRates: int32 { read-only } 1.3 open
PostLine: string { read-write } 1.6 open, claim, & enable
PredefinedPaymentLines: string { read-only } 1.3 open
PreLine: string { read-write } 1.6 open, claim, & enable
PrinterState: int32 { read-only } 1.3 open, claim, & enable
QuantityDecimalPlaces: int32 { read-only } 1.3 open, claim, & enable

QuantityLength: int32 { read-only } 1.3 open, claim, & enable
RecEmpty: (1) boolean { read-only } 1.3 open, claim, & enable

RecNearEnd: (1) boolean { read-only } 1.3 open, claim, & enable
RemainingFiscalMemory: int32 { read-only } 1.3 open, claim, & enable

ReservedWord: string { read-only } 1.3 open
SlpEmpty: (1) boolean { read-only } 1.3 open, claim, & enable

SlpNearEnd: (1) boolean { read-only } 1.3 open, claim, & enable
SlipSelection: int32 { read-write } 1.3 open, claim, & enable

TotalizerType: int32 { read-write } 1.6 open, claim, & enable
TrainingModeActive: boolean { read-only } 1.3 open, claim, & enable

Summary 469

Common
Name Version
close ( ): 1.3
release ( ): 1.3
clearInput ( ): Not
void { } supported
void { } supported
Specific - Presetting Fiscal

setCurrency ( newCurrency: int32 ): 1.6
setDate ( date: string ): 1.3
setHeaderLine ( lineNumber: int32, text: string, doubleWidth: boolean ): 1.3
setPOSID ( POSID: string, cashierID: string ): 1.3
setStoreFiscalID ( ID: string ): 1.3
setTrailerLine ( lineNumber: int32, text: string, doubleWidth: boolean ): 1.3
setVatTable ( ): 1.3

470 Fiscal Printer
Specific - Fiscal Receipt

setVatValue ( vatID: int32, vatValue: string ): 1.3
beginFiscalReceipt ( printHeader: boolean ): 1.3
endFiscalReceipt ( printHeader: boolean ): 1.3
printDuplicateReceipt ( ): 1.3
printRecCash ( amount: currency ): 1.6
printRecItem ( description: string, price: currency, quantity: int32, 1.3
vatInfo: int32, unitPrice: currency, unitName: string ):
printRecItemVoid ( description: string, price: currency, quantity: int32, 1.11
printRecItemAdjustment ( adjustmentType: int32, description: string, 1.3
amount: currency, vatInfo: int32 ):
printRecItemAdjustmentVoid ( adjustmentType: int32, description: string, 1.11
printRecItemFuel ( description: string, price: currency, quantity: int32, 1.6
vatInfo: int32, unitPrice: currency, unitName: string,
specialTax: currency, specialTaxName: string ):
printRecItemFuelVoid ( description: string, price: currency, vatInfo: int32, 1.6
specialTax: currency ):
printRecItemRefund ( description: string, amount: currency, quantity: int32, 1.12
vatInfo: int32, unitAmount: currency, unitName: string ):
printRecItemRefundVoid ( description: string, amount: currency, quantity: 1.12
int32, vatInfo: int32, unitAmount: currency, unitName: string ):
printRecMessage ( message: string ): 1.3
printRecNotPaid ( description: string, amount: currency ): 1.3
printRecPackageAdjustment ( adjustmentType: int32, description: string, 1.6
vatAdjustment: string ):
printRecPackageAdjustVoid ( adjustmentType: int32, 1.6
printRecRefund ( description: string, amount: currency, vatInfo: int32 ): 1.3
printRecRefundVoid ( description: string, amount: currency, vatInfo: int32 ): 1.6

Summary 471
printRecSubtotal ( amount: currency ): 1.3

printRecSubtotalAdjustment ( adjustmentType: int32, description: string, 1.3
amount: currency ):
printRecSubtotalAdjustVoid ( adjustmentType: int32, amount: currency ): 1.6
printRecTaxID ( taxId: string ): 1.6
printRecTotal ( total: currency, payment: currency, description: string ): 1.3
printRecVoid ( description: string ): 1.3
printRecVoidItem ( description: string, amount: currency, quantity: int32, 1.3
adjustmentType: int32, adjustment: currency, vatInfo: int32 ): Deprecated
void { raises-exception, use after open, claim, enable } v1.11
Specific - Fiscal Document

beginFiscalDocument ( documentAmount: int32 ): 1.3
endFiscalDocument ( ): 1.3
printFiscalDocumentLine ( documentLine: string ): 1.3
Specific - Item Lists

beginItemList ( vatID: int32 ): 1.3
endItemList ( ): 1.3
verifyItem ( itemName: string, vatID: int32 ): 1.3
Specific - Fiscal Reports

printPeriodicTotalsReport ( date1: string, date2: string ): 1.3
printPowerLossReport ( ): 1.3
printReport ( reportType: int32, startNum: string, endNum: string ): 1.3
printXReport ( ): 1.3
printZReport ( ): 1.3

472 Fiscal Printer
Specific - Slip Insertion

void { raises-exception, use after open, claim, enable } (1)
endRemoval ( ): 1.3
Specific - Non-Fiscal
beginFixedOutput ( station: int32, documentType: int32 ): 1.3
beginNonFiscal ( ): 1.3
beginTraining ( ): 1.3
endFixedOutput ( ): 1.3
endNonFiscal ( ): 1.3
endTraining ( ): 1.3
printFixedOutput ( documentType: int32, lineNumber: int32, data: string ): 1.3
printNormal ( station: int32, data: string ): 1.3
Specific - Data Requests

getData ( dataItem: int32, inout optArgs: int32, inout data: string ): 1.3
getDate ( inout date: string ): 1.3
getTotalizer ( vatID: int32, optArgs: int32, inout data: string ): 1.3
getVatEntry ( vatID: int32, optArgs: int32, inout vatRate: int32 ): 1.3
Specific - Error Corrections

clearError ( ): 1.3
resetPrinter ( ): 1.3

Summary 473

Note:
(1) Properties and methods marked with (1) are adapted from the POS Printer
device.

474 Fiscal Printer
General Information
The Fiscal Printer programmatic name is “FiscalPrinter”.
The Fiscal Printer Control does not attempt to encapsulate a generic graphics
printer. Rather, for performance and ease of use considerations, the interfaces are
defined to directly control the normal printer functions.
Since fiscal rules differ between countries, this interface tries to generalize the
common requirements at the maximum extent specifications. This interface is
based upon the fiscal requirements of the following countries, but it may fit the
needs of other countries as well:
• Brazil
• Bulgaria
• Greece
• Hungary
• Italy
• Poland
• Romania
• Russia
• Turkey
• Czech Republic
• Ukraine
• Sweden
The Fiscal Printer model defines three stations with the following general uses:
• Journal Used for simple text to log transaction and activity information. Kept
by the store for audit and other purposes.
• Receipt Used to print transaction information. It is mandatory to give a
printed fiscal receipt to the customer. Also often used for store reports.
Contains either a knife to cut the paper between transactions, or a tear bar to
manually cut the paper.
• Slip Used to print information on a form. Usually given to the customer.
The Slip station is also used to print “validation” information on a form. The
form type is typically a check or credit card slip.
It may also be used to print complete transaction information instead of
printing it on the receipt station.
Sometimes, limited forms-handling capability is integrated with the receipt or

journal station to permit validation printing. Often this limits the number of print
lines, due to the station’s forms-handling throat depth. The Fiscal Printer Control
nevertheless addresses this printer functionality as a slip station.
Configuration and initialization of the fiscal memory of the Fiscal Printer are not
covered in this specification. These low-level operations must be performed by
authorized technical assistance personnel.

Fiscal Printer Class Diagram
The following diagram shows the relationships between the Fiscal Printer classes.
< < e ve nt> > < < e x ce ption> > < < Inte rfa ce > > < < use s> > < < utility> >
Da ta Eve nt UposEx ce pti on Ba se Control UposConst
(f rom e ve nts) (from upos) (from upos) (from upos)
< < prop> > S ta tus : int32
< < se nds> >
fire s
< < e ve nt> >
Di re ctIO Eve nt
(from e ve nts) < < se nds> > < < utility> >
< < use s> >
< < prop> > Eve ntNum be r : int32 Fisca lP rinte rConst
fire s
< < prop> > Da ta : int32 < < Inte r fa ce > > (from upos)
< < prop> > Obj : obje ct Fisc a lP ri nte rControl
(from upos)
fire s
< < e ve nt> >

ErrorEve nt
(from e ve nts)
< < prop> > ErrorCode : int32
< < prop> > Error Code Ex te nde d : i nt32
fire s fire s
< < prop> > Error Locus : int3 2
< < prop> > Error Re sponse : i nt3 2
< < e ve nt> > < < e ve nt> >

O utputComp le te Eve nt S ta tusUpda te Eve nt
(from e ve nts) (from e ve nts)
< < prop> > OutputID : int32 < < prop> > S ta tus : int32

476 Fiscal Printer
General Requirements
Fiscal Printers do not simply print text similar to standard printers. They are used
to monitor and memorize all fiscal information about a sale transaction. A Fiscal
Printer has to accumulate totals, discounts, number of canceled receipts, taxes, etc.
and has to store this information in different totalizers, counters and the fiscal
memory. In order to perform these functions, it is not sufficient to send
unformatted strings of text to the Fiscal Printer; there is a need to separate each
individual field in a receipt line item, thus differentiating between descriptions,
prices and discounts. Moreover, it is necessary to define different printing
commands for each different sale functionality (such as refund, item or void).
Fiscal rules are different among countries. This interface tries to generalize these
requirements by summarizing the common requirements. Fiscal law requires that:
• Fiscal receipts must be printed and given to the customer.
• Fiscal Printers must be equipped with memory to store daily totals. Each
receipt line item must increment totals registers and, in most countries
(Greece, Poland, Brazil, Hungary, Romania, Bulgaria, Russia and Turkey) tax
registers as well.
• Discounts, canceled items and canceled receipts must increment their
associated registers on the Fiscal Printer.
• Fiscal Printer must include a clock to store date and time information relative
to each single receipt.
• Each fiscal receipt line item is normally printed both on the receipt and on the
journal (Italy, Greece, Poland), but as an extension it can also be printed on
the slip and journal.
• After a power failure (or a power off) the Fiscal Printer must be in the same
state as it was before this event occurred. This implies that care must be taken
in managing the Fiscal Printer status and that power failure events must be
managed by the application. In some countries, a power failure must be logged
and a report must be printed.

Fiscal Printer Modes
According to fiscal rules, it is possible for a Fiscal Printer to also offer

functionality beyond the required fiscal printing mode. These additional modes are
optional and may or may not be present on any particular Fiscal Printer.
There are three possible Fiscal Printer modes:
• Fiscal: This is the only required mode for a Fiscal Printer. In this mode the
application has access to all the methods needed to manage a sale transaction
and to print a fiscal receipt. It is assumed that any lines printed to the receipt
station while in fiscal mode are also printed on the journal station.
• Training: In this mode, the Fiscal Printer is used for training purposes (such
as cashier training). In this mode, the Fiscal Printer will accept fiscal
commands but the Fiscal Printer will indicate on each receipt or document that
the transaction is not an actual fiscal transaction. The Fiscal Printer will not
update any of its internal fiscal registers while in training mode. Such printed
receipts are usually marked as “training” receipts by Fiscal Printers.
CapTrainingMode will be true if the Fiscal Printer supports training mode,
otherwise it is false.
• Non-Fiscal: In this mode the Fiscal Printer can be used to print simple text on
the receipt station (echoed on the journal station) or the slip station. The Fiscal
Printer will print some additional lines along with the application requested
output to indicate that this output is not of a fiscal nature. Such printed receipts
are usually marked as “non-fiscal” receipts by Fiscal Printers.
CapNonFiscalMode will be true if the Fiscal Printer supports non-fiscal
printing, otherwise it is false.

478 Fiscal Printer

The Fiscal Printer follows the output model for devices, with some enhancements:
• Most methods are always performed synchronously. Synchronous methods
will throw a UposException if asynchronous output is outstanding.
• The following methods are performed either synchronously or
asynchronously, depending on the value of the AsyncMode property:
printFiscalDocumentLine
printFixedOutput
printNormal
printRecCash
printRecItem
printRecItemVoid
printRecItemAdjustment
printRecItemAdjustmentVoid
printRecItemFuel
printRecItemFuelVoid
printRecItemRefund
printRecItemRefundVoid
printRecMessage
printRecNotPaid
printRecPackageAdjustment
printRecPackageAdjustVoid
printRecRefund
printRecRefundVoid
printRecSubtotal
printRecSubtotalAdjustment
printRecSubtotalAdjustVoid
printRecTaxID
printRecTotal
printRecVoid
When AsyncMode is false, then these methods print synchronously.
When AsyncMode is true, then these methods operate as follows:
as soon as possible. When the device completes the request successfully,
the OutputCompleteEvent is enqueued. A parameter of this event
contains the OutputID of the completed request.
Asynchronous Fiscal Printer methods will not throw a UposException due to
a printing problem, such as out of paper or Fiscal Printer fault. These errors
will only be reported by an ErrorEvent. A UposException is thrown only if
the Fiscal Printer is not claimed and enabled, a parameter is invalid, or the re-
quest cannot be enqueued. The first two error cases are due to an application
error, while the last is a serious system resource exception.


ErrorEvent is enqueued. The ErrorStation property is set to the station
or stations that were printing when the error occurred. The ErrorLevel,
ErrorString and ErrorState and ErrorOutID properties are also set.
The event handler may call synchronous print methods (but not asynchronous
methods), then can either retry the outstanding output or clear it.
• All buffered output data, including all asynchronous output, may be
deleted by calling clearOutput. OutputCompleteEvents will not be
delivered for cleared output. This method also stops any output that may
be in progress (when possible).
• The property FlagWhenIdle may be set to cause a StatusUpdateEvent
to be enqueued when all outstanding outputs have finished, whether
successfully or because they were cleared.
Error Model Updated in Release 1.12

The Fiscal Printer error reporting model is as follows:
• Most of the Fiscal Printer error conditions are reported by setting the
UposException’s (or ErrorEvent’s) ErrorCode to E_EXTENDED and then
setting ErrorCodeExtended to one of the following:
EFPTR_COVER_OPEN
The Fiscal Printer cover is open.
EFPTR_JRN_EMPTY
The journal station has run out of paper.
EFPTR_REC_EMPTY
The receipt station has run out of paper.
EFPTR_SLP_EMPTY
The slip station has run out of paper.
EFPTR_SLP_FORM
The device was taken out of removal mode while a form was still present.
EFPTR_MISSING_DEVICES
Some of the other devices that according to the local fiscal legislation are
to be connected are missing. In some countries in order to use a Fiscal
Printer a full set of peripheral devices are to be connected to the POS
(such as cash drawer and customer display). In case one of these devices
is not present, sales are not allowed.
EFPTR_WRONG_STATE
The requested method could not be executed in the Fiscal Printer’s current
state.
EFPTR_TECHNICAL_ASSISTANCE
The Fiscal Printer has encountered a severe error condition. Calling for
Fiscal Printer technical assistance is required.
EFPTR_CLOCK_ERROR
The Fiscal Printer’s internal clock has failed.
EFPTR_FISCAL_MEMORY_FULL
The Fiscal Printer’s fiscal memory has been exhausted.
EFPTR_FISCAL_MEMORY_DISCONNECTED
The Fiscal Printer’s fiscal memory has been disconnected.

480 Fiscal Printer
EFPTR_FISCAL_TOTALS_ERROR
The Grand Total in working memory does not match the one in the
EPROM.
EFPTR_BAD_ITEM_QUANTITY
The quantity parameter is invalid.
EFPTR_BAD_ITEM_AMOUNT
The amount parameter is invalid.
EFPTR_BAD_ITEM_DESCRIPTION
The description parameter is either too long, contains illegal characters or
contains a reserved word.
EFPTR_RECEIPT_TOTAL_OVERFLOW
The receipt total has overflowed.
EFPTR_BAD_VAT
The vat parameter is invalid.
EFPTR_BAD_PRICE
The price parameter is invalid.
EFPTR_BAD_DATE
The date parameter is invalid.
EFPTR_NEGATIVE_TOTAL
The Fiscal Printer’s computed total or subtotal is less than zero.
EFPTR_WORD_NOT_ALLOWED
The description contains the reserved word.
EFPTR_BAD_LENGTH
The length of the string to be printed as post or pre line is too long.
EFPTR_MISSING_SET_CURRENCY
The Fiscal Printer is expecting the activation of a new currency.
EFPTR_DAY_END_REQUIRED
The completion of the fiscal day is required.
Other Fiscal Printer errors are reported by setting the exception’s (or
ErrorEvent’s) ErrorCode to E_FAILURE or another error status. These failures
are typically due to a Fiscal Printer fault or jam, or to a more serious error.
Release 1.8 additional Model clarifications
While the Fiscal Printer is enabled, the printer state is monitored, and changes are
reported to the application. Most Fiscal Printer statuses are reported by both firing
a StatusUpdateEvent and by updating a printer property. Statuses, as defined in
the later properties and events sections, are:
Prior to Release 1.8
StatusUpdateEvent Property
FPTR_SUE_COVER_OPEN CoverOpen = true
FPTR_SUE_COVER_OK CoverOpen = false
FPTR_SUE_JRN_EMPTY JrnEmpty = true
FPTR_SUE_JRN_NEAREMPTY JrnNearEnd = true
FPTR_SUE_JRN_PAPEROK JrnEmpty = JrnNearEnd = false
FPTR_SUE_REC_EMPTY RecEmpty = true
FPTR_SUE_REC_NEAREMPTY RecNearEnd = true
FPTR_SUE_REC_PAPEROK RecEmpty = RecNearEnd = false
FPTR_SUE_SLP_EMPTY SlpEmpty = true

FPTR_SUE_SLP_NEAREMPTY SlpNearEnd = true

FPTR_SUE_SLP_PAPEROK SlpEmpty = SlpNearEnd = false
Release 1.8 and later
FPTR_SUE_JRN_COVER_OPEN CoverOpen = true
FPTR_SUE_JRN_COVER_OK CoverOpen = false if all covers closed;
CoverOpen = true if any other cover is
open
FPTR_SUE_REC_COVER_OPEN CoverOpen = true
FPTR_SUE_REC_COVER_OK CoverOpen = false if all covers closed;
open
FPTR_SUE_SLP_COVER_OPEN CoverOpen = true
FPTR_SUE_SLP_COVER_OK CoverOpen = false if all covers closed;
open
Release 1.8 – Clarification
The Fiscal Printer’s slip station statuses must be reported independently from the
slip insertion and removal methods – beginInsertion / endInsertion and
beginRemoval / endRemoval. This is important because some applications base
logic decisions upon Fiscal Printer state changes. That is, the application will only
perform slip insertion after knowing that a slip has been placed at the entrance to
the slip station. An example: After the Total key is pressed, the application enters
tendering mode. It begins to monitor peripherals and the keyboard to determine the
type of tender to perform. If a credit or debit card is swiped at an MSR, then its
DataEvent causes the application to begin credit/debit tender. But if a form is
placed at the slip station, then its StatusUpdateEvent or SlpEmpty property
change causes the application to begin a check MICR read.
When a form is placed at the entrance to the slip station, the Fiscal Printer must
fire a PTR_SUE_SLP_PAPEROK StatusUpdateEvent and set the SlpEmpty
and SlpNearEnd properties to false. The application may then call the
beginInsertion and endInsertion methods with reasonable confidence that they
will succeed. Note that it must not be assumed that the form is ready for printing
after the PTR_SUE_SLP_PAPEROK is received. Only after successful
beginInsertion and endInsertion calls is the form ready for printing.
When a form is removed from the slip station, the Fiscal Printer must fire a
PTR_SUE_SLP_EMPTY StatusUpdateEvent and set the SlpEmpty property to
true. If the beginInsertion and endInsertion method sequence has not been
called, then removing the form from the slip station entrance will cause this to
occur. If this method sequence has successfully completed, then the event and
property change will typically occur after a beginRemoval and endRemoval
method sequence. But they would also occur if the slip prints beyond the end of
the form or if the form is forcibly removed.
Exception: The design of some Fiscal Printers makes it impossible for a service to
determine the presence of a form until the printer “jaws” are opened, which occurs
when beginInsertion is called. This exception is largely limited to cases where the
CapSlpFullslip property is false, indicating a “validation” type of slip station.
Validation stations typically use the same Fiscal Printer mechanism as the receipt
and/or journal stations. In these cases, the slip status events must be fired as soon
as possible, given the constraints of the device.

482 Fiscal Printer
Fiscal Printer States Updated in Release 1.8

As previously described, a Fiscal Printer is characterized by different printing
modes. Moreover, the set of commands that can be executed at a particular
moment depends upon the current state of the Fiscal Printer.
The current state of the Fiscal Printer is kept in the PrinterState property.
The Fiscal Printer has the following states:
• Monitor:
This is a neutral state. From this state, it is possible to move to most of the
other Fiscal Printer states. After a successful call to the claim method and
successful setting of the DeviceEnabled property to true the Fiscal Printer
should be in this state unless there is a Fiscal Printer error.
• Fiscal Receipt:
The Fiscal Printer is processing a fiscal receipt. All printRec… methods
except printRecNotPaid and printRecTaxID are available for use while in
this state. This state is entered from the Monitor state using the
beginFiscalReceipt method.
• Fiscal Receipt Total:
The Fiscal Printer has already accepted at least one payment method, but the
receipt’s total amount has not yet been tendered. This state is entered from the
Fiscal Receipt state by use of the printRecTotal method. The Fiscal Printer
remains in this state while the total remains unpaid. This state can be left by
using the printRecTotal, printRecNotPaid or printRecVoid methods.
• Fiscal Receipt Ending:
The Fiscal Printer has completed the receipt up to the Total line. In this state,
it may be possible to print tax information using the printRecTaxID method
if this is supported by the Fiscal Printer. This state is entered from the Fiscal
Receipt state via the printRecVoid method or from the Fiscal Receipt Total
state using either the printRecTotal, printRecNotPaid, or printRecVoid
methods. This state is exited using the endFiscalReceipt method at which
time the Fiscal Printer returns to the Monitor state.
• Fiscal Document:
The Fiscal Printer is processing a fiscal document. The Fiscal Printer will
accept the printFiscalDocumentLine method while in this state.
This state is entered from the Monitor state using the beginFiscalDocument
method. This state is exited using the endFiscalDocument method at which
time the Fiscal Printer returns to the Monitor state.
• Monitor and TrainingModeActive are true:
The Fiscal Printer is being used for training purposes. All fiscal receipt and
document commands are available. This state is entered from the Monitor
state using the beginTraining method. This state is exited using the
endTraining method at which time the Fiscal Printer returns to the Monitor
state.
• Fiscal Receipt and TrainingModeActive are true:
The Fiscal Printer is being used for training purposes and a receipt is currently
opened. To each line of the receipt, special text will be added in order to
differentiate it from a fiscal receipt.
• Fiscal Total and TrainingModeActive are true:
The Fiscal Printer is in training mode and receipt total is being handled.
• Fiscal ReceiptEnding and TrainingModeActive are true:
The Fiscal Printer is being used for training is in the receipt ending phase.

• NonFiscal:
The Fiscal Printer is printing non-fiscal output on either the receipt (echoed on
the journal) or the slip. In this state the Fiscal Printer will accept the
printNormal method. The Fiscal Printer prints a message that indicates that
this is non-fiscal output with all application text. This state is entered from the
Monitor state using the beginNonFiscal method. This state is exited using the
endNonFiscal method at which time the Fiscal Printer returns to the Monitor
state.
• Fixed:
The Fiscal Printer is being used to print fixed, non-fiscal output to one of the
Fiscal Printer’s stations. In this state the Fiscal Printer will accept the
printFixedOutput method. This state is entered from the Monitor state using
the beginFixedOutput method. This state is exited using the
endFixedOutput method at which time the Fiscal Printer returns to the
Monitor state.
• ItemList:
The Fiscal Printer is currently printing a line item report. In this state the Fiscal
Printer will accept the verifyItem method. This state is entered from the
Monitor state using the beginItemList method. This state is exited using the
endItemList method at which time the Fiscal Printer returns to the Monitor
state.
• Report:
The Fiscal Printer is currently printing one of the supported types of reports.
This state is entered from the Monitor state using one of the printReport,
printPeriodicTotalsReport, printPowerLossReport, printXReport or
printZReport methods. When the report print completes, the Fiscal Printer
automatically returns to Monitor state.
• FiscalSystemBlocked:
The Fiscal Printer is no longer operational due to one of the following reasons:
• The Fiscal Printer has been disconnected or has lost power.
• The Fiscal Printer’s fiscal memory has been exhausted.
• The Fiscal Printer’s internal data has become inconsistent.
In this state the Fiscal Printer will only accept methods to print reports and
retrieve data. The Fiscal Printer cannot exit this state without the assistance of
an authorized technician.
When the application sets the property DeviceEnabled to true it also monitors its
current state. In a standard situation, the PrinterState property is set to
FPTR_PS_MONITOR after a successfully setting DeviceEnabled to true. This
indicates that there was no interrupted operation remaining in the Fiscal Printer.
If the Fiscal Printer is not in the FPTR_PS_MONITOR state, the state reflects the
Fiscal Printer's interrupted operation and the PowerState property is set to
PS_OFF. In this situation, it is necessary to force the Fiscal Printer to a normal
state by calling the resetPrinter method.
This means that a power failure occurred or the last application that accessed the
device left it in a not clear state.
Notice that even in this case the method returns successfully after setting
DeviceEnabled to true. It is required that the application checks the PowerState
property and checks for a received StatusUpdateEvent with the value
SUE_POWER_OFF in the Status property after successfully setting the
DeviceEnabled property.

484 Fiscal Printer
Fiscal Printer State Diagram Added in Release 1.12

Document Printing
Using a Fiscal Printer’s slip station it may be possible (depending upon the Fiscal
Printer’s capabilities and on special fiscal rules) to print the following kinds of
documents:
• Fiscal Documents:
In order to print fiscal documents an amount value must be sent to the Fiscal
Printer and recorded by it. CapSlpFiscalDocument will be true if the Fiscal
Printer supports printing fiscal documents. If fiscal documents are supported
they may be either full length (if CapSlpFullSlip is true) or validation (if
CapSlpValidation is true). The actual selection is made using the
SlipSelection property but only one totalizer is assigned to all the fiscal
documents.
A fiscal document is started using the beginFiscalDocument method and
terminated by using the endFiscalDocument method. A line is printed using
the printFiscalDocumentLine method.
• Non-Fiscal Full Length Documents:
Full-length slip documents may be printed if CapSlpFullSlip is true and
SlipSelection is set to FPTR_SS_FULL_LENGTH.
This document is started using the beginNonFiscal method and terminated by
using the endNonFiscal method. A line is printed using the printNormal
method.
• Non-Fiscal Validation Documents:
Validation documents may be printed if CapSlpValidation is true and
SlipSelection is set to FPTR_SS_VALIDATION.
This document is started using the beginNonFiscal method and terminated by
using the endNonFiscal method. A line is printed using the printNormal
method.
• Fixed Text Documents:
Fixed text documents may be printed if CapFixedOutput is true. If fixed text
documents are supported they may be either full length (if CapSlpFullSlip is
true) or validation (if CapSlpValidation is true). The actual selection is made
using the SlipSelection property.

486 Fiscal Printer
Ordering of Fiscal Receipt Print Requests

Updated in Release 1.12
A fiscal receipt is started using the beginFiscalReceipt method.
Each fiscal receipt consists of a mandatory receipt header and a mandatory receipt
trailer, normally with the country specific logotype. If CapFiscalReceiptType is
true the type of a fiscal receipt may be specified by the FiscalReceiptType
property.
The following receipt types are defined:
• Retail Sales Receipt:
The daily totalizers are updated, the printRec... methods must be used.
• Simplified Invoice Receipt:
The daily totalizers are updated, a special title is printed, the printRec...
methods can be used, except the printRecRefund, printRecRefundVoid
printRecItemRefund, and printRecItemRefundVoid methods.
• Service Sales Receipt:
The daily totalizers are updated, but a special header line is printed to identify
this type of receipt. The printRec... methods must be used.
• Generic Receipt:
Free text can be printed using printNormal method, no totalizer is updated.
A special header line is printed to identify this type of receipt.
• Cash-In Receipt:
This type of receipt helps to reconcile the cash amount. The cash-in amount is
incremented by the amount given as an argument to the printRecCash
method. Free text can be printed using printNormal method, the receipt can
be cancelled.
• Cash-Out Receipt:
This type of receipt helps to reconcile the cash amount. The cash-in amount is
decremented by the amount given as an argument to the printRecCash
method. Free text can be printed using printNormal method, the receipt can
be cancelled.
If CapIndependentHeader is true, then it is up to the application to decide if the
fiscal receipt header lines are to be printed at this time or not. Otherwise, the
header lines are printed immediately prior to the first line item inside a fiscal
receipt. Printing the header lines at this time will decrease the amount of time
required to process the first fiscal receipt print method, but it may result in more
receipt voids as well. The beginFiscalReceipt method may only be called if the
Fiscal Printer is currently in the Monitor state and this call will change the Fiscal
Printer’s current state to Fiscal Receipt.
Before selling the first line item, it is possible to exit from the Fiscal Receipt state
by calling the endFiscalReceipt method. If header lines have already been printed,
this method will cause also receipt voiding.
Once when a Retail Sales Receipt is selected and the first line item has been
printed, the Fiscal Printer remains in the Fiscal Receipt state and the following
fiscal print methods are available:

printRecItem
printRecItemVoid
printRecItemFuel
printRecItemRefund
printRecItemRefundVoid
printRecRefund
printRecRefundVoid
printRecSubtotal
printRecTotal
printRecVoid
The printRecItem, printRecItemVoid, printRecItemAdjustment,
printRecItemAdjustmentVoid, printRecItemFuel, printRecItemFuelVoid,
printRecItemRefund, printRecItemRefundVoid,
printRecPackageAdjustment, printRecPackageAdjustVoid,
printRecRefund, printRecRefundVoid, printRecSubtotal,
printRecSubtotalAdjustment, and printRecSubtotalAdjustVoid will leave the
Fiscal Printer in the Fiscal Receipt state. The printRecTotal methods will change
the Fiscal Printer’s state to either Fiscal Receipt Total or Fiscal Receipt Ending,
depending upon whether the entire receipt total has been met. The printRecVoid
method will change the Fiscal Printer’s state to Fiscal Receipt Ending.
While in the Fiscal Receipt Total state the following fiscal print methods are
available:
printRecNotPaid
printRecTotal
printRecVoid
The printRecNotPaid (only available if CapReceiptNotPaid is true) and
printRecTotal methods will either leave the Fiscal Printer in the Fiscal Receipt
Total state or change the Fiscal Printer’s state to Fiscal Receipt Ending, depending
upon whether the entire receipt total has been met. The printRecVoid method will
change the Fiscal Printer’s state to Fiscal Receipt Ending.
While in the Fiscal Receipt Ending state the following fiscal methods are
available:
printRecMessage
printRecTaxID
endFiscalReceipt
The printRecMessage (only available if CapAdditionalLines is true) and
printRecTaxID methods will leave the Fiscal Printer in the Fiscal Receipt Ending
state. The endFiscalReceipt will cause receipt closing and will then change the
Fiscal Printer’s state to Monitor.
At no time can the Fiscal Printer’s total for the receipt be negative. If this occurs
the Fiscal Printer will generate an ErrorEvent.

488 Fiscal Printer
Fiscal Receipt Layouts Updated in Release 1.8

The following is an example of a typical fiscal receipt layout:
• Header Lines:
Header lines contain all of the information about the store, such as telephone
number, address and name of the store. All of these lines are fixed and are
defined before selling the first item (using the setHeaderLine method).
If CapMultiContractor property is true, two sets of header lines can be
defined, assigned to the value of the ContractorId property. These lines may
either be printed when the beginFiscalReceipt method is called or when the
first fiscal receipt method is called.
• Additional Header Lines:
Header lines defined by the AdditionalHeader property to be printed after the
fixed header lines when the beginFiscalReceipt method is called.
• Transaction Lines:
All of the lines of a fiscal transaction, such as line items, discounts and
surcharges. Optionally they may be assigned to a specific contractor.
• Total Line:
The line containing the transaction total, tender amounts and possibly change
due.
• Message Lines:
These are lines printed using the printRecMessage method.
• Trailer Lines:
These are fixed promotional messages stored on the Fiscal Printer (using the
setTrailerLine method). They are automatically printed when the
endFiscalReceipt method is called. In fact, depending upon fiscal legislation
and upon the Fiscal Printer vendor, the relative position of the trailer and the
fiscal logotype lines can vary.
• Fiscal Lines:
These are lines containing information to be inserted in the receipt due to
fiscal legislations such as the fiscal logotype, date, time and serial number.
They are also printed automatically when the endFiscalReceipt method is
called.
• Additional Trailer Lines:
These are receipt specific information defined in the AdditionalTrailer
property to be printed after the Fiscal Lines on the receipt before cutting it,
when the endFiscalReceipt method is called.

Example of a Fiscal Receipt
Fiscal receipt Definition of the UPOS methods and

line properties
name of the store fixed header lines beginFiscalReceipt

address data stored with
ZIP code and place setHeaderLine and
fiscal identification of the store tax number line setFIscalID
Good Morning add. header line AdditionalHeader property
Milk 1.000 A transaction line printRecItem

Special offer pre item line PreLine property
Beer 4.000 B transaction line printRecItem
Discount Beer -500 B transaction line printRecItemAdjustment
Bread 3.500 A transaction line printRecItem
Storno Bread -3.500 A transaction line printRecItemVoid
Apples 2.000 A transaction line printRecItem
SUBTOTAL 6.500 subtotal line printRecSubtotal
Lamp 12.000 C transaction line printRecItem
VAT category A 3.000 VAT summary printRecTotal

VAT 7.50% 225 ( … , 10000, “Check” )
VAT category B 3.500
VAT 12.00% 420
VAT category C 12.000
VAT 10.00% 1.200
sum of VAT 1.845
T O T AL E 18.500 total line
Check 10.000 payment line

Cash 10.000 payment line printRecTotal
( … , 10000, “Cash” )
Return - 1.500 change line
Advertising messages a.s.o. message line printRecMessage

THANK YOU FOR BUYING AT trailer line endFiscalReceipt
SABERTINI trailer line data stored with
setTrailerLine and
24/05/99 14:25 No 225 logo line at initialisation time
MF B5 012345678 logo line of the fiscal printer
Good Bye additional trailer AdditionalTrailer property

CONGRATULATION Mrs. Smith! lines
You have won: 150 points of fidelity

490 Fiscal Printer
Totalizers and Fiscal Memory

The Fiscal Printer is able to select the fiscal relevant data and to accumulate and
store them in following types of totalizers:
• Receipt Totalizers:
The different kind of amounts of the current receipt are accumulated in receipt
totalizers.
• Day Totalizers:
At the end of a fiscal receipt, when calling the endFiscalReceipt method, the
receipt totalizers are added to the day totalizers where the totals of a fiscal
period (day) are summarized. The contents of the current day totalizers are
printed when calling the printXReport method. At the end of a fiscal day or
period totalizers are printed when calling the printZReport method.
• Document Totalizers:
The different kind of amounts of the current document are accumulated in
document totalizers.
• Grand Totalizers:
Some of the totalizers are stored in the fiscal memory at the end of a fiscal
period when calling the printZReport method. These are the grand totalizers.
The application may print the contents of the fiscal memory by calling
printReport method.
The application may fetch the different totalizers using the getData method or the
getTotalizer method, whereas the type of totalizer can be specified by setting the
TotalizerType property and the assignment to a contractor by setting the
ContractorId property.
Counters
The Fiscal Printer is able to count some features of fiscal receipt and documents.
The application may fetch the different counters using the getData method.
VAT Tables
Some Fiscal Printers support storing VAT (Value Added Tax) tables in the Fiscal
Printer’s memory. Some of these Fiscal Printers will allow the application to set
and modify any of the table entries. Others allow only adding new table entries but
do not allow existing entries to be modified. Some Fiscal Printers allow the VAT
table to bet set only once.
If the Fiscal Printer supports VAT tables, CapHasVatTable is true. If the Fiscal
Printer allows the VAT table entries to be set or modified CapSetVatTable is true.
The maximum number of different vat rate entries in the VAT table is given by the
NumVatRates property. VAT tables are set through a two step process. First the
application uses the setVatValue method to set each table entry to be sent to the
Fiscal Printer.
Next, the setVatTable method is called to send the entire VAT table to the Fiscal
Printer at one time.
Receipt Duplication
In some countries, fiscal legislation can allow printing more than one copy of the
same receipt. CapDuplicateReceipt will be true if the Fiscal Printer is capable of
printing duplicate receipts. Then, setting DuplicateReceipt true causes the

buffering of all receipt printing commands. DuplicateReceipt is set false after

receipt closing. In order to print the receipt again the printDuplicateReceipt
method has to be called.
Currency amounts, percentage amounts, VAT rates, and

quantity amounts
• Currency amounts (and also prices) are passed as values with the data type
long. This is a 64 bit signed integer value that implicitly assumes four digits
as the fractional part. For example, an actual value of 12345 represents 1.2345.
So, the range supported is from
-922,337,203,685,477.5808
to
+922,337,203,685,477.5807
The fractional part used in the calculation unit of a Fiscal Printer may differ
from the long data type. The number of digits in the fractional part is stored in
the AmountDecimalPlaces property and determined by the Fiscal Printer.
The application has to take care that calculations in the application use the
same fractional part for amounts.
• If CapHasVatTable is true, VAT rates are passed using the indexes that were
sent to the setVatValue method.
• If CapHasVatTable is false, VAT rates are passed as amounts with the data
type int32. The number of digits in the fractional part is implicitly assumed to
be four.
• Percentage amounts are used in methods which allow also surcharge and/or
discount amounts. If the amounts are specified to be a percentage value the
value is also passed in a parameter of type long.
• The percentage value has (as given by the long data type) four digits in the
fractional part. It is the percentage (0.0001% to 99.9999%) multiplied by
10000.
• Quantity amounts are passed as values with the data type int32. The number
of digits in the fractional part is stored in the QuantityDecimalPlaces
property and determined by the Fiscal Printer.
Currency Change
If CapSetCurrency is true the Fiscal Printer is able to change the currency, the
application may set a new currency (e.g., EURO) using the setCurrency method.
Device Sharing
The Fiscal Printer is an exclusive-use device, as follows:
Fiscal Printer-specific properties.
See the “Summary” table for precise usage prerequisites.

492 Fiscal Printer
ActualCurrency Property Updated in Release 1.12
Syntax ActualCurrency: int32 { read-only, access after open-claim-enable }

Remarks Holds a value identifying which actual currency is used by the Fiscal Printer.
This property is only valid if CapSetCurrency is true.
Values are:
Value Meaning
FPTR_AC_BRC The actual currency is Brazilian cruceiro.
FPTR_AC_BGL The actual currency is Bulgarian lev.
FPTR_AC_EUR The actual currency is EURO.
FPTR_AC_GRD The actual currency is Greek drachma.
FPTR_AC_HUF The actual currency is Hungarian forint.
FPTR_AC_ITL The actual currency is Italian lira.
FPTR_AC_PLZ The actual currency is Polish zloty.
FPTR_AC_ROL The actual currency is Romanian leu.
FPTR_AC_RUR The actual currency is Russian rouble.
FPTR_AC_TRL The actual currency is Turkish lira.
FPTR_AC_CZK The actual currency is Czechian Koruna.
FPTR_AC_UAH The actual currency is Ukrainian Hryvnia.
FPTR_AC_SEK The actual currency is Swedish Krona.
FPTR_AC_OTHER The actual currency is unknown. (May be used for a
country that recently fiscalized.)
See Also setCurrency Method, CapSetCurrency Property.

AdditionalHeader Property Added in Release 1.6

Syntax AdditionalHeader: string { read-write, access after open-claim-enable }
Remarks Specifies a user specific text which will be printed on the receipt after the fixed
header lines when calling the beginFiscalReceipt method.
This property is only valid if CapAdditionalHeader is true.
This property is initialized to an empty string and kept current while the device is
enabled.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support printing text after the
fixed header lines.
See Also beginFiscalReceipt Method, CapAdditionalHeader Property.
AdditionalTrailer Property Added in Release 1.6

Syntax AdditionalTrailer: string { read-write, access after open-claim-enable }
Remarks Specifies a user specific text which will be printed on the receipt after the fiscal
trailer lines when calling the endFiscalReceipt method.
This property is only valid if CapAdditionalTrailer is true.
This property is initialized to an empty string and kept current while the device is
enabled.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support printing text after the
fiscal trailer lines.
See Also endFiscalReceipt Method, CapAdditionalTrailer Property.

494 Fiscal Printer
AmountDecimalPlaces Property
Syntax AmountDecimalPlaces: int32 { read-only, access after open-claim-enable }
Remarks Holds the number of decimal digits that the fiscal device uses for calculations.
This property is initialized when the device is enabled.
AsyncMode Property
Remarks If true, then some print methods such as printRecItemAdjustment,
printRecItem, printNormal, etc. will be performed asynchronously.
See Also “Model” on page 478 for the output model description.
CapAdditionalHeader Property Added in Release 1.6

Syntax CapAdditionalHeader: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer is able to print application specific text defined in
the AdditionalHeader property after printing the fixed header lines.

CapAdditionalLines Property Updated in Release 1.8

Syntax CapAdditionalLines: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports the printing of application defined lines on
a fiscal receipt between the total line and the end of the fiscal receipt.
If true, then after all totals lines are printed it is possible to print application-
defined strings, such as the ones used for fidelity cards.
CapAdditionalTrailer Property Added in Release 1.6

Syntax CapAdditionalTrailer: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer is able to print application specific text defined in
the AdditionalTrailer property after printing the fiscal trailer lines.
CapAmountAdjustment Property
Syntax CapAmountAdjustment: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer handles fixed amount discounts or fixed amount
surcharges on items.
CapAmountNotPaid Property Deprecated in Release 1.11

Syntax CapAmountNotPaid: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer allows the recording of not paid amounts.

496 Fiscal Printer
CapChangeDue Property Added in Release 1.6

Syntax CapChangeDue: boolean { read-only, access after open }
Remarks If true, the text to be printed as the cash return description when using
printRecTotal method can be defined in the ChangeDue property.
CapCheckTotal Property Updated in Release 1.11

Syntax CapCheckTotal: boolean { read-only, access after open }
Remarks If true, then automatic comparison of the Fiscal Printer’s total and the
application’s total can be enabled and disabled. If false, then the automatic
comparison cannot be enabled or disabled, meaning that the property CheckTotal
can not be changed and is read-only.
See Also CheckTotal Property.
CapCoverSensor Property
Syntax CapCoverSensor: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer has a “cover open” sensor.
CapDoubleWidth Property
Syntax CapDoubleWidth: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer can print double width characters.

CapDuplicateReceipt Property
Syntax CapDuplicateReceipt: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer allows printing more than one copy of the same
fiscal receipt.
CapEmptyReceiptIsVoidable Property Added in Release 1.6

Syntax CapEmptyReceiptIsVoidable: boolean { read-only, access after open }
Remarks If true, then it is allowed to void an opened receipt without any items.
CapFiscalReceiptStation Property Added in Release 1.6

Syntax CapFiscalReceiptStation: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports printing transactions on the station defined
by the FiscalReceiptStation property.
CapFiscalReceiptType Property Added in Release 1.6

Syntax CapFiscalReceiptType: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports printing different types of fiscal receipts
defined by the FiscalReceiptType property.

498 Fiscal Printer
CapFixedOutput Property
Syntax CapFixedOutput: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports fixed format text printing through the
beginFixedOutput, printFixedOutput and endFixedOutput methods.
CapHasVatTable Property
Syntax CapHasVatTable: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer has a tax table.
CapIndependentHeader Property
Syntax CapIndependentHeader: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports printing the fiscal receipt header lines
before the first fiscal receipt command is processed.
CapItemList Property
Syntax CapItemList: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer can print a report of items of a specified VAT class.

CapJrnEmptySensor Property
Syntax CapJrnEmptySensor: boolean { read-only, access after open }
Remarks If true, then the journal has an out-of-paper sensor.
CapJrnNearEndSensor Property
Syntax CapJrnNearEndSensor: boolean { read-only, access after open }
Remarks If true, then the journal has a low paper sensor.
CapJrnPresent Property
Syntax CapJrnPresent: boolean { read-only, access after open }
Remarks If true, then the journal print station is present.
Unlike POS printers, on Fiscal Printers the application is not able to directly access
the journal. The Fiscal Printer itself prints on the journal if present.
CapMultiContractor Property Added in Release 1.6

Syntax CapMultiContractor: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports more than one contractor assigned to the
fiscal receipt and items.

500 Fiscal Printer
CapNonFiscalMode Property
Syntax CapNonFiscalMode: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer allows printing in non-fiscal mode.
CapOnlyVoidLastItem Property Added in Release 1.6

Syntax CapOnlyVoidLastItem: boolean { read-only, access after open }
Remarks If true, then only the last printed item can be voided.
CapOrderAdjustmentFirst Property
Syntax CapOrderAdjustmentFirst: boolean { read-only, access after open }
Remarks If false, the application has to call printRecItem first and then call
printRecItemAdjustment to give a discount or a surcharge for a single article.
If true, then the application has to call printRecItemAdjustment first and then
call printRecItem.
CapPackageAdjustment Property Added in Release 1.6

Syntax CapPackageAdjustment: boolean { read-only, access after open }
Remarks If true, an adjustment may be given to a package of booked items.

CapPercentAdjustment Property
Syntax CapPercentAdjustment: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer handles percentage discounts or percentage
surcharges on items.
CapPositiveAdjustment Property
Syntax CapPositiveAdjustment: boolean { read-only, access after open }
Remarks If true, then it is possible to apply surcharges via the printRecItemAdjustment
method.
CapPositiveSubtotalAdjustment Property Added in Release 1.11
Syntax CapPositiveSubtotalAdjustment: boolean { read-only, access after open }
Remarks If true, then it is possible to apply surcharges via the
printRecSubtoalAdjustment method.
CapPostPreLine Property Added in Release 1.6
Syntax CapPostPreLine: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports printing additional lines defined by the
PostLine and/or the PreLine properties when calling some printRec... methods.
CapPowerLossReport Property
Syntax CapPowerLossReport: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer can print a power loss report using the
printPowerLossReport method.

502 Fiscal Printer
CapPredefinedPaymentLines Property
Syntax CapPredefinedPaymentLines: boolean { read-only, access after open }
Remarks If true, the Fiscal Printer can store and print predefined payment descriptions.
CapReceiptNotPaid Property
Syntax CapReceiptNotPaid: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports using the printRecNotPaid method to
specify a part of the receipt total that is not paid.
CapRecEmptySensor Property
Syntax CapRecEmptySensor: boolean { read-only, access after open }
Remarks If true, then the receipt has an out-of-paper sensor.
CapRecNearEndSensor Property
Syntax CapRecNearEndSensor: boolean { read-only, access after open }
Remarks If true, then the receipt has a low paper sensor.

CapRecPresent Property
Syntax CapRecPresent: boolean { read-only, access after open }
Remarks If true, then the receipt print station is present.
CapRemainingFiscalMemory Property
Syntax CapRemainingFiscalMemory: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports using the RemainingFiscalMemory
property to show the amount of Fiscal Memory remaining. If false, the Fiscal
Printer does not support reporting the Fiscal Memory status of the Fiscal Printer.
CapReservedWord Property
Syntax CapReservedWord: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer prints a reserved word (for example, “TOTALE”)
before printing the total amount.
If true, the reserved word is stored in the ReservedWord property. This reserved
word may not be printed using any fiscal print method.
CapSetCurrency Property Added in Release 1.6

Syntax CapSetCurrency: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer is able to change the currency to a new one by calling
the setCurrency method.

504 Fiscal Printer
CapSetHeader Property
Syntax CapSetHeader: boolean { read-only, access after open }
Remarks If true, then it is possible to use the setHeaderLine method to initialize the
contents of a particular line of the receipt header.
CapSetPOSID Property
Syntax CapSetPOSID: boolean { read-only, access after open }
Remarks If true, then it is possible to use the setPOSID method to initialize the values of
POSID and CashierID. These values are printed on each fiscal receipt.
CapSetStoreFiscalID Property
Syntax CapSetStoreFiscalID: boolean { read-only, access after open }
Remarks If true, then it is possible to use the setStoreFiscalID method to set up the Fiscal
ID number which will be printed on each fiscal receipt.
CapSetTrailer Property
Syntax CapSetTrailer: boolean { read-only, access after open }
Remarks If true, then it is possible to use the setTrailerLine method to initialize the
contents of a particular line of the receipt trailer.

CapSetVatTable Property
Syntax CapSetVatTable: boolean { read-only, access after open }
Remarks If true, then it is possible to use the setVatValue and setVatTable methods to
modify the contents of the Fiscal Printer’s VAT table. Some Fiscal Printers may
not allow existing VAT table entries to be modified. Only new entries may be set
on these Fiscal Printers.
CapSlpEmptySensor Property
Syntax CapSlpEmptySensor: boolean { read-only, access after open }
Remarks If true, then the slip has a “slip in” sensor.
CapSlpFiscalDocument Property
Syntax CapSlpFiscalDocument: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer allows fiscal printing to the slip station.
CapSlpFullSlip Property
Syntax CapSlpFullSlip: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports printing full length forms on the slip station.
It is possible to choose between full slip and validation documents by setting the
SlipSelection property.

506 Fiscal Printer
CapSlpNearEndSensor Property
Syntax CapSlpNearEndSensor: boolean { read-only, access after open }
Remarks If true, then the slip has a “slip near end” sensor.
CapSlpPresent Property
Syntax CapSlpPresent: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer has a slip station.
CapSlpValidation Property
Syntax CapSlpValidation: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports printing validation information on the slip
station.
It is possible to choose between full slip and validation documents by setting the
SlipSelection property. In some countries, when printing non fiscal validations
using the slip station a limited number of lines could be printed.
CapSubAmountAdjustment Property
Syntax CapSubAmountAdjustment: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer handles fixed amount discounts on the subtotal.

CapSubPercentAdjustment Property
Syntax CapSubPercentAdjustment: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer handles percentage discounts on the subtotal.
CapSubtotal Property
Syntax CapSubtotal: boolean { read-only, access after open }
Remarks If true, then it is possible to use the printRecSubtotal method to print the current
subtotal.
CapTotalizerType Property Added in Release 1.6

Syntax CapTotalizerType: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports reading different types of totalizers by
calling the getTotalizer method.
CapTrainingMode Property
Syntax CapTrainingMode: boolean { read-only, access after open }
Remarks If true, then the Fiscal Printer supports a training mode.

508 Fiscal Printer
CapValidateJournal Property
Syntax CapValidateJournal: boolean { read-only, access after open }
Remarks If true, then it is possible to use the printNormal method to print a validation
string on the journal station.
CapXReport Property
Syntax CapXReport: boolean { read-only, access after open }
Remarks If true, then it is possible to use the printXReport method to print an X report.
ChangeDue Property Added in Release 1.6

Syntax ChangeDue: string { read-write, access after open }
Remarks This property holds the text to be printed as a description for the cash return when
using the printRecTotal method.
This property is only valid if CapChangeDue is true.
Value Meaning
E_ILLEGAL Setting this property is not valid for this service (see
CapChangeDue property).
E_EXTENDED ErrorCodeExtended = EFPTR_BAD_LENGTH:
The length of the string to be printed is too long.
See Also printRecTotal Method, CapChangeDue Property.

CheckTotal Property Updated in Release 1.11

Syntax CheckTotal: boolean { read-write, access after open }
Remarks If true, automatic comparison between the Fiscal Printer’s total and the
application’s total is enabled. If false, automatic comparison is disabled.
This property can be changed if CapCheckTotal is true. Otherwise, it is read-
only.
This property is initialized to true by the open method.
Value Meaning
E_ILLEGAL Setting this property is not valid for this Service (see
CapCheckTotal).
See Also CapCheckTotal Property.
ContractorId Property Added in Release 1.6

Syntax ContractorId: int32 { read-write, access after open-claim-enable }
Remarks The identification of the contractor to whom the receipt and/or some items of the
receipt are assigned.
It is used to define different header lines to be printed on the fiscal receipt, in order
to assign any item to a specific contractor and to modify the counters and totalizers
to be read using getData and getTotalizer methods.
Values are:
Value Meaning
FPTR_CID_FIRST First contractor is defined.
FPTR_CID_SECOND Second contractor is defined.
FPTR_CID_SINGLE Single contractor.
This property is initialized to FPTR_CID_SINGLE and kept current while the
device is enabled, which is the functionality supported prior to Release 1.6.
Value Meaning
E_ILLEGAL Setting this property is not valid for this service (see
CapMultiContractor property).
See Also beginFiscalReceipt Method, getData Method, getTotalizer Method,
printRec... Methods, CapMultiContractor Property.

510 Fiscal Printer
CountryCode Property Updated in Release 1.12

Syntax CountryCode: int32 { read-only, access after open }
Remarks Holds a value identifying which countries are supported by the Fiscal Printer. It
can contain any of the following values logically ORed together:
Value Meaning
FPTR_CC_BRAZIL The Fiscal Printer supports Brazil’s fiscal rules.
FPTR_CC_GREECE The Fiscal Printer supports Greece’s fiscal rules.
FPTR_CC_HUNGARY The Fiscal Printer supports Hungary’s fiscal rules.
FPTR_CC_ITALY The Fiscal Printer supports Italy’s fiscal rules.
FPTR_CC_POLAND The Fiscal Printer supports Poland’s fiscal rules.
FPTR_CC_TURKEY The Fiscal Printer supports Turkey’s fiscal rules.
FPTR_CC_RUSSIA The Fiscal Printer supports Russia’s fiscal rules.
FPTR_CC_BULGARIA The Fiscal Printer supports Bulgaria’s fiscal rules.
FPTR_CC_ROMANIA The Fiscal Printer supports Romania’s fiscal rules.
FPTR_CC_CZECH_REPUBLIC
The Fiscal Printer supports the Czech Republic’s fiscal
rules.
FPTR_CC_UKRAINE The Fiscal Printer supports Ukraine’s fiscal rules.
FPTR_CC_SWEDEN The Fiscal Printer supports Sweden’s fiscal rules.
FPTR_CC_OTHER This is an unknown or new fiscal country.
method. (In releases prior to 1.5, this description stated that initialization took
place by the open method. In Release 1.5, it was updated for consistency with
other devices.)
CoverOpen Property
Syntax CoverOpen: boolean { read-only, access after open-claim-enable }
Remarks If true, then the Fiscal Printer’s cover is open.
If CapCoverSensor is false, then the Fiscal Printer does not have a cover open
sensor and this property is always false.

DateType Property Updated in Release 1.11
Syntax DateType: int32 { read-write, access after open-claim-enable }

Remarks Specifies the type of date to be requested when calling the getDate method.
Values are:
Value Meaning
FPTR_DT_CONF Date of configuration.
FPTR_DT_EOD Date of last end of day.
FPTR_DT_RESET Date of last reset.
FPTR_DT_RTC Real time clock of the Fiscal Printer.
FPTR_DT_VAT Date of last VAT change.
FPTR_DT_START The date and time that the fiscal day started or of the first
fiscal receipt or first fiscal document.
Starting with Release 1.11 support is added for countries (e.g., Greece, Russia,
Italy) where it is required by law to make a Z report and therefore end the fiscal
day within a 24 hour period. If the 24 hour period after the first fiscal ticket or after
the fiscal day opening is exceeded, then no new fiscal ticket can be started and
printing of a Z report is required. Setting DateType to FPTR_DT_START and
calling getDate provides the information necessary to detect this situation.
This property is initialized to FPTR_DT_RTC and kept current while the device is
enabled, which is the functionality supported prior to Release 1.6.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support the specified type.
See Also getDate Method.

512 Fiscal Printer
DayOpened Property Updated in Release 1.6

Syntax DayOpened: boolean { read-only, access after open-claim-enable }
Remarks If true, then the fiscal day has been started on the Fiscal Printer by a first call to the
beginFiscalReceipt or beginFiscalDocument method at a fiscal period (day).
The Fiscal Day of the Fiscal Printer can be either opened or not opened. The
DayOpened property reflects whether or not the Fiscal Printer considers its Fiscal
Day to be opened or not.
Some methods may only be called while the Fiscal Day is not yet opened
(DayOpened is false). Methods that can be called after the Fiscal Day is opened
change from country to country. Usually all the configuration methods are to be
called only before the Fiscal Day is opened.
This property changes to false after calling printZReport.
Depending on fiscal legislation, the following methods may be allowed only if the
Fiscal Printer is in the Monitor State and has not yet begun its Fiscal Day:
setCurrency
setDate
setHeaderLine
setPOSID
setStoreFiscalID
setTrailerLine
setVatTable
setVatValue
DescriptionLength Property Updated in Release 1.6

Syntax DescriptionLength: int32 { read-only, access after open }
Remarks Holds the maximum number of characters that may be passed as a description
parameter.
The exact maximum number for a description parameter of a specific method can
be obtained by calling getData method.
See Also getData Method.

DuplicateReceipt Property
Syntax DuplicateReceipt: boolean { read-write, access after open }
Remarks If true, all the printing commands inside a fiscal receipt will be buffered and they
can be printed again via the printDuplicateReceipt method.
This property is only valid if CapDuplicateReceipt is true.
ErrorLevel Property
Syntax ErrorLevel: int32 { read-only, access after open }
Remarks Holds the severity of the error condition.
This property has one of the following values:
Value Meaning
FPTR_EL_NONE No error condition is present.

FPTR_EL_RECOVERABLE
A recoverable error has occurred.
(Example: Out of paper.)
FPTR_EL_FATAL A non-recoverable error has occurred.
(Example: Internal printer failure.)
FPTR_EL_BLOCKED A severe hardware failure which can be resolved only by
authorized technicians. (Example: Fiscal memory
failure.). This error cannot be recovered.
This property is set just before delivering an ErrorEvent. When the error is
cleared, then the property is changed to FPTR_EL_NONE.
ErrorOutID Property Updated in Release 1.6
Syntax ErrorOutID: int32 { read-only, access after open }
Remarks Holds the identifier of the output in the queue which caused an ErrorEvent, when
using asynchronous printing.
other devices.)
This property is set just before an ErrorEvent is delivered.

514 Fiscal Printer
ErrorState Property
Syntax ErrorState: int32 { read-only, access after open }
Remarks Holds the current state of the Fiscal Printer when an ErrorEvent is delivered for
an asynchronous output.
This property is set just before an ErrorEvent is delivered.
See Also PrinterState Property.
ErrorStation Property
Syntax ErrorStation: int32 { read-only, access after open }
Remarks Holds the station or stations that were printing when an error was detected.
This property will be set to one of the following values: FPTR_S_JOURNAL,
FPTR_S_RECEIPT, FPTR_S_SLIP, FPTR_S_JOURNAL_RECEIPT,
FPTR_S_JOURNAL_SLIP, FPTR_S_RECEIPT_SLIP.
This property is only valid if the ErrorLevel is not equal to PTR_EL_NONE. It is
set just before delivering an ErrorEvent.
Remarks Holds a vendor-supplied description of the current error.
This property is set just before delivering an ErrorEvent. If no description is
available, the property is set to an empty string. When the error is cleared, then the
property is changed to an empty string.

FiscalReceiptStation Property Added in Release 1.6

Syntax FiscalReceiptStation: int32 { read-write, access after open-claim-enable }
Remarks Selects the station where the transaction of the fiscal receipt started with
beginFiscalReceipt method will be printed. Setting this property is only allowed
in the Monitor State.
Values are:
Value Meaning
FPTR_RS_RECEIPT The following transactions will be printed on the receipt

station.
FPTR_RS_SLIP The following transactions will be printed on the slip
station.
This property is only valid if CapFiscalReceiptStation is true.
This property is initialized to FPTR_RS_RECEIPT and kept current while the
device is enabled, which is the functionality supported prior to Release 1.6.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support the specified station.
E_EXTENDED ErrorCodeExtended = EFPTR_WRONG_STATE:
The Fiscal Printer is not currently in the Monitor State.
See Also beginFiscalReceipt Method, CapFiscalReceiptStation Property.

516 Fiscal Printer
FiscalReceiptType Property Updated in Release 1.11
Syntax FiscalReceiptType: int32 { read-write, access after open-claim-enable }

Remarks Selects the type of the fiscal receipt. Setting this property is only allowed in the
Monitor State.
Values are:
Value Meaning
FPTR_RT_CASH_IN Cash-in receipt
FPTR_RT_CASH_OUT Cash-out receipt
FPTR_RT_GENERIC Generic receipt
FPTR_RT_SALES Retail sales receipt
FPTR_RT_SERVICE Service sales receipt
FPTR_RT_SIMPLE_INVOICE Simplified invoice receipt
FPTR_RT_REFUND Refund sales receipt
This property is only valid if CapFiscalReceiptType is true.
Starting with Release 1.11, due to the need for negative receipts (e.g., in Italy),
such as refund receipts, the receipt type FPTR_RT_REFUND is added.
This property is initialized to FPTR_RT_SALES and kept current while the device
is enabled, which is the functionality supported prior to Release 1.6.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support the specified receipt
type.
The Fiscal Printer is not currently in the Monitor State.
See Also beginFiscalReceipt Method, CapFiscalReceiptType Property.

JrnEmpty Property
Syntax JrnEmpty: boolean { read-only, access after open-claim-enable }
Remarks If true, the journal is out of paper. If false, journal paper is present.
If CapJrnEmptySensor is false, then the value of this property is always false.
See Also JrnNearEnd Property.
JrnNearEnd Property
Syntax JrnNearEnd: boolean { read-only, access after open-claim-enable }
Remarks If true, the journal paper is low. If false, journal paper is not low.
If CapJrnNearEndSensor is false, then the value of this property is always false.
See Also JrnEmpty Property.

518 Fiscal Printer
MessageLength Property
Syntax MessageLength: int32 { read-only, access after open }
Remarks Holds the maximum number of characters that may be passed as a message line in
the method printRecMessage. The value may change in different modes of the
Fiscal Printer. For example in the mode “Fiscal Receipt” the number of characters
may be bigger than in the mode “Fiscal Receipt Total.”
MessageType Property Added in Release 1.6

Syntax MessageType: int32 { read-write, access after open-claim-enable }
Remarks Selects the kind of message to be printed when using the printRecMessage
method. Values are:
Value
FPTR_MT_ADVANCE
FPTR_MT_ADVANCE_PAID
FPTR_MT_AMOUNT_TO_BE_PAID
FPTR_MT_AMOUNT_TO_BE_PAID_BACK
FPTR_MT_CARD
FPTR_MT_CARD_NUMBER
FPTR_MT_CARD_TYPE
FPTR_MT_CASH
FPTR_MT_CASHIER
FPTR_MT_CASH_REGISTER_NUMBER
FPTR_MT_CHANGE
FPTR_MT_CHEQUE
FPTR_MT_CLIENT_NUMBER
FPTR_MT_CLIENT_SIGNATURE
FPTR_MT_COUNTER_STATE
FPTR_MT_CREDIT_CARD
FPTR_MT_CURRENCY
FPTR_MT_CURRENCY_VALUE
FPTR_MT_DEPOSIT
FPTR_MT_DEPOSIT_RETURNED
FPTR_MT_DOT_LINE
FPTR_MT_DRIVER_NUMB
FPTR_MT_EMPTY_LINE
FPTR_MT_FREE_TEXT

FPTR_MT_FREE_TEXT_WITH_DAY_LIMIT
FPTR_MT_GIVEN_DISCOUNT
FPTR_MT_LOCAL_CREDIT
FPTR_MT_MILEAGE_KM
FPTR_MT_NOTE
FPTR_MT_PAID
FPTR_MT_PAY_IN
FPTR_MT_POINT_GRANTED
FPTR_MT_POINTS_BONUS
FPTR_MT_POINTS_RECEIPT
FPTR_MT_POINTS_TOTAL
FPTR_MT_PROFITED
FPTR_MT_RATE
FPTR_MT_REGISTER_NUMB
FPTR_MT_SHIFT_NUMBER
FPTR_MT_STATE_OF_AN_ACCOUNT
FPTR_MT_SUBSCRIPTION
FPTR_MT_TABLE
FPTR_MT_THANK_YOU_FOR_LOYALTY
FPTR_MT_TRANSACTION_NUMB
FPTR_MT_VALID_TO
FPTR_MT_VOUCHER
FPTR_MT_VOUCHER_PAID
FPTR_MT_VOUCHER_VALUE
FPTR_MT_WITH_DISCOUNT
FPTR_MT_WITHOUT_UPLIFT
This property is initialized to FPTR_MT_FREE_TEXT by the open method,
which is the functionality supported prior to Release 1.6.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support this value.

See Also printRecMessage Method.

520 Fiscal Printer
NumHeaderLines Property
Syntax NumHeaderLines: int32 { read-only, access after open }
Remarks Holds the maximum number of header lines that can be printed for each fiscal
receipt. Header lines usually contain information such as store address, store
name, store Fiscal ID. Each header line is set using the setHeaderLine method and
remains set even after the Fiscal Printer is switched off. Header lines are
automatically printed when a fiscal receipt is initiated using the
beginFiscalReceipt method or when the first line item inside a receipt is sold.
NumTrailerLines Property
Syntax NumTrailerLines: int32 { read-only, access after open }
Remarks Holds the maximum number of trailer lines that can be printed for each fiscal
receipt. Trailer lines are usually promotional messages. Each trailer line is set
using the setTrailerLine method and remains set even after the Fiscal Printer is
switched off. Trailer lines are automatically printed either after the last
printRecTotal or when a fiscal receipt is closed using the endFiscalReceipt
method.
NumVatRates Property
Syntax NumVatRates: int32 { read-only, access after open }
Remarks Holds the maximum number of vat rates that can be entered into the Fiscal
Printer’s Vat table.

PostLine Property Added in Release 1.6

Syntax PostLine: string { read-write, access after open-claim-enable }
Remarks An application specific text to be printed on the fiscal receipt after a line item
invoked by some printRec... methods. The property can be written in the Fiscal
Receipt State. The length of the text is reduced to a country specific value
This property is only valid if CapPostPreLine is true.
This property is initialized to an empty string and will be reset to an empty string
after being used.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support printing post item
lines or the text contains invalid characters.
The length of the string is too long.
See Also printRecSubtotal Method, printRecTotal Method, CapPostPreLine Property.
PredefinedPaymentLines Property
Syntax PredefinedPaymentLines: string { read-only, access after open }
Remarks Holds the list of all possible words to be used as indexes of the predefined payment
lines (for example, “a, b, c, d, z”). Those indexes are used in the printRecTotal
method for the description parameter.
If CapPredefinedPaymentLines is true, only predefined payment lines are
allowed.

522 Fiscal Printer
PreLine Property Added in Release 1.6

Syntax PreLine: string { read-write, access after open-claim-enable }
Remarks An application specific text to be printed on the fiscal receipt before a line item
invoked by some printRec... methods. The property can be written in the Fiscal
Receipt State. The length of the text is reduced to a country specific value
This property is only valid if CapPostPreLine is true.
This property is initialized to an empty string and will be reset to an empty string
after being used.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support printing pre item
lines or the text contains invalid characters.
The length of the string is too long.
See Also printRecItem Method, printRecItemAdjustment Method,
printRecItemRefund Method, printRecRefund Method,
printRecSubtotalAdjustment Method, CapPostPreLine Property.

PrinterState Property Updated in Release 1.6

Syntax PrinterState: int32 { read-only, access after open }
Remarks Holds the Fiscal Printer’s current operational state. This property controls which
methods are currently legal.
Values are:
Value Meaning
FPTR_PS_MONITOR If TrainingModeActive is false:

The Fiscal Printer is currently not in a specific
operational mode. In this state the Fiscal Printer will
accept any of the begin… methods as well as the set…
methods.
If TrainingModeActive is true:
The Fiscal Printer is currently being used for training
purposes. In this state the Fiscal Printer will accept any
of the printRec… methods or the endTraining method.
FPTR_PS_FISCAL_RECEIPT
If TrainingModeActive is false:
The Fiscal Printer is currently processing a fiscal
receipt. In this state the Fiscal Printer will accept any of
the printRec… methods.
purposes and a fiscal receipt is currently opened.
FPTR_PS_FISCAL_RECEIPT_TOTAL
The Fiscal Printer has already accepted at least one
payment, but the total has not been completely paid. In
this state the Fiscal Printer will accept either the
printRecTotal or printRecNotPaid methods.
purposes and the Fiscal Printer has already accepted at
least one payment, but the total has not been completely
paid.
FPTR_PS_FISCAL_RECEIPT_ENDING
The Fiscal Printer has completed the receipt up to the
total line. In this state the Fiscal Printer will accept either
the printRecMessage or endFiscalReceipt methods.
purposes and a fiscal receipt is going to be closed.

524 Fiscal Printer
FPTR_PS_FISCAL_DOCUMENT
The Fiscal Printer is currently processing a fiscal slip. In
this state the Fiscal Printer will accept either the
printFiscalDocumentLine or endFiscalDocument
methods.
FPTR_PS_FIXED_OUTPUT
The Fiscal Printer is currently processing fixed text
output to one or more stations. In this state the Fiscal
Printer will accept either the printFixedOutput or
endFixedOutput methods.
FPTR_PS_ITEM_LIST The Fiscal Printer is currently processing an item list
report. In this state the Fiscal Printer will accept either
the verifyItem or endItemList methods.
FPTR_PS_NONFISCAL The Fiscal Printer is currently processing non-fiscal
output to one or more stations. In this state the Fiscal
Printer will accept either the printNormal or
endNonFiscal methods.
FPTR_PS_LOCKED The Fiscal Printer has encountered a non-recoverable
hardware problem. An authorized Fiscal Printer
technician must be contacted to exit this state.
FPTR_PS_REPORT The Fiscal Printer is currently processing a fiscal report.
In this state the Fiscal Printer will not accept any
methods until the report has completed.
There are a few methods that are accepted in any state except
FPTR_PS_LOCKED. These are beginInsertion, endInsertion, beginRemoval,
endRemoval, getDate, getData, getTotalizer, getVatEntry, resetPrinter and
clearOutput.
other devices.)
QuantityDecimalPlaces Property Updated in Release 1.6
Syntax QuantityDecimalPlaces: int32 { read-only, access after open }
Remarks Holds the number of decimal digits in the fractional part that should be assumed
to be in any quantity parameter.
other devices.)

QuantityLength Property Updated in Release 1.6

Syntax QuantityLength: int32 { read-only, access after open }
Remarks Holds the maximum number of digits that may be passed as a quantity parameter,
including both the whole and fractional parts.
other devices.)
RecEmpty Property
Syntax RecEmpty: boolean { read-only, access after open-claim-enable }
Remarks If true, the receipt is out of paper. If false, receipt paper is present.
If CapRecEmptySensor is false, then this property is always false.
See Also RecNearEnd Property.
RecNearEnd Property
Syntax RecNearEnd: boolean { read-only, access after open-claim-enable }
Remarks If true, the receipt paper is low. If false, receipt paper is not low.
If CapRecNearEndSensor is false, then this property is always false.
See Also RecEmpty Property.

526 Fiscal Printer
RemainingFiscalMemory Property
Syntax RemainingFiscalMemory: int32 { read-only, access after open-claim-enable }
Remarks Holds the remaining counter of Fiscal Memory.
This property is initialized and kept current while the device is enabled and may
be updated by printZReport method.
See Also CapRemainingFiscalMemory Property.
ReservedWord Property
Syntax ReservedWord: string { read-only, access after open }
Remarks Holds the string that is automatically printed with the total when the
printRecTotal method is called. This word may not occur in any string that is
passed into any fiscal output methods.
This property is only valid if CapReservedWord is true.
SlpEmpty Property
Syntax SlpEmpty: boolean { read-only, access after open-claim-enable }
Remarks If true, a slip form is not present. If false, a slip form is present.
If CapSlpEmptySensor is false, then this property is always false.
Note:
The “slip empty” sensor should be used primarily to determine whether a form has
been inserted before printing. It can also be monitored to determine whether a
form is still in place. This sensor is usually placed one or more print lines above
the slip print head.
However, the “slip near end” sensor (when present) should be used to determine
when nearing the end of the slip. This sensor is usually placed one or more print
lines below the slip print head.
See Also SlpNearEnd Property.

SlpNearEnd Property
Syntax SlpNearEnd: boolean { read-only, access after open-claim-enable }
Remarks If true, the slip form is near its end. If false, the slip form is not near its end. The
“near end” sensor is also sometimes called the “trailing edge” sensor, referring to
the bottom edge of the slip.
If CapSlpNearEndSensor is false, then this property is always false.
Note:
However, the “slip near end” sensor (when present) should be used to determine
when nearing the end of the slip. This sensor is usually placed one or more print
lines below the slip print head.
See Also SlpEmpty Property.
SlipSelection Property
Syntax SlipSelection: int32 { read-write, access after open-claim-enable }
Remarks Selects the kind of document to be printed on the slip station.
Value Meaning
FPTR_SS_FULL_LENGTH Print full length documents.

FPTR_SS_VALIDATION Print validation documents.
This property is initialized to FPTR_SS_FULL_LENGTH by the claim method.

Value Meaning
E_ILLEGAL An invalid slip type was specified.

528 Fiscal Printer
TotalizerType Property Added in Release 1.6

Syntax TotalizerType: int32 { read-write, access after open-claim-enable }
Remarks Specifies the type of totalizer to be requested when calling the getTotalizer
method.
Values are:
Value Meaning
FPTR_TT_DOCUMENT Document totalizer
FPTR_TT_DAY Day totalizer
FPTR_TT_RECEIPT Receipt totalizer
FPTR_TT_GRAND Grand totalizer
This property is only valid if CapTotalizerType is true.
This property is initialized to FPTR_TT_DAY and kept current while the device
is enabled, which is the functionality supported prior to Release 1.6.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support defining totalizer
types or an invalid type was specified.
See Also getTotalizer Method, CapTotalizerType Property.
TrainingModeActive Property
Syntax TrainingModeActive: boolean { read-only, access after open-claim-enable }
Remarks Holds the current Fiscal Printer's operational state concerning the training mode.
Training mode allows all fiscal commands, but each receipt is marked as non-
fiscal and no internal Fiscal Printer registers are updated with any data while in
training mode. Some countries' fiscal rules require that all blank characters on a
training mode receipt be printed as some other character. Italy, for example,
requires that all training mode receipts print a “?” instead of a blank.
Value Meaning
true The Fiscal Printer is currently in training mode. That

means no data are written into the EPROM of the Fiscal
Printer.
false The Fiscal Printer is currently in normal mode. All
printed receipts will also update the fiscal memory.


beginFiscalDocument Method Updated in Release 1.11
Syntax beginFiscalDocument ( documentAmount: int32 ):
documentAmount Amount of document to be stored by the Fiscal Printer.
Remarks Initiates fiscal printing to the slip station.
This method is only supported if CapSlpFiscalDocument is true.
If this is the first call to the beginFiscalDocument method, the Fiscal Day will be
started and the DayOpened property will be set to true.
Each fiscal line will be printed using the printFiscalDocumentLine method. The
fiscal document handling would be as follows:
beginFiscalDocument()
beginInsertion(); endInsertion()
// print fist page
printFiscalDocumentLine()*
beginRemoval(); endRemoval()
beginInsertion(); endInsertion()
// print second page
printFiscalDocumentLine()*
beginRemoval(); endRemoval()
endFiscalDocument()
If this method is successful, the PrinterState property will be changed to
FPTR_PS_FISCAL_DOCUMENT.
Value Meaning
E_ILLEGAL The slip station does not exist (see the CapSlpPresent
property) or the printer does not support fiscal output to the
slip station (see the CapSlpFiscalDocument property).
The printer’s current state does not allow this state transition.
ErrorCodeExtended = EFPTR_SLP_EMPTY:
There is no paper in the slip station.
ErrorCodeExtended = EFPTR_BAD_ITEM_AMOUNT:
The documentAmount parameter is invalid.
ErrorCodeExtended =
EFPTR_MISSING_SET_CURRENCY:
The new receipt cannot be opened, the Fiscal Printer is
expecting the current currency to be changed by calling
setCurrency method.
ErrorCodeExtended = EFPTR_DAY_END_REQUIRED:
The completion of the fiscal day is required by calling
printZReport. No further fiscal receipts or documents can
be started before this is done.

530 Fiscal Printer
See Also CapSlpFiscalDocument Property, CapSlpPresent Property,

AmountDecimalPlaces Property, DayOpened Property, PrinterState Property,
beginInsertion Method, endFiscalDocument Method, endInsertion Method,
printFiscalDocumentLine Method, printZReport Method.
beginFiscalReceipt Method Updated in Release 1.11

Syntax beginFiscalReceipt ( printHeader: boolean ):
printHeader Indicates if the header lines are to be printed at this time.
Remarks Initiates fiscal printing to the receipt station.
If CapFiscalReceiptStation is true the FiscalReceiptStation property defines the
station where the receipt will be printed. If CapFiscalReceiptStation is false the
receipt will be printed on the receipt station. If CapFiscalReceiptType is true the
receipt type must be defined in FiscalReceiptType and a header line according to
the specified receipt type will be printed.
If this is the first call to the beginFiscalReceipt method, the Fiscal Day will be
started and the DayOpened property will be set to true.
If printHeader and CapIndependentHeader are both true all defined header lines
will be printed before control is returned. Otherwise, header lines will be printed
when the first item is sold in the case they are not printed at the end of the
preceding receipt. If CapAdditionalHeader is true, application specific header
lines defined by the AdditionalHeader property will be printed after the fixed
header lines.
If CapMultiContractor is true, the current receipt is assigned to the contractor
specified by the ContractorId property.
FPTR_PS_FISCAL_RECEIPT.
Value Meaning
E_ILLEGAL An invalid receipt type was specified.
The Fiscal Printer’s current state does not allow this state
transition.
ErrorCodeExtended =
EFPTR_MISSING_SET_CURRENCY:
The new receipt cannot be opened, the Fiscal Printer is
expecting the current currency to be changed by calling
setCurrency method.
ErrorCodeExtended = EFPTR_DAY_END_REQUIRED:
The completion of the fiscal day is required by calling
printZReport. No further fiscal receipts or documents can
be started before this is done.

See Also CapAdditionalHeader Property, CapFiscalReceiptStation Property,

CapFiscalReceiptType Property, CapIndependentHeader Property,
CapMultiContractor Property, AdditionalHeader Property, ContractorId
Property, DayOpened Property, FiscalReceiptStation Property,
FiscalReceiptType Property, PrinterState Property, endFiscalReceipt Method,
printRec… Methods.
beginFixedOutput Method
Syntax beginFixedOutput ( station: int32, documentType: int32 ):
station The Fiscal Printer station to be used. May be either
FPTR_S_RECEIPT or FPTR_S_SLIP.
documentType Identifier of a document stored in the Fiscal Printer.
Remarks Initiates non-fiscal fixed text printing on a Fiscal Printer station.

This method is only supported if CapFixedOutput is true.
If the station parameter is FPTR_S_SLIP, the slip paper must be inserted into the
slip station using begin/endInsertion before calling this method.
Each fixed output will be printed using the printFixedOutput method. If this
method is successful, the PrinterState property will be changed to
FPTR_PS_FIXED_OUTPUT. The endFixedOutput method ends fixed output
modality and resets PrinterState.
Value Meaning
• Station does not exist (see the CapSlpPresent property).
• Fiscal Printer does not support fixed output (see the
CapFixedOutput property).
• station parameter is invalid.
• documentType is invalid.
The Fiscal Printer’s current state does not allow this state
transition.
There is no paper in the slip station.
See Also CapFixedOutput Property, CapSlpPresent Property, PrinterState Property,
beginInsertion Method, endFixedOutput Method, endInsertion Method,
printFixedOutput Method.

532 Fiscal Printer
timeout The timeout parameter gives the number of milliseconds

before failing the method.
If zero, the method tries to begin insertion mode, then returns the appropriate status
immediately. If FOREVER (-1), the method tries to begin insertion mode, then
waits as long as needed until either the form is inserted or an error occurs.
Remarks Initiates slip processing.
When called, the slip station is made ready to receive a form by opening the form’s
handling “jaws” or activating a form insertion mode. This method is paired with
the endInsertion method for controlling form insertion.
If the Fiscal Printer device cannot be placed into insertion mode, a UposException
is thrown. Otherwise, the device continues to monitor form insertion until either:
• The form is successfully inserted.
• The form is not inserted before timeout milliseconds have elapsed, or an error
is reported by the Fiscal Printer device. In this case, a UposException is
thrown with an ErrorCode of E_TIMEOUT or another value. The Fiscal
Printer device remains in form insertion mode. This allows an application to
perform some user interaction and reissue the beginInsertion method without
altering the form handling mechanism.
Value Meaning
property) or an invalid timeout parameter was specified.
E_TIMEOUT The specified time has elapsed without the form being
properly inserted.
See Also CapSlpPresent Property, endInsertion Method, beginRemoval Method,
endRemoval Method.

beginItemList Method
Syntax beginItemList ( vatID: int32 ):
vatID Vat identifier for reporting.
Remarks Initiates a validation report of items belonging to a particular VAT class.

This method is only supported if CapItemList is true.
If this method is successful, PrinterState will be changed to

FPTR_PS_ITEM_LIST.
After this method, only verifyItem and endItemList methods may be called.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support an item list report
(see the CapItemList property) or the Fiscal Printer
does not support VAT tables (see the CapHasVatTable
property).

The Fiscal Printer’s current state does not allow this
state transition.
ErrorCodeExtended = EFPTR_BAD_VAT:
The vatID parameter is invalid.
See Also CapHasVatTable Property, CapItemList Property, PrinterState Property,

endItemList Method, verifyItem Method.

534 Fiscal Printer
beginNonFiscal Method
Syntax beginNonFiscal ( ):
Remarks Initiates non-fiscal operations on the Fiscal Printer.
This method is only supported if CapNonFiscalMode is true. Output in this mode
is accomplished using the printNormal method. This method can be successfully
called only if the current value of the PrinterState property is
FPTR_PS_MONITOR. If this method is successful, the PrinterState property
will be changed to FPTR_PS_NONFISCAL. In order to stop non fiscal modality
endNonFiscal method should be called.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support non-fiscal output

(see the CapNonFiscalMode property).
state transition.
See Also CapNonFiscalMode Property, PrinterState Property, endNonFiscal Method,

printNormal Method.

beginRemoval Method
timeout The timeout parameter gives the number of milliseconds

before failing the method.
If zero, the method tries to begin removal mode, then returns the appropriate status
immediately. If FOREVER (-1), the method tries to begin removal mode, then
waits as long as needed until either the form is removed or an error occurs.
Remarks Initiates form removal processing.
When called, the Fiscal Printer is made ready to remove a form by opening the
form handling “jaws” or activating a form ejection mode. This method is paired
with the endRemoval method for controlling form removal.
If the Fiscal Printer device cannot be placed into removal or ejection mode, a
UposException is thrown. Otherwise, the device continues to monitor form
removal until either:
• The form is successfully removed.
• The form is not removed before timeout milliseconds have elapsed, or an error
is reported by the Fiscal Printer device. In this case, a UposException is
thrown with an ErrorCode of E_TIMEOUT or another value. The Fiscal
Printer device remains in form removal mode. This allows an application to
perform some user interaction and reissue the beginRemoval method without
altering the form handling mechanism.
Value Meaning
E_ILLEGAL The Fiscal Printer does not have a slip station (see the
CapSlpPresent property) or an invalid timeout
parameter was specified.
properly removed.
See Also CapSlpPresent Property, beginInsertion Method, endInsertion Method,
endRemoval Method.

536 Fiscal Printer
beginTraining Method
Syntax beginTraining ( ):
Remarks Initiates training operations.
This method is only supported if CapTrainingMode is true. Output in this mode
is accomplished using the printRec… methods in order to print a receipt or other
methods to print reports. This method can be successfully called only if the current
value of the PrinterState property is FPTR_PS_MONITOR. If this method is
successful, the TrainingModeActive property will be changed to true.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support training mode (see
the CapTrainingMode property).

state transition.
See Also CapTrainingMode Property, PrinterState Property, TrainingModeActive

Property, endTraining Method, printRec… Methods.

clearError Method
Syntax clearError ( ):
Remarks Clears all Fiscal Printer error conditions.
This method is always performed synchronously.
Value Meaning
E_FAILURE Error recovery failed.
endFiscalDocument Method
Syntax endFiscalDocument ( ):
Remarks Terminates fiscal printing to the slip station.
FPTR_PS_MONITOR.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support fiscal output to the
slip station (see the CapSlpFiscalDocument property).
The Fiscal Printer is not currently in the Fiscal
Document state.
See Also CapSlpFiscalDocument Property, PrinterState property,

beginFiscalDocument Method, printFiscalDocumentLine Method.

538 Fiscal Printer
endFiscalReceipt Method Updated in Release 1.6

Syntax endFiscalReceipt ( printHeader: boolean ):
printHeader Indicates if the header lines of the following receipt are

to be printed at this time.
Remarks Terminates fiscal printing to the receipt station.

If printHeader is false, this method will close the current fiscal receipt, print the
trailer lines, if they were not already printed after the total lines, and cut it.
If printHeader is true additionally the header of the next receipt will be printed
before cutting the receipt, otherwise the header will be printed when beginning the
next receipt.
All functions carried out by this method will be completed before this call returns.
If CapAdditionalTrailer is true application specific trailer lines defined by the

AdditionalTrailer property will be printed after the fiscal trailer lines.
FPTR_PS_MONITOR.
Value Meaning

The Fiscal Printer is not currently in the Fiscal Receipt
Ending state.
See Also beginFiscalReceipt Method, printRec… Methods, CapAdditionalTrailer
Property, AdditionalTrailer Property.

endFixedOutput Method
Syntax endFixedOutput ( ):
Remarks Terminates non-fiscal fixed text printing on a Fiscal Printer station.
This method is only supported if CapFixedOutput is true. If this method is
successful, the PrinterState property will be changed to FPTR_PS_MONITOR.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support fixed output (see the
CapFixedOutput property).
The Fiscal Printer is not currently in the Fixed Output
state.
See Also beginFixedOutput Method, printFixedOutput Method.
endInsertion Method
Remarks Ends form insertion processing.
When called, the Fiscal Printer is taken out of form insertion mode. If the slip
device has forms “jaws,” they are closed by this method. If no form is present, a
UposException is thrown with its ErrorCodeExtended property set to
EFPTR_SLP_EMPTY.
This method is paired with the beginInsertion method for controlling form
insertion. The application may choose to call this method immediately after a
successful beginInsertion if it wants to use the Fiscal Printer sensors to determine
when a form is positioned within the slip printer. Alternatively, the application
may prompt the user and wait for a key press before calling this method.
Value Meaning
E_ILLEGAL The Fiscal Printer is not in slip insertion mode.
E_EXTENDED ErrorCodeExtended = EFPTR_COVER_OPEN:
The device was taken out of insertion mode while the
Fiscal Printer cover was open.
form being inserted.
See Also beginInsertion Method, beginRemoval Method, endRemoval Method.

540 Fiscal Printer
endItemList Method
Syntax endItemList ( ):
Remarks Terminates a validation report of items belonging to a particular VAT class.
This method is only supported if CapItemList is true and CapHasVatTable is
true.
This method is paired with the beginItemList method.
This method can be successfully called only if current value of PrinterState
property is equal to FPTR_PS_ITEM_LIST.
FPTR_PS_MONITOR.
Value Meaning
CapItemList property) or the Fiscal Printer does not
support VAT tables (see the CapHasVatTable
property).
state transition.
See Also beginItemList Method, verifyItem Method.
endNonFiscal Method
Syntax endNonFiscal ( ):
Remarks Terminates non-fiscal operations on one Fiscal Printer station.
This method is only supported if CapNonFiscalMode is true. If this method is
successful, the PrinterState property will be changed to FPTR_PS_MONITOR.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support non-fiscal output
(see the CapNonFiscalMode property).
The Fiscal Printer is not currently in the Non-Fiscal
state.
See Also beginNonFiscal Method, printNormal Method.

endRemoval Method
Remarks Ends form removal processing.
When called, the Fiscal Printer is taken out of form removal or ejection mode. If a
form is present, a UposException is thrown with the ErrorCodeExtended property
set to EFPTR_SLP_FORM.
This method is paired with the beginRemoval method for controlling form
removal. The application may choose to call this method immediately after a
successful beginRemoval if it wants to use the Fiscal Printer sensors to determine
when the form has been removed. Alternatively, the application may prompt the
user and wait for a key press before calling this method.
Value Meaning
E_ILLEGAL The Fiscal Printer is not in slip removal mode.
E_EXTENDED ErrorCodeExtended = EFPTR_SLP_FORM:
The device was taken out of removal mode while a form
was still present.
See Also beginInsertion Method, endInsertion Method, beginRemoval Method.
endTraining Method
Syntax endTraining ( ):
Remarks Terminates training operations on either the receipt or the slip station.
This method is only supported if CapTrainingMode is true. If this method is
successful, the TrainingModeActive property will be changed to false.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support training mode (see
the CapTrainingMode property).
The Fiscal Printer is not currently in the Training state.
See Also CapTrainingMode property, beginTraining Method, printRec… Methods.

542 Fiscal Printer
getData Method Updated in Release 1.12

Syntax getData ( dataItem: int32, inout optArgs: int32, inout data: string ):
dataItem The specific data item to retrieve.
optArgs For some dataItem this additional argument is needed.
Consult the Service vendor's documentation for further
use of this argument.
data Character string to hold the data retrieved.
The dataItem parameter has one of the following values:
Value Meaning
Identification data
FPTR_GD_FIRMWARE Get the Fiscal Printer’s firmware release
number.
FPTR_GD_PRINTER_ID Get the Fiscal Printer’s fiscal ID.
Totals
FPTR_GD_CURRENT_TOTAL Get the current receipt total.
FPTR_GD_DAILY_TOTAL Get the daily total.
FPTR_GD_GRAND_TOTAL Get the Fiscal Printer’s grand total.
FPTR_GD_MID_VOID Get the total number of voided receipts.
FPTR_GD_NOT_PAID Get the current total of not paid receipts.
FPTR_GD_RECEIPT_NUMBERGet the number of fiscal receipts printed.
FPTR_GD_REFUND Get the current total of refunds.
FPTR_GD_REFUND_VOID Get the current total of voided refunds.
Fiscal memory counts
FPTR_GD_NUMB_CONFIG_BLOCK
Get the grand number of configuration blocks.
FPTR_GD_NUMB_CURRENCY_BLOCK
Get the grand number of currency blocks.
FPTR_GD_NUMB_HDR_BLOCK
Get the grand number of header blocks.
FPTR_GD_NUMB_RESET_BLOCK
Get the grand number of reset blocks.
FPTR_GD_NUMB_VAT_BLOCK
Get the grand number of VAT blocks.
Counter
FPTR_GD_FISCAL_DOC Get the number of daily fiscal documents.
FPTR_GD_FISCAL_DOC_VOIDGet the number of daily voided fiscal
documents.
FPTR_GD_FISCAL_REC Get the number of daily fiscal sales receipts.
FPTR_GD_FISCAL_REC_VOIDGet the number of daily voided fiscal sales
receipts.
FPTR_GD_NONFISCAL_DOC Get the number of daily non fiscal documents.

FPTR_GD_NONFISCAL_DOC_VOID
Get the number of daily voided non fiscal
documents.
FPTR_GD_NONFISCAL_REC Get the number of daily non fiscal receipts.
FPTR_GD_RESTART Get the Fiscal Printer’s restart count
FPTR_GD_SIMP_INVOICE Get the number of daily simplified invoices.
FPTR_GD_Z_REPORT Get the Z report number.
Fixed fiscal printer text
FPTR_GD_TENDER Get the payment description used in the
printRecTotal method, defined by the given
identifier in the optArgs argument.Valid only,
if the CapPredefinedPaymentLines property
is true.
Linecounter
FPTR_GD_LINECOUNT Get the number of printed lines, defined by the
given identifier in the optArgs argument. If the
CapMultiContractor property is true, line
counters depend on the contractor defined by
the ContractorId property.
Description length
FPTR_GD_DESCRIPTION_LENGTH
Get the maximum number of characters that
may be passed as a description parameter for a
specific method, defined by the given identifier
in the optArgs argument.
If dataItem is FPTR_GD_TENDER the optArgs parameter has to be set to one of
Value Meaning
FPTR_PDL_CASH Cash.
FPTR_PDL_CHEQUE Cheque.
FPTR_PDL_CHITTY Chitty.
FPTR_PDL_COUPON Coupon.
FPTR_PDL_CURRENCY Currency.
FPTR_PDL_DRIVEN_OFF
FPTR_PDL_EFT_IMPRINTER Printer EFT.
FPTR_PDL_EFT_TERMINAL Terminal EFT.
FPTR_PDL_TERMINAL_IMPRINTER
FPTR_PDL_FREE_GIFT Gift.
FPTR_PDL_GIRO Giro.
FPTR_PDL_HOME Home.
FPTR_PDL_IMPRINTER_WITH_ISSUER
FPTR_PDL_LOCAL_ACCOUNT Local account.
FPTR_PDL_LOCAL_ACCOUNT_CARDLocal card account.
FPTR_PDL_PAY_CARD Pay card.
FPTR_PDL_PAY_CARD_MANUAL Manual pay card.
FPTR_PDL_PREPAY Prepay.
FPTR_PDL_PUMP_TEST Pump test.

544 Fiscal Printer
FPTR_PDL_SHORT_CREDIT Credit.
FPTR_PDL_STAFF Staff.
FPTR_PDL_VOUCHER Voucher.
If dataItem is FPTR_GD_LINECOUNT the optArgs parameter has to be set to one
of the following values:
Value Meaning
FPTR_LC_ITEM Number of item lines.
FPTR_LC_ITEM_VOID Number of voided item lines.
FPTR_LC_DISCOUNT Number of discount lines.
FPTR_LC_DISCOUNT_VOID Number of voided discount lines.
FPTR_LC_SURCHARGE Number of surcharge lines.
FPTR_LC_SURCHARGE_VOID Number of voided surcharge lines.
FPTR_LC_REFUND Number of refund lines.
FPTR_LC_REFUND_VOID Number of voided refund lines.
FPTR_LC_SUBTOTAL_DISCOUNT Number of subtotal discount lines.
FPTR_LC_SUBTOTAL_DISCOUNT_VOID
Number of voided subtotal discount
lines.
FPTR_LC_SUBTOTAL_SURCHARGE Number of subtotal surcharge lines.
FPTR_LC_SUBTOTAL_SURCHARGE_VOID
Number of voided subtotal surcharge
lines.
FPTR_LC_COMMENT Number of comment lines.
FPTR_LC_SUBTOTAL Number of subtotal lines.
FPTR_LC_TOTAL Number of total lines.
If dataItem is FPTR_GD_DESCRIPTION_LENGTH the optArgs parameter has
to be set to one of the following values:
Value Meaning
FPTR_DL_ITEM printRecItem method.
FPTR_DL_ITEM_ADJUSTMENT printRecItemAdjustment method.
FPTR_DL_ITEM_FUEL printRecItemFuel method.
FPTR_DL_ITEM_FUEL_VOID printRecItemFuelVoid method.
FPTR_DL_NOT_PAID printRecNotPaid method.
FPTR_DL_PACKAGE_ADJUSTMENT printRecPackageAdjustment
method.
FPTR_DL_REFUND printRecRefund method,
printRecItemRefund method.
FPTR_DL_REFUND_VOID printRecRefundVoid method,
printRecItemRefundVoid method.
FPTR_DL_SUBTOTAL_ADJUSTMENT printRecSubtotalAdjustment
method.
FPTR_DL_TOTAL printRecTotal method.
FPTR_DL_VOID printRecVoid method.
FPTR_DL_VOID_ITEM printRecItemVoid and
methods.

Remarks Retrieves data and counters from the printer’s fiscal module.
If CapMultiContractor is true, line counters depend on the contractor defined by
the ContractorId property.
The data is returned in a string because some of the fields, such as the grand total,
might overflow a 4-byte integer.
Value Meaning
E_BUSY Cannot perform while output is in progress. (Only
applies if AsyncMode is false.)
E_ILLEGAL The dataItem, optArgs or ContractorId specified is
invalid.
See Also printRecTotal Method, CapPredefinedPaymentLines Property,

ContractorId Property, PredefinedPaymentLines Property.
getDate Method Updated in Release 1.6

Syntax getDate ( inout date: string ):
date Date and time returned as a string.
Remarks Gets the Fiscal Printer’s date and time specified by the DateType property.
The date and time are returned as a string in the format “ddmmyyyyhhmm”:
dd day of the month (1 - 31)

mm month (1 - 12)
yyyy year (1997-)
hh hour (0-23)
mm minutes (0-59)
The fiscal controller may not support hours and minutes depending on the date
type. In such cases the corresponding fields in the returned string are filled with
“0”.
Value Meaning
E_ILLEGAL Retrieval of the date and time is not valid at this time.
See Also DateType Property.

546 Fiscal Printer
getTotalizer Method Updated in Release 1.6

Syntax getTotalizer ( vatID: int32, optArgs: int32, inout data: string ):
vatID VAT identifier of the required totalizer.
optArgs Specifies the required totalizer.
data Totalizer returned as a string.
The optArgs parameter has one of the following values:
Value Meaning
FPTR_GT_GROSS Gross totalizer specified by the TotalizerType

and ContractorId properties.
FPTR_GT_NET Net totalizer specified by the TotalizerType
FPTR_GT_DISCOUNT Discount totalizer specified by the
TotalizerType and ContractorId properties.
FPTR_GT_DISCOUNT_VOID Voided discount totalizer specified by the
FPTR_GT_ITEM Item totalizer specified by the TotalizerType
FPTR_GT_ITEM_VOID Voided item totalizer specified by the
FPTR_GT_NOT_PAID Not paid totalizer specified by the
FPTR_GT_REFUND Refund totalizer specified by the
FPTR_GT_REFUND_VOID Voided refund totalizer specified by the
FPTR_GT_SUBTOTAL_DISCOUNT
Subtotal discount totalizer specified by the
FPTR_GT_SUBTOTAL_DISCOUNT_VOID
Voided discount totalizer specified by the
FPTR_GT_SUBTOTAL_SURCHARGES
Subtotal surcharges totalizer specified by the

FPTR_GT_SUBTOTAL_SURCHARGES_VOID
Voided surcharges totalizer specified by the
FPTR_GT_SURCHARGE Surcharge totalizer specified by the
FPTR_GT_SURCHARGE_VOIDVoided surcharge totalizer specified by the
FPTR_GT_VAT VAT totalizer specified by the TotalizerType
FPTR_GT_VAT_CATEGORY VAT totalizer per VAT category specified by
the TotalizerType and ContractorId
properties associated to the given vatID.
Remarks Gets the totalizer specified by the optArgs argument Some of the totalizers such as
item or VAT totalizers may be associated with the given vatID.
If CapTotalizerType is true the type of totalizer (grand, day, receipt specific)
depends on the TotalizerType property.
If CapMultiContractor is true the type depends on the ContractorId property.
If CapSetVatTable is false, then only one totalizer is present.

Value Meaning
• The vatID parameter is invalid, or
• The ContractorId property is invalid, or
• The specified totalizer is not available.
See Also CapTotalizerType Property, TotalizerType Property,

CapMultiContractor Property, ContractorId Property.

548 Fiscal Printer
getVatEntry Method Updated in Release 1.11
Syntax getVatEntry ( vatID: int32, optArgs: int32, inout vatRate: int32 ):

vatID VAT identifier of the required rate.
optArgs For some countries, this additional argument may be
needed. Consult the Fiscal Printer Service vendor's
documentation for details.
vatRate The rate associated with the VAT identifier.
Remarks Gets the rate associated with a given VAT identifier.

This method is only supported if CapHasVatTable is true.
Value Meaning
E_ILLEGAL The vatID parameter is invalid, or CapHasVatTable is
false.
See Also CapHasVatTable Property.

printDuplicateReceipt Method
Syntax printDuplicateReceipt ( ):
Remarks Prints a duplicate of a buffered transaction.
This method is only supported if CapDuplicateReceipt is true. This method will
succeed if both the CapDuplicateReceipt and DuplicateReceipt properties are
true.
This method resets the DuplicateReceipt property to false.

Value Meaning
E_ILLEGAL The Fiscal Printer does not support duplicate receipts
(see the CapDuplicateReceipt property) or there is no
buffered transaction to print (see DuplicateReceipt
property).
The Fiscal Printer is not currently in the Monitor state.
ErrorCodeExtended = EFPTR_JRN_EMPTY:
The journal station is out of paper.
ErrorCodeExtended = EFPTR_REC_EMPTY:
The receipt station is out of paper.
See Also CapDuplicateReceipt Property, DuplicateReceipt Property.

550 Fiscal Printer
printFiscalDocumentLine Method
Syntax printFiscalDocumentLine ( documentLine: string ):
documentLine String to be printed on the fiscal slip.
Remarks Prints a line of fiscal text to the slip station.

Value Meaning
E_ILLEGAL The Fiscal Printer does not support fiscal documents
(see the CapSlpFiscalDocument property).
The Fiscal Printer is not currently in the Fiscal
Document state.
ErrorCodeExtended = EFPTR_COVER_OPEN:
(Only applies if AsyncMode is false.)
The slip station was specified, but a form is not inserted.
See Also beginFiscalDocument Method, endFiscalDocument Method.

printFixedOutput Method
Syntax printFixedOutput ( documentType: int32, lineNumber: int32, data: string ):
documentType Identifier of a document stored in the Fiscal Printer
lineNumber Number of the line in the document to print.
data String parameter for placement in printed line.
Remarks Prints a line of a fixed document to the print station specified in the
beginFixedOutput method. Each call prints a single line from a document by
merging the stored text with the parameter data. Within a document lines must be
printed sequentially. First and last lines are required; others may be optional.
This method is only supported if CapFixedOutput is true. The Fiscal Printer state
is set to FPTR_PS_FIXED_OUTPUT. This method is performed synchronously if
AsyncMode is false, and asynchronously if AsyncMode is true.
Value Meaning
CapFixedOutput property) or the lineNumber is
invalid.
The Fiscal Printer is not in the Fixed Output state.
The receipt station was specified but is out of paper.
See Also beginFixedOutput Method, endFixedOutput Method

552 Fiscal Printer
printNormal Method Updated in Release 1.7

Syntax printNormal ( station: int32, data: string ):
station The Fiscal Printer station to be used. May be
FPTR_S_RECEIPT, FPTR_S_JOURNAL, or
FPTR_S_SLIP.
data1 The characters to be printed. May consist mostly of
printable characters, escape sequences, carriage returns
(13 decimal), and line feeds (10 decimal) but in many
cases these are not supported.
Remarks Performs non-fiscal printing. Prints data on the Fiscal Printer station.
Special character values within data are:
Value Meaning
Line Feed (10 decimal)
Print any data in the line buffer, and feed to the next print
line. (A Carriage Return is not required in order to cause
the line to be printed.)
Carriage Return (13 decimal)
If a Carriage Return immediately precedes a Line Feed,
or if the line buffer is empty, then it is ignored.
Otherwise, the line buffer is printed and the Fiscal
Printer does not feed to the next print line. On some
Fiscal Printers, print without feed may be directly
supported. On others, a print may always feed to the next
line, in which case the Device will print the line buffer
and perform a reverse line feed if supported. If the Fiscal
Printer does not support either of these features, then
Carriage Return acts like a Line Feed.
Value Meaning
E_ILLEGAL The specified station does not exist. (See the
CapJrnPresent, CapRecPresent and CapSlpPresent
properties.)
1. In the OPOS environment, the format of data depends upon the value of the


The Fiscal Printer is not currently in the Non-Fiscal
state.
The journal station was specified but is out of paper.
See Also beginNonFiscal Method, endNonFiscal Method, AsyncMode Property.

554 Fiscal Printer
printPeriodicTotalsReport Method
Syntax printPeriodicTotalsReport ( date1: string, date2: string ):
date1 Starting date of report to print.
date2 Ending date of report to print.
Remarks Prints a report of totals for a range of dates on the receipt.
The dates are strings in the format “ddmmyyyyhhmm”, where:
mm month (1 - 12)
yyyy year (1997-)
hh hour (0-23)
mm minutes (0-59)

Value Meaning
state transition.
ErrorCodeExtended = EFPTR_BAD_DATE:
One of the date parameters is invalid.

printPowerLossReport Method
Syntax printPowerLossReport ( ):
Remarks Prints on the receipt a report of a power failure that resulted in a loss of data stored
in the CMOS of the Fiscal Printer.
This method is only supported if CapPowerLossReport is true.


Value Meaning
E_ILLEGAL The Fiscal Printer does not support power loss reports
(see the CapPowerLossReport property).
state transition.
See Also CapPowerLossReport Property.

556 Fiscal Printer
printRecCash Method Added in Release 1.6

Syntax printRecCash ( amount: currency ):
amount Amount to be incremented or decremented.
Remarks Prints a cash-in or cash-out receipt amount on the station defined by the
FiscalReceiptStation property.
This method is only allowed if CapFiscalReceiptType is true and the
FiscalReceiptType property is set to FPTR_RT_CASH_IN or
FPTR_RT_CASH_OUT and the fiscal Fiscal Printer is in the Fiscal Receipt state.

Value Meaning
E_BUSY Cannot perform while output is in progress.
E_ILLEGAL The Fiscal Printer does not support this method.
state.
See Also beginFiscalReceipt Method, FiscalReceiptStation Property,

FiscalReceiptType Property.

printRecItem Method Updated in Release 1.6

Syntax printRecItem ( description: string, price: currency, quantity: int32, vatInfo:
int32, unitPrice: currency, unitName: string ):
description Text describing the item sold.
price Price of the line item.
quantity Number of items. If zero, a single item is assumed.
vatInfo VAT rate identifier or amount. If not used a zero must be
transferred.
unitPrice Price of each item. If not used a zero must be transferred.
unitName Name of the unit i.e., “kg” or “ltr” or “pcs”. If not used
an empty string (“”) must be transferred
Remarks Prints a receipt item for a sold item on the station specified by the
FiscalReceiptStation property. If the quantity parameter is zero, then a single
item quantity will be assumed.
Minimum parameters are description and price or description, price, quantity, and
unitPrice. Most countries require quantity and vatInfo and some countries also
require unitPrice and unitName.
VatInfo parameter contains a VAT table identifier if CapHasVatTable is true.

Otherwise, it contains a VAT amount.
If CapPostPreLine is true additional application specific lines defined by the

PostLine and PreLine properties will be printed. After printing these lines
PostLine and PreLine will be reset to an empty string.

Value Meaning
state.

558 Fiscal Printer
ErrorCodeExtended =
EFPTR_BAD_ITEM_QUANTITY:
The quantity is invalid.
ErrorCodeExtended = EFPTR_BAD_PRICE:
The unit price is invalid.
ErrorCodeExtended =
EFPTR_BAD_ITEM_DESCRIPTION:
The discount description is too long or contains a
reserved word.
The VAT parameter is invalid.
ErrorCodeExtended =
EFPTR_RECEIPT_TOTAL_OVERFLOW:
See Also beginFiscalReceipt Method, endFiscalReceipt Method, printRec… Methods,

AmountDecimalPlaces Property, FiscalReceiptStation Property,
PostLine Property, PreLine Property.

printRecItemAdjustment Method Updated in Release 1.11

Syntax printRecItemAdjustment ( adjustmentType: int32, description: string,
adjustmentType Type of adjustment. See below for values.
description Text describing the adjustment.
amount Amount of the adjustment.
vatInfo VAT rate identifier or amount.
The adjustmentType parameter has one of the following values (Note: If currency
value, four decimal places are used):
Value Meaning
FPTR_AT_AMOUNT_DISCOUNT
Fixed amount discount. The amount parameter contains
a currency value.
FPTR_AT_AMOUNT_SURCHARGE
Fixed amount surcharge. The amount parameter
contains a currency value.
FPTR_AT_PERCENTAGE_DISCOUNT
Percentage discount. The amount parameter contains a
percentage value.
FPTR_AT_PERCENTAGE_SURCHARGE
Percentage surcharge. The amount parameter contains a
percentage value.
FPTR_AT_COUPON_AMOUNT_DISCOUNT
Fixed amount discount for an advertising coupon. The
amount parameter contains a currency value. The
coupon is registered by the fiscal memory. If coupons
are not registered at fiscal memory separately from
ordinary discounts in the actual country then it is
recommend to use FPTR_AT_AMOUNT_DISCOUNT
instead.
FPTR_AT_COUPON_PERCENTAGE_DISCOUNT
Percentage discount for an advertising coupon. The
amount parameter contains a percentage value. The
recommend to use
FPTR_AT_PERCENTAGE_DISCOUNT instead.
Remarks Applies and prints a discount or a surcharge to the last receipt item sold on the
station specified by the FiscalReceiptStation property. This discount may be
either a fixed currency amount or a percentage amount relating to the last item.
If CapOrderAdjustmentFirst is true, the method must be called before the
corresponding printRecItem method. If CapOrderAdjustmentFirst is false, the
method must be called after the printRecItem.
This discount/surcharge may be either a fixed currency amount or a percentage
amount relating to the last item. If the discount amount is greater than the receipt

560 Fiscal Printer
subtotal, an error occurs since the subtotal can never be negative. In many
countries discount operations cause the printing of a fixed line of text expressing
the kind of operation that has been performed.
The VatInfo parameter contains a VAT table identifier if CapHasVatTable is
true. Otherwise, it contains a VAT amount.
Fixed amount discounts/surcharges are only supported if the property
CapAmountAdjustment is true. Percentage discounts are only supported if
CapPercentAdjustment is true.
If CapPostPreLine is true an additional application specific line defined by the
PreLine property will be printed. After printing this line PreLine will be reset to
an empty string.
Value Meaning
• The Fiscal Printer does not support fixed amount
adjustments (see the CapAmountAdjustment
property).
• The Fiscal Printer does not support percentage
discounts (see the CapPercentAdjustment
property).
• The adjustmentType parameter is invalid.
state.
ErrorCodeExtended = FPTR_BAD_ITEM_AMOUNT:
The discount amount is invalid.
ErrorCodeExtended =


reserved word. (Only applies if AsyncMode is false.)
AmountDecimalPlaces Property, FiscalReceiptStation Property, PreLine
Property.
printRecItemAdjustmentVoid Method Added in Release 1.11

Syntax printRecItemAdjustmentVoid ( adjustmentType: int32, description: string,
adjustmentType Type of adjustment to be voided. See below for values.
description Text describing the adjustment to be voided.
amount Amount of the adjustment to be voided.
Value Meaning
Fixed amount discount to be voided. The amount
parameter contains a currency value.
Fixed amount surcharge to be voided. The amount
parameter contains a currency value.
Percentage discount to be voided. The amount
parameter contains a percentage value.
Percentage surcharge to be voided. The amount
parameter contains a percentage value.
Fixed amount discount for an advertising coupon to be
voided. The amount parameter contains a currency
value. The coupon is registered by the fiscal memory. If
coupons are not registered at fiscal memory separately
from ordinary discounts in the actual country then it is
instead.
Percentage discount for an advertising coupon to be
voided. The amount parameter contains a percentage
value. The coupon is registered by the fiscal memory. If
coupons are not registered at fiscal memory separately
from ordinary discounts in the actual country then it is
recommend to use
FPTR_AT_PERCENTAGE_DISCOUNT instead.

562 Fiscal Printer
Remarks Cancels an adjustment that has been added to fiscal receipt before and prints a
cancellation line with a negative amount on the station specified by the
FiscalReceiptStation property. This adjustment cancellation amount may be
either a fixed currency amount or a percentage amount.
The VatInfo parameter contains a VAT table identifier if CapHasVatTable is
true. Otherwise, it contains a VAT amount.
Fixed amount adjustment cancellations are only supported if the property
CapAmountAdjustment is true. Percentage adjustment cancellations are only
supported if CapPercentAdjustment is true.
an empty string.
Value Meaning
• The Fiscal Printer does not support fixed amount
adjustments (see the CapAmountAdjustment
property).
• The Fiscal Printer does not support percentage
discounts (see the CapPercentAdjustment
property).
state.
ErrorCodeExtended = FPTR_BAD_ITEM_AMOUNT:
ErrorCodeExtended =


See Also AmountDecimalPlaces Property, FiscalReceiptStation Property, PreLine
Property, beginFiscalReceipt Method, endFiscalReceipt Method, printRec…
Methods, printRecItemAdjustment Method.
printRecItemFuel Method Added in Release 1.6

Syntax printRecItemFuel ( description: string, price: currency, quantity: int32,
vatInfo: int32, unitPrice: currency, unitName: string, specialTax:
currency, specialTaxName: string ):
description Text describing the fuel product.
price Price of the fuel item.
transferred.
unitPrice Price of the fuel item per volume.
unitName Name of the volume unit, i.e., “ltr”. If not used an empty
string (“”) must be transferred
specialTax Special tax amount, e.g., road tax. If not used a zero
must be transferred.
specialTaxName Name of the special tax.
Remarks Prints a receipt fuel item on the station specified by the FiscalReceiptStation
property. vatInfo parameter contains a VAT table identifier if CapHasVatTable
is true. Otherwise, it contains a VAT amount.

Value Meaning
E_ILLEGAL This method is not supported.
state.

564 Fiscal Printer
ErrorCodeExtended =
ErrorCodeExtended =
reserved word.
ErrorCodeExtended =
See Also beginFiscalReceipt Method, FiscalReceiptStation Property.

printRecItemFuelVoid Method Added in Release 1.6

Syntax printRecItemFuelVoid ( description: string, price: currency, vatInfo: int32,
specialTax: currency ):
description Text describing the fuel product.
price Price of the fuel item. If not used a zero must be
transferred.
transferred.
specialTax Special tax amount, e.g., road tax. If not used a zero
must be transferred.
Remarks Called to void a fuel item on the station specified by the FiscalReceiptStation
property.
If CapOnlyVoidLastItem is true, only the last fuel item transferred to the Fiscal
Printer can be voided.

Value Meaning
E_ILLEGAL This method is not supported.
state.
The price is invalid.

566 Fiscal Printer
ErrorCodeExtended =
reserved word.
See Also beginFiscalReceipt Method, endFiscalReceipt Method,
printRecItemFuel Method, CapOnlyVoidLastItem Property,
FiscalReceiptStation Property.
printRecItemRefund Method Added in Release 1.12

Syntax printRecItemRefund ( description: string, amount: currency, quantity: int32,
vatInfo: int32, unitAmount: currency, unitName: string ):
description Text describing the refund.
amount The amount of the refund line.
transferred.
unitAmount Amount of each refund item. If not used a zero must be
transferred.
Remarks Processes one or more item refunds. The amount is positive, but it is printed as a
negative number and the totals registers are decremented.
If unitAmount and quantity are non zero then the amount parameter corresponds to
the product of quantity and unitAmount. Otherwise this method has the same
functionality as the method printRecRefund.
Some fixed text, along with the description, will be printed on the station defined
by the FiscalReceiptStation property to indicate that a refund has occurred.
The vatInfo parameter contains a VAT table identifier if CapHasVatTable is true.
Otherwise it, contains a VAT amount.
PreLine property will be printed. After printing this line, PreLine will be reset to
an empty string.


Value Meaning
state.
ErrorCodeExtended =
ErrorCodeExtended =
EFPTR_BAD_ITEM_AMOUNT:
The refund amount is invalid.
ErrorCodeExtended =
reserved word.
See Also CapHasVatTable Property, CapPostPreLine Property, FiscalReceiptStation

Property, PreLine Property, printRecItemRefundVoid Method,
printRecRefund Method.

568 Fiscal Printer
printRecItemRefundVoid Method Added in Release 1.12

Syntax printRecItemRefundVoid ( description: string, amount: currency, quantity:
int32, vatInfo: int32, unitAmount: currency, unitName: string ):
amount The amount of the refund line.
transferred.
unitAmount Amount of each refund item. If not used a zero must be
transferred.
Remarks Processes a void of one or more item refunds. The amount is positive and the totals
registers are incremented.
If unitAmount and quantity are non zero then the amount parameter corresponds to
the product of quantity and unitAmount. Otherwise this method has the same
functionality as the method printRecRefundVoid.
by the FiscalReceiptStation property to indicate that a void of a refund has
occurred.
If CapOnlyVoidLastItem is true, only the last refund item transferred to the
Fiscal Printer can be voided.

Value Meaning
E_ILLEGAL Cancelling is not allowed at this ticket state. May be
because no item has been sold previously.
(See CapOnlyVoidLastItem.)
state.

ErrorCodeExtended =
ErrorCodeExtended =
The refund amount is invalid.
ErrorCodeExtended =
reserved word.
ErrorCodeExtended =
See Also CapHasVatTable Property, CapPostPreLine Property, FiscalReceiptStation
Property, PreLine Property, printRecItemRefund Method,
printRecRefundVoid Method.

570 Fiscal Printer
printRecItemVoid Method Added in Release 1.11

Syntax printRecItemVoid ( description: string, price: currency, quantity: int32,
description Text describing the item to be voided.
price Price of the item to be voided.
quantity Quantity of item to be voided. If zero, a single item is
assumed.
transferred.
unitPrice Price of each item. If not used a zero must be transferred.
Remarks Cancels one or more items that has been added to the receipt and prints a void
description on the station defined by the FiscalReceiptStation property.
Minimum parameters are description and price or description, quantity, and
unitPrice. Most countries require quantity and vatInfo and some countries also
require unitPrice and unitName.
price is a positive number, it will be printed as a negative and will be decremented
from the totals registers. In some countries price will be ignored, instead the
computation from quantity and unitPrice will be printed as a negative amount. The
vatInfo parameter contains a VAT table identifier if CapHasVatTable is true.
Otherwise, it contains a VAT amount.
If CapOnlyVoidLastItem is true, only the last item transferred to the Fiscal
Printer can be voided exclusive an adjustment line for this item.
If CapPostPreLine is true, additional application specific lines defined by the
PostLine and PreLine properties will be printed. After printing these lines
PostLine and PreLine will be reset to an empty string.
Value Meaning
E_ILLEGAL Cancelling is not allowed at this ticket state. May be
because no item has been sold previously.
(See CapOnlyVoidLastItem.)

state.
ErrorCodeExtended =
The price is invalid.
ErrorCodeExtended =
The VAT information is invalid.
ErrorCodeExtended =
The description is too long or contains a reserved word.
ErrorCodeExtended = EFPTR_NEGATIVE_TOTAL:
The computed total is less than zero.
See Also AmountDecimalPlaces Property, CapOnlyVoidLastItem Property,
FiscalReceiptStation Property, beginFiscalReceipt Method, endFiscalReceipt
Method, printRecItem Method, printRec… Methods.

572 Fiscal Printer
printRecMessage Method Updated in Release 1.11

Syntax printRecMessage ( message: string ):
message Text message to print.
Remarks Prints a message on the fiscal receipt on the station specified by the
FiscalReceiptStation property. The length of an individual message is limited to
the number of characters given in the MessageLength property. The kind of
message to be printed is defined by the MessageType property.
This method is only supported if CapAdditionalLines is true. This method is only
supported when the Fiscal Printer is in one of the Fiscal Receipt states.

Value Meaning
The Fiscal Printer is not in the Fiscal Receipt Ending
state.
ErrorCodeExtended =
The message is too long or contains a reserved word.
CapAdditionalLines Property, FiscalReceiptStation Property,
MessageLength Property, MessageType Property.

printRecNotPaid Method Updated in Release 1.11

Syntax printRecNotPaid ( description: string, amount: currency ):
description Text describing the not paid amount.
amount Amount not paid.
Remarks Indicates a part of the receipt’s total to not be paid.
by the FiscalReceiptStation property to indicate that part of the receipt total has
not been paid. This method is only supported if CapReceiptNotPaid is true. If this
method is successful, the PrinterState property will remain in
FPTR_PS_FISCAL_RECEIPT_TOTAL state or change to the value
FPTR_PS_FISCAL_RECEIPT_ENDING depending upon whether the entire
receipt total is now accounted for or not. This method is performed synchronously
if AsyncMode is false, and asynchronously if AsyncMode is true.
Value Meaning
The Fiscal Printer is not currently in either the Fiscal
Receipt or Fiscal Receipt Total state.
ErrorCodeExtended =
ErrorCodeExtended =
The amount is invalid.
See Also AmountDecimalPlaces Property, CapReceiptNotPaid Property,
FiscalReceiptStation Property, beginFiscalReceipt Method, endFiscalReceipt
Method, printRec… Methods.

574 Fiscal Printer
printRecPackageAdjustment Method Added in Release 1.6

Syntax printRecPackageAdjustment ( adjustmentType: int32,
description: string, vatAdjustment: string ):

description Text describing the adjustment.
vatAdjustment String containing a list of adjustment(s) for different
Vat(s).
The adjustmentType parameter has one of the following values:
Value Meaning
FPTR_AT_DISCOUNT Discount.
FPTR_AT_SURCHARGE Surcharge.
The vatAdjustment parameter consists of ASCII numeric semicolon delimited
pairs of values which denote each the VAT identifier of the package item to be
adjusted and adjustment amount, separated by a comma.
The number of pairs is delimited by the NumVatRates property.

Remarks Called to give an adjustment for a package of some items booked before. This
adjustment (discount/surcharge) may be either a fixed currency amount or a
percentage amount relating to items combined to an adjustment package.
Each item of the package must be transferred before.
Fixed amount adjustments are only supported if CapPackageAdjustment is true.


Value Meaning

E_ILLEGAL The Fiscal Printer does not support package adjustments
(see the CapPackageAdjustment property), or the
adjustmentType parameter is invalid.


state.
ErrorCodeExtended =
See Also printRecPackageAdjustVoid Method, CapPackageAdjustment Property.

576 Fiscal Printer
printRecPackageAdjustVoid Method Added in Release 1.6

Syntax printRecPackageAdjustVoid ( adjustmentType: int32,

vatAdjustment String containing a list of adjustment(s) to be voided for
different VAT(s).
The adjustmentType parameter has one of the following values:

Value Meaning
FPTR_AT_DISCOUNT Discount.
FPTR_AT_SURCHARGE Surcharge.
The vatAdjustment parameter consists of ASCII numeric semicolon delimited
pairs of values which denote each the VAT identifier of the package item to be
adjusted and adjustment amount, separated by a comma.
The number of pairs is delimited by the NumVatRates property.

Remarks Called to void the adjustment for a package of some items. This adjustment
(discount/surcharge) may be either a fixed currency amount or a percentage
amount relating to the current receipt subtotal.
Fixed amount void adjustments are only supported if CapPackageAdjustment is
true.

an empty string.

Value Meaning

E_ILLEGAL The Fiscal Printer does not support package adjustments
(see the CapPackageAdjustment property), or the
adjustmentType parameter is invalid.


state.
ErrorCodeExtended =
See Also printRecPackageAdjustment Method, CapPackageAdjustment Property,

PreLine Property.

578 Fiscal Printer
printRecRefund Method Updated in Release 1.12

Syntax printRecRefund ( description: string, amount: currency, vatInfo: int32 ):

amount Amount of the refund.
Remarks Processes a refund. The amount is positive, but it is printed as a negative number
and the totals registers are decremented.
by the FiscalReceiptStation property to indicate that a refund has occurred.
an empty string.
If several items of the same item type are to be refunded, then it is recommended
to use printRecItemRefund.

Value Meaning



state.
ErrorCodeExtended =
ErrorCodeExtended =
PreLine Property, printRecItemRefund Method.

580 Fiscal Printer
printRecRefundVoid Method Updated in Release 1.12

Syntax printRecRefundVoid ( description: string, amount: currency,
vatInfo: int32 ):

amount Amount of the voided refund.
Remarks Called to process a void of a refund.
The amount is positive and the totals registers are incremented.
by the FiscalReceiptStation property to indicate that a void of a refund has
occurred.
If CapOnlyVoidLastItem is true, only the last refund item transferred to the
Fiscal Printer can be voided.
If the refund of several items of the same item type is to be voided, then it is
recommended to use printRecItemRefundVoid.

Value Meaning



state.
ErrorCodeExtended =
ErrorCodeExtended =
See Also printRecRefund Method, printRecItemRefundVoid Method,

582 Fiscal Printer
printRecSubtotal Method Updated in Release 1.6

Syntax printRecSubtotal ( amount: currency ):
amount Amount of the subtotal.
Remarks Checks and prints the current receipt subtotal on the station defined by the
If CapCheckTotal is true, the amount is compared to the subtotal calculated by
the Fiscal Printer. If the subtotals match, the subtotal is printed on the station
defined by the FiscalReceiptStation property. If the results do not match, the
receipt is automatically canceled. If CapCheckTotal is false, then the subtotal is
printed on the station defined by the FiscalReceiptStation property and the
parameter is never compared to the subtotal computed by the Fiscal Printer.
PostLine property will be printed. After printing this line PostLine will be reset
to an empty string.
If this method compares the application’s subtotal with the Fiscal Printer’s subtotal
and they do not match, the PrinterState property will be changed to
FPTR_PS_FISCAL_RECEIPT_ENDING.

Value Meaning



state.
ErrorCodeExtended =
The subtotal from the application does not match the
subtotal computed by the Fiscal Printer.
The total computed by the Fiscal Printer is less than
zero.

PostLine Property.

584 Fiscal Printer
printRecSubtotalAdjustment Method Updated in Release 1.11

Syntax printRecSubtotalAdjustment ( adjustmentType: int32,
description: string, amount: currency ):
description Text describing the discount or surcharge.
amount Amount of the adjustment (discount or surcharge).
Value Meaning
a currency value.
percentage value.
percentage value.
Fixed amount discount for an advertising coupon. The
amount parameter contains a currency value. The
instead.
Percentage discount for an advertising coupon. The
amount parameter contains a percentage value. The
recommend to use FPTR_AT_PERCENTAGE_DISCOUNT
instead.
Remarks Applies and prints a discount/surcharge to the current receipt subtotal on the
station defined by the FiscalReceiptStation property. This discount/surcharge
may be either a fixed currency amount or a percentage amount relating to the
current receipt subtotal.
If the discount/surcharge amount is greater than the receipt subtotal, an error
occurs since the subtotal can never be negative.
In many countries discount/surcharge operations cause the printing of a fixed line
of text expressing the kind of operation that has been performed.

Fixed amount discounts are only supported if CapSubAmountAdjustment is

true. Percentage discounts are only supported if CapSubPercentAdjustment is
true. Surcharges are only supported if CapPositiveSubtotalAdjustment is true.
an empty string.
Value Meaning
• Fixed amount discounts are not supported
(see the CapSubAmountAdjustment property).
• Percentage discounts are not supported
(see the CapSubPercentAdjustment property).
• Surcharges are not supported
(see the CapPositiveSubtotalAdjustment property).
state.
(Only applies AsyncMode is false.)
ErrorCodeExtended =
AmountDecimalPlaces Property, CapPositiveSubtotalAdjustment Property,
FiscalReceiptStation Property, PreLine Property.

586 Fiscal Printer
printRecSubtotalAdjustVoid Method Added in Release 1.6

Syntax printRecSubtotalAdjustVoid ( adjustmentType: int32,
amount: currency ):

amount Amount of the adjustment (discount or surcharge).
Value Meaning
a currency value.
percentage value.
percentage value.
Remarks Called to void a preceding subtotal adjustment on the station defined by the
FiscalReceiptStation property. This discount/surcharge may be either a fixed
currency amount or a percentage amount relating to the current receipt subtotal.
Fixed amount void discounts are only supported if CapSubAmountAdjustment
is true. Percentage void discounts are only supported if the property
CapSubPercentAdjustment is true.
an empty string.

Value Meaning

• Fixed amount discounts are not supported
(see the CapSubAmountAdjustment property).
(see the CapSubPercentAdjustment property).
state.
ErrorCodeExtended =

PreLine Property.

588 Fiscal Printer
printRecTaxID Method Added in Release 1.6

Syntax printRecTaxID ( taxId: string ):
taxId Customer identification with identification characters

and tax number.
Remarks Called to print the customers tax identification on the station defined by the
This method is only supported when the Fiscal Printer is in the Fiscal Receipt
Ending state.
Value Meaning

E_ILLEGAL The Fiscal Printer does not support printing tax
identifications.
Ending state.
See Also FiscalReceiptStation Property.

printRecTotal Method Updated in Release 1.6

Syntax printRecTotal ( total: int32, payment: int32, description: string ):
total Application computed receipt total.

payment Amount of payment tendered.
description Text description of the payment or the index of a
predefined payment description.
Remarks Checks and prints the current receipt total on the station defined by the
FiscalReceiptStation property and to tender a payment.
If CapCheckTotal is true, the total is compared to the total calculated by the
Fiscal Printer. If the totals match, the total is printed on both the receipt and journal
along with some fixed text. If the results do not match, the receipt is automatically
canceled. If CapCheckTotal is false, then the total is printed on the receipt and
journal and the parameter is never compared to the total computed by the Fiscal
Printer.
If CapPredefinedPaymentLines is true, then the description parameter contains

the index of one of the Fiscal Printer’s predefined payment descriptions. The index
is typically a single character of the alphabet. The set of allowed values for this
index is to be described in the description of the service and stored in the
PredefinedPaymentLines property.
If payment = total, a line containing the description and payment is printed. The
PrinterState property will be set to FPTR_PS_FISCAL_RECEIPT_ENDING.
If payment > total, a line containing the description and payment is printed
followed by a second line containing the change due. If CapChangeDue property
is true, a description for the change due defined by the ChangeDue property is
printed as the second line. The PrinterState property will be set to
If payment < total, a line containing the description and payment is printed. Since
the entire receipt total has not yet been tendered, the PrinterState property will be
set to FPTR_PS_FISCAL_RECEIPT_TOTAL.
If payment = 0, no line containing the description and payment is printed. The
PrinterState property will be set to FPTR_PS_FISCAL_RECEIPT_TOTAL.
If CapAdditionalLines is false, then receipt trailer lines, fiscal logotype and
receipt cut are executed after the last total line, whenever receipt’s total became
equal to the payment from the application. Otherwise these lines are printed calling
the endFiscalReceipt method.
PostLine property will be printed. After printing this line PostLine will be reset
to an empty string.

590 Fiscal Printer
Value Meaning

state.
ErrorCodeExtended =
• The application computed total does not match the
Fiscal Printer computed total, or
• the total parameter is invalid, or
• the payment parameter is invalid
ErrorCodeExtended =
ErrorCodeExtended =
EFPTR_WORD_NOT_ALLOWED:
The description contains the reserved word.
PredefinedPaymentLines Property, AmountDecimalPlaces Property,
ChangeDue Property, FiscalReceiptStation Property, PostLine Property.

printRecVoid Method Updated in Release 1.6

Syntax printRecVoid ( description: string ):
description Text describing the void.
Remarks Cancels the current receipt.

The receipt is annulled but it is not physically canceled from the Fiscal Printer’s
fiscal memory since fiscal receipts are printed with an increasing serial number
and totals are accumulated in registers. When a receipt is canceled, its subtotal is
subtracted from the totals registers, but it is added to the canceled receipt register.
by the FiscalReceiptStation property to indicate that the receipt has been
canceled.
Normally only a receipt with at least one transaction can be voided. If
CapEmptyReceiptIsVoidable is true also an empty receipt (only the
beginFiscalReceipt method was called) can be voided.
Value Meaning


592 Fiscal Printer

state.
ErrorCodeExtended =
See Also beginFiscalReceipt Method, endFiscalReceipt Method, printRec… Methods

CapEmptyReceiptIsVoidable Property, FiscalReceiptStation Property.

printRecVoidItem Method Deprecated in Release 1.11

Syntax printRecVoidItem ( description: string, amount: currency,
quantity: int32, adjustmentType: int32,
adjustment: currency, vatInfo: int32 ):
description Text description of the item void.
amount Amount of item to be voided.
quantity Quantity of item to be voided.
adjustment Amount of the adjustment (discount or surcharge).
Value Meaning
Fixed amount discount. The adjustment parameter
Fixed amount surcharge. The adjustment parameter
Percentage discount. The adjustment parameter contains
a percentage value.
Percentage surcharge. The adjustment parameter
contains a percentage value.
Remarks Cancels an item that has been added to the receipt and prints a void description on
the station defined by the FiscalReceiptStation property.
amount is a positive number, it will be printed as a negative and will be
decremented from the totals registers.
Otherwise, it contains a VAT amount. Fixed amount discounts/surcharges are only
supported if CapAmountAdjustment is true. Percentage discounts are only
supported if CapPercentAdjustment is true.
If CapOnlyVoidLastItem is true, only the last item transferred to the Fiscal
Printer can be voided.

594 Fiscal Printer

Value Meaning
• Fixed amount adjustments are not supported
(see the CapAmountAdjustment property), or
(see the CapPercentAdjustment property), or
The Fiscal Printer is not currently in the Fiscal Receipt state.
ErrorCodeExtended = EFPTR_BAD_ITEM_QUANTITY:
ErrorCodeExtended =
(Only applies if AsyncMode is false.
CapOnlyVoidLastItem Property, AmountDecimalPlaces Property,

printReport Method Updated in Release 1.11

Syntax printReport ( reportType: int32, startNum: string, endNum: string ):
reportType The kind of report to print.
startNum ASCII string identifying the starting record in Fiscal
Printer memory from which to begin printing
endNum ASCII string identifying the final record in Fiscal Printer
memory at which printing is to end. See reportType
table below to find out the exact meaning of this
parameter.
The reportType parameter has one of the following values:
Value Meaning
FPTR_RT_ORDINAL Prints a report between two fiscal memory record
numbers. If both startNum and endNum are valid and
endNum > startNum, then a report of the period between
startNum and endNum will be printed. If startNum is
valid and endNum is zero, then a report relating only to
startNum will be printed.
FPTR_RT_DATE Prints a report between two dates. The dates are strings
in the format “ddmmyyyyhhmm”, where:
mm month (01 - 12)
yyyy year (1997- ...)
hh hour (00-23)
mm minutes (00-59)
FPTR_RT_EOD_ORDINAL
Prints a report between two Z reports where startNum
and endNum represent a Z report number. If both
startNum and endNum are valid and endNum >
startNum, then a report of the period between startNum
and endNum will be printed. If startNum is valid and
endNum is zero, then a report relating only to startNum
will be printed.
Remarks Prints a report of the fiscal EPROM contents on the receipt that occurred between
two end points.

596 Fiscal Printer

Value Meaning
• The reportType parameter is invalid, or
• One or both of startNum and endNum are invalid, or
• startNum > endNum.
The Fiscal Printer's current state does not allow this state
transition.
printXReport Method
Syntax printXReport ( ):
Remarks Prints a report of all the daily fiscal activities on the receipt. No data will be written
to the fiscal EPROM as a result of this method invocation.
This method is only supported if CapXReport is true. This method is always
performed synchronously.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support X reports (see the
CapXReport property).
state transition.
See Also CapXReport Property.

printZReport Method Updated in Release 1.6

Syntax printZReport ( ):
Remarks Prints a report of all the daily fiscal activities on the receipt. Data will be written
to the fiscal EPROM as a result of this method invocation.
Since running printZReport is implicitly a fiscal end of day function, the
DayOpened property will be set to false.

Value Meaning

state transition.
See Also beginFiscalDocument Method, beginFiscalReceipt Method,
DayOpened Property.

598 Fiscal Printer
resetPrinter Method
Syntax resetPrinter ( ):
Remarks Forces the Fiscal Printer to return to Monitor state. This forces any interrupted
operations to be canceled and closed. This method must be invoked when the
Fiscal Printer is not in a Monitor state after a successful call to the claim method
and successful setting of the DeviceEnabled property to true. This typically
happens if a power failures occurs during a fiscal operation.
Calling this method does not close the Fiscal Printer, i.e., does not force a Z report
to be printed.
The Device will handle this command as follows:
• If the Fiscal Printer was in either Fiscal Receipt, Fiscal Receipt Total or Fiscal
Receipt Ending state, the receipt will be ended without updating any registers.
• If the Fiscal Printer was in a non-fiscal state, the Fiscal Printer will exit that
state.
• If the Fiscal Printer was in the training state, the Fiscal Printer will exit the
training state.

setCurrency Method Added in Release 1.6

Syntax setCurrency ( newCurrency: int32 ):
newCurrency The new currency.
The newCurrency parameter has one of the following values:

Value Meaning
FPTR_SC_EURO Change to the EURO currency.

Remarks Called to change to a new currency, e.g., EURO.
This method is only supported if CapSetCurrency is true and can only be called
while DayOpened is false.
The actual currency is kept in the ActualCurrency property.
Value Meaning

• The Fiscal Printer does not support this method (see
the CapSetCurrency property), or
• The Fiscal Printer has already begun the fiscal day
(see the DayOpened property), or
• the specified newCurrency value is not valid.
See Also ActualCurrency Property, CapSetCurrency Property, DayOpened Property.

600 Fiscal Printer
setDate Method
Syntax setDate ( date: string ):
date Date and time as a string.
Remarks Sets the Fiscal Printer’s date and time.

The date and time is passed as a string in the format “ddmmyyyyhhmm”, where:
mm month (1 - 12)
yyyy year (1997-)
hh hour (0-23)
mm minutes (0-59)
This method can only be called while DayOpened is false.

Value Meaning
E_ILLEGAL The Fiscal Printer has already begun the fiscal day (see
the DayOpened property).
E_EXTENDED ErrorCodeExtended = EFPTR_BAD_DATE:
One of the entries of the date parameters is invalid.
See Also DayOpened Property.

setHeaderLine Method Updated in Release 1.6

Syntax setHeaderLine ( lineNumber: int32, text: string, doubleWidth: boolean ):
lineNumber Line number of the header line to set.

text Text to which to set the header line.
doubleWidth Print this line in double wide characters.
Remarks Sets one of the fiscal receipt header lines. The text set by this method will be stored
by the Fiscal Printer and retained across power losses.
If CapMultiContractor property is true, header lines can be defined for different
contractors specified by the ContractorId property.
The lineNumber parameter must be between 1 and the value of the
NumHeaderLines property. If text is an empty string (“”), then the header line is
unset and will not be printed. The doubleWidth characters will be printed if the
Fiscal Printer supports them. See the CapDoubleWidth property to determine if
they are supported. This method is only supported if CapSetHeader is true. This
method can only be called while DayOpened is false.
Value Meaning

• The Fiscal Printer does not support setting header
lines (see the CapSetHeader property), or
• the lineNumber parameter was invalid.
E_EXTENDED ErrorCodeExtended =
The text parameter is too long or contains a reserved
word.
See Also CapDoubleWidth Property, CapMultiContractor Property, CapSetHeader

Property, ContractorId Property, DayOpened Property, NumHeaderLines
Property.

602 Fiscal Printer
setPOSID Method
Syntax setPOSID ( POSID: string, cashierID: string ):
POSID Identifier for the POS system.

cashierID Identifier of the current cashier.
Remarks Sets the POS and cashier identifiers. These values will be printed when each fiscal
receipt is closed.
This method is only supported if CapSetPOSID is true. This method can only be
called while DayOpened is false.
Value Meaning

• The Fiscal Printer does not support setting the POS
identifier (see the CapSetPOSID property), or
• The printer has already begun the fiscal day (see the
DayOpened property), or
• Either the POSID or cashierID parameter is invalid.
See Also CapSetPOSID Property, DayOpened Property.

setStoreFiscalID Method
Syntax setStoreFiscalID ( ID: string ):
ID Fiscal identifier.
Remarks Sets the store fiscal ID. This value is retained by the Fiscal Printer even after power
failures. This ID is automatically printed by the Fiscal Printer after the fiscal
receipt header lines.
This method is only supported if CapSetStoreFiscalID is true. This method can
only be called while DayOpened is false.
Value Meaning

• The Fiscal Printer does not support setting the store
fiscal identifier (see the CapSetStoreFiscalID
property), or
• The ID parameter was invalid.
See Also CapSetStoreFiscalID Property, DayOpened Property.

604 Fiscal Printer
setTrailerLine Method
Syntax setTrailerLine ( lineNumber: int32, text: string, doubleWidth: boolean ):
lineNumber Line number of the trailer line to set.

text Text to which to set the trailer line.
doubleWidth Print this line in double wide characters.
Remarks Sets one of the fiscal receipt trailer lines. The text set by this method will be stored
by the Fiscal Printer and retained across power losses.
The lineNumber parameter must be between 1 and the value of the
NumTrailerLines property. If text is an empty string (“”), then the trailer line is
unset and will not be printed. The doubleWidth characters will be printed if the
Fiscal Printer supports them. See the CapDoubleWidth property to determine if
they are supported. This method is only supported if CapSetTrailer is true. This
method can only be called while DayOpened is false.
Value Meaning

• The Fiscal Printer does not support setting the receipt
trailer lines (see the CapSetTrailer property), or
The text parameter is too long or contains a reserved
word.
See Also CapDoubleWidth Property, CapSetTrailer Property, DayOpened Property,

NumTrailerLines Property.

setVatTable Method Updated in Release 1.11

Syntax setVatTable ( ):
Remarks Sends the VAT table built inside the Service to the Fiscal Printer. The VAT table
is built one entry at a time using the setVatValue method.
This method is only supported if CapHasVatTable and CapSetVatTable are
true. This method can only be called while DayOpened is false.
Value Meaning

• The Fiscal Printer does not support VAT tables or
their setting (see the CapHasVatTable or
CapSetVatTable property), or
(see the DayOpened property).
See Also CapHasVatTable Property, CapSetVatTable Property, DayOpened Property,

setVatValue Method.

606 Fiscal Printer
setVatValue Method Updated in Release 1.11

Syntax setVatValue ( vatID: int32, vatValue: string ):
vatID Index of the VAT table entry to set.
vatValue Tax value as a percentage.
Remarks Sets the value of a specific VAT class in the VAT table. The VAT table is built
one entry at a time in the Service using this method. The entire table is then sent
to the Fiscal Printer at one time using the setVatTable method.
This method is only supported if CapHasVatTable and CapSetVatTable are
true. This method can only be called while DayOpened is false.

Value Meaning
• The Fiscal Printer does not support VAT tables (see
the CapHasVatTable or CapSetVatTable property),
or
• The Fiscal Printer does not support changing an
existing VAT value (see the CapSetVatTable
property).
See Also CapHasVatTable Property, CapSetVatTable Property, DayOpened Property,

setVatTable Method.

verifyItem Method
Syntax verifyItem ( itemName: string, vatID: int32 ):
itemName Item to be verified.

vatID VAT identifier of the item.
Remarks Compares itemName and its vatID with the values stored in the Fiscal Printer.
This method is only supported if CapHasVatTable is true. This method can only
be called while the Fiscal Printer is in the Item List state.
Value Meaning
E_ILLEGAL The Fiscal Printer does not support VAT tables (see the
CapHasVatTable property).
The Fiscal Printer is not currently in the Item List state.
ErrorCodeExtended =
The item name is too long or contains a reserved word.
See Also CapHasVatTable property, setVatTable Method.

608 Fiscal Printer

DirectIOEvent
means for a vendor-specific Fiscal Printer Service to provide events to the
Service.
from being used with other vendor’s Fiscal Printer devices which may not have

Description Notifies the application that a Fiscal Printer error has been detected and that a
Codes on page 52.
ErrorCodeExtended
ErrorLocus int32 Location of the error, and is set to EL_OUTPUT
indicating that the error occurred while processing
asynchronous output.


values below.
following values:
Value Meaning
EFPTR_COVER_OPEN The Fiscal Printer cover is open.
EFPTR_JRN_EMPTY The journal station is out of paper.
EFPTR_REC_EMPTY The receipt station is out of paper.
EFPTR_SLP_EMPTY A form is not inserted in the slip station.
EFPTR_SLP_FORM The device was taken out of removal mode
while a form was still present.
EFPTR_WRONG_STATE The requested method could not be executed in
the Fiscal Printer’s current state.
EFPTR_TECHNICAL_ASSISTANCE
The Fiscal Printer has encountered a severe
error condition. Calling for Fiscal Printer
technical assistance is required.
EFPTR_CLOCK_ERROR The Fiscal Printer’s internal clock has failed.
EFPTR_FISCAL_MEMORY_FULL
The Fiscal Printer’s fiscal memory has been
exhausted.
EFPTR_FISCAL_MEMORY_DISCONNECTED
The Fiscal Printer’s fiscal memory has been
disconnected.
EFPTR_FISCAL_TOTALS_ERROR
The Grand Total in working memory does not
match the one in the EPROM.
EFPTR_BAD_ITEM_QUANTITY
The Quantity parameter is invalid.
EFPTR_BAD_ITEM_AMOUNT The Amount parameter is invalid.
EFPTR_BAD_ITEM_DESCRIPTION
The Description parameters is either to long,
contains illegal characters or contains the
reserved word.
EFPTR_RECEIPT_TOTAL_OVERFLOW
EFPTR_BAD_VAT The Vat parameter is invalid.
EFPTR_BAD_PRICE The Price parameter is invalid.
EFPTR_BAD_DATE The date parameter is invalid.
EFPTR_WORD_NOT_ALLOWED
The description contains a reserved word.
EFPTR_NEGATIVE_TOTAL The Fiscal Printer’s computed total or subtotal
is less than zero.
EFPTR_MISSING_DEVICES Some of the other devices which according to
the local fiscal legislation are to be connected
has been disconnected. In some countries in

610 Fiscal Printer
order to use a fiscal Fiscal Printer a full set of

peripheral devices are to be connected to the
POS (such as cash drawer and customer
display). In case one of these devices is not
present sales are not allowed.
EFPTR_BAD_LENGTH The length of the string to be printed as post or
pre line is too long.
EFPTR_MISSING_SET_CURRENCY
The Fiscal Printer is expecting the activation of
a new currency.
EFPTR_DAY_END_REQUIRED
The completion of the fiscal day is required by
calling printZReport. No further fiscal
receipts or documents can be started before this
is done.
Value Meaning
ER_CLEAR Clear all buffered output data, including all
asynchronous output. The error state is exited.
ER_RETRY Retry the asynchronous output. The error state is exited.
The default.
Remarks Enqueued when an error is detected and the Service’s State transitions into the
error state.
page 62.
OutputCompleteEvent
is complete.


Description Notifies the application that a Fiscal Printer has had an operation status change.
Status int32 Indicates the status change, and has one of the
following values:
Value Meaning
FPTR_SUE_COVER_OPEN Fiscal Printer cover is open.
FPTR_SUE_COVER_OK Fiscal Printer cover is closed.
FPTR_SUE_JRN_EMPTY No journal paper.
FPTR_SUE_JRN_NEAREMPTYJournal paper is low.
FPTR_SUE_JRN_PAPEROK Journal paper is ready.
FPTR_SUE_REC_EMPTY No receipt paper.
FPTR_SUE_REC_NEAREMPTYReceipt paper is low.
FPTR_SUE_REC_PAPEROK Receipt paper is ready.
FPTR_SUE_SLP_EMPTY No slip form is inserted, and no slip form has
been detected at the entrance to the slip station.
(See “Model” on page 478 for further details on
slip properties and events.)
FPTR_SUE_SLP_NEAREMPTY Almost at the bottom of the slip form.
FPTR_SUE_SLP_PAPEROK Slip form is inserted.
FPTR_SUE_IDLE All asynchronous output has finished, either
successfully or because output has been
cleared. The Fiscal Printer State is now
S_IDLE. The FlagWhenIdle property must be
true for this event to be delivered, and the
property is automatically reset to false just
before the event is delivered.
process.

612 Fiscal Printer
Release 1.8 and later – Specific Cover State Reporting

Starting with Release 1.8, StatusUpdateEvents for specific stations’ covers are
supported. If a Fiscal Printer has only one cover or if it cannot determine/report
which covers are open, then only the original FPTR_SUE_COVER_OPEN and
FPTR_SUE_COVER_OK events should be fired.
For Fiscal Printers supporting multiple covers, the original events should also be
fired for compatibility with current applications. In these cases, the station-specific
event should be fired first, followed by the original event.
If more than one cover is open, the original FPTR_SUE_COVER_OPEN event
should only be fired once after a cover is opened. A FPTR_SUE_COVER_OK
event should only be fired after all the covers are closed.
The event’s Status attribute can contain one of the following additional values to
indicate a status change.
Value Meaning
FPTR_SUE_JRN_COVER_OPEN Journal station cover is open.
FPTR_SUE_JRN_COVER_OK Journal station cover is closed.
FPTR_SUE_REC_COVER_OPEN Receipt station cover is open.
FPTR_SUE_REC_COVER_OK Receipt station cover is closed.
FPTR_SUE_SLP_COVER_OPEN Slip station cover is open.
FPTR_SUE_SLP_COVER_OK Slip station cover is closed.
Remarks Enqueued when a significant status event has occurred.


C H A P T E R 1 6
Gate
This Chapter defines the Gate device category.
Summary

614 Gate
CapGateStatus: boolean { read-only } 1.12 open
GateStatus: int32 { read-only } 1.12 open & enable

Common
Name Version
close ( ): 1.12
release ( ): 1.12
clearInput ( ): Not
void { } supported
void { } supported
void { } supported
Specific
Name
openGate ( ): 1.12
waitForGateClose ( timeout: int32 ): 1.12

Summary 615


616 Gate
General Information
The Gate programmatic name is “Gate”.

Various doors and gates can be controlled by the Gate device category, examples
are:
• Kiosk front door which can be opened by an application for servicing.
• Self Checkout door which can be opened by an application for servicing.
• Exit gate in kiosk or self checkout environments where a customer scans a
barcode printed on the receipt in order to open the gate.
Capabilities
The Gate Control has the following capability:

• Supports a command to “open” the gate.
The Gate Control may have the following additional capability:

• Gate status reporting of such a nature that the service can determine whether
the gate is opened or closed in environments where the gate is accessible via
a hardware port.

Gate Class Diagram
The following diagram shows the relationships between the Gate classes.

UposException «sends» BaseControl «uses» UposConst GateConst
«sends» «uses»
«interface»
GateControl
+CapGateStatus : boolean
+GateStatus : int32
+openGate() : void
+waitForGateClose(timeout : int32) : void
«fires» «fires»
«event» «event»
+Data : int32
+Obj : object

618 Gate
Gate Sequence Diagram

The following sequence diagram show the typical usage of the Gate device
illustrating the device sharing model.
NOTE: We are assuming that the :ClientApp(s) already successfully opened the controls. This
means that the platform specific loading/configuration/creation code executed successfully
:StatusUpdate Gate
:ClientApp0 :ClientApp1 gate0:Gate gate1:Gate Event :Gate Service0 :Gate Service1
Device
1: setDeviceEnabled(true) 3: connect or somehow have access

2: setDeviceEnabled(true) to the hardware
Service returns
current status of
the gate
4: openGate()
5: openGate() 6: send command to open gate
Gate device is assumed

If the command to open the physical Gate
open successfully and
is successful then this will result in
GateStatus property is
StatusUpdateEvent delivered to any
now GATE_GS_OPEN
registered listeners. This is not shown in
this diagram for simplicity.
8: setDeviceEnabled(true) 9: might communicate with
device
10: openGate()
11: openGate()
12: send command to open
gate
13: claim(timeout)
Assume the Gate is
14: claim(timeout)
successfully claimed
at this point by
:ClientApp1
15: openGate()
16: openGate()
This call results in a UposException
17: throw UposException since the Gate device is claimed by
the gate1 instance that is used by
:ClientApp1
18: openGate() This call is successful

19: openGate() and Gate device is
open since gate1
Assume that both claimed the device
:ClientApp0 and :ClientApp1 20: new sucessfully.
registered to receive events
22: deliver SUE to control 21: send command

to open gate
24: new
StatusUpdateEvent is delivered
to all registered handlers, even
though, in the situation above,
only :ClientApp1 is allowed to
26: notify client of new event 25: deliver SUE to control
call openGate() – since it
sucessfully claimed the device.
Service0 also detects the gate is opened,

either via a message from Service1, a SUE
from Service1 or a lower level interface

Device Sharing
The gate is a sharable device. Its device sharing rules are:

fired to all of these applications.
• If one application claims the gate, then only that application may call
openGate and waitForGateClose. This feature provides a degree of security,
such that these methods may effectively be restricted to the main application
if that application claims the device at startup.

620 Gate
CapGateStatus Property
Syntax CapGateStatus: boolean { read-only, access after open }
Remarks If true, the gate can report status. If false, the Service is not able to determine
whether the gate is open or closed.
GateStatus Property
Syntax GateStatus: int32 { read-only, access after open-enable }
Remarks Holds the current status of the device. It has one of the following values:
Value Meaning
GATE_GS_CLOSED The gate is closed.
GATE_GS_OPEN The gate is open.
GATE_GS_BLOCKED The gate is blocked.
GATE_GS_MALFUNCTION The gate has a hardware problem. Technical
assistance is needed.
If the capability CapGateStatus is false, then the device does not support status
reporting, and this property has no meaning.
See Also CapGateStatus Property.

openGate Method
Syntax openGate ( ):
Remarks Opens the gate.
waitForGateClose Method
Syntax waitForGateClose ( timeout: int32 ):
timeout Maximum number of milliseconds to wait until the gate
is closed before returning control back to the
application. If FOREVER (-1), the method waits as long
as needed until the gate is closed or an error occurs.
Remarks Waits until the gate is closed.
Unless a UposException is thrown, this method will not return to the application
while the gate is open.
If CapGateStatus is false, then the device does not support status reporting, and
this method will return immediately.
Value Meaning
E_TIMEOUT The timeout period expired before the gate was closed.
See Also CapGateStatus Property.

622 Gate
DirectIOEvent
means for a vendor-specific Gate Service to provide events to the application that
Service.
from being used with other vendor’s Gate devices which may not have any

StatusUpdateEvent
Description Notifies the application when the status of the Gate changes.

Status int32 The status reported from the Gate.
Value Description
GATE_SUE_CLOSED The gate is closed.
GATE_SUE_OPEN The gate is open.
GATE_SUE_BLOCKEDThe gate is blocked.
GATE_SUE_MALFUNCTION
The gate has a hardware problem. Technical assistance
is needed.
process.
Remarks If CapGateStatus is false, then the device does not support status reporting, and
this event will never be delivered to report status changes.
See Also CapGateStatus Property, “Events” on page 51.

624 Gate

C H A P T E R 1 7
Hard Totals
This Chapter defines the Hard Totals device category.
Summary

626 Hard Totals
CapErrorDetection: boolean { read-only } 1.0 open
CapSingleFile: boolean { read-only } 1.0 open
CapTransactions: boolean { read-only } 1.0 open
FreeData: int32 { read-only } 1.0 open & enable
NumberOfFiles: int32 { read-only } 1.0 open & enable
TotalsSize: int32 { read-only } 1.0 open & enable
TransactionInProgress: boolean { read-only } 1.0 open

Common
Name Version
close ( ): 1.0
release ( ): 1.0
void { raises-exception, use after open, enable }a
clearInput ( ): Not
void { } supported
void { } supported
void { } supported

Summary 627
Specific
beginTrans ( ): 1.0
claimFile ( hTotalsFile: int32, timeout: int32 ): 1.0
void { raises-exception, use after open, enable } b
commitTrans ( ): 1.0
create ( fileName: string, inout hTotalsFile: int32, size: int32, 1.0
errorDetection: boolean ):
void { raises-exception, use after open, enable } a
delete ( fileName: string ): 1.0
find ( fileName: string, inout hTotalsFile: int32, inout size: int32 ): 1.0
findByIndex ( index: int32, inout fileName: string ): 1.0
read ( hTotalsFile: int32, inout data: binary, offset: int32, count: int32 ): 1.0
recalculateValidationData ( hTotalsFile: int32 ): 1.0
releaseFile ( hTotalsFile: int32 ): 1.0
rename ( hTotalsFile: int32, fileName: string ): 1.0
rollback ( ): 1.0
setAll ( hTotalsFile: int32, value: byte ): 1.0
validateData ( hTotalsFile: int32 ): 1.0
write ( hTotalsFile: int32, data: binary, offset: int32, count: int32 ): 1.0
a. Also requires that no other application has claimed the hard totals device.
b. Also requires that no other application has claimed the hard totals device or
the file on which this method acts.

628 Hard Totals


General Information
The Hard Totals programmatic name is “HardTotals”.
Capabilities
The Hard Totals device has the following minimal set of capabilities:
• Supports at least one totals file with the name “” (the empty string) in an area
of totals memory. Each totals file is read and written as if it were a sequence
of byte data.
• Creates each totals file with a fixed size and may be deleted, initialized, and
claimed for exclusive use.
The Hard Totals device may have the following additional capabilities:
• Supporting additional named totals files. They share some characteristics of a
file system with only a root directory level. In addition to the minimal
capabilities listed above, each totals file may also be renamed.
• Supporting transactions, with begin and commit operations, plus rollback.
• Supporting advanced error detection. This detection may be implemented
through hardware or software.

630 Hard Totals
Hard Totals Class Diagram
The following diagram shows the relationships between the Hard Totals classes.
<<utility>>
UposConst
(from upos)
<<uses>>
<<ex ception>> <<Interface>>

<<event>> Upos Ex ception BaseControl
DirectIOEvent (from upos) (from upos) <<utility>>
(from events) HardTotalsConst
<<prop>> EventNumber : int 32 <<sends>> (from upos)
<<uses>>
<<sends>>
fires
<<Interface>>
HardTotalsControl
(from upos)
<<capability>> CapErrorDetection : boolean
<<capability>> CapSingleFile : boolean
<<capability>> CapTransactions : boolean
<<event>> <<prop>> FreeData : int32
StatusUpdateEvent <<prop>> NumberOfFiles : int32
(from events) <<prop>> TotalsSize : int32
fires
<<prop>> TransactionInProgress : boolean
beginTrans() : void
claimFile(hTotalsSize : int32, timeout : int32) : void
commitTrans() : void
create(fileName : string, inout hTotalsFile : int32, size : int32, errorDetection : boolean) : void
delete(fileName : string) : void
find(fileName : string, inout hTotalsFile : int32, inout size : int32) : void
findByIndex(index : int32, inout fileName : string) : void
read(hTotalsSize : int32, inout data : binary, offset : int32, count : int32) : void
recalculateValidationData(hTotalsSize : int32) : void
releaseFile(hTotalsFile : int32) : void
rename(hTotalsFile : int32, fileName : string) : void
rollback() : void
setAll(hTotalsFile : int32, value : byte) : void
validateData(hTotalsFile : int32) : void
write(hTotalsFile : int32, data : binary, offset : int32, count : int32) : void

Hard Totals Sequence Diagram Added in Release 1.7

The following sequence diagram shows the typical usage of the Hard Totals
device, and assumes that a file already exists on the device containing data. It also
demonstrates the transactional capabilities of the Hard Totals device.
NOTE: we are assuming that the :ClientApp already successfully opened and enabled the HardTotals device. This
means that the DeviceEnabled property is == true. Also assumes that file by name fileName is already created
:ClientApp :HardTotals :HardTotalsService
1: getTotalSize()
2: getTotalSize()
3: getFreeData() 4: getFreeData()
5: gather data to write to totals
6: find(fileName,hTotalsFile, size)
7: find(fileName,hTotalsFile, size)
9: hTotalsFile and size 8: hTotalsFile and size

Assumes that the
claimFile succeeded (also
implies that no other
10: claimFile(hTotalsFile, timeout)
11: claimFile(hTotalsFile, timeout) controls or application is
using this file). Note also
12: write(hTotalsFile, data, offset, count) that claimFile(...) is not
13: write(hTotalsFile, data, offset, count) required to write to the
totals file.
The following section tries to demonstrate the
transactional capabilities of the HardTotals
device. After this call succeeds
14: beginTrans() the data2 contains the
15: beginTrans() last value written data1.
16: write(hTotalsFile, data1, offset1, count1) 17: write(hTotalsFile, data1, offset1, count1)
18: read(hTotalsFile, data2, offset1, count1) At this point the started

19: read(hTotalsFile, data2, offset1, count1) transaction ended and
Assume user TransactionInProgress
decided to undo property is now false. If
previous data write. instead commitTrans()
20: rollback() was called then all writes
21: rollback()
would be saved to the
totals area and
transaction would end.
22: read(hTotalsFile, data2, offset1, count1) 23: read(hTotalsFile, data2, offset1, count1)
The return values in data2

now matches the data
values since the values
last written are discarded
by the rollback() call. This
is due to the fact that the
file was claimed thus
guaranteeing that no other
writes could have occurred.

632 Hard Totals
Model
Totals memory is frequently a limited but secure resource - perhaps of only several
thousand bytes of storage. The following is the general model of the Hard Totals:
• A Hard Totals device is logically treated as a sequence of byte data, which the
application subdivides into “totals files.” This is done by the create method,
which assigns a name, size, and error detection level to the totals file. Totals
files have a fixed-length that is set at create time.
At a minimum, a single totals file with the name “” (the empty string) can be
created and manipulated. Optionally, additional totals files with arbitrary
names may be created.
Totals files model many of the characteristics of a traditional file system. The
intent, however, is not to provide a robust file system. Rather, totals files allow
partitioning and ease of access into what is frequently a limited but secure
resource. In order to reduce unnecessary overhead usage of this resource,
directory hierarchies are not supported, file attributes are minimized, and files
may not be dynamically resized.
• The following operations may be performed on a totals file:

• read: Read a series of data bytes.
• write: Write a series of data bytes.
• setAll: Set all the data in a totals file to a value.
• find: Locate an existing totals file by name, and return a file handle and
size.
• findByIndex: Enumerate all of the files in the Hard Totals area.
• delete: Delete a totals file by name.
• rename: Rename an existing totals file.
• claimFile: Gain exclusive access to a specific file for use by the claiming
application. A timeout value may be specified in case another application
maintains access for a period a time.
The common claim method may also be used to claim the entire Hard
Totals device.
• releaseFile: Release exclusive access to the file.
• The FreeData property holds the current number of unassigned data bytes.
• The TotalsSize property holds the totals memory size.
• The NumberOfFiles property holds the number of totals files that exist in the
hard totals device.

• Transaction operations are optionally supported. A transaction is defined as a

series of data writes to be applied as an atomic operation to one or more Hard
Totals files.
During a transaction, data writes will typically be maintained in memory until
a commit or rollback. Also FreeData will typically be reduced during a
transaction to ensure that the commit has temporary totals space to perform the
commit as an atomic operation.
• beginTrans: Marks the beginning of a transaction.
• commitTrans: Ends the current transaction, and saves the updated data.
Software and/or hardware methods are used to ensure that either the entire
transaction is saved, or that none of the updates are applied.
This will typically require writing the transaction to temporary totals

space, setting state information within the device indicating that a commit
is in progress, writing the data to the totals files, and freeing the temporary
totals space. If the commit is interrupted, perhaps due to a system power
loss or reset, then when the Hard Totals Service is reloaded and
initialized, it can complete the commit by copying data from the
temporary space into the totals files. This ensures the integrity of related
totals data.
• rollback: Ends the current transaction, and discards the updates. This
may be useful in case of user intervention to cancel an update. Also, if
advanced error detection shows that some totals data cannot be read
properly in preparation for an update, then the transaction may need to be
aborted.
• TransactionInProgress: Holds the current state of transactions.
The application should claim the files used during a transaction so that no
other Hard Totals Control claims a file before commitTrans, causing the
commit to fail, with the exception’s ErrorCode reflecting an already claimed
status.
• Advanced error detection is optionally supported by the following:
• A read or a write may report a validation error. Data is usually divided
into validation blocks, over which sumchecks or CRCs are maintained.
The size of validation data blocks is determined by the Service.
A validation error informs the application that one or more of the
validation blocks containing the data to be read or written may be invalid
due to a hardware error. (An error on a write can occur when only a
portion of a validation block must be changed. The validation block must
be read and the block validated before the portion is changed.)
When a validation error is reported, it is recommended that the application
read all of the data in the totals file. The application will want to determine
which portions of data are invalid, and take action based on the results of
the reads.
• recalculateValidationData may be called to cause recalculation of all
validation data within a totals file. This may be called after recovery has
been performed as in the previous paragraph.

634 Hard Totals
• validateData may be called to verify that all data within a totals file
passes validation.
• Data writes automatically cause recalculation of validation data for the
validation block or blocks in which the written data resides.
• Since advanced error detection usually imposes a performance penalty,
the application may choose to select this feature when each totals file is
created.
Device Sharing
The hard totals device is sharable. Its device sharing rules are:
• After opening the device, most properties are readable.
properties and methods.
applications may access its properties and methods.
• One application may claim the hard totals device. This restricts all other
applications from reading, changing, or claiming any files on the device.
• One application may claim a hard totals file. This restricts all other
applications from reading, changing, or claiming the file, and from claiming
the hard totals device.

CapErrorDetection Property
Syntax CapErrorDetection: boolean { read-only, access after open }
Remarks If true, then advanced error detection is supported.
CapSingleFile Property
Syntax CapSingleFile: boolean { read-only, access after open }
Remarks If true, then only a single file, identified by the empty string (“”), is supported.
CapTransactions Property
Syntax CapTransactions: boolean { read-only, access after open }
Remarks If true, then transactions are supported.
FreeData Property
Syntax FreeData: int32 { read-only, access after open-enable }
Remarks Holds the number of bytes of unallocated data in the Hard Totals device.
It is initialized to an appropriate value when the device is enabled and is updated
as files are created and deleted. If creating a file requires some overhead to
support the file information, then this overhead is not included in what is reported
by this property. This guarantees that a new file of size FreeData may be created.
Data writes within a transaction may temporarily reduce what’s reported by this
property, since some Hard Totals space may need to be allocated to prepare for the
transaction commit. Therefore, the application should ensure that sufficient
FreeData is maintained to allow its maximally sized transactions to be performed.
See Also create Method, write Method.

636 Hard Totals
NumberOfFiles Property
Syntax NumberOfFiles: int32 { read-only, access after open-enable }
Remarks Holds the number of totals file currently in the Hard Totals device.
See Also FreeData Property.
TotalsSize Property
Syntax TotalsSize: int32 { read-only, access after open-enable }
Remarks Holds the size of the Hard Totals area. This size is equal to the largest totals file
that can be created if no other files exist.
This property is initialized when the device is enabled.
See Also FreeData Property.
TransactionInProgress Property
Syntax TransactionInProgress: boolean { read-only, access after open }
Remarks If true, then the application is within a transaction.
See Also beginTrans Method.

beginTrans Method
Syntax beginTrans ( ):
Remarks Marks the beginning of a series of Hard Totals writes that must either be applied
as a group or not at all.
Value Meaning
E_ILLEGAL Transactions are not supported by this device.

See Also commitTrans Method, rollback Method.
claim Method (Common)

Syntax claim ( timeout: int32 ):
exclusive access to be satisfied. If zero, the method attempts to claim the device,
then returns the appropriate status immediately. If FOREVER (-1), the method
waits as long as needed until exclusive access is satisfied.
Remarks Requests exclusive access to the device.
If any other application has claimed exclusive access to any of the hard totals files
by using claimFile, then this claim cannot be satisfied until those files are released
by releaseFile.
Value Meaning

E_TIMEOUT Another application has exclusive access to the device
or one or more of its files and did not relinquish control
before timeout milliseconds expired.
See Also “Device Sharing Model” on page 50, release Method, claimFile Method,
releaseFile Method.

638 Hard Totals
claimFile Method Updated in Release 1.8

Syntax claimFile ( hTotalsFile: int32, timeout: int32 ):
hTotalsFile Handle to the totals file that is to be claimed.

timeout The time in milliseconds to wait for the file to become
available. If zero, the method attempts to claim the file,
then returns the appropriate status immediately.
If FOREVER (-1), the method waits as long as needed
until exclusive access is satisfied.
Remarks Attempts to gain exclusive access to a specific file for use by the claiming
application. Once granted, the application maintains exclusive access until it
explicitly releases access or until the device is closed.
If another application has claimed exclusive access to this file by using this
method, or if another application has claimed exclusive access to the entire totals
area by using claim, then this request cannot be satisfied until such claims have
been released.
All claims are released when the application calls the close method.
Value Meaning
E_ILLEGAL The handle is invalid, or an invalid timeout parameter
was specified.
E_TIMEOUT The timeout value expired before another application
released exclusive access of either the requested totals
file or the entire totals area.
See Also claim Method, releaseFile Method.
commitTrans Method
Syntax commitTrans ( ):
Remarks Ends the current transaction. All writes between the previous beginTrans method
and this method are saved to the Hard Totals areas.
Value Meaning
E_ILLEGAL Transactions are not supported by this device, or no
transaction is in progress.
See Also beginTrans Method, rollback Method.

create Method
Syntax create ( fileName: string, inout hTotalsFile: int32, size: int32,
errorDetection: boolean ):
fileName The name to be assigned to the file. Must be no longer than 10

characters. All displayable ASCII characters (0x20 through
0x7F) are valid.
hTotalsFile Handle of the newly created totals file. Set by the method.
size The byte array size for the data. Once created, the array size
and therefore the file size used to store the array cannot be
changed – totals files are fixed-length files.
errorDetection The level of error detection desired for this file: If true, then the
Service will enable advanced error detection if supported. If
false, then higher performance access is required, so advanced
error detection need not be enabled for this file.
Remarks Creates a totals file with the specified name, size, and error detection level. The
data area is initialized to binary zeros.
If CapSingleFile is true, then only one file may be created, and its name must be
the empty string (“”). Otherwise, the number of totals files that may be created is
limited only by the free space available in the Hard Totals area.
Value Meaning
E_CLAIMED Cannot create because the entire totals file area is

claimed by another application.
E_ILLEGAL The fileName is too long or contains invalid characters.
E_EXISTS fileName already exists.
E_EXTENDED ErrorCodeExtended = ETOT_NOROOM:
There is insufficient room in the totals area to create the
file.
See Also find Method, delete Method, rename Method.

640 Hard Totals
delete Method
Syntax delete ( fileName: string ):
The fileName parameter specifies the totals file to be deleted.
Remarks Deletes the named file.
Value Meaning
E_CLAIMED Cannot delete because either the totals file or the entire
totals area is claimed by another application.
E_ILLEGAL The fileName is too long or contains invalid characters.
See Also create Method, find Method, rename Method.
find Method
Syntax find ( fileName: string, inout hTotalsFile: int32, inout size: int32 ):
fileName The totals file name to be located.

hTotalsFile Handle of the totals file. Set by the method.
size The length of the file in bytes. Set by the method.
Remarks Locates an existing totals file.
Value Meaning
E_CLAIMED Cannot find because the entire totals file area is claimed
by another application.
E_ILLEGAL The fileName contains invalid characters.
See Also create Method, delete Method, rename Method.

findByIndex Method
Syntax findByIndex ( index: int32, inout fileName: string ):
index The index of the totals file name to be found.

fileName The file name associated with index. Set by the method.
Remarks Determines the totals file name currently associated with the given index.
This method provides a means for enumerating all of the totals files currently
defined. An index of zero will return the file name at the first file position, with
subsequent indices returning additional file names. The largest valid index value
is one less than NumberOfFiles.
The creation and deletion of files may change the relationship between indices and
the file names; the data areas used to manage file names and attributes may be
compacted or rearranged as a result. Therefore, the application may need to claim
the device to ensure that all file names are retrieved successfully.
Value Meaning
E_CLAIMED Cannot find because the entire totals file area is claimed
by another application.
E_ILLEGAL The index is greater than the largest file index that is
currently defined.
See Also create Method, find Method.

642 Hard Totals
read Method Updated in Release 1.7

Syntax read ( hTotalsFile: int32, inout data: binary, offset: int32, count: int32 ):
hTotalsFile Totals file handle returned from a create or find

method.
data1 The data buffer in which the totals data will be placed.
Array length must be at least count.
offset Starting offset for the data to be read.
count Number of bytes of data to read.
Remarks Reads data from a totals file.
Value Meaning
E_CLAIMED Cannot read because either the totals file or the entire
E_ILLEGAL The handle is invalid, part of the data range is outside the
bounds of the totals file, or data array length is less than
count.
E_EXTENDED ErrorCodeExtended = ETOT_VALIDATION:
A validation error has occurred while reading data.
See Also write Method

recalculateValidationData Method
Syntax recalculateValidationData ( hTotalsFile: int32 ):
The hTotalsFile parameter contains the handle of a totals file.
Remarks Recalculates validation data for the specified totals file.
Value Meaning
E_CLAIMED Cannot recalculate because either the totals file or the

entire totals area is claimed by another application.
E_ILLEGAL The handle is invalid, or advanced error detection is
either not supported by the Service or by this file.
release Method (Common)

Syntax release ( ):
An application may own claims on both the Hard Totals device through claim as
well as individual files through claimFile. Calling release only releases the claim
on the Hard Totals device.
Value Meaning
E_ILLEGAL The application does not have exclusive access to the

device.
See Also “Device Sharing Model” on page 50, claim Method, claimFile Method.

644 Hard Totals
releaseFile Method
Syntax releaseFile ( hTotalsFile: int32 ):
The hTotalsFile parameter contains the handle of the totals file to be released.
Remarks Releases exclusive access to a specific file.
Value Meaning
E_ILLEGAL The handle is invalid, or the specified file is not claimed

by this application.
See Also claim Method, claimFile Method.
rename Method
Syntax rename ( hTotalsFile: int32, fileName: string ):
hTotalsFile The handle of the totals file to be renamed.

fileName The new name to be assigned to the file. Must be no
longer than 10 characters. All displayable ASCII
characters (0x20 through 0x7F) are valid.
Remarks Renames a totals file.
If CapSingleFile is true, then this method will fail.
Value Meaning
E_CLAIMED Cannot rename because either the totals file or the entire
E_ILLEGAL The handle is invalid, the fileName contains invalid
characters, or the CapSingleFile property is true.
E_EXISTS fileName already exists.
See Also CapSingleFile Property.

rollback Method
Syntax rollback ( ):
Remarks Ends the current transaction. All writes between the previous beginTrans and this
method are discarded; they are not saved to the Hard Totals areas.
Value Meaning
E_ILLEGAL Transactions are not supported by this device, or no

transaction is in progress.
See Also beginTrans Method, commitTrans Method.
setAll Method Updated in Release 1.7

Syntax setAll ( hTotalsFile: int32, value: byte ):
hTotalsFile Handle of a totals file.

value Value to set all locations to in totals file.
Remarks Sets all the data in a totals file to the specified value.
Value Meaning
E_CLAIMED Cannot set because either the totals file or the entire
E_ILLEGAL The handle is invalid.

646 Hard Totals
validateData Method
Syntax validateData ( hTotalsFile: int32 ):
The hTotalsFile parameter contains the handle of a totals file.
Remarks Verifies that all data in the specified totals file passes validation checks.
Value Meaning
E_CLAIMED Cannot validate because either the totals file or the entire
E_ILLEGAL The handle is invalid, or advanced error detection is
either not supported by the Service or by this file.
write Method Updated in Release 1.7
Syntax write ( hTotalsFile: int32, data: binary, offset: int32, count: int32 ):
hTotalsFile Totals file handle returned from a create or find
method.
data2 Data buffer containing the totals data to be written.
offset Starting offset for the data to be written.
count Number of bytes of data to write.
Remarks Writes data to a totals file.
If a transaction is in progress, then the write will be buffered until a commitTrans
or rollback method is called.
Value Meaning
E_CLAIMED Cannot write because either the totals file or the entire
E_ILLEGAL The handle is invalid, or part of or all of the data range
is outside the bounds of the totals file.
E_EXTENDED ErrorCodeExtended = ETOT_NOROOM:
Cannot write because a transaction is in progress, and
there is not enough free space to prepare for the
transaction commit.
ErrorCodeExtended = ETOT_VALIDATION:
A validation error has occurred while reading data.
See Also read Method, beginTrans Method, commitTrans Method, rollback Method,
FreeData Property.


DirectIOEvent
means for a vendor-specific Hard Totals Service to provide events to the
Service.
from being used with other vendor’s Hard Totals devices which may not have any
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a Hard Totals
device.
Status int32 Reports a change in the power state of a Hard Totals
device.
process.
Remarks Enqueued when the Hard Totals device detects a power state change.

648 Hard Totals

C H A P T E R 1 8
Image Scanner
This Chapter defines the Image Scanner device category.
Summary

650 Image Scanner
CapAim: boolean { read-only } 1.11 open
CapDecodeData: boolean { read-only } 1.11 open
CapHostTriggered: boolean { read-only } 1.11 open
CapIlluminate: boolean { read-only } 1.11 open
CapImageData: boolean { read-only } 1.11 open
CapImageQuality: boolean { read-only } 1.11 open
CapVideoData: boolean { read-only } 1.11 open
AimMode: boolean { read-write } 1.11 open

BitsPerPixel: int32 { read-only } 1.11 open
FrameData: binary { read-only } 1.11 open
FrameType: int32 { read-only} 1.11 open
IlluminateMode: boolean { read-write } 1.11 open
ImageHeight: int32 { read-only } 1.11 open
ImageLength: int32 { read-only } 1.11 open
ImageMode: int32 { read-write } 1.11 open
ImageQuality: int32 { read-write } 1.11 open
ImageType: int32 { read-only } 1.11 open
ImageWidth: int32 { read-only } 1.11 open
VideoCount: int32 { read-write } 1.11 open
VideoRate: int32 { read-write } 1.11 open

Summary 651

Common
Name Version
close ( ): 1.11
release ( ): 1.11
void { } supported
Specific
startSession ( ): 1.11
stopSession ( ): 1.11

652 Image Scanner


General Information
The Image Scanner programmatic name is “ImageScanner”.
Capabilities
The Image Scanner has the capability of reading a single frame of image data in
scanning sessions initiated by its own triggering source. It may also have one or
more of the following capabilities (see the capabilities properties for specific
information):
• Reads encoded data from a label
• Reads low-resolution video streams for aiming purposes
• Host is able to control the image scanner’s Illumination feature
• Host is able to control the image scanner’s Aiming feature
• Host is able to start and stop a scanning session

654 Image Scanner
Image Scanner Class Diagram
The following diagram shows the relationships between the Image Scanner and
Scanner classes.
<<fires>>
<<fires>>
<<fires>>
<<event>>
<<event>> <<event>> <<event>>
StatusUpdateEvent
<<fires>> ErrorEvent DataEvent DirectIOEvent
(from events)
(from events) (from events) (from events)
fires
fires
fires
fires
<<exception>>
UposException
(from upos)
<<Interface>>
ImageScannerControl
(from upos)
<<capability>> CapAim : boolean
<<capability>> CapDecodeData : boolean <<sends>>
<<capability>> CapHostTriggered : boolean
<<capability>> CapIlluminate : boolean
<<capability>> CapImageData : boolean <<sends>>
<<capability>> CapImageQuality : boolean <<Interface>>
<<capability>> CapVideoData : boolean BaseControl <<Interface>>
<<property>> AimMode : boolean (from upos) ScannerControl
(from upos)
<<property>> BitsPerPixel : int32
<<property>> FrameData : binary
<<property>> FrameType : int32
<<property>> IlluminateMode : boolean
<<property>> ImageHeight : int32
<<property>> ImageLength : int32 <<uses>> <<uses>>
<<property>> ImageMode : int32
<<property>> ImageQuality : int32
<<property>> ImageType : int32
<<property>> ImageWidth : int32 <<utility>> <<utility>>
<<property>> VideoCount : int32 UposConst ScannerConst
<<property>> VideoRate : int32 (from upos)
(from upos)
startSession() : void
stopSession() : void <<uses>>
<<utility>>
ImageScannerConst
(from upos)

Image Scanner Sequence Diagram 1
The following sequence diagram shows the typical usage of an Image Scanner
device with the ImageMode property set to “IMG_STILL_ONLY”. In this
instance there is no interaction with the Scanner class.
: POS Hardware
: :
Application
ImageScannerControl ScannerControl
1: setImageMode("IMG_STILL_ONLY")
2: setAutoDisable(true)
4: acquire image frame
5: create/enqueue data event and increment data count
6: setDeviceEnabled(false)
8: getFrameData()
9: getImageHeight()
10: getImageWidth()
11: getImageType()
12: setDeviceEnabledTrue()

656 Image Scanner
device with the ImageMode property set to “IMG_DECODE_ONLY”. The
scanner decodes bar codes, is triggered by the host, but does not send image frame
data. This device could be implemented as a hydra device that supports both the
Image Scanner and the Scanner classes.
: POS Hardware
: :
Application
ImageScan... ScannerControl
1: setImageMode("IMG_DECODE_ONLY")
2: setDecodeData(true)
5: startSession( )
6: Scanner Specific Command to start Session
7: scan successful label
8: create/enqueue Data event and increment DataCount
11: getScanData()
12: getScanDataLabel()
15: stopSession( )
It's a formality to end

the session because a
barcode was acquired


device with the ImageMode property set to “IMG_STILL_DECODE”. The
scanner decodes bar codes, is triggered by the host, and sends the image frame that
was decoded. This device could be implemented as a hydra device that supports
both the Image Scanner and the Scanner classes.
: POS : : Hardware
Application ImageScannerControl ScannerControl
1: setImageMode("IMG_STILL_DECODE")
7: startSession( )
9: Acquire Image Frame
10: create/enqueu Data event and increment DataCount
17: getScanData()
19: getFrameData()
20: getImageHeight()
21: getImageWidth()
22: getImageType()

658 Image Scanner

device with the ImageMode property set to “IMG_VIDEO_DECODE”. The
scanner sends a low-res video stream for use as a viewfinder, is triggered by the
host and decodes bar codes. In this mode, there is no tie between the image frame
that was decoded and the decoded data. This device could be implemented as a
hydra device that supports both the Image Scanner and the Scanner classes.
: POS : : Hardware
Application ImageScannerControl ScannerControl
1: setImageMode("IMG_VIDEO_DECODE")
6: startSession( )
8: Acquire 15 frames of Image Data No decode of

these frames
11: getImageHeight()
12: getImageWidth()
13: getImageType()
14: getFrameData()
Decode of one of
these frames is
16: Acquire 15 frames of Image Data
sucessful
19: getFrameData()
25: getScanData()

Model
The Image Scanner follows the general “Device Input Model” for event-driven
input:
• When a frame of image data is received from the image scanner, a DataEvent
is enqueued by a Image Scanner service.
• If the AutoDisable property is true and the image scanner is in Decode or Still
Image mode, then the device automatically disables itself when a DataEvent
is enqueued. The AutoDisable property does not apply in the Low-Res Video
mode.
properties, and further DataEvents are disabled by setting
DataEventEnabled to false. This causes subsequent input data to be
properties. When the application has finished processing the current input and
is ready for more data, it reenables events by setting DataEventEnabled to
true.
• An ErrorEvent (or events) is enqueued if an error occurs while gathering or
processing input, and is delivered to the application when DataEventEnabled
is true and other event delivery requirements are met.
• The DataCount property may be read to obtain the total number of enqueued
DataEvents.
Image Scanners that also decode labels are implemented as a “hydra device”.
Services are supported for both a Scanner device and an Image Scanner device.
• When a frame of image data yields decode data, a DataEvent is enqueued by
the Scanner service object
Scanned data is placed into the property ScanData. If the application sets the
property DecodeData to true, then the data is decoded into the ScanDataLabel
and ScanDataType properties.
Device Sharing
The image scanner is an exclusive-use device, as follows:
reading input.

660 Image Scanner
Image Scanner State Diagram
The following diagram illustrates the various state transitions within the Image
Scanner device category.
[Closed || Released || Disabled]

[Open && Claim && Enable]
[ ImageMode == IMG_ALL ||
/ setIlluminateMode
ImageMode == IMG_VIDEO_STILL ||
ImageMode == IMG_VIDEO_DECODE
] / startSession()
Idle
Receive Video
/ setAimMode Stream
/ stopSession() || timeout
/ stopSession() || timeout
[ ImageMode == IMG_DECODE_ONLY ] /
startSession() / stopSession() || timeout
[ ImageMode = IMG_STILL_ONLY ||
ImageMode= IMG_STILL_DECODE ] /
Receive startSession() [ (ImageMode == IMG_ALL ||
Decode Data ImageMoe == IMG_VIDEO_STILL)
&& Still Image Data Received ]
[ (ImageMode == IMG_ALL ||
ImageMode ==
IMG_STILL_DECODE) &&
Decode Data Received ] Receive
Still Image
[ (ImageMode == IMG_ALL || ImageMode == IMG_VIDEO_DECODE) &&

Decode Data Received ]


AimMode Property
Syntax AimMode: boolean { read-write, access after open }
Remarks If true, then the image scanner will turn on an aiming spot or aiming grid during a
scan session. If false, then the image scanner will turn off the aiming spot during
a scan session
Value Meaning
E_ILLEGAL An attempt was made to change AimMode property
when the CapAim property is false.
See Also CapAim Property.
BitsPerPixel Property
Syntax BitsPerPixel: int32 { read-only, access after open }
Remarks Holds a value identifying the number of bits that are used to encode a single pixel
of image data.
Its value is set prior to a DataEvent being delivered to the application.
CapAim Property
Syntax CapAim: boolean { read-only, access after open }
Remarks If true, then the image scanner supports the property to enable or disable the
display of an aiming spot or grid by the image scanner.
CapDecodeData Property
Syntax CapDecodeData: boolean { read-only, access after open }
Remarks If true, then the image scanner is able to read encoded data from a label. Any label
data that is read is sent by a Scanner service.

662 Image Scanner
CapHostTriggered Property
Syntax CapHostTriggered: boolean { read-only, access after open }
Remarks If true, then the image scanner is able to support the startSession and stopSession
method calls.
CapIlluminate Property
Syntax CapIlluminate: boolean { read-only, access after open }
Remarks If true, then the image scanner supports the property to enable or disable the use
of an illumination source by the image scanner.
CapImageData Property
Syntax CapImageData: boolean { read-only, access after open }
Remarks If true, then the image scanner supports a still image capture mode.
CapImageQuality Property
Syntax CapImageQuality: boolean { read-only, access after open }
Remarks If true, then the image scanner supports the ImageQuality property that the
application can use to control image compression or capture that effects the quality
of the image in exchange for smaller image sizes.
See Also ImageQuality Property.
CapVideoData Property
Syntax CapVideoData: boolean { read-only, access after open }
Remarks If true, then the image scanner supports a low-resolution video stream mode.

FrameData Property
Syntax FrameData: binary { read-only, access after open } 1
Remarks Holds a frame of image data or one or more frames of video data read from the
image scanner.
Image data is, in general, in the format as delivered from the image scanner. The
attributes of the image sent are placed in the BitsPerPixel, ImageHeight,
ImageWidth, ImageType, and ImageLength properties.
Video data is, in general, one or more still images that are concatenated together
in one frame with no data compression. This video data is typically used to project
a “view finder” that the operator can use to aim the image scanner (without an
aiming pattern). Each block contains at most the number of frames specified in the
VideoCount property. A DataEvent is fired for each block of video data sent.
Multiple blocks of image data are periodically sent by the service object to up to
the maximum frames per second rate set by the VideoRate property. The attributes
of every still image that makes up a block of video data are placed in the
BitsPerPixel, ImageHeight, ImageWidth, ImageType, and ImageLength
properties.
Image data, whether for still images or video streams may be acquired in a scan
session started by the startSession method, or by a scan session started
asynchronously by the image scanner. The FrameType property indicates
whether the FrameData property contains a single still image, or a block of video
data.
See Also BitsPerPixel Property, FrameType Property, ImageHeight Property,
ImageLength Property, ImageType Property, ImageWidth Property,
VideoCount Property, VideoRate Property, “Device Input Model” on page 54.
FrameType Property
Syntax FrameType: int32 { read-only, access after open }
Remarks Holds a value identifying the contents of the FrameData property.
Value Meaning
IMG_FRAME_STILL The FrameData property contains a single still image.
IMG_FRAME_VIDEO The FrameData property contains a block of video
stream frames (one or more still images concatenated
without data compression).

664 Image Scanner
See Also FrameData Property.
IlluminateMode Property
Syntax IlluminateMode: boolean { read-write, access after open }
Remarks If true, then the image scanner will enable the illumination source during a scan
session. If false, then the image scanner will not turn on the illumination source
during a scan session
Value Meaning
E_ILLEGAL An attempt was made to change IlluminateMode
property when the CapIlluminate property is false.
See Also CapIlluminate Property.
ImageHeight Property
Syntax ImageHeight: int32 { read-only, access after open }
Remarks Holds a value identifying the height of the acquired image in pixels.
ImageLength Property
Syntax ImageLength: int32 { read-only, access after open }
Remarks Holds a value identifying the length of the acquired image in bytes.

ImageMode Property
Syntax ImageMode: int32 { read-write, access after open }
Remarks Holds a value identifying the image scanner’s mode of operation.
The value of this property indicates the type of data that is placed into the
FrameData property upon a DataEvent.
This property is initialized by the open method. The default value of this property
is IMG_STILL_ONLY.
Value Meaning
IMG_DECODE_ONLY The image scanner will not transmit still images or video
to the application, but it will transmit bar code data
decoded from acquired images via a Scanner service. A
hydra implementation of Image Scanner and Scanner is
required for this mode.
IMG_STILL_ONLY The image scanner will transmit still images, but it will
not attempt to read bar code data, nor will it transmit
video.
IMG_STILL_DECODE The image scanner will transmit still images, and it will
attempt to read bar code data, but it will not transmit
video streams. A hydra implementation of Image
Scanner and Scanner is required for this mode.
IMG_VIDEO_DECODE The image scanner will transmit video streams, and it
will attempt to read bar code data. A hydra
implementation of Image Scanner and Scanner is
IMG_VIDEO_STILL The image scanner will transmit video streams, and it
will transmit still images, but it will not attempt to read
bar code data. The image resolution of video data could
be different from the resolution of still image data.
IMG_ALL The image scanner will transmit video streams, and it
will attempt to read bar code data. When a bar code is
read, the bar code data is transmitted as well as a still
image. The image resolution of video data could be
different from the resolution of still image data. A hydra
implementation of Image Scanner and Scanner is
Value Meaning
E_ILLEGAL An attempt was made to change the ImageMode
property to a value that is not in agreement with the
capabilities of the image scanner as indicated in the
CapImageData, CapVideoData and CapDecodeData
properties.
See Also CapDecodeData Property, CapImageData Property, CapVideoData Property,
FrameData Property, startSession Method, “Device Input Model” on page 54.

666 Image Scanner
ImageQuality Property
Syntax ImageQuality: int32 { read-write, access after open }
Remarks Defines the quality of the image that the application requires.
Value Meaning
IMG_QUAL_LOW The quality of the image data is to be low.
IMG_QUAL_MED The quality of the image data is to be medium.
IMG_QUAL_HIGH The quality of the image data is to be high.
This property is initialized to IMG_QUAL_HIGH by the open method.
See Also CapImageQuality Property.
ImageType Property
Syntax ImageType: int32 { read-only, access after open }
Remarks Holds a value identifying the format of the image data that is contained in the
FrameData property.
Value Meaning
IMG_TYP_BMP The acquired image data is in the Bit Mapped (BMP)
format.
IMG_TYP_JPEG The acquired image data is in the Joint Photographic
Experts Group (JPEG) format.
IMG_TYP_GIF The acquired image data is in the Graphic Interchange
Format (GIF) format.
IMG_TYP_PNG The acquired image data is in the Portable Network
Graphics (PNG) format.
IMG_TYP_TIFF The acquired image data is in the Tagged Image File
Format (TIFF) format.
See Also FrameData Property.

ImageWidth Property
Syntax ImageWidth: int32 { read-only, access after open }
Remarks Holds a value identifying the width of the acquired image in pixels.
VideoCount Property
Syntax VideoCount: int32 { read-write, access after open }
Remarks Holds a value identifying the number of frames of video data that are sent with
each DataEvent. The default value of this property is 15. When the VideoRate
property is set to 30 frames per second, this value yields a DataEvent twice a
second.
Should the value of this property be larger than the image scanner’s memory
storage capabilities, the value of this property will be coerced by the Service to the
image scanner’s maximum supported count.
Value Meaning
E_ILLEGAL An attempt was made to change the VideoCount
property to a value that exceeds the image scanner’s
memory storage capabilities.
See Also “Device Input Model” on page 54, VideoRate Property.

668 Image Scanner
VideoRate Property
Syntax VideoRate: int32 { read-write, access after open }
Remarks Holds a value identifying the number of video frames per second that the
application can receive. The default value of this property is 30 frames per second.
The application can set this property and the VideoCount property to throttle the
number of DataEvents that are fired. For example, with the default values of the
VideoCount and VideoRate properties, the application would get a DataEvent
two times a second.
Should the value of this property be larger than the image scanner’s maximum
supported rate, the value of this property will be coerced by the Service to the
image scanner’s maximum supported rate.
The image scanner may discard frames of image data that exceed the specified
VideoRate property.
Value Meaning
E_ILLEGAL An attempt was made to change the VideoRate property
to a value that exceeds the image scanner’s maximum
supported rate.
See Also “Device Input Model” on page 54, VideoCount Property.


startSession Method
Syntax startSession ():
Remarks This method is used to trigger the image scanner to acquire decode data, still
images and video stream data in the mode selected by the ImageMode property.
A session is active until the stopSession method is invoked, or until the image
scanner ends the session on its own. A session may terminate early when an
image or decode data is acquired, or when a session timeout has expired. The
criteria for ending a session is implementation dependant.
Value Meaning
E_ILLEGAL An attempt was made to call the startSession method
when the CapHostTriggered property is false.
See Also CapHostTriggered Property, ImageMode Property, stopSession Method.
stopSession Method
Syntax stopSession ():
Remarks This method is used to stop a session that was started with a startSession method.
If this method is invoked and the session is no longer active, then no exception is
raised (see startSession method details)
Value Meaning
E_ILLEGAL An attempt was made to call the stopSession method
when the CapHostTriggered property is false.
See Also CapHostTriggered Property, startSession Method.

670 Image Scanner

DataEvent
Description Notifies the application that input data from the Image Scanner is available.

Status int32 Always zero.
Remarks The image scanner data is placed in the BitsPerPixel, FrameData, FrameType,
ImageHeight, ImageLength, ImageType, and ImageWidth properties prior to a
See Also BitsPerPixel Property, FrameData Property, FrameType Property,
ImageHeight Property, ImageLength Property, ImageType Property,
ImageWidth Property, “Events” on page 51.
DirectIOEvent
means for a vendor-specific Image Scanner Service to provide events to the
Service.
from being used with other vendor’s Image Scanner devices which may not have

ErrorEvent
Description Notifies the application that an image scanner device error has been detected and
ErrorCode int32 Error code causing the error event. See list of
ErrorCodes on page 52.
ErrorCodeExtended
int32 Extended error code causing the error event. It may
values below.
The ErrorLocus property has one of the following values:
Value Meaning
available.
available.
Value Meaning
EL_INPUT. Default when locus is EL_INPUT_DATA.
Remarks Enqueued when an error is detected while trying to read image scanner data. This
event is not delivered until DataEventEnabled is true, so that proper application
sequencing occurs.

672 Image Scanner
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of an Image
Scanner device.
Status int32 Reports a change in the power state of a Image Scanner
device.

The Update Firmware capability, added in Release 1.9, added
additional Status values for communicating the status/progress of
an asynchronous update firmware process.
Remarks Enqueued when the Image Scanner device detects a power state change.

C H A P T E R 1 9
Item Dispenser
This Chapter defines the Item Dispenser device category.
Summary

674 Item Dispenser
CapEmptySensor: boolean { read-only } 1.12 open
CapIndividualSlotStatus: boolean { read-only } 1.12 open
CapJamSensor: boolean { read-only } 1.12 open
CapNearEmptySensor: boolean { read-only } 1.12 open
DispenserStatus: int32 { read-only } 1.12 open, claim, & enable

MaxSlots: int32 { read-only } 1.12 open

Common
Name Version
close ( ): 1.12
release ( ): 1.12
clearInput ( ): Not
void { } supported
void { } supported
void { } supported

Summary 675
Specific
Name
adjustItemCount ( itemCount: int32, slotNumber: int32 ): 1.12
dispenseItem ( inout numItem: int32, slotNumber: int32 ): 1.12
readItemCount ( inout itemCount: int32, slotNumber: int32 ): 1.12


676 Item Dispenser
General Information
The Item Dispenser programmatic name is “ItemDispenser”.

Capabilities
The Item Dispenser has the following capability:

• Supports a method that allows a specified number of items to be dispensed
from the device.
The Item Dispenser may have the following additional capabilities:

• Status reporting which indicates empty item slot conditions, near empty item
slot conditions and item slot jamming conditions.
• Supports multiple items dispensed from different slots.
• Status reporting in individual item type.

Item Dispenser Class Diagram

The following diagram shows the relationships between the Item Dispenser
classes.

UposException «sends» BaseControl «uses» UposConst ItemDispenserConst
«sends» «uses»
«interface»
ItemDispenserControl
+CapEmptySensor : boolean
+CapIndividualSlotStatus : boolean
+CapJamSensor : boolean
+CapNearEmptySensor : boolean
+DispenserStatus : int32
+MaxSlots : int32
+adjustItemCount(itemCount : int32, slotNumber : int32) : void

+dispenseItem(inout numItemt : int32, slotNumber : int32) : void
+readItemCount(inout itemCount : int32, slotNumber : int32) : void
«fires» «fires»
«event» «event»
+Data : int32
+Obj : object

678 Item Dispenser
Item Dispenser Sequence Diagram

The following sequence diagram show the typical usage of the Item Dispenser
device illustrating dispensing and the near-empty condition.
NOTE: We are assuming that the Application has already successfully opened and claimed the ItemDispenser Device
and is registered to receive events from the control.
Application ItemDispenser Control ItemDispenser Service ItemDispenser
2: setDeviceEnabled(true) access to the hardware
4: dispenseItem(numItem1,slotNumber1)
5: dispenseItem(numItem1,slotNumber1) 6: dispense Items from slotNumber1
7: dispenseItem(numItem2,slotNumber2)
8: dispenseItem(numItem2,slotNumber2) 9: dispense Items from slotNumber2
Assume that after this

point the ItemDispenser
slot2 is getting low
10: update DispenserStatus and deliver SUE
Application event handling code takes appropriate

action (like informing user), after refilling slot2 the
ItemCount has to be adjusted
12: adjustItemCount(itemCount,slotNumber2)
13: adjustItemCount(itemCount,slotNumber2)

Model
The general model of an Item Dispenser is:
An Item Dispenser consists of slots holding items (e.g. CD’s, prepaid telephone
card, etc.) to be dispensed. An application using the Item Dispenser Service is not
concerned with controlling the individual slots of items to be dispensed, but rather
calls a method with the number of items to be dispensed. It is the responsibility of
the Item Dispenser Device or the Service to dispense the correct number of items
from the various slots.
Device Sharing
The Item Dispenser is an exclusive-use device. Its device sharing rules are:
Item Dispenser State Diagram

The following diagram illustrates the various state transitions within the Item
Dispenser device category.
open claim
close release
)
ls e
e)
(tru
( fa
le d
led
ab
ab
close release En
En
ice
ice
ev
ev
tD
tD
se
se
Enabled
dispenseItem
dispenseItem
Has Items Near Empty Empty

adjustItemCount
readItemCount add items
adjustItemCount / items added
done
jams done fire event

jams fire event
fire event
Jammed Fire Events
done

680 Item Dispenser
Remarks If true, the item dispenser can report an out-of-item condition.
CapIndividualSlotStatus Property
Syntax CapIndividualSlotStatus: boolean { read-only, access after open }
Remarks If true, the item dispenser can report an individual status for each slot.
An individual status can be only reported if the device supports multiple slots.
Therefore, if CapIndividualSlotStatus is true, then it is implied that MaxSlots is
greater than one (1).
See Also MaxSlots Property.
Remarks If true, the item dispenser can report the occurrence of a mechanical jam or failure
condition.
Remarks If true, the item dispenser can report that it is nearly out of items.

DispenserStatus Property
Syntax DispenserStatus: int32 { read-only, access after open-claim-enable }
Remarks Holds the current status of the item dispenser. It may be one of the following:
Value Meaning
ITEM_DS_OK Ready to dispense items. This value is also set
when the dispenser is unable to detect error
conditions.
ITEM_DS_EMPTY Cannot dispense items, because the dispenser is
empty. If MaxSlots is greater than one (1),
some of the slots are empty.
ITEM_DS_NEAREMPTY Can still dispense items, but the dispenser is
nearly empty. If MaxSlots is greater than one
(1), some of the slots are near empty.
ITEM_DS_JAM Cannot dispense items, because a mechanical
fault has occurred.
See Also CapEmptySensor Property, CapJamSensor Property, CapNearEmptySensor
Property, MaxSlots Property.
MaxSlots Property
Syntax MaxSlots: int32 { read-only, access after open }
Remarks MaxSlots specifies the maximum number of slots that the device can support.

682 Item Dispenser

adjustItemCount Method
Syntax adjustItemCount (itemCount: int32, slotNumber: int32):
itemCount The itemCount parameter contains the number of items
to be initialized.
slotNumber The slotNumber parameter contains the slot number to
be initialized. Valid slot numbers are 1 through
MaxSlots.
Remarks This method is called to set the initial number of items in the Item Dispenser after
initial setup, or to adjust the item count after replenishment or removal. This
method is called when needed for devices which cannot determine the exact
number of items in them automatically. If the device can determine the exact
number of items, then this method call is ignored. The application would first call
readItemCount to get the current item count, and adjust it to the amount being
replenished. Then the application will call this method to set the number of items
currently in the dispenser.
To reset the item count simply set it to zero
Value Meaning
E_ILLEGAL The slotNumber parameter exceeds MaxSlots.
See Also MaxSlots Property, readItemCount Method.

dispenseItem Method
Syntax dispenseItem (inout numItem: int32, slotNumber: int32):
numItem The numItem parameter contains the number of items to
be dispensed. On return, it contains the actual number of
items dispensed.
slotNumber The slotNumber parameter contains the slot number
used for dispensing items. Valid slot numbers are 1
through MaxSlots.
Remarks Dispenses items. The actual number of dispensed items is returned in numItem.
Value Meaning
E_FAILURE The number of items could not be dispensed due to a
hardware problem.
E_ILLEGAL The numItem parameter value was illegal or contains a
value greater than the device can dispense, or the
slotNumber parameter exceeds MaxSlots.
readItemCount Method
Syntax readItemCount (inout itemCount: int32, slotNumber: int32):
itemCount The item count data is placed into itemCount.
slotNumber The slotNumber parameter contains the slot number
used for reading the item count. Valid slot numbers are
1 through MaxSlots.
Remarks Reads the number of items currently in the item dispenser.
Value Meaning
E_ILLEGAL The slotNumber parameter exceeds MaxSlots.

684 Item Dispenser
DirectIOEvent
means for a vendor-specific Item Dispenser Service to provide events to the
Service.
from being used with other vendor’s Item Dispenser devices which may not have

StatusUpdateEvent
Description Notifies the application when the status of the Item Dispenser changes.

Status int32 The status reported from the Item Dispenser.
The low word of the Status attribute has one of the following values:
Value Description
ITEM_SUE_OK Ready to dispense items from all slots. This value is
also set when the dispenser is unable to detect error
conditions.
ITEM_SUE_EMPTY Cannot dispense items, because the dispenser is
empty. If MaxSlots is greater than one (1), some of
the slots are empty.
ITEM_SUE_NEAREMPTY Can still dispense items, but the dispenser is nearly
empty. If MaxSlots is greater than one (1), some of
the slots are nearly empty.
ITEM_SUE_JAM Cannot dispense items, because a mechanical fault
has occurred.
process.
Remarks This event applies for status changes of the sensor types supported as indicated by
CapEmptySensor, CapNearEmptySensor and CapJamSensor properties.
If MaxSlots is greater than one (1) but the device can not report status changes on
individual slots, the application will be notified when some of the slots are empty
or nearly empty.
If in addition CapIndividualSlotStatus is true, the high word of the Status
attribute contains the corresponding number of the slot having a status change.
See Also CapEmptySensor Property, CapIndividualSlotStatus Property,
CapJamSensor Property, CapNearEmptySensor Property, MaxSlots Property,
“Events” on page 51

686 Item Dispenser

C H A P T E R 2 0
Keylock
This Chapter defines the Keylock device category.
Summary

688 Keylock
CapKeylockType: int32 { read-only } 1.11 open
ElectronicKeyValue: binary { read-only } 1.11 open & enable
KeyPosition: int32 { read-only } 1.0 open & enable
PositionCount: int32 { read-only } 1.0 open

Common
Name Version
close ( ): 1.0
release ( ): 1.0
clearInput ( ): Not
void { } supported
void { } supported
void { } supported
Specific
Name
waitForKeylockChange ( keyPosition: int32, timeout: int32 ): 1.0

Summary 689


690 Keylock
General Information
The Keylock programmatic name is “Keylock”.

The keylock has the following minimal set of capabilities:
• Supports at least three keylock positions.
• Supports reporting of keylock position changes, either by hardware or
software detection.
The keylock may have the following additional capability:
• Supports an electronic keylock.
Keylock Class Diagram Updated in Release 1.11

The following diagram shows the relationships between the Keylock classes.
<<uses>> <<utility>>
<<exception>>
<<Interface>> UposConst
UposException
BaseControl (from upos)
(from upos)
<<sends>> (from upos)
<<event>>
StatusUpdateEvent
(from events)
<<utility>>
KeylockConst
(from upos)
fires <<sends>>
<<event>> <<uses>>
DirectIOEvent
(from events)
<<prop>> Data : int32 fires
<<Interface>>
<<prop>> Obj : object KeylockControl
(from upos)
<<capability>> CapKeylockType : int32
<<prop>> ElectronicKeyValue : binary
<<prop>> KeyPosition : int32
<<prop>> PositionCount : int32
waitForKeylockChange(keyPosition : int32, timeout : int32) : void

Keylock Sequence Diagram Updated in Release 1.12

The following sequence diagram show the typical usage of the Keylock; as well as
showing the unique sharing model of the Keylock.
NOTE: we are assuming t hat t he : Client App0 already successfully opened t he controls. This means t hat t he plat form specific loading/c onfiguration/ creation
code execut ed successfully. We are also assuming that the :ClientApp has regist ered event handlers with the cont rol ins tance.
:ClientApp0 :ClientApp1 k0:Keylock k1:Keylock :StatusUpdate :Keylock : Keylock : Keylock

Event Service0 Service1 Hardware
2: s etDeviceEnabled(true)
:Operator
3: service will need to update itself of current Keylock position
Current Keylock position

is returned to the control
4: getKeyPosition()
5: getKeyPosition()
6: change Keylock position

SUE == Status UpdateEvent
7: notify KeylockService of change
8: deliver SUE to cont rol [ FreezeEvent s == false]

10: notify c lient of new event
The details of the

Config/Loader are
not shown
11: create and regist er an event handler with cont rol
12: open(logicalName) 13: open(logicalName)
15: setDeviceEnabled(true) Actual order of
delivery from
hardware to
service might vary
16: change Keylock position
17: notify s ervice of change
18: deliver SUE to control [FreezeEvents == false]
20: notify client of new event 19: deliver event t o all regis tered listeners
21: notify service of change
23: deliver event to all registered listeners

25: claim(timeout)
26: claim(timeout)
27: throws UposException to :ClientApp since Keylock cannot be claimed

692 Keylock

The keylock defines three keylock positions as constants. It is assumed that the
keylock supports locked, normal, and supervisor positions. The constants for these
keylock positions and their values are as follows:
• LOCK_KP_LOCK 1
• LOCK_KP_NORM 2
• LOCK_KP_SUPR 3
The KeyPosition property holds the value of the keylock position where the
values range from one (1) to the total number of keylock positions contained in the
PositionCount property.
For electronic keylocks the ElectronicKeyValue property holds the value of the
keylock. It is a unique value provided as binary string. The range depends on the
device.
Device Sharing
The keylock is a sharable device. Its device sharing rules are:

• The keylock may not be claimed for exclusive access. Therefore, if an
application calls claim or release, these methods will always raise a
UposException.

CapKeylockType Property Added in Release 1.11

Syntax CapKeylockType: int32 { read-only, access after open }
Remarks Holds a value that indicates the type of the keylock.
Value Meaning
LOCK_KT_STANDARD Standard Keylock. Value is one (1). This is
equivalent to Services compatible with prior
versions of the specification.
LOCK_KT_ELECTRONIC Electronic Keylock. Value is two (2).
If CapKeylockType is LOCK_KT_ELECTRONIC an Electronic Keylock is used
and its status will be provided by the ElectronicKeyValue property. In this case
the PositionCount and KeyPosition properties have no meaning.
See Also ElectronicKeyValue Property, KeyPosition Property, PositionCount Property,
StatusUpdateEvent.
ElectronicKeyValue Property Added in Release 1.11

Syntax ElectronicKeyValue: binary { read-only, access after open-enable }1
Remarks Holds the value read from the electronic keylock.
This property is only valid if CapKeylockType is LOCK_KT_ELECTRONIC.
Usually electronic keylocks send unique key numbers in “raw” format when an
electronic key is plugged in. Therefore, a typical value could be e.g., “0x00, 0x00,
0x01, 0x52, 0x27, 0xaf”, if an electronic key is plugged in and “0x00, 0x00, 0x00,
0x00, 0x00, 0x00”, if it is removed.
See Also CapKeylockType Property, StatusUpdateEvent.

694 Keylock
KeyPosition Property Updated in Release 1.11

Syntax KeyPosition: int32 { read-only, access after open-enable }
Remarks Holds a value that indicates the keylock position.
This value is set whenever the keylock position is changed. In addition to the
application receiving the StatusUpdateEvent, this value is changed to reflect the
new keylock position.
Value Meaning
LOCK_KP_LOCK Keylock is in the “locked” position. Value is one (1).

LOCK_KP_NORM Keylock is in the “normal” position. Value is two (2).
LOCK_KP_SUPR Keylock is in the “supervisor” position. Value is three
(3).
Other Values Keylock is in one of the auxiliary positions. This value
may range from four (4) up to the total number of
keylock positions indicated by the PositionCount
property.
If CapKeylockType is LOCK_KT_ELECTRONIC this property has no meaning
and is always 0.
See Also CapKeylockType Property, PositionCount Property, StatusUpdateEvent.
PositionCount Property Updated in Release 1.11

Syntax PositionCount: int32 { read-only, access after open }
Remarks Holds the total number of keylock positions that are present on the keylock device.
If CapKeylockType is LOCK_KT_ELECTRONIC this property has no meaning
and is initialized to 0.
See Also CapKeylockType Property


waitForKeylockChange Method Updated in Release 1.11
Syntax waitForKeylockChange ( keyPosition: int32, timeout: int32 ):
keyPosition Requested keylock position. See values below.
timeout Maximum number of milliseconds to wait for the
keylock before returning control back to the application.
If zero, the method then returns immediately. If
FOREVER (-1), the method waits as long as needed
until the requested key position is satisfied or an error
occurs.
The keyPosition parameter has one of the following values:
Value Meaning
LOCK_KP_ANY Wait for any keylock position change. Value is zero (0).
LOCK_KP_LOCK Wait for keylock position to be set to the “locked”
position. Value is one (1).
LOCK_KP_NORM Wait for keylock position to be set to the “normal”
position. Value is two (2).
LOCK_KP_SUPR Wait for keylock position to be set to the “supervisor”
position. Value is three (3).
Other Values Wait for keylock position to be set to one of the auxiliary
positions. This value may range from four (4) up to the
total number of keylock positions indicated by the
PositionCount property.
Remarks Waits for a specified keylock position to be set.
If the keylock position specified by the keyPosition parameter is the same as the
current keylock position, then the method returns immediately.
If CapKeylockType is LOCK_KT_ELECTRONIC only LOCK_KP_ANY is
allowed as value of the keyPosition parameter.
Value Meaning
E_ILLEGAL An invalid parameter value was specified.
E_TIMEOUT The timeout period expired before the requested keylock
positioning occurred.
See Also CapKeylockType Property, PositionCount Property.

696 Keylock
DirectIOEvent
means for a vendor-specific Keylock Service to provide events to the application
Service.
from being used with other vendor’s Keylock devices which may not have any


Description Notifies the application when the keylock position changes.

Status int32 The key position in the Keylock.
Value Description
LOCK_KP_ELECTRONIC
Electronic Keylock value. Value is zero (0).
LOCK_KP_LOCK Keylock is in the “locked” position. Value is one (1).
LOCK_KP_NORM Keylock is in the “normal” position. Value is two (2).
LOCK_KP_SUPR Keylock is in the “supervisor” position. Value is three
(3).
Other Values Keylock is in one of the auxiliary positions. This value
may range from four (4) to the total number of keylock
positions indicated by the PositionCount property.

process.
Remarks This event is enqueued when a keylock switch position undergoes a change or if
Power State Reporting is enabled and a change in the power state is detected.
If CapKeylockType is LOCK_KT_ELECTRONIC the electronic key value is
placed in the ElectronicKeyValue property prior to a StatusUpdateEvent being
delivered to the application and Status is set to LOCK_KP_ELECTRONIC.
See Also CapKeylockType Property, ElectronicKeyValue Property, PositionCount
Property, “Events” on page 51.

698 Keylock

C H A P T E R 2 1
Lights
This Chapter defines the Lights device category.
Summary

700 Lights
CapAlarm: int32 { read-only } 1.12 open
CapBlink: boolean { read-only } 1.12 open
CapColor: int32 { read-only } 1.12 open
MaxLights: int32 { read-only } 1.12 open

Common
Name Version
close ( ): 1.12
release ( ): 1.12
clearInput ( ): Not
void { } supported
void { } supported
void { } supported
Specific
Name
switchOff ( lightNumber: int32 ): 1.12

Summary 701
switchOn ( lightNumber: int32, blinkOnCycle: int32, 1.12

blinkOffCycle: int32, color: int32, alarm: int32):


702 Lights
General Information
The Lights programmatic name is “Lights”.

Capabilities
The Lights Control has the following capability:
• Supports commands to “switch on” and “switch off” a light.
The Lights Control may have the following additional capabilities:
• Supports device-level blinking at adjustable blink cycles.
• Supports multiple lights.
• Supports different colors of a light.
• Supports different alarms
Lights Class Diagram

The following diagram shows the relationships between the Lights classes.

UposException «sends» BaseControl «uses» UposConst LightsConst
«sends» «uses»
«interface»
LightsControl
+CapAlarm : int32
+CapBlink : boolean
+CapColor : int32
+MaxLights : int32
+switchOff(lightNumber : int32) : void

+switchOn(lightNumber : int32, blinkOnCycle : int32, blinkOffCycle : int32, color : int32, alarm : int32) : void
«fires» «fires»
«event»
«event»
DirectIOEvent
StatusUpdateEvent
+EventNumber : int32
+Status : int32
+Data : int32
+Obj : object

Lights Sequence Diagram

The following sequence diagram show the typical usage of the Lights device
illustrating the handling of the media entry indicator lights.
NOTE: We are assuming that the Application has already successfully opened and claimed the Lights Device, MaxLights is 4
defining the SelfCheckout Media Entry Indicators (light1 is BillAcceptor, light2 is BillDispenser, light3 is CoinAcceptor,
light4 is CoinDispenser) and that CapBlink is true.
Application Lights Control Lights Service MEI Lights
Assume transaction is finished access to the hardware
and the customer pays cash
4: switchOn(light1,0,0,
LGT_COLOR_PRIMARY,
LGT_ALARM_NOALARM) 5: switchOn(light1,0.0,
LGT_COLOR_PRIMARY,
7: switchOn(light3,0,0, LGT_ALARM_NOALARM)
LGT_COLOR_PRIMARY, 6: Service switches on the MEI
LGT_ALARM_NOALARM) 8: switchOn(light3,0.0, light for BillAcceptor
LGT_COLOR_PRIMARY,
LGT_ALARM_NOALARM)
9: Service switches on the MEI
Assume customer has paid light for CoinAcceptor
and needs to get back change
10: switchOff(light1)
12: Service switches off the MEI
light for BillAcceptor
16: switchOn(light2,250,250, light for CoinAcceptor
LGT_COLOR_PRIMARY,
LGT_COLOR_PRIMARY,
LGT_ALARM_NOALARM)
19: switchOn(light4,250,250, light for BillDispenser and let it blink
LGT_COLOR_PRIMARY,
LGT_COLOR_PRIMARY,
LGT_ALARM_NOALARM)
light for CoinDispenser and let it blink
Assume customer has taken
the change
light for BillDispenser
light for CoinDispenser

704 Lights
The following sequence diagram show the typical usage of the Lights device
illustrating the handling of the pole lights.
NOTE: We are assuming that the Application has already successfully opened and claimed the Lights Device, MaxLights is 3
defining a SelfCheckout Pole Light (light1 is green, light2 is yellow, light3 is red) and that the device supports alarms.
Application Lights Control Lights Service Pole Light
4: switchOn(light1,0,0, access to the hardware
LGT_COLOR_PRIMARY,
LGT_ALARM_NOALARM) 5: switchOn(light1,0,0,
LGT_COLOR_PRIMARY,
LGT_ALARM_NOALARM)
6: Service switches on the green
Assume there is a problem and light with no alarm
the customer needs assitance
9: Service switches off the
10: switchOn(light3,0,0, green light
LGT_COLOR_PRIMARY,
LGT_ALARM_MEDIUM) 11: switchOn(light3,0,0,
LGT_COLOR_PRIMARY,
LGT_ALARM_MEDIUM)
12: Service switches on the
red light with medium alarm
Device Sharing
Lights is an exclusive-use device. Its device sharing rules are:

properties and methods, or receiving events.


CapAlarm Property
Syntax CapAlarm: int32 { read-only, access after open }
Remarks This capability indicates if the device supports different alarms.
CapAlarm is a logical OR combination of any of the following values:
Value Meaning
LGT_ALARM_NOALARM Alarms are not supported.
LGT_ALARM_SLOW Supports a slow beep.
LGT_ALARM_MEDIUM Supports a medium beep.
LGT_ALARM_FAST Supports a fast beep.
LGT_ALARM_CUSTOM1 Supports 1st custom alarm.
LGT_ALARM_CUSTOM2 Supports 2nd custom alarm.
This property is initialized by the open method. If the device does not support
alarms, it is initialized to LGT_ALARM_NOALARM.
CapBlink Property
Syntax CapBlink: boolean { read-only, access after open }
Remarks If true, a blinking capability is supported. It may be either a physical capability of
the device or emulated by the service.
CapColor Property
Syntax CapColor: int32 { read-only, access after open }
Remarks This capability indicates if the device supports different colors.
CapColor is a logical OR combination of any of the following values:
Value Meaning
LGT_COLOR_PRIMARY Supports Primary Color (Usually Green).
LGT_COLOR_CUSTOM1 Supports 1st Custom Color (Usually Red).
LGT_COLOR_CUSTOM2 Supports 2nd Custom Color (Usually Yellow).
LGT_COLOR_CUSTOM3 Supports 3rd Custom Color.
LGT_COLOR_CUSTOM4 Supports 4th Custom Color.
LGT_COLOR_CUSTOM5 Supports 5th Custom Color.
This property is initialized by the open method. If the device supports only one
color, it is initialized to LGT_COLOR_PRIMARY.

706 Lights
MaxLights Property
Syntax MaxLights: int32 { read-only, access after open }
Remarks MaxLights specifies the maximum number of lights that the device can support.

switchOff Method
Syntax switchOff ( lightNumber: int32 ):
lightNumber Specifies the light number. Valid light numbers are 1
through MaxLights.
Remarks Switches off the light specified by lightNumber.
Value Meaning
E_ILLEGAL The lightNumber parameter exceeds MaxLights.
See Also MaxLights Property.

708 Lights
switchOn Method
Syntax switchOn ( lightNumber: int32, blinkOnCycle: int32,
blinkOffCycle: int32, color: int32, alarm: int32 ):
lightNumber Specifies the light number. Valid light numbers are 1
through MaxLights.
blinkOnCycle A zero (0) value indicates no blink cycle. A positive
value indicates the blink on cycle time in milliseconds.
Negative values are not allowed.
blinkOffCycle A zero (0) value indicates no blink cycle. A positive
value indicates the blink off cycle time in milliseconds.
Negative values are not allowed.
color Specifies the color of the light, must be one of the colors
defined by CapColor.
alarm Specifies the used alarm type, must be one of the alarms
defined by CapAlarm.
Remarks Switches on the light specified by lightNumber or let it blink.
If blinkOnCycle and blinkOffCycle are zero (0) or CapBlink is false, then the
parameters blinkOnCycle and blinkOffCycle will be ignored and the light will only
be switched on.
If CapBlink is true and blinkOnCycle and blinkOffCycle are positive then the light
will blink.
If CapColor is LGT_COLOR_PRIMARY the light does not support different
colors and color is ignored, otherwise switchOn will use the color specified by
color.
If CapAlarm is LGT_ALARM_NOALARM the light does not support different
alarms and alarm is ignored, otherwise switchOn will use the alarm specified by
alarm.
Subsequent calls to switchOn will change the blink cycles, the color or the alarm
type of the light.
Value Meaning
E_ILLEGAL The lightNumber parameter exceeds MaxLights, an
invalid color or alarm was specified.
See Also CapBlink Property, CapBlink Property, CapColor Property, MaxLights
Property.

DirectIOEvent
means for a vendor-specific Lights Service to provide events to the application that
Service.
from being used with other vendor’s Lights devices which may not have any

710 Lights
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a light.

Status int32 Reports a change in the power status of a light.

process.
Remarks Enqueued when the light detects a power state change.

C H A P T E R 2 2
Line Display
This Chapter defines the Line Display device category.
Summary

712 Line Display
CapBlink: int32 { read-only } 1.0 open
CapBitmap: boolean { read-only } 1.7 open
CapBlinkRate: boolean { read-only } 1.6 open
CapBrightness: boolean { read-only } 1.0 open
CapCharacterSet: int32 { read-only } 1.0 open
CapCursorType: int32 { read-only } 1.6 open
CapCustomGlyph: boolean { read-only } 1.6 open
CapDescriptors: boolean { read-only } 1.0 open
CapHMarquee: boolean { read-only } 1.0 open
CapICharWait: boolean { read-only } 1.0 open
CapMapCharacterSet: boolean { read-only } 1.7 open
CapReadBack: int32 { read-only } 1.6 open
CapReverse: int32 { read-only } 1.6 open
CapScreenMode: boolean { read-only } 1.7 open
CapVMarquee: boolean { read-only } 1.0 open
BlinkRate: int32 { read-write } 1.6 open

CharacterSet: int32 { read-write } 1.0 open, claim, & enable
CharacterSetList: string { read-only } 1.0 open
Columns: int32 { read-only } 1.0 open
CurrentWindow: int32 { read-write } 1.0 open
CursorColumn: int32 { read-write } 1.0 open
CursorRow: int32 { read-write } 1.0 open
CursorType: int32 { read-write } 1.6 open
CursorUpdate: boolean { read-write } 1.0 open
CustomGlyphList: string { read-only } 1.6 open
DeviceBrightness: int32 { read-write } 1.0 open, claim, & enable
DeviceColumns: int32 { read-only } 1.0 open
DeviceDescriptors: int32 { read-only } 1.0 open
DeviceRows: int32 { read-only } 1.0 open
DeviceWindows: int32 { read-only } 1.0 open
GlyphHeight: int32 { read-only } 1.6 open
GlyphWidth: int32 { read-only } 1.6 open
InterCharacterWait: int32 { read-write } 1.0 open
MapCharacterSet: boolean { read-write } 1.7 open
MarqueeFormat: int32 { read-write } 1.0 open
MarqueeRepeatWait: int32 { read-write } 1.0 open

Summary 713
MarqueeType: int32 { read-write } 1.0 open
MarqueeUnitWait: int32 { read-write } 1.0 open
MaximumX: int32 { read-only } 1.7 open
MaximumY: int32 { read-only } 1.7 open
Rows: int32 { read-only } 1.0 open
ScreenMode: int32 { read-write } 1.7 open & claim
ScreenModeList: string { read-only } 1.7 open

Common
Name Version
close ( ): 1.0
release ( ): 1.0
clearInput ( ): Not
void { } supported

714 Line Display
Specific
Name Version
clearText ( ): 1.0
displayText ( data: string, attribute: int32 ): 1.0
displayTextAt (row: int32, column: int32, data: string, attribute: int32): 1.0
scrollText ( direction: int32, units: int32 ): 1.0
clearDescriptors ( ): 1.0
setDescriptor ( descriptor: int32, attribute: int32 ): 1.0
createWindow ( viewportRow: int32, viewportColumn: int32, 1.0

viewportHeight: int32, viewportWidth: int32, windowHeight:
int32, windowWidth: int32 ):
destroyWindow ( ): 1.0
refreshWindow ( window: int32 ): 1.0
defineGlyph ( glyphCode: int32, glyph: binary ): 1.6

readCharacterAtCursor ( inout cursorData: int32 ): 1.6
displayBitmap ( fileName: string, width: int32, alignmentX: int32, align- 1.7

mentY: int32 ):
setBitmap ( bitmapNumber: int32, fileName: string, width: int32, 1.7
alignmentX: int32, alignmentY: int32 ):


General Information
The Line Display programmatic name is “LineDisplay”.
Capabilities Updated in Version 1.7
The Line Display has the following capability:

• Supports text character display. The default mode (or perhaps only mode) of
the display is character display output.
The line display may also have the following additional capabilities:
• Supports windowing with marquee-like scrolling of the window. The display
may support vertical or horizontal marquees, or both.
• Supports a waiting period between displaying characters, for a teletype effect.
• Supports character-level or device-level blinking at adjustable blink rates.
• Supports character-level or device-level reverse video.
• Supports one or more descriptors. Descriptors are small indicators with a fixed
label, and are typically used to indicate transaction states such as item, total,
and change.
• Supports device brightness control, with one or more levels of device
dimming. All devices support brightness levels of “normal” and “blank” (at
least through software support), but some devices also support one or more
levels of dimming.
• Supports various cursor attributes including underline, block, and reverse
video.
• Supports “glyphs” which represent pixel level user definition of character
cells.
• Supports changing screen modes - the number of rows and columns supported
by the device.
• Supports setting and displaying bitmaps. Can also support the addressing of
individual pixels or dots using this functionality.

716 Line Display
Line Display Class Diagram Updated in Release 1.7
The following diagram shows the relationships between the Line Display classes.
<<uses>> <<utility>>
UposConst
<<exception>> <<Interface>>
(from upos)
UposException BaseControl
<<event>>
DirectIOEvent
(from events)
<<sends>>
<<prop>> EventNumber : int3...
<<prop>> Data : int32 <<utility>>
<<prop>> Obj : object Lin eDispla yConst
(from upos)
<<sends>>
<<uses>>
fires
<<event>>
Sta tusUpdateEvent <<Interface>>
(from events) LineDisplayControl
<<prop>> Status : int32 (from upos)
<<capabil ity>> Cap Bit map : boole an
<<capabil ity>> Cap Bli nk : i nt32
<<capabil ity>> Cap Bli nkRa te : boole an
fires <<capabil ity>> Cap Bri gh tn ess : bo ol ea n
<<capabil ity>> Cap Ch aracterSe t : in t32
<<capabil ity>> Cap Cu rsorT yp e : int3 2
<<capabil ity>> Cap Cu stom Gl yp h : b oo lean
<<capabil ity>> Cap De scrip tors : bool ea n
<<capabil ity>> Cap HMa rquee : bo ol ea n
<<capabil ity>> Cap ICha rWait : bo olean
<<capabil ity>> Cap MapCh aract erSe t : bo ol ea n
<<capabil ity>> Cap Re ad Back : int 32
<<capabil ity>> Cap Re ve rse : int 32
<<capabil ity>> Cap Screen Mode : bo ol ea n
<<capabil ity>> Cap VMa rquee : bo ol ea n
<<pro p> > Bl inkRate : i nt 32
<<pro p> > Ch aracterSe t : in t32
<<pro p> > Ch aracterSe tL ist : string
<<pro p> > Co lu mns : int3 2
<<pro p> > Cu rrent Wi nd ow : in t32
<<pro p> > Cu rsorCol umn : i nt32
<<pro p> > Cu rsorRow : in t32
<<pro p> > Cu rsorTyp e : int3 2
<<pro p> > Cu rsorUpdat e : b oo lean
<<pro p> > Cu stom Gl yp hL ist : stri ng
<<pro p> > De vi ceBri gh tn ess : int 32
<<pro p> > De vi ceCo lumn s : in t3 2
<<pro p> > De vi ceDe scrip tors : in t32
<<pro p> > De vi ceRo ws : i nt 32
<<pro p> > De vi ceWi nd ows : in t3 2
<<pro p> > Gl yp hHei gh t : in t32
<<pro p> > Gl yp hWid th : i nt32
<<pro p> > Int erCh aract erWait : int3 2
<<pro p> > Map Ch aract erSe t : bo ol ea n
<<pro p> > Marq ueeFormat : int3 2
<<pro p> > Marq ueeRe pe atWa it : int3 2
<<pro p> > Marq ueeType : i nt32
<<pro p> > Marq ueeUn itWai t : in t32
<<pro p> > Maxi mum X : i nt32
<<pro p> > Maxi mum Y : i nt32
<<pro p> > Ro ws : int 32
<<pro p> > Sc re en Mode : in t32
<<pro p> > Sc re en ModeL ist : string
cle arTe xt() : vo id

displayText(da ta : st rin g, at tribu te : int3 2) : voi d
displayTextA t(row : int 32 , c olum n : int3 2, data : stri ng , a ttribute : int 32 ) : vo id
scrollTe xt(direc tio n : int3 2, units : int 32 ) : vo id
cle arDe script ors() : void
set De scrip tor(descrip to r : in t32, attrib ute : int 32 ) : void
cre ateWin do w(vRow : int 32 , vCo l : in t3 2, vHeigh t : int 32 , v Widt h : in t3 2, wHei gh t : in t32, wWid th : i nt32) : vo id
destroyWindow() : void
refreshWin do w(wi nd ow : int 32 ) : vo id
def ineG lyph (gl yp hCod e : int3 2, gl yp h : bi na ry) : vo id
rea dChara cterAtCursor(in out curso rData : int 32 ) : vo id
displayBitma p(fileName : string, widt h : int3 2, al ignm en tX : i nt 32 , a lig nme ntY : in t32) : void
set Bit map (bi tm ap Num be r : in t32, fileName : string, widt h : in t3 2, ali gn men tX : i nt32 , a lig nme ntY : in t32) : void

Line Display Sequence Diagram Added in Release 1.7
The following sequence diagram shows the typical usage of the Line Display
device.
NOTE: we are assuming that the :ClientApp already successfully opened and enabled the
LineDisplay device. This means that the Claimed, DeviceEnabled properties are == true
:ClientApp :LineDisplay :LineDisplayService
1: claim(timeout) 2: claim(timeout)
3: clearText() 4: clearText()
At this point the data

is showing on the
5: displayText(data)
6: displayText(data) LineDisplay device.
Assuming the display supports descriptors

that is CapDescriptors == true.
7: setDescriptor(dValue, DISP_SD_BLINK) The descriptor

8: setDescriptor(dValue, DISP_SD_BLINK) number = dValue is
now blinking.
:ClientApp will perform

similar processing with
the display as needed.
9: clearText() 10: clearText()
At this point other

controls can
claim(...) the device
and use it.
11: release()
12: release()
13: releases exclusive access to this device
14: close()
15: close()
16: perform necessary cleanup

718 Line Display
The general model of a line display consists of:

• One or more rows containing one or more columns of characters. The rows
and columns are numbered beginning with (0, 0) at the upper-left corner of the
window. The characters in the default character set will include at least one of
the following, with a capability defining the character set:
• The digits ‘0’ through ‘9’ plus space, minus (‘-’), and period (‘.’).
• The above set plus uppercase ‘A’ through ‘Z.’
• All ASCII characters from 0x20 through 0x7F, which includes space,
digits, uppercase, lowercase, and some special characters.
• Window 0, which is always defined as follows:
• Its “viewport” — the portion of the display that is updated by the window
— covers the entire display.
• The size of the window matches the entire display.
Therefore, window 0, which is also called the “device window,” maps directly
onto the display.
• Option to create additional windows. A created window has the following
characteristics:
• Its viewport covers part or all of the display.
• The window may either match the size of the viewport, or it may be larger
than the viewport in either the horizontal or vertical direction. In the
second case, marquee scrolling of the window can be set.
• The window maintains its own values for rows and columns, current
cursor row and column, cursor update flag, cursor type, scroll type and
format, and timers.
• All viewports behave transparently. If two viewports overlap, then the last
data displayed by either of the windows will be visible.

Display Modes
• Immediate Mode
In effect when MarqueeType is DISP_MT_NONE and InterCharacterWait
is zero.
If the window is bigger than the viewport, then only those characters which
map into the viewport will be seen.
• Teletype Mode
In effect when MarqueeType is DISP_MT_NONE and InterCharacterWait
is not zero.
Calls to displayText and displayTextAt are enqueued and processed in the
order they are received. InterCharacterWait specifies the time to wait
between outputting each character. InterCharacterWait only applies to those
characters within the viewport.
• Marquee Mode
In effect when MarqueeType is not DISP_MT_NONE.
The window must be bigger than the viewport.
A marquee is typically initialized after entering Marquee Init Mode by setting
MarqueeType to DISP_MT_INIT, then calling clearText, displayText and
displayTextAt. Then, when MarqueeType is changed to an “on” value,
Marquee On Mode is entered, and the marquee begins to be displayed in the
viewport beginning at the start of the window (or end if the type is right or
down).
When the mode is changed from Marquee On Mode to Marquee Off Mode,
the marquee stops in place. A subsequent transition from back to Marquee On
Mode continues from the current position.
When the mode is changed from Marquee On Mode to Marquee Init Mode,
the marquee stops. Changes may be made to the window, then the window
may be returned to Marquee On Mode to restart the marquee with the new
data.
It is illegal to use displayText, displayTextAt, clearText, refreshWindow,
and scrollText unless in Marquee Init Mode or Marquee Off Mode.

720 Line Display
Data Characters and Escape Sequences Added in Release 1.7
The default character set of all line displays is assumed to support at least the
ASCII characters 0x20 through 0x7F, which include spaces, digits, uppercase,
lowercase, and some special characters. If the line display does not support
lowercase characters, then the Service may translate them to uppercase.
Starting with Release 1.7, escape sequences are supported.

Every escape sequence begins with the escape character ESC, whose value is 27
decimal, followed by a vertical bar ('|'). This is followed by zero or more digits and/
or lowercase alphabetic characters. The escape sequence is terminated by an
uppercase alphabetic character.
The following escape sequences are recognized within the string data of the
displayText and displayTextAt methods. If an escape sequence specifies an
operation that is not supported by the line display, then it is ignored.
Commands Perform the indicated action.
Name Data Remarks

Displays the pre-stored bitmap. The character '#' is
replaced by the bitmap number. See setBitmap
Display bitmap ESC |#B method. (If this bitmap is not defined, or if the
bitmap cannot be properly displayed, then the
escape sequence is ignored.)
Characteristics These are reset at the end of each display method or by a

“Normal” sequence.
Name Data Remarks

Reverse video ESC |rvC Displays in reverse video format.
Blink ESC |kC Displays as blinking characters.
Restores line display characteristics to normal
Normal ESC |N
condition.
Device Sharing
The line display is an exclusive-use device, as follows:

• The application must claim and enable the device before accessing some
properties or calling methods that update the device.


BlinkRate Property Added in Release 1.6
Syntax BlinkRate: int32 { read-write, access after open }
Remarks Contains the blink cycle time in milliseconds. A blink cycle is the period of time
when text completes an on-off-on cycle during blinking. After this property is set,
the service will set the blink rate to the closest supported rate and change this
property to reflect the actual rate. Performing this approximation is necessary
because blink cycles are hardware dependent and probably not controllable at
precise millisecond granularity.
Value Meaning
E_ILLEGAL CapBlinkRate is false.
See Also CapBlinkRate Property.
CapBitmap Property Added in Release 1.7

Syntax CapBitmap: boolean { read-only, access after open }
Remarks If true, then the display of bitmaps is supported.
CapBlink Property
Syntax CapBlink: int32 { read-only, access after open }
Remarks Holds the character blink capability of the device. It has one of the following
values:
Value Meaning
DISP_CB_NOBLINK Blinking is not supported. Value is 0.
DISP_CB_BLINKALL Blinking is supported. The entire contents of the display
are either blinking or in a steady state.
DISP_CB_BLINKEACH
Blinking is supported. Each character may be
individually set to blink or to be in a steady state.

722 Line Display
CapBlinkRate Property Added in Release 1.6

Syntax CapBlinkRate: boolean { read-only, access after open }
Remarks If true, then the device’s blink rate can be controlled and the BlinkRate property
is used to indicate the rate at which the display blinks.
See Also BlinkRate Property.
CapBrightness Property
Syntax CapBrightness: boolean { read-only, access after open }
Remarks If true, then the brightness control is supported.
CapCharacterSet Property Updated in Release 1.5

Syntax CapCharacterSet: int32 { read-only, access after open }
Remarks Holds the default character set capability. It has one of the following values:
Value Meaning
DISP_CCS_NUMERIC The default character set supports numeric data, plus
space, minus, and period.
DISP_CCS_ALPHA The default character set supports uppercase alphabetic
plus numeric, space, minus, and period.
DISP_CCS_ASCII The default character set supports all ASCII characters
0x20 through 0x7F.
DISP_CCS_KANA The default character set supports partial code page 932,
including ASCII characters 0x20 through 0x7F and the
Japanese Kana characters 0xA1 through 0xDF, but
excluding the Japanese Kanji characters.
DISP_CCS_KANJI The default character set supports code page 932,
including the Shift-JIS Kanji characters, Levels 1 and 2.
DISP_CCS_UNICODE The default character set supports Unicode.
The default character set may contain a superset of these ranges. The initial
CharacterSet property may be examined for additional information.
See Also CharacterSet Property.

CapCursorType Property Updated in Release 1.8

Syntax CapCursorType: int32 { read-only, access after open }
Remarks Holds a bitwise indication of the cursor types supported by the device and
selectable via the CursorType property. The following are the values:
Value Meaning
DISP_CCT_NONE Cursor is not displayable.
DISP_CCT_FIXED Cursor is always displayed.
DISP_CCT_BLOCK Cursor is displayable as a block.
DISP_CCT_HALFBLOCK Cursor is displayable as a halfblock.
DISP_CCT_UNDERLINE Cursor is displayable as an underline.
DISP_CCT_REVERSE Cursor is displayable in reverse video.
DISP_CCT_BLINK A blinking cursor is supported.
DISP_CCT_OTHER Cursor is displayable but form is unknown.
If DISP_CCT_NONE is set, then none of the other values will be set. This is
because the cursor is not displayable.
If DISP_CCT_FIXED is set, DISP_CCT_BLINK may be set, and one and only
one of the other values will also be set. This other value will indicate the cursor
type that is always displayed.
CapCustomGlyph Property Added in Release 1.6

Syntax CapCustomGlyph: boolean { read-only, access after open }
Remarks Holds the glyph definition capability of the device. If true, then the device allows
custom glyphs to be defined.
CapDescriptors Property
Syntax CapDescriptors: boolean { read-only, access after open }
Remarks If true, then the display supports descriptors.

724 Line Display
CapHMarquee Property
Syntax CapHMarquee: boolean { read-only, access after open }
Remarks If true, the display supports horizontal marquee windows.
CapICharWait Property
Syntax CapICharWait: boolean { read-only, access after open }
Remarks If true, the display supports intercharacter wait.
CapMapCharacterSet Property Added in Release 1.7

Syntax CapMapCharacterSet: boolean { read-only, access after open}
Remarks Defines the ability of the Service to map the characters of the application to the
selected character set when displaying data.
If CapMapCharacterSet is true, then the Service is able to map the characters to
the character sets defined in CharacterSetList.
See Also CharacterSet Property, MapCharacterSet Property, CharacterSetList
Property.
CapReadBack Property Added in Release 1.6

Syntax CapReadBack: int32 { read-only, access after open }
Remarks Holds the capability of the video device to read back the data displayed upon it. It
may be one of the following:
Value Meaning
DISP_CRB_NONE Read back is not supported.
DISP_CRB_SINGLE Read back of a single character at a time is supported.

CapReverse Property Added in Release 1.6

Syntax CapReverse: int32 { read-only, access after open }
Remarks Holds the reverse video capability of the device. It may be one of the following:
Value Meaning
DISP_CR_NONE Reverse video is not supported. Value is 0.
DISP_CR_REVERSEALL Reverse video is supported. The entire contents of
the display are either in reverse video or normal.
DISP_CR_REVERSEEACH Reverse video is supported. Each character may be
individually set to reverse video or normal.
CapScreenMode Property Added in Release 1.7

Syntax CapScreenMode: boolean { read-only, access after open }
Remarks If true, then the display supports changing the screen mode (i.e., the number of text
rows and columns on the device).
See Also ScreenMode Property, ScreenModeList Property.
CapVMarquee Property
Syntax CapVMarquee: boolean { read-only, access after open }
Remarks If true, the display supports vertical marquee windows.

726 Line Display
CharacterSet Property Updated in Release 1.10

Syntax CharacterSet: int32 { read-write, access after open-claim-enable }
Remarks Holds the character set for displaying characters. It has one of the following
values:
Value Meaning
Range 101 - 199 Device-specific character sets that do not match a code
page or the ASCII or ANSI character sets.
Range 400 - 990 Code page; matches one of the standard values.
DISP_CS_UNICODE The character set supports Unicode. The value of this
constant is 997.
DISP_CS_ASCII The ASCII character set, supporting the ASCII
characters 0x20 through 0x7F. The value of this
constant is 998.
DISP_CS_ANSI The ANSI character set. The value of this constant is
999.
Range 1000 and above Code page; matches one of the standard values.
For additional implementation-specific information on the use of this property,

refer to the “Mapping of CharacterSet” section in the Appendices. For OPOS,
see page A-80, for JavaPOS, see page B-97.
This property is initialized to an appropriate value when the device is first enabled
following the open method. This value is guaranteed to support at least the set of
characters specified by CapCharacterSet.
See Also CharacterSetList Property, CapCharacterSet Property.
CharacterSetList Property
Syntax CharacterSetList: string { read-only, access after open }
Remarks Holds the character set numbers supported. It consists of ASCII numeric set
numbers separated by commas.
For example, if the string is “101,850,999”, then the device supports a device-
specific character set, code page 850, and the ANSI character set.

Columns Property
Syntax Columns: int32 { read-only, access after open }
Remarks Holds the number of columns for this window.
For window 0, this property is the same as DeviceColumns.
For other windows, it may be less or greater than DeviceColumns.
This property is initialized to DeviceColumns by the open method, and is updated
when CurrentWindow is set and when createWindow or destroyWindow are
called.
See Also Rows Property.
CurrentWindow Property Updated in Release 1.6

Syntax CurrentWindow: int32 { read-write, access after open }
Remarks Holds the current window to which text is displayed.
Several properties are associated with each window: Rows, Columns,
CursorRow, CursorColumn, CursorUpdate, CursorType, MarqueeFormat,
MarqueeType, MarqueeUnitWait, MarqueeRepeatWait, and
InterCharacterWait.
When set, this property changes the current window and sets the associated
properties to their values for this window.
Setting a window does not refresh its viewport. If this window and another
window’s viewports overlap, and the other window has changed the viewport, then
refreshWindow may be called to restore this window’s viewport contents.
This property is initialized to zero – the device window – by the open method, and
is updated when createWindow or destroyWindow are called.
Value Meaning
E_ILLEGAL The new current window value is invalid.

728 Line Display
CursorColumn Property
Syntax CursorColumn: int32 { read-write, access after open }
Remarks Holds the column in the current window to which the next displayed character will
be output.
Legal values range from zero through Columns. (See displayText for a note on
the interpretation of CursorColumn = Columns.)
This property is initialized to zero by the open and createWindow methods, and
is updated when CurrentWindow is set or clearText, displayTextAt, or
destroyWindow is called. It is also updated when displayText is called if
CursorUpdate is true.
Value Meaning
E_ILLEGAL An invalid cursor column value was specified.

See Also CursorRow Property, displayText Method.
CursorRow Property
Syntax CursorRow: int32 { read-write, access after open }
Remarks Holds the row in the current window to which the next displayed character will be
output.
Legal values range from zero through one less than Rows.
is updated when CurrentWindow is set or clearText, displayTextAt, or
destroyWindow is called. It is also updated when displayText is called if
CursorUpdate is true.
Value Meaning
E_ILLEGAL An invalid cursor row value was specified.
See Also CursorColumn Property, displayText Method.

CursorType Property Updated in Release 1.8

Syntax CursorType: int32 { read-write, access after open }
Remarks Holds the cursor type for the current window. The following are the possible
values:
Value Meaning
DISP_CT_NONE Cursor is not displayed.
DISP_CT_BLOCK Cursor is displayed as a block.
DISP_CT_HALFBLOCK Cursor is displayed as a halfblock.
DISP_CT_UNDERLINE Cursor is displayed as an underline.
DISP_CT_REVERSE Cursor is displayed in reverse video.
DISP_CT_BLINK A blinking cursor is supported. This value is to be
logically ORed with one of the other values defined
for this property.
DISP_CT_OTHER Cursor is displayed but form is unknown.
This property cannot be written if CapCursorType has either DISP_CCT_NONE
or DISP_CCT_FIXED set. Otherwise it can be set to one of the cursor types
specified by CapCursorType, and if supported, DISP_CT_BLINK can be
logically ORed with that cursor type to display a blinking cursor.
This property is maintained for each window. Setting this property affects only the
current window since only the current window has a displayable cursor.
This property is initialized to DISP_CT_NONE (or the appropriate cursor type if
CapCursorType has DISP_CCT_FIXED set) by the open and createWindow
methods, and is updated when CurrentWindow is set or destroyWindow is
called.
Value Meaning
E_ILLEGAL CapCursorType is either DISP_CCT_NONE or
DISP_CCT_FIXED is set, or an invalid cursor type
value was specified.
See Also CapCursorType Property.
CursorUpdate Property
Syntax CursorUpdate: boolean { read-write, access after open }
Remarks When true, CursorRow and CursorColumn will be updated to point to the
character beyond the last character output when characters are displayed using the
displayText or displayTextAt method. When false, the cursor properties will not
be updated when characters are displayed.
This property is maintained for each window. It initialized to true by the open and
createWindow methods, and is updated when CurrentWindow is set or
destroyWindow is called.
See Also CursorRow Property, CursorColumn Property.

730 Line Display
CustomGlyphList Property Added in Release 1.6

Syntax CustomGlyphList: string { read-only, access after open }
Remarks Contains character codes that are available for definition as glyphs. Character
codes are represented as two-digit (ASCII) or four-digit (Unicode) hexadecimal
values. These values are comma separated and each value may actually represent
a range of values specified by using the ‘-’ character.
For example, if the string is “2D,4D”, then the device supports glyph definitions
for the characters “-” and “M” respectively. If the string is “002D-004D”, then the
device supports glyph definitions for the Unicode characters between 002D and
004D inclusive. Also, if the string is “2D-2F,3D-3F”, then the device supports
glyph definitions for the ranges of hex characters 2D through 2F and 3D through
3F.
See Also CapCustomGlyph Property, GlyphHeight Property, GlyphWidth Property,
defineGlyph Method.
DeviceBrightness Property
Syntax DeviceBrightness: int32 { read-write, access after open-claim-enable }
Remarks Holds the device brightness value, expressed as a percentage between 0 and 100.
Any device can support 0% (blank) and 100% (full intensity). Blanking can, at a
minimum, be supported by sending spaces to the device. If CapBrightness is true,
then the device also supports one or more levels of dimming.
If a device does not support the specified brightness value, then the Service will
choose an appropriate substitute.
This property is initialized to 100 when the device is first enabled following the
open method.
Value Meaning
E_ILLEGAL An invalid value was used: Not in the range 0 - 100.
See Also CapBrightness Property.

DeviceColumns Property Updated in Release 1.7

Syntax DeviceColumns: int32 { read-only, access after open }
Remarks Holds the number of columns on this device.
This property is initialized by the open method. It is updated when the
ScreenMode property is changed.
See Also DeviceRows Property, ScreenMode Property.
DeviceDescriptors Property
Syntax DeviceDescriptors: int32 { read-only, access after open }
Remarks Holds the number of descriptors on this device. If CapDescriptors is true, then
this property is non-zero.
See Also setDescriptor Method, clearDescriptors Method.
DeviceRows Property Updated in Release 1.7

Syntax DeviceRows: int32 { read-only, access after open }
Remarks Holds the number of rows on this device.
This property is initialized by the open method. It is updated when the
See Also DeviceColumns Property, ScreenMode Property.
DeviceWindows Property
Syntax DeviceWindows: int32 { read-only, access after open }
Remarks Holds the maximum window number supported by this device. A value of zero
indicates that only the device window is supported and that no windows may be
created.
See Also CurrentWindow Property.

732 Line Display
GlyphHeight Property Added in Release 1.6

Syntax GlyphHeight: int32 { read-only, access after open }
Remarks Indicates the glyph height based on the number of pixels for a character cell.
See Also CapCustomGlyph Property, CustomGlyphList Property, defineGlyph Method.
GlyphWidth Property Added in Release 1.6
Syntax GlyphWidth: int32 { read-only, access after open }
Remarks Indicates the glyph width based on the number of pixels for a character cell.
See Also CapCustomGlyph Property, CustomGlyphList Property, defineGlyph Method.
InterCharacterWait Property
Syntax InterCharacterWait: int32 { read-write, access after open }
Remarks Holds the wait time between displaying each character with the displayText and
displayTextAt methods. This provides a “teletype” appearance when displaying
text.
This property is only used if the window is not in Marquee Mode — that is,
MarqueeType must be DISP_MT_NONE.
When non-zero and the window is not in Marquee Mode, the window is in
Teletype Mode: displayText and displayTextAt requests are enqueued and
processed in the order they are received. This property specifies the time to wait
between outputting each character into the viewport. The wait time is the specified
number of milliseconds. (Note that the system timer resolution may reduce the
precision of the wait time.) If CursorUpdate is true, CursorRow and
CursorColumn are updated to their final values before displayText or
displayTextAt returns, even though all of its data may not yet be displayed.
When this property is zero and the window is not in Marquee Mode, Immediate
Mode is in effect, so that characters are processed as quickly as possible. If some
display requests are enqueued at the time this property is set to zero, the requests
are completed as quickly as possible.
If CapICharWait is false, then intercharacter waiting is not supported, and the
value of this property is not used.
is updated when CurrentWindow is set or destroyWindow is called.
Value Meaning
E_ILLEGAL An illegal value was specified.
See Also displayText Method.

MapCharacterSet Property Added in Release 1.7

Syntax MapCharacterSet: boolean { read-write, access after open}
Remarks If MapCharacterSet is true and when outputting data, the Service maps the
characters transferred by the application to the character set selected in the
CharacterSet property for displaying data.
If MapCharacterSet is false, then no mapping is supported. In such a case the
application has to ensure the mapping of the character set used in the application
to the character set selected in the CharacterSet property.
If CapMapCharacterSet is false, then this property is always false.
See Also CharacterSet Property, CapMapCharacterSet Property.
MarqueeFormat Property
Syntax MarqueeFormat: int32 { read-write, access after open }
Remarks Holds the marquee format for the current window.
Value Meaning
DISP_MF_WALK Begin the marquee by walking data from the opposite
side. For example, if the marquee type is “left,” then the
viewport is filled by bringing characters into the right
side and scrolling them to the left.
DISP_MF_PLACE Begin the marquee by placing data. For example, if the
marquee type is “left,” then the viewport is filled by
placing characters starting at the left side, and beginning
scrolling only after the viewport is full.
This property is initialized to DISP_MF_WALK by the open and createWindow
called.
This property is read when a transition is made to Marquee On Mode. It is not used
when not in Marquee Mode.
When this property is DISP_MF_WALK, and a transition is made from Marquee
Init Mode to Marquee On Mode, the following occurs:
1. Map the window to the viewport as follows:
Marquee TypeWindow Viewport
LeftFirst Column = Last Column
UpFirst Row = Last Row
RightLast Column = First Column
DownLast Row = First Row
Fill the viewport with blanks. Continue to Step 2 without waiting.

734 Line Display
2. Display the mapped portion of the window into the viewport, then wait Mar-
queeUnitWait milliseconds. Move the window mapping onto the viewport by
one row or column in the marquee direction. Repeat until the viewport is full.
3. Refresh the viewport, then wait MarqueeUnitWait milliseconds. Move the
window mapping by one row or column. Repeat until the last row or column
is scrolled into the viewport (in which case, omit the unit wait).
4. Wait MarqueeRepeatWait milliseconds. Then go to step back to Step 1.
When this property is DISP_MF_PLACE, and a transition is made from Marquee
Init Mode to Marquee On Mode, the following occurs:
1. Map the window to the viewport as follows:
Marquee TypeWindow Viewport
LeftFirst Column = First Column
UpFirst Row = First Row
RightLast Column = Last Column
DownLast Row = Last Row
Fill the viewport with blanks. Continue to Step 2 without waiting.
2. Display a row or column into viewport, then wait MarqueeUnitWait milli-
seconds. Repeat until the viewport is full.
3. Move the window mapping onto the viewport by one row or column in the
marquee direction, and refresh the viewport, then wait MarqueeUnitWait
milliseconds. Repeat until the last row or column is scrolled into the viewport
(in which case, omit the unit wait).
4. Wait MarqueeRepeatWait milliseconds. Then go to step back to Step 1.
Value Meaning
E_ILLEGAL An invalid value was used, or attempted to change
window 0.
See Also MarqueeType Property, MarqueeUnitWait Property, MarqueeRepeatWait
Property.
Example 1 Marquee Walk format.
- Assume a 2x20 display.
- An application has a line display instance named myLD.
- The application has performed:
myLD.createWindow(0, 3, 2, 3, 2, 5); // 2x3 viewport of 2x5 window
myLD.displayText(“0123456789”, DISP_DT_NORMAL);
The window contains:
0 1 2 3 4
0 0 1 2 3 4
1 5 6 7 8 9

and the display contains (assuming the other windows are all blank):
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0 1 2
1 5 6 7
If the application performs the sequence:

myLD.setMarqueeType(DISP_MT_INIT);
myLD.setMarqueeFormat(DISP_MF_WALK);
myLD.displayTextAt(0, 4, “AB”, DISP_DT_NORMAL);
the viewport is not changed (since we are in Marquee Init Mode), and the window
becomes:
0 1 2 3 4
0 0 1 2 3 A
1 B 6 7 8 9
If the application performs:

myLD.setMarqueeType(DISP_MT_LEFT);
the window is not changed, and the viewport becomes:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0
1 B
After MarqueeUnitWait milliseconds, the viewport is changed to:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0 1
1 B 6

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0 1 2
1 B 6 7

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 1 2 3
1 6 7 8

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 2 3 A
1 7 8 9

736 Line Display
The marquee has scrolled to the end of the window.

After MarqueeRepeatWait milliseconds, the marquee display restarts with the
viewport changing to:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0
1 B
Example 2 Marquee Place format.

- Assume a 2x20 display.
myLD.displayText(“0123456789”, DISP_DT_NORMAL);
0 1 2 3 4
0 0 1 2 3 4
1 5 6 7 8 9
and display contains (assuming the other windows are all blank):
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0 1 2
1 5 6 7
If the application performs the sequence:

myLD.setMarqueeType(DISP_MT_INIT);
myLD.setMarqueeFormat(DISP_MF_PLACE);
myLD.displayTextAt(0, 4, “AB”, DISP_DT_NORMAL);
the viewport is not changed (since we are in Marquee Init Mode), and the window
becomes:
0 1 2 3 4
0 0 1 2 3 A
1 B 6 7 8 9
If the application performs:

myLD.setMarqueeType(DISP_MT_LEFT);
the window is not changed, and the viewport becomes:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0
1 B

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0 1
1 B 6


0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0 1 2
1 B 6 7
From this point to the end of the window, the marquee action is the same as with
marquee walking…
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 1 2 3
1 6 7 8

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 2 3 A
1 7 8 9
The marquee has scrolled to the end of the window.

After MarqueeRepeatWait milliseconds, the marquee display restarts with the
viewport changing to:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 0
1 B
MarqueeRepeatWait Property
Syntax MarqueeRepeatWait: int32 { read-write, access after open }
Remarks Holds the wait time between scrolling the final character or row of the window into
its viewport and restarting the marquee with the first or last character or row.
The wait time is the specified number of milliseconds. (Note that the timer
resolution may reduce the precision of the wait time.)
This property is not used if not in Marquee Mode.
Value Meaning
See Also MarqueeType Property, MarqueeFormat Property, MarqueeUnitWait
Property.

738 Line Display
MarqueeType Property
Syntax MarqueeType: int32 { read-write, access after open }
Remarks Holds the marquee type for the current window. When not DISP_MT_NONE, the
window is in Marquee Mode. This property has one of the following values:
Value Meaning
DISP_MT_NONE Marquees are disabled for this window.

DISP_MT_INIT Marquee Init Mode. Changes to the window are not
reflected in the viewport until this property is changed to
another value.
DISP_MT_UP Scroll the window up. Illegal unless Rows is greater
than the viewportHeight parameter used for the
window’s createWindow call, and CapVMarquee is
true.
DISP_MT_DOWN Scroll the window down. Illegal unless Rows is greater
than the viewportHeight parameter used for the
window’s createWindow call, and CapVMarquee is
true.
DISP_MT_LEFT Scroll the window left. Illegal unless Columns is greater
than the viewportWidth parameter used for the
window’s createWindow call, and CapHMarquee is
true.
DISP_MT_RIGHT Scroll the window right. Illegal unless Columns is
greater than the viewportWidth parameter used for the
window’s createWindow call, and CapHMarquee is
true.
A marquee is typically initialized after entering Marquee Init Mode by setting this
property to DISP_MT_INIT, then calling clearText and displayText(At)
methods. Then, when this property is changed to an “on” value, Marquee On
Mode is entered, and the marquee begins to be displayed in the viewport beginning
at the start of the window (or end if the type is right or down).
When the mode is changed from Marquee On Mode to Marquee Off Mode, the
marquee stops in place. A subsequent transition back to Marquee On Mode
continues from the current position.
When the mode is changed from Marquee On Mode to Marquee Init Mode, the
marquee stops. Changes may be made to the window, then the window may be
returned to Marquee On Mode to restart the marquee with the new data.
This property is always DISP_MT_NONE for window 0 – the device window.
This property is initialized to DISP_MT_NONE by the open and createWindow
called.

Value Meaning
E_ILLEGAL An invalid value was used, or attempted to change

window 0.
See Also MarqueeFormat Property, MarqueeUnitWait Property, MarqueeRepeatWait
Property.
MarqueeUnitWait Property
Syntax MarqueeUnitWait: int32 { read-write, access after open }
Remarks Holds the wait time between marquee scrolling of each column or row in the
window.
The wait time is the specified number of milliseconds. (Note that the timer
resolution may reduce the precision of the wait time.)
This property is not used if MarqueeType is DISP_MT_NONE.
Value Meaning
See Also MarqueeType Property, MarqueeFormat Property, MarqueeRepeatWait
Property.
MaximumX Property Added in Release 1.7

Syntax MaximumX: int32 { read-only, access after open }
Remarks A value of zero indicates that bitmaps are not supported. Otherwise, contains the
maximum number of horizontal pixels supported by the device. It must be less than
65,536. Dividing MaximumX by DeviceColumns gives the number of pixels
required for each character.
This property is initialized by the open method. It may be updated when the
See Also DeviceColumns Property, ScreenMode Property.MaximumY Property.

740 Line Display
MaximumY Property Added in Release 1.7

Syntax MaximumY: int32 { read-only, access after open }
Remarks A value of zero indicates that bitmaps are not supported. Otherwise, contains the
maximum number of vertical pixels supported by the device. It must be less than
65,536. Dividing MaximumY by DeviceRows gives the number of pixels
required for each character
This property is initialized by the open method. It may be updated when the
See Also DeviceRows Property, MaximumX Property, ScreenMode Property.
Rows Property
Syntax Rows: int32 { read-only, access after open }
Remarks Holds the number of rows for this window.
For window 0, this property is the same as DeviceRows.
For other windows, it may be less or greater than DeviceRows.
This property is initialized to DeviceRows by the open method, and is updated
when CurrentWindow is set or createWindow or destroyWindow are called.
See Also Columns Property.
ScreenMode Property Added in Release 1.7

Syntax ScreenMode: int32 { read-write, access after open-claim }
Remarks Contains the screen mode value of the device. If CapScreenMode is false, then
only a value of zero is allowed. If CapScreenMode is true, then the values can be
set to index the values contained in ScreenModeList. For example:
0 = Default value
1 = First setting in ScreenModeList
2 = Second setting in ScreenModeList, etc.
Note: This property can only be updated when the device is opened and claimed,
but not enabled.
Changing the ScreenMode property also changes the DeviceColumns and
DeviceRows properties to the new screen size. Also, for some devices, the
MaximumX and MaximumY properties may be changed due to the columns and/
or rows requiring a different number of physical pixels. For example, if the display
physically contains 48x256 pixels and supports 2x20, 4x32, and 5x32, then the
Service layout may be:

Pixels Pixels Unused Unused

Mode per per MaximumY MaximumX Vertical Horizontal
Row Column Pixels Pixels
2x20 24 12 48 240 0 16
4x32 12 8 48 256 0 0
5x32 8 8 40 256 8 0

See Also CapScreenMode Property, DeviceColumns Property, DeviceRows Property,
MaximumX Property, MaximumY Property, ScreenModeList Property.
ScreenModeList Property Added in Release 1.7

Syntax ScreenModeList: string { read-only, access after open }
Remarks Contains the comma-delimited list of row-column pairs that are supported by the
device.
If CapScreenMode is false, only one pair will be listed. For example, if the device
only supports 2 rows and 20 columns, then this property should be set to “2x20”.
If the device can operate in 2 by 20, 4 by 32, or 5 by 32 modes, then this property
should be set to “2x20,4x32,5x32”.
See Also CapScreenMode Property, ScreenMode Property.

742 Line Display
clearDescriptors Method
Syntax clearDescriptors ( ):
Remarks Turns off all descriptors.
This function is illegal if CapDescriptors is false.
Value Meaning
E_ILLEGAL The device does not support descriptors.

See Also setDescriptor Method, DeviceDescriptors Property, CapDescriptors Property.
clearText Method Updated in Release 1.7

Syntax clearText ( ):
Remarks Clears the current window to blanks, sets CursorRow and CursorColumn to
zero, and resynchronizes the beginning of the window with the start of the
viewport. All clears all bitmaps displayed in the window.
If in Immediate Mode or Teletype Mode, the viewport is also cleared immediately.
If in Marquee Init Mode, the viewport is not changed.
If in Marquee On Mode, this method is illegal.
Value Meaning
E_ILLEGAL In Marquee On Mode.


createWindow Method Updated in Release 1.6

Syntax createWindow ( viewportRow: int32, viewportColumn: int32,
viewportHeight: int32, viewportWidth: int32, windowHeight: int32,
windowWidth: int32 ):
viewportRow The viewport’s start device row.
viewportColumn The viewport’s start device column.
viewportHeight The number of device rows in the viewport.
viewportWidth The number of device columns in the viewport.
windowHeight The number of rows in the window.
windowWidth The number of columns in the window.
Remarks Creates a viewport over the portion of the display given by the first four
parameters. The window size is given by the last two parameters. Valid window
row values range from zero to one less than windowHeight and column values
range from zero to one less than windowWidth.
The window size must be at least as large as the viewport size.
The window size may be larger than the viewport size in one direction. Using the
window marquee properties MarqueeType, MarqueeFormat,
MarqueeUnitWait, and MarqueeRepeatWait, such a window may be
continuously scrolled in a marquee fashion.
When successful, createWindow sets the CurrentWindow property to the
window number assigned to this window. The following properties are maintained
for each window, and are initialized as given:
Property Value
Rows Set to windowHeight.
Columns Set to windowWidth.
CursorRow Set to 0.
CursorColumn Set to 0.
CursorType Set to DISP_CT_NONE (or the appropriate cursor type
if CapCursorType has DISP_CCT_FIXED set).
CursorUpdate Set to true.
MarqueeType Set to DISP_MT_NONE.
MarqueeFormat Set to DISP_MF_WALK.
MarqueeUnitWait Set to 0.
MarqueeRepeatWait Set to 0.
InterCharacterWait Set to 0.
Value Meaning
E_ILLEGAL One or more parameters are out of their valid ranges, or
all available windows are already in use.
See Also CapCursorType Property, CurrentWindow Property, destroyWindow Method.

744 Line Display
defineGlyph Method Updated in Release 1.7

Syntax defineGlyph ( glyphCode: int32, glyph: binary ):
glyphCode The character code to be defined.

glyph Data bytes that define the glyph.1
Remarks Defines a glyph character.

The glyph is defined as bits representing each pixel packed into bytes using whole
bytes to represent each row.
The minimum number of bytes are sent for each row, based on GlyphWidth and
using 8 bits per byte. Bytes are sent left-to-right across each row; if more than one
byte is required per row, the leftmost byte is sent first. The lowest-order bit within
a byte represents the rightmost pixel. Bits that do not represent pixels are the
highest order bits and their value is ignored. Rows are sent from the top down.
A 10 pixel wide glyph would have the two leftmost pixels represented in bits 1 and
0 of the first byte, respectively. The remaining 8 pixels would be represented in the
second byte.
Enough rows must be sent to define the entire character. Whether changing the
definition of a glyph causes currently displayed characters to change, or the change
appears only when next drawn, is hardware-defined.
Example: A 5 column 7 row character cell –
Bit Position
Byte Hex Value
76543210
.*... 0 08
..*.. 1 04
*..*. 2 12
.*..* 3 09
..*.. 4 04
...*. 5 02
....* 6 01

Example: A 12 column by 16 row character cell –
Bit Position
111111 Bytes Hex Values
5432109876543210
............ 0,1 00 00
.....*...... 2,3 00 40
....***..... 4,5 00 E0
...**.**.... 6,7 01 B0
..**...**... 8,9 03 18
..**...**... 10,11 03 18
..*******... 12,13 03 F8
..*******... 14,15 03 F8
..**...**... 16,17 03 18
..**...**... 18,19 03 18
..**...**... 20,21 03 18
............ 22,23 00 00
............ 24,25 00 00
............ 26,27 00 00
............ 28,29 00 00
............ 30,31 00 00
This function is illegal if CapCustomGlyph is false.

Value Meaning
E_ILLEGAL CapCustomGlyph is false, or glyphCode is an

unsupported character code for glyph definition.
See Also CapCustomGlyph Property, CustomGlyphList Property, GlyphHeight
Property, GlyphWidth Property.

746 Line Display
destroyWindow Method
Syntax destroyWindow ( ):
Remarks Destroys the current window. The characters displayed in its viewport are not
changed.
CurrentWindow is set to window 0. The device window and the associated
window properties are updated.
Value Meaning
E_ILLEGAL The current window is 0. This window may not be
destroyed.
See Also createWindow Method, CurrentWindow Property.
displayBitmap Method Added in Release 1.7

Syntax displayBitmap ( fileName:string,width:int32,alignmentX:int32,alignmentY:int32 ):
fileName File name or URL of bitmap file. Various file formats
may be supported, such as bmp, gif, or jpeg files.2
width Width of the bitmap to be displayed. See values below.
alignmentX Horizontal placement of the bitmap. See values below.
alignmentY Vertical placement of the bitmap. See values below.
The width parameter has one of the following values:
Value Meaning
DISP_BM_ASIS Display the bitmap with one bitmap pixel per dot.
Other values Bitmap width expressed in number of pixels.
The alignmentX parameter has one of the following values:
Value Meaning
DISP_BM_LEFT Align the bitmap's left edge with the leftmost pixel of the
current character position, as specified by
CursorColumn.
DISP_BM_CENTER Align the bitmap in the horizontal center of the current
character position, as specified by CursorColumn.
DISP_BM_RIGHT Align the bitmap's right edge with the rightmost pixel of
the current character position, as specified by
CursorColumn.
2.
In the OPOS environment, the Service Object must support two-color (black and
white) uncompressed Windows bitmaps. Black pixels are displayed with the
foreground color, while white pixels are displayed with the background color.
Additional formats may be supported.

Other values Distance from the window’s leftmost pixel column to

the left edge of the bitmap, expressed in number of
pixels.
The alignmentY parameter has one of the following values:
Value Meaning
DISP_BM_TOP Align the bitmap's top edge with the topmost pixel of the
current character position, as specified by CursorRow.
DISP_BM_CENTER Align the bitmap in the vertical center of the current
character position, as specified by CursorRow.
DISP_BM_BOTTOM Align the bitmap's bottom edge with the bottommost
pixel of the current character position, as specified by
CursorRow.
Other values Distance from the window’s topmost pixel row to the
start of the bitmap, expressed in number of pixels.
Remarks Called to display a bitmap on the LineDisplay. The bitmap is displayed within the
current window’s viewport.
If DISP_BM_... constants are specified for alignmentX and alignmentY, then it is
displayed in relation to the character position specified by CursorRow and
CursorColumn. If, in addition, CursorUpdate is true, then CursorRow and
CursorColumn are updated to point to the first character position following the
bitmap.
If the bitmap does not exactly occupy a multiple of rows and columns, then the
unoccupied pixels of those character positions which are partially occupied are
displayed with the background color. In other words, the Service will effectively
fill all character positions partially or completely occupied by the bitmap with the
background color before drawing the bitmap.
Bitmap display has the following restrictions:
• Bitmap display is only legal in Immediate Mode.
• The window size must match the window's viewport size.
• The bitmap must be displayable within the window, after consideration of the
function parameters. For example, if alignmentX specifies a pixel near the
bottom of the window, and the bitmap height (after bitmap transformation, if
required) exceeds the distance from alignmentX to the window bottom, then
the bitmap is not displayed.
The width parameter controls transformation of the bitmap. If width is
DISP_BM_ASIS, then no transformation is performed. The bitmap is displayed
with one bitmap pixel per line display pixel. The advantages of this option are that
it:
• Provides the highest performance bitmap display.
• Works well for bitmaps tuned for a specific LineDisplay's aspect ratio
between horizontal and vertical dots.
If width is non-zero, then the bitmap will be transformed by stretching or
compressing the bitmap such that its width is the specified width and the aspect
ratio is unchanged. The advantages of this option are that it:
• Sizes a bitmap to fit a variety of LineDisplays.
• Maintains the bitmap's aspect ratio.

748 Line Display
The disadvantages of this option are:

• Lower performance than untransformed data.
• Some lines and images that are “smooth” in the original bitmap may show
some “ratcheting”.
Value Meaning
• The LineDisplay does not support bitmap display
(CapBitmap is false).
• The width parameter is invalid or too big.
• The alignmentX / alignmentY parameter is invalid or
too big.
• The window is not in Immediate Mode.
• The window size does not match its viewport size.
• The bitmap is too large to display at the requested
location.
E_NOEXIST The fileName was not found.
E_EXTENDED ErrorCodeExtended = EDISP_TOOBIG:
The bitmap is either too wide to display without
transformation, or it is too big to transform.
ErrorCodeExtended = EDISP_BADFORMAT:
The specified file is either not a bitmap file or it is an
unsupported format.
See Also CapBitmap Property, CursorColumn Property, CursorRow Property,
CursorUpdate Property.
displayText Method Updated in Release 1.7
Syntax displayText ( data: string, attribute: int32 ):
data The string of characters to display.3
attribute The display attribute for the text. Must be either
DISP_DT_NORMAL, DISP_DT_BLINK,
DISP_DT_REVERSE, or DISP_DT_BLINK_REVERSE.
Remarks The characters in data are processed beginning at the location specified by
CursorRow and CursorColumn, and continue in succeeding character positions.
Any previous data in a character position is overwritten, including character and
bitmap data.
Character processing continues to the next row when the end of a window row is
reached. If the end of the window is reached with additional characters to be
processed, then the window is scrolled upward by one row and the bottom row is

set to blanks. If CursorUpdate is true, then CursorRow and CursorColumn are

updated to point to the character position following the last character of data.
Note
Scrolling will not occur when the last character of data is placed at the end of a row. In this
case, when CursorUpdate is true, then CursorRow is set to the row containing the last
character, and CursorColumn is set to Columns (that is, to one more than the final
character of the row).
This stipulation ensures that the display does not scroll when a character is written into its
last position. Instead, the Service will wait until another character is written before scrolling
the window.
The operation of displayText (and displayTextAt) varies for each mode:

• Immediate Mode (MarqueeType = DISP_MT_NONE and
InterCharacterWait = 0): Updates the window and viewport immediately.
• Teletype Mode (MarqueeType = DISP_MT_NONE and
InterCharacterWait not = 0): data is enqueued. Enqueued data requests are
processed in order (typically by another thread within the Service), updating
the window and viewport using a wait of InterCharacterWait milliseconds
after each character is sent to the viewport.
• Marquee Init Mode (MarqueeType = DISP_MT_INIT): Updates the
window, but doesn’t change the viewport.
• Marquee On Mode (MarqueeType not = DISP_MT_INIT): Illegal.
If CapBlink is DISP_CB_NOBLINK, then attribute value DISP_DT_BLINK is
ignored, and attribute DISP_DT_BLINK_REVERSE is treated as
DISP_DT_REVERSE. If CapBlink is DISP_CB_BLINKALL, then the entire
display will blink when one or more characters have been set to blink. If CapBlink
is DISP_CB_BLINKEACH, then only those characters displayed with the blink
attribute will blink.
If CapReverse is DISP_CR_NONE, then attribute value DISP_DT_REVERSE is
ignored, and attribute DISP_DT_BLINK_REVERSE is treated as
DISP_DT_BLINK. If CapReverse is DISP_CR_REVERSEALL, then the entire
display will be displayed in reverse video when one or more characters have been
set to reverse. If CapReverse is DISP_CR_REVERSEEACH, then only those
characters displayed with the reverse attribute will be displayed in reverse video.
The attribute parameter value establishes the initial blink and reverse video
attributes. Beginning with Release 1.7, escape sequences within data may be used
to set or reset these attributes.
Value Meaning
Carriage Return (13 decimal) Change the next character’s output position to
the beginning of the current row.
Line Feed (10 decimal) Change the next character’s output position to
the beginning of the next row. Scroll the
window if the current row is the last row of the
window.

750 Line Display
Value Meaning
E_ILLEGAL attribute is illegal, or the display is in Marquee On
Mode.
See Also CapBlink Property, CapReverse Property, CursorColumn Property,
CursorRow Property, CursorUpdate Property, InterCharacterWait Property,
clearText Method, displayTextAt Method.
displayTextAt Method Updated in Release 1.7

Syntax displayTextAt ( row: int32, column: int32, data: string, attribute: int32 ):
row The start row for the text.
column The start column for the text.
data The string of characters to display.4
attribute The display attribute for the text. Must be either
DISP_DT_NORMAL, DISP_DT_BLINK,
DISP_DT_REVERSE, or DISP_DT_BLINK_REVERSE.
Remarks The characters in data are processed beginning at the window location specified
by the row and column parameters, and continuing in succeeding columns.
The operational characteristics of the displayTextAt method are the same as the
displayText method.
This method has the same effect as setting the CursorRow to row, setting
CursorColumn to column, and calling the displayText method.
Value Meaning
E_ILLEGAL row or column are out or range, attribute is illegal, or in
Marquee On Mode.
See Also CapBlink Property, CapReverse Property, CursorColumn Property,
CursorRow Property, InterCharacterWait Property, displayText Method,
clearText Method.

readCharacterAtCursor Method Added in Release 1.6

Syntax readCharacterAtCursor ( inout cursorData: int32 ):
cursorData The character read from the display.
Remarks Reads the currently displayed character at the cursor position.
This function is illegal if CapReadBack is DISP_CRB_NONE.
Value Meaning
E_ILLEGAL CapReadBack is DISP_CRB_NONE.
See Also CapReadBack Property.
refreshWindow Method
Syntax refreshWindow ( window: int32 ):
The window parameter specifies which window must be refreshed.
Remarks Changes the current window to window, then redisplays its viewport. Neither the
mapping of the window to its viewport nor the window’s cursor position is
changed.
This function may be used to restore a window after another window has
overwritten some of its viewport.
Value Meaning
E_ILLEGAL window is larger than DeviceWindows or has not been

created, or in Marquee On Mode.
See Also DeviceWindows Property.

752 Line Display
scrollText Method Updated in Release 1.7

Syntax scrollText ( direction: int32, units: int32 ):
The direction parameter indicates the scrolling direction, and is one of the
following values:
Value Meaning
DISP_ST_UP Scroll the window up.
DISP_ST_DOWN Scroll the window down.
DISP_ST_LEFT Scroll the window left.
DISP_ST_RIGHT Scroll the window right.
The units parameter indicates the number of columns or rows to scroll.
Remarks Scrolls the current window.
This function is only legal in Immediate Mode.
If the window size for the scroll direction matches its viewport size, then the
window data is scrolled, the last units rows or columns are set to spaces, and the
viewport is updated. If the window contains bitmap data, it is also scrolled.
If the window size for the scroll direction is larger than its viewport, then the
window data is not changed. Instead, the mapping of the window into the viewport
is moved in the specified direction. The window data is not altered, but the
viewport is updated. If scrolling by units would go beyond the beginning of the
window data, then the window is scrolled so that the first viewport row or column
contains the first window row or column. If scrolling by units would go beyond the
end of the window data, then the window is scrolled so that the last viewport row
or column contains the last window row or column.
Value Meaning
E_ILLEGAL direction is illegal, or in Teletype Mode or Marquee
Mode.
Example 1 - Assume a 2x20 display.

myLD.displayText(“abcdABCD”, DISP_DT_NORMAL);
0 1 2 3
0 a b c d
1 A B C D

and the viewport on the display is:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 a b c d
1 A B C D
If the application next performs:

myLD.scrollText (DISP_ST_LEFT, 2);
the window data becomes:
0 1 2 3
0 c d
1 C D
and the viewport becomes:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 c d
1 C D
Example 2 - Assume a 2x20 display.

myLD.displayText(“abcdefghABCDEFGH”, DISP_DT_NORMAL);
0 1 2 3 4 5 6 7
0 a b c d e f g h
1 A B C D E F G H
and the viewport on the display is:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 a b c d
1 A B C D

myLD.scrollText (DISP_ST_LEFT, 2);
the window data is unchanged, and the viewport becomes:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 c d e f
1 C D E F

754 Line Display

myLD.scrollText (DISP_ST_UP, 1);
the window data becomes:
0 1 2 3 4 5 6 7
0 A B C D E F G H
1
and the viewport becomes:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 C D E F
1
setBitmap Method Added in Release 1.7

Syntax setBitmap ( bitmapNumber: int32, fileName: string, width: int32, alignmentX: int32,
alignmentY: int32 ):
bitmapNumber The number to be assigned to this bitmap. Valid bitmap
numbers are 1 through 100.
If set to the empty string (“”), then the bitmap is unset.
width Width of the bitmap to be displayed. See values below.
alignmentX Horizontal placement of the bitmap. See values below.
alignmentY Vertical placement of the bitmap. See values below.
Value Meaning
DISP_BM_ASIS Display the bitmap with one bitmap pixel per dot.
Other values Bitmap width expressed in number of pixels.
The alignmentX parameter has one of the following values:
Value Meaning
DISP_BM_LEFT Align the bitmap’s left edge with the leftmost pixel of
the current character position.
DISP_BM_CENTER Align the bitmap in the horizontal center of the current
character position.
DISP_BM_RIGHT Align the bitmap’s right edge with the rightmost pixel of
5.
white) uncompressed Windows bitmaps. Black pixels are displayed with the
foreground color, while white pixels are displayed with the background color.
Additional formats may be supported.

Other values Distance from the window’s leftmost pixel column to

the left edge of the bitmap, expressed in number of
pixels.
The alignmentY parameter has one of the following values:
Value Meaning
DISP_BM_TOP Align the bitmap’s top edge with the topmost pixel of
DISP_BM_CENTER Align the bitmap in the vertical center of the current
character position.
DISP_BM_BOTTOM Align the bitmap’s bottom edge with the bottommost
pixel of the current character position.
Other values Distance from the window’s topmost pixel row to the
start of the bitmap, expressed in number of pixels.
Remarks Called to save information about a bitmap for later display.
The bitmap may then be displayed by calling the displayText or displayTextAt
method with the display bitmap escape sequence in the display data. The display
bitmap escape sequence will typically be included in a string for displaying
advertisements, store logos, or icons. See the Remarks section of displayBitmap
for restrictions on displaying the saved bitmap. If one or more restrictions are not
fulfilled, then the bitmap is not displayed, and the method continues on with the
next character of display data.
A Service may choose to cache the bitmap for later use to provide better
performance. Regardless, the bitmap file and parameters are validated for
correctness by this method.
The most frequently used bitmaps should be assigned a small bitmapNumber
(close to 1), while occasionally used bitmaps should be assigned the larger
bitmapNumbers. The Service will use this information to determine how best to
store the bitmaps. It may download them to the device when possible, or cache
them in Service memory, or simply remember the fileName and associated
properties for use when it is displayed.
An application must ensure that the LineDisplay window metrics, such as
viewport width and height, are set before calling this method. A Service may
perform transformations on the bitmap in preparation for later displaying based on
the current values of these metrics.
Value Meaning

• The bitmapNumber parameter is invalid.
• The LineDisplay does not support bitmap display
(CapBitmap is false).
• The width parameter is invalid or too big.
• The alignmentX or alignmentY parameter is invalid or
too big.

756 Line Display
E_NOEXIST The fileName was not found.

E_EXTENDED ErrorCodeExtended = EDISP_TOOBIG:
The bitmap is either too wide to display without
ErrorCodeExtended = EDISP_BADFORMAT:
The specified file is either not a bitmap file or it is an
unsupported format.
See Also CapBitmap Property, displayBitmap Method, displayText Method,
displayTextAt Method.
setDescriptor Method
Syntax setDescriptor ( descriptor: int32, attribute: int32 ):
The descriptor parameter indicates which descriptor to change. The value may
range between zero and one less than DeviceDescriptors.
The attribute parameter indicates the attribute for the descriptor. It has one of the
following values:
Value Meaning
DISP_SD_ON Turns the descriptor on.
DISP_SD_BLINK Sets the descriptor to blinking.
DISP_SD_OFF Turns the descriptor off.
Remarks Sets the state of one of the descriptors, which are small indicators with a fixed
label.
This function is illegal if CapDescriptors is false.
The device and its Service determine the mapping of descriptor to its descriptors.
Value Meaning
E_ILLEGAL The device does not support descriptors, or one of the
parameters contained an illegal value.
See Also clearDescriptors Method, DeviceDescriptors Property, CapDescriptors
Property.


DirectIOEvent
means for a vendor-specific Line Display Service to provide events to the
Service.
from being used with other vendor’s Line Display devices which may not have any
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a Line Display.
Status int32 Reports a change in the power state of a display.

process.
Remarks Enqueued when the Line Display detects a power state change.

758 Line Display

C H A P T E R 2 3
MICR - Magnetic Ink Character Recognition

Reader
This Chapter defines the MICR - Magnetic Ink Character Recognition Reader
device category.
Summary

760 MICR - Magnetic Ink Character Recognition Reader
Amount: string { read-only } 1.0 open
BankNumber: string { read-only } 1.0 open
CapValidationDevice: boolean { read-only } 1.0 open
CheckType: int32 { read-only } 1.0 open
CountryCode: int32 { read-only } 1.0 open
EPC: string { read-only } 1.0 open
RawData: string { read-only } 1.0 open
SerialNumber: string { read-only } 1.0 open
TransitNumber: string { read-only } 1.0 open

Common
Name Version
close ( ): 1.0
release ( ): 1.0
clearInput ( ): 1.0
void { } supported

Summary 761

Specific
Name
endRemoval ( ): 1.0


General Information
The MICR - Magnetic Ink Character Recognition Reader programmatic name is

“MICR”.
Capabilities
The MICR Control has the following minimal set of capabilities:
• Reads magnetic ink characters from a check.
• Provides programmatic control of check insertion, reading and removal. For
some MICR devices, this will require no processing in the Service since the
device may automate many of these functions.
• Parses the MICR data into output properties. This version of the specification
defines the parsing of fields as specified in the ANSI MICR standard used in
North America. For other countries, the application may need to parse the
MICR data from the data in RawData.
The MICR device may be physically attached to or incorporated into a check val-
idation print device. If this is the case, once a check is inserted via MICR Control
methods, the check can still be used by the Printer Control prior to check removal.
Some MICR devices support exception tables, which cause non-standard parsing
of the serial number for specific check routing numbers. Exception tables are not
directly supported by this specification release. However, a Service may choose to
support them, and could assign entries under its device name to define the
exception entries.
This release of the specification does not define any parsing of partial MICR check
data if an error occurs while reading a check. This is done intentionally since any
Service that implements such functionality cannot guarantee that fields parsed
from partial data are correct. For example, it is possible to get MICR data that
contains no ‘?’ characters, but fails its checksum. This would indicate that one or
more characters in the data are incorrect, but there is no way to determine which
characters they are. If an application wishes to try and parse the partial data itself,
the RawData property is filled in with whatever was read even in error cases.

MICR Class Diagram
The following diagram shows the relationships between the MICR classes.
<<utility>>
<<exception>> <<Interface>> <<uses>> UposConst
UposException BaseControl (from upos)
(from upos) <<sends>> (from upos)
<<event>>
DataEvent
(from events)
<<utility>>
<<sends>> MICRCons t
fires (from upos)
<<event>>
<<Interface>>
DirectIOEvent
MICRControl <<us es>>
(from events)
(from upos)
<<capability>> CapValidationDevice : boolean
<<prop>> Data : int32 fires <<prop>> AccountNumber : string
<<prop>> Amount : string
<<prop>> BankNumber : string
<<prop>> CheckType : int32
<<prop>> CountryCode : int32
<<event>>
fires <<prop>> EPC : string
ErrorEvent
<<prop>> RawData : string
(from event s)
<<prop>> SerialNumber : string
<<prop>> ErrorCode : int32 <<prop>> TransitNumber : string
<<prop>> ErrorLocus : int32 beginInsertion(timeout : int32) : void
<<prop>> ErrorResponse : int32 f ires beginRemoval(timeout : int32) : void
endInsertion() : void
endRemoval() : void
<<event >>
StatusUpdateEvent
(from events)

MICR Sequence Diagram Updated in Release 1.8

The following sequence diagram shows the typical usage of the MICR device.
This also demonstrate the usage of the “Device Input Model” and how that works
with DataEventEnabled; also shows the steps in the check removal process.
NOTE: we are assuming that the :ClientApp(s) already successfully opened the controls. This means that the platform specific
loading/configuration/creation code executed successfully. We also assume that the application already registered some event handlers with the controls.
:ClientApp :MICR :DataEvent :MICRService
1: claim(timeout)
2: claim(timeout)
3: setDataEventEnabled(false)
4: setDataEventEnabled(false)
Further initialization of the

service should be done at
this point
9: beginInsertion(timeout) Detect check

10: beginInsertion(timeout) insertion and
gather check data
11: endInsertion()
12: endInsertion()
13: new
14: copy data to new DataEvent

15: enqueue DataEvent to
service's internal queue
16: parse and set MICR properties, DataCount++ and deliver

DataEvent [DataEventEnabled == true && FreezeEvents == false ]
Right before the DataEvent is

delivered set DataEventEnabled to
17: deliver event to all registered handlers false and DataCount--.
19: beginRemoval(timeout)
20: beginRemoval(timeout)
21: indicate user to start removing check
22: endRemoval()
23: endRemoval()

Model
The MICR Device follows the general “Device Input Model” for input devices.
One point of difference is that the MICR Device requires the invocation of
methods to insert and remove the check for processing. Therefore, this Device
requires more than simply setting the DataEventEnabled property to true in order
to receive data. The basic model is as follows:
• The MICR Control is opened, claimed, and enabled.
• When an application wishes to perform a MICR read, the application calls
beginInsertion, specifying a timeout value. This results in the device being
made ready to have a check inserted. If the check is not inserted before the
timeout limit expires, a UposException is raised.
In the event of a timeout, the MICR device will remain in a state allowing a
check to be inserted while the application provides any additional prompting
required and then reissues the beginInsertion method.
• Once a check is inserted, the method returns and the application calls
endInsertion, which results in the MICR device being taken out of check
insertion mode and the check, if present, actually being read.
• If the check is successfully read, a DataEvent is enqueued.
• If the AutoDisable property is true, then the Device automatically
disables itself when a DataEvent is enqueued.
• A queued DataEvent can be delivered to the application when
DataEventEnabled is true and other event delivery requirements are
met. Just before delivering this event, data is copied into properties, and
further data events are disabled by setting DataEventEnabled to false.
This causes subsequent input data to be enqueued while the application
processes the current input and associated properties. When the
application has finished processing the current input and is ready for more
data, it reenables events by setting DataEventEnabled to true.
• An ErrorEvent (or events) is enqueued if an error occurs while reading
the check, and is delivered to the application when DataEventEnabled is
true and other event delivery requirements are met.
• The DataCount property may be read to obtain the number of enqueued
DataEvents.
• All enqueued input may be deleted by calling clearInput. See the
• After processing a DataEvent, the application should query the
CapValidationDevice property to determine if validation printing can be
performed on the check prior to check removal. If this property is true, the
application may call the Printer Service’s beginInsertion and endInsertion
methods. This positions the check for validation printing. The POS Printer’s
validation printing methods can then be used to perform validation printing.
When validation printing is complete, the application should call the Printer
Service’s removal methods to remove the check.

• Once the check is no longer needed in the device, the application must call the
beginRemoval method of the MICR, or the Check Scanner (if the device can
also scan checks), or the POS Printer (if CapValidationDevice is true),
specifying a timeout value. This method will raise a UposException if the
check is not removed within the timeout period. In this case, the application
may perform any additional prompting prior to calling the method again. Once
the check is removed, the application should call the same device’s
endRemoval method to take the device out of removal mode.
Many models of MICR devices do not require any check handling processing from
the application. Such MICR devices may always be capable of processing a check
and require no commands to actually read and eject the check. For these types of
MICR devices, the beginInsertion, endInsertion, beginRemoval, and
endRemoval methods simply return, and input data will be enqueued until the
DataEventEnabled property is set to true. However, applications should still use
these methods to ensure application portability across different MICR devices.
Device Sharing
The MICR is an exclusive-use device. Its device sharing rules are:


MICR Character Substitution
The E13B MICR format used by the ANSI MICR standard contains 15 possible
characters. Ten of these are the numbers 0 through 9. A space character may also
be returned. The other four characters are special to MICR data and are known as
the Transit, Amount, On-Us, and Dash characters. These character are used to
mark the boundaries of certain special fields in MICR data. Since these four
characters are not in the ASCII character set, the following lower-case characters
will be used to represent them in properties and in parameters to methods:
MICR Character Name Substitute

Character
Transit t
Amount a
On-Us o
Dash -


Remarks Holds the account number parsed from the most recently read MICR data.
This account number will not include a check serial number if a check serial
number is able to be separately parsed, even if the check serial number is
embedded in the account number portion of the ‘On Us’ field. If the account
number cannot be identified, the string will be empty (“”).
See Also RawData Property, DataEvent.
Amount Property
Syntax Amount: string { read-only, access after open }
Remarks Holds the amount field parsed from the most recently read MICR data.
The amount field on a check consists of ten digits bordered by Amount symbols.
All non space digits will be represented in the test string including leading 0’s. If
the amount is not present, the string will be empty (“”).
BankNumber Property
Syntax BankNumber: string { read-only, access after open }
Remarks Holds the bank number portion of the transit field parsed from the most recently
read MICR data.
The bank number is contained in digits 5 through 8 of the transit field. If the bank
number or transit field is not present or successfully identified, the string will be
empty (“”).
See Also RawData Property, TransitNumber Property, DataEvent.

CapValidationDevice Property
Syntax CapValidationDevice: boolean { read-only, access after open }
Remarks If true, the device also performs validation printing via the POS Printer’s slip
station, and a check does not have to be removed from the MICR device prior to
performing validation printing.
For devices that are both a MICR device as well as a POS Printer, the device will
automatically position the check for validation printing after successfully
performing a MICR read. Either the MICR’s or the POS Printer’s beginRemoval
and endRemoval methods may be called to remove the check once processing is
complete.
CheckType Property
Syntax CheckType: int32 { read-only, access after open }
Remarks Holds the type of check parsed from the most recently read MICR data. It has one
Value Meaning
MICR_CT_PERSONAL The check is a personal check.

MICR_CT_BUSINESS The check is a business or commercial check.
MICR_CT_UNKNOWN Unknown type of check.

CountryCode Property
Syntax CountryCode: int32 { read-only, access after open }
Remarks Holds the country of origin of the check parsed from the most recently read MICR
data. It has one of the following values:
Value Meaning
MICR_CC_USA The check is from America.

MICR_CC_CANADA The check is from Canada.
MICR_CC_MEXICO The check is from Mexico.
MICR_CC_UNKNOWN Check origination is unknown.

EPC Property
Syntax EPC: string { read-only, access after open }
Remarks Holds the Extended Processing Code (“EPC”) field parsed from the most recently
read MICR data. It will contain a single character 0 though 9 if the field is present.
If not, the string will be empty (“”).

RawData Property
Syntax RawData: string { read-only, access after open }
Remarks Holds the MICR data from the most recent MICR read. It contains any of the 15
MICR characters with appropriate substitution to represent non-ASCII characters
(see “MICR Character Substitution”, page 767). No parsing or special processing
is done to the data returned in this property. A sample value may look like the
following:
“2t123456789t123 4 567890o 123 a0000001957a”
Note that spaces are used to represent spaces in the MICR data.
See Also AccountNumber Property, Amount Property, BankNumber Property,
CheckType Property, CountryCode Property, EPC Property, SerialNumber
Property, TransitNumber Property, DataEvent.
SerialNumber Property
Syntax SerialNumber: string { read-only, access after open }
Remarks Holds the serial number of the check parsed from the most recently read MICR
data.
If the serial number cannot be successfully parsed, the string will be empty (“”).
TransitNumber Property
Syntax TransitNumber: string { read-only, access after open }
Remarks Holds the transit field of the check parsed from the most recently read MICR data.
It consists of all the characters read between the ‘Transit’ symbols on the check. It
is a nine character string.

If zero, the method tries to begin insertion mode, then returns immediately if
successful. Otherwise a UposException is raised. If FOREVER (-1), the method
initiates the begin insertion mode, then waits as long as needed until either the
check is inserted or an error occurs.
Remarks Initiates check insertion processing.
When called, the MICR is made ready to receive a check by opening the MICR’s
check handling “jaws” or activating a MICR’s check insertion mode. This method
is paired with the endInsertion method for controlling check insertion. Although
some MICR devices do not require this sort of processing, the application should
still use these methods to ensure application portability across different MICR
devices.
If the MICR device cannot be placed into insertion mode, a UposException is
raised. Otherwise, check insertion is monitored until either:
• The check is successfully inserted.
• The check is not inserted before timeout milliseconds have elapsed, or an error
is reported by the MICR device. In this case, a UposException is raised. The
MICR device remains in check insertion mode. This allows an application to
perform some user interaction and reissue the beginInsertion method without
altering the MICR check handling mechanism.
Value Meaning
E_BUSY If the MICR is a combination device, the peer device

may be busy.
properly inserted.
See Also endInsertion Method, beginRemoval Method, endRemoval Method.

beginRemoval Method
If zero, the method tries to begin removal mode, then returns immediately if
successful. Otherwise a UposException is raised. If FOREVER (-1), the method
initiates the begin removal mode, then waits as long as needed until either the
check is removed or an error occurs.
Remarks Initiates check removal processing.
When called, the MICR is made ready to remove a check, by opening the MICR’s
check handling “jaws” or activating a MICR’s check ejection mode. This method
is paired with the endRemoval method for controlling check removal. Although
some MICR devices do not require this sort of processing, the application should
still use these methods to ensure application portability across different MICR
devices.
If the MICR device cannot be placed into removal or ejection mode, a
UposException is raised. Otherwise, check removal is monitored until either:
• The check is successfully removed.
• The check is not removed before timeout milliseconds have elapsed, or an
error is reported by the MICR device. In this case, a UposException is raised.
The MICR device remains in check removal mode. This allows an application
to perform some user interaction and reissue the beginRemoval method
without altering the MICR check handling mechanism.
Value Meaning
E_BUSY If the MICR is a combination device, the peer device

may be busy.
properly removed.

endInsertion Method
Remarks Ends check insertion processing.
When called, the MICR is taken out of check insertion mode. If a check is not
detected in the device, a UposException is raised with an extended error code of
EMICR_NOCHECK. After a successful endInsertion, if a check is detected, the
check will be read by the MICR device and either a DataEvent or ErrorEvent
will be delivered. Data will be available as soon as the DataEventEnabled
property is set to true. This allows an application to prompt the user prior to calling
this method to ensure that the form is correctly positioned.
This method is paired with the beginInsertion method for controlling check
insertion. Although some MICR devices do not require this sort of processing, the
application should still use these methods to ensure application portability across
different MICR devices.
Value Meaning
E_ILLEGAL The device is not in check insertion mode.

E_EXTENDED ErrorCodeExtended = EMICR_NOCHECK:
check being inserted.

endRemoval Method
Remarks Ends check removal processing.
When called, the MICR is taken out of check removal or ejection mode. If a check
is detected in the device, a UposException is raised with an extended error code of
EMICR_CHECK.
This method is paired with the beginRemoval method for controlling check
removal. Although some MICR devices do not require this sort of processing, the
application should still use these methods to ensure application portability across
different MICR devices.
Value Meaning
E_ILLEGAL The device is not in check removal mode.

E_EXTENDED ErrorCodeExtended = EMICR_CHECK:
The device was taken out of removal mode while a
check is still present.


DataEvent
Description Notifies the application when MICR data is read from a check and is available to
be read.
Status int32 Set to zero.

Before delivering this event, the RawData property is updated and the data is
parsed (if possible) into the MICR data fields.
See Also “Device Input Model” on page 54, “Events” on page 51, RawData Property,
AccountNumber Property, Amount Property, BankNumber Property,
CheckType Property, CountryCode Property, EPC Property, SerialNumber
Property, TransitNumber Property.
DirectIOEvent
means for a vendor-specific MICR Service to provide events to the application that
Service.
not otherwise described as part of the JavaPOS standard. Use of this event may
restrict the application program from being used with other vendor’s MICR
devices which may not have any knowledge of the Service’s need for this event.


Description Notifies the application that an error has been detected when reading MICR data.
ErrorCodeExtended
int32 Extended Error Code causing the error event. If
values below.
If ErrorCode is E_EXTENDED then ErrorCodeExtended contains one of the
following values:
Value Meaning
EMICR_BADDATA An unreadable character was detected during input
processing. The RawData property will contain partial
data if available, otherwise it will be an empty string.
EMICR_NODATA The entire input data stream was unreadable. No data is
available.
EMICR_BADSIZE The length of the check was beyond the expected
readable range. The RawData property will contain
partial data if available, otherwise it will be an empty
string.
EMICR_JAM The check insertion process has caused a paper jam. No
data is available.
EMICR_CHECKDIGIT The check digit verification has failed even though there
was no error during input processing. The RawData
property will contain partial data if available, otherwise
it will be an empty string.
EMICR_COVEROPEN The check insertion process failed due to the POSPrinter
cover being open. No data is available.
Value Meaning
available.


available.
Value Meaning
ER_CONTINUEINPUT
Use only when locus is EL_INPUT_DATA.
EL_INPUT.
Remarks This event is not delivered until DataEventEnabled is true and other event
page 62.
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a MICR
device.
Status int32 Reports a change in the power state of a MICR device.
process.
Remarks Enqueued when the MICR device detects a power state change.

C H A P T E R 2 4
Motion Sensor
This Chapter defines the Motion Sensor device category.
Summary


Timeout: int32 { read-write } 1.7 open & enable
Motion: boolean { read-only } 1.7 open & enable
780 Motion Sensor

Common
Name Version
close ( ): 1.7
release ( ): 1.7
clearInput ( ): Not
void { } supported
void { } supported
void { } supported
Specific
Name
waitForMotion( timeout: int32 ): 1.7

Summary 781


782 Motion Sensor
General Information
The Motion Sensor programmatic name is “MotionSensor”.
Capabilities
The Motion Sensor has the following minimal set of capabilities:

• Supports detection of person present at POS device
• Supports reporting of motion detection changes, either by hardware or
software detection.
Motion Sensor Class Diagram
The following diagram shows the relationships between the Motion Sensor
classes.
<<uses>>
<<utility>>
<<exception>> <<Interface>> UposConst
<<event>> UposException BaseControl (from upos)
StatusUpdateEvent (from upos) (from upos)
(from events) <<sends>>
<<sends>>
<<utility>>
<<uses>> MotionSensorConst
<<Interface>>
<<event>> MotionSensorControl
DirectIOEvent fires <<prop>> Mot ion : boolean
(from events)
<<prop>> Timeout : int32
<<prop>> Data : int 32 waitForMotion(timeout : int 32) : void

Model
The Motion Sensor defines two Motion Sensor indications as constants. It is

assumed that the Motion Sensor supports present and absent indications. The
constants for these Motion Sensor positions and their values are as follows:
• MOTION_M_PRESENT 1
• MOTION_M_ABSENT 2
StatusUpdateEvents are fired using the above values. The Timeout value is used
to set the number of milliseconds between the last time someone was present and
a MOTION_M_ABSENT StatusUpdateEvent being fired.
Device Sharing
The Motion Sensor is a sharable device. Its device sharing rules are:
• The Motion Sensor may not be claimed for exclusive access. Therefore, if an
application calls claim or release, these methods will always raise a
UposException.

784 Motion Sensor
Motion Sensor Sequence Diagram

The following sequence diagram shows the typical usage of the Motion Sensor
device.
Note: we are assuming that the :ClientApp0 already successfully opened the controls. This means that the platform specific loading/config/creation
code executed successfully. We are also assuming that the :ClientApp has registered event handlers with the control instance.
:ClientApp0 : Client App1 ms0:MotionSensor ms1: MotionSensor :StatusUpdate : MotionS ensor :MotionSensor :MotionS ens or :Operator
Event Service0 Service1 Hardware
3: service will need to update itself of current Keylock position
Current "Motion" position

4: getMotion() is returned to the control
5: getMotion()
6: Operator steps within Motion Detection range

7: notify MotionSens or Service of change
8: deliver SUE to cont rol [FreezeEvents == false]

11: create and register an event handler with control
12: open(logicalName)
13: open(logical Name)
Actual order of
delivery from
hardware to service
might vary
16: Operator steps within Motion Detection rang

17: notify servic e of c hange
21: notify service of change

23: deliver events to all regist ered list eners
25: claim(timeout)
26: claim(t imeout )
27: throws UposException to :ClientApp since Motion Sensor cannot be claimed

Motion Sensor State Diagram

The following state diagram depicts the Motion Sensor Control device model.
Closed open() Opened

close()
close()
Enabled
setDeviceEnabled( fals e )
setDeviceEnabled( true )
Motion Detection
Motion Detected
Operator in
Range
Operator Detect ed
enqueue Status
Reset Timer Update Event
Keep checking
Start Timer
Timer
Running
Timer Expired
Timer expired
Operator Absent
Enqueue Status
Update Event
Operator out of range

786 Motion Sensor
Motion Property
Syntax Motion: boolean { read-only, access after open-enable }
Remarks Holds a boolean value that indicates whether motion has been detected. This
property is initialized and kept current while the device is enabled.
Timeout Property
Syntax Timeout: int32 { read-write, access after open-enable }
Remarks Holds a value that indicates the number of milliseconds from the last time motion
was detected until the StatusUpdateEvent of MOTION_M_ABSENT is fired.
This property needs to be application specific for a shared device. If several
applications are sharing the device, each application may set an independent
timeout value, and each application will receive StatusUpdateEvents according
to its supplied timeout.

waitForMotion Method
Syntax waitForMotion ( timeout: int32 ):
timeout Maximum number of milliseconds for the Motion

Sensor to wait for a person to be present before returning
control back to the application.
If zero, the method returns immediately.
If FOREVER (-1), the method waits as long as needed
until motion is detected or an error occurs.
Remarks Waits for a presence detection from the Motion Sensor.
If the Motion Sensor detects someone is present, then the method returns
immediately.
Value Meaning
E_TIMEOUT The timeout period expired before motion was detected.

788 Motion Sensor
DirectIOEvent
means for a vendor-specific Motion Sensor Service to provide events to the
Service.
from being used with other vendor’s Motion Sensor devices which may not have

StatusUpdateEvent
Description Notifies the application when the Motion Sensor detects a change.

Status int32 The status of the Motion Sensor.

Value Description
MOTION_M_PRESENT Motion Sensor has detected someone is present. Value

is one (1).
MOTION_M_ABSENT Motion Sensor has detected no one has been present
for the number of milliseconds specified in Timeout.
Value is two (2).

process.
Remarks This event is enqueued when a Motion Sensor detection undergoes a change or if
Power State Reporting is enabled and a change in the power state is detected.
See Also Timeout Property, “Events” on page 51.

790 Motion Sensor

C H A P T E R 2 5
MSR - Magnetic Stripe Reader

This Chapter defines the Magnetic Stripe Reader device category.
Summary


792 MSR - Magnetic Stripe Reader
CapCardAuthentication: string { read-only } 1.12 open
CapDataEncryption: int32 { read-only } 1.12 open
CapDeviceAuthentication: int32 { read-only } 1.12 open
CapISO: boolean { read-only } 1.0 open
CapJISOne: boolean { read-only } 1.0 open
CapJISTwo: boolean { read-only } 1.0 open
CapTrackDataMasking: boolean { read-only } 1.12 open
CapTransmitSentinels: boolean { read-only } 1.5 open
CapWritableTracks: int32 { read-only } 1.10 open

AdditionalSecurityInformation: binary { read-only } 1.12 open
CardAuthenticationData: binary { read-only } 1.12 open
CardAuthenticationDataLength: int32 { read-only } 1.12 open
CardPropertyList: string { read-only } 1.12 open
CardType: string { read-only } 1.12 open
CardTypeList: string { read-only } 1.12 open
DataEncryptionAlgorithm: int32 { read-write } 1.12 open & claim
DecodeData: boolean { read-write } 1.0 open
DeviceAuthenticated: boolean { read-only } 1.12 open, claim, & enable
DeviceAuthenticationProtocol: int32 { read-only } 1.12 open
EncodingMaxLength: int32 { read-only } 1.10 open, claim, & enable
ErrorReportingType: int32 { read-write } 1.2 open
ExpirationDate: string { read-only } 1.0 open
FirstName: string { read-only } 1.0 open
MiddleInitial: string { read-only } 1.0 open
ParseDecodeData: boolean { read-write } 1.0 open
ServiceCode: string { read-only } 1.0 open
Suffix: string { read-only } 1.0 open
Surname: string { read-only } 1.0 open
Title: string { read-only } 1.0 open
Track1Data: binary { read-only } 1.0 open
Track1DiscretionaryData: binary { read-only } 1.0 open
Track1EncryptedData: binary { read-only } 1.12 open
Track1EncryptedDataLength: int32 { read-only } 1.12 open
Track2DiscretionaryData: binary { read-only } 1.0 open

Summary 793

TracksToRead: int32 { read-write } 1.0 open
TracksToWrite: int32 { read-write } 1.10 open, claim, & enable
TransmitSentinels: boolean { read-write } 1.5 open
WriteCardType: string { read-write } 1.12 open

Common
Name Version
close ( ): 1.0
release ( ): 1.0
clearInput ( ): 1.0
void { } supported


Specific
authenticateDevice ( response: binary ): 1.12
deauthenticateDevice ( response: binary ): 1.12
retrieveCardProperty ( name: string, inout value: string ): 1.12
retrieveDeviceAuthenticationData ( inout challenge: binary ): 1.12
updateKey ( key: string, keyName: string ): 1.12
writeTracks ( data: array of binary, timeout: int32 ): 1.10

upos::events::OutputCompleteEvent Not supported

General Information
The Magnetic Stripe Reader programmatic name is “MSR”.

The MSR device class supports attachment of a card reader to provide input to the
application from a card inserted (swiped) through the reader. The targeted
environment is electronic funds data such as an account number, customer name,
etc. from a magnetically encoded credit and/or debit card.
The MSR Control has the following minimal set of capabilities:
• Reads encoded data from a magnetic stripe. Data is obtainable from any
combination of ISO or JIS-I tracks 1,2, 3, and JIS-II.
• Supports decoding of the alphanumeric data bytes into their corresponding
alphanumeric codes. Furthermore, this decoded alphanumeric data may be
divided into specific fields accessed as device properties.
The MSR Control may have the following additional capabilities:
• Support for specific card types: ISO, JIS Type I and/or JIS Type II. Note: for
the purpose of this standard, the following convention is assumed:
• Track 1 is ISO or JIS-I Track 1
• Track 4 is JIS-II data
• Determination of the type of card is based on the type of content the card
tracks are expected to hold.
• Support for optionally returning the track sentinels with track data.
• Support for writing data to the MSR track(s).
• Supports the reading of driver licenses and other cards formatted according to
the AAMVA specification. This specification can be downloaded from the
following web site: http://www.aamva.org/.
• Support for returning track data in an encrypted format to prevent the loss of
potentially sensitive cardholder information.
• Support for returning masked track data to the application when the track data
is encrypted.
• Support for returning a card authentication data for the purpose of determining
if the swiped card is the original or a duplicate.
• Support for device/host based mutual authentication for the purpose of
detecting and preventing phishing/man-in-the-middle attacks.
Clarifications for JIS-II data handling
Prior to Version 1.5 of this specification, it was not clearly stated how the Control
should treat JIS-II data and into which of the TracknData properties the data
should be stored. This version of the specification defines Track4Data, which the
Control should use to store JIS-II data. However, in order to maintain application
backward compatibility with previous versions, the Control may also store the JIS-
II data into the previously used TracknData property. In such cases, the
DataEvent Status and the ErrorEvent ErrorCodeExtended attributes should be
set to reflect both Track4Data and TracknData. Note that applications that use
this particular method of accessing JIS-II data may not be portable across Controls.

MSR Class Diagram Updated in Release 1.12

The following diagram shows the relationships between the MSR classes.
<<utility>> <<utility>> <<Interface>>

<<uses>>
MSRConst UposConst BaseControl
(from upos) (from upos) (from upos)
<<uses>>
<<Interface>>
MSRControl
(from upos) <<sends>>
<<capability>> CapCardAuthentication : string
<<capability>> CapDataEncryption : int32
<<capability>> CapDeviceAuthentication : int32
<<event>>
<<capability>> CapISO : boolean
DataEvent
<<capability>> CapJISOne : boolean
(from events) <<exception>>
<<capability>> CapJISTwo : boolean
<<capability>> CapTrackDataMasking : boolean UposException
(from upos)
<<capability>> CapTransmitSentinels : boolean
fires <<capability>> CapWritableTracks : int32
<<prop>> AccountNumber : string
<<prop>> AdditionalSecurityInformation : binary
<<prop>> CardAuthenticationData : binary <<sends>>
<<event>> <<prop>> CardAuthenticationDataLength : int32
DirectIOEvent <<prop>> CardPropertyList : string
(from events) <<prop>> CardType : string
fires <<prop>> CardTypeList : string
<<prop>> DataEncryptionAlgorithm : int32
<<prop>> DecodeData : boolean
<<prop>> DeviceAuthenticated : boolean
<<event>> <<prop>> DeviceAuthenticationProtocol : int32
ErrorEvent <<prop>> EncodingMaxLength : int32
(from events) fires <<prop>> ErrorReportingType : int32
<<prop>> ExpirationDate : string
<<prop>> FirstName : string
<<prop>> MiddleInitial : string
<<prop>> ParseDecodeData : boolean
<<event>> fires <<prop>> ServiceCode : string
StatusUpdateEvent <<prop>> Suffix : string
(from events) <<prop>> Surname : string
<<prop>> Title : string
<<prop>> Track1Data : binary
<<prop>> Track1DiscretionaryData : binary
<<prop>> Track1EncryptedData : binary
<<prop>> Track1EncryptedDataLength : int32
<<prop>> Track2DiscretionaryData : binary
<<prop>> TracksToRead : int32
<<prop>> TracksToWrite : int32
<<prop>> TransmitSentinels : boolean
<<prop>> WriteCardType : string
authenticateDevice(response : binary) : void

deauthenticateDevice(response : binary) : void
retrieveCardProperty(name : string, inout value : string) : void
retrieveDeviceAuthenticationData(inout challenge : binary) : void
updateKey(key : string, keyName : string) : void
writeTracks(data : array of binary, timeout : int32) : void

Device Behavior Model Updated in Release 1.12

The general device behavior model of the MSR is:
• Five unique writable properties control MSR data handling:
• The TracksToRead property controls which combination of the tracks
should be read. It is not an error to swipe a card containing less than this
set of tracks. Rather, this property should be set to the set of tracks that the
application may need to process.
• The DecodeData property controls decoding of track data from raw into
displayable data.
• The ParseDecodeData property controls parsing of decoded data into
fields, based on common MSR standards.
• The ErrorReportingType property controls the type of handling that
occurs when a track containing invalid data is read.
• The DataEncryptionAlgorithm property controls the type of encryption
(if any) that the device should use.
Input – MSR Updated in Release 1.12
The MSR follows the general “Device Input Model” for event-driven input:
• When input is received from the card reader generated by the card swipe, a
• If the AutoDisable property is true, the device will automatically disable itself
when a DataEvent is enqueued.
properties, and further data events are disabled by setting the
DataEventEnabled property to false. This causes subsequent input data to be
properties. When the application has finished the current input and is ready for
more data, it re-enables events by setting DataEventEnabled to true.
• An ErrorEvent or events are enqueued if an error is encountered while
gathering or processing input, and are delivered to the application when the
met.
• The DataCount property can be read to obtain the total number of data events
enqueued.
• Queued input may be deleted by calling the clearInput method. See the
• If the CapDeviceAuthentication property is set to MSR_DA_REQUIRED,
the device will only enqueue input data from a card swipe when the device is
in the authenticated state (DeviceAuthenticated is true). The device can be
put in the authenticated state by calling the authenticateDevice method.
Output – MSR Added in Release 1.10
• To write data to a track, the application calls the writeTracks method. The
ability to write data depends upon the capabilities of the device.
• The writeTracks method is always performed synchronously.

Device Sharing
The MSR is an exclusive-use device, as follows:

MSR Sequence Diagram Updated in Release 1.8

The following sequence diagram shows the typical usage of an MSR device.
NOTE: we are assuming that the :ClientApp(s) already successfully registered to receive events and opened the controls. This
means that the platform specific loading/configuration/creation code executed successfully.
:ClientApp :MSRControl :DataEvent :MSRService
1: setAutoDisable( true )
: Operator
2: setAutoDisable( true )
3: setDataEventEnabled( true ) 4: setDataEventEnabled( true )
If timeoutValue expires then

raise a UposException with
E_TIMEOUT error code
5: claim( timeoutValue )
6: claim( timeoutValue )
7: try to claim for exclusive use
8: setDeviceEnabled( true )
9: setDeviceEnabled( true )
10: be ready for input from device
11: successful card swiped
12: input received [DataEventEnabled == true]
13: data decoding and parse data [DecodeData == true && ParseDecodeData == true]
14: create DataEvent
15: set DeviceEnabled property to false [AutoDisable == true]
16: DataCount++ and enqueue event for delivery
17: set parsed data properties and deliver DataEvent [DataEventEnabled == true && FreezeEvents == false]
delivered set DataEventEnabled
to false and DataCount-- .

MSR Device Authentication Sequence Diagram

Added in Release 1.12
The following sequence diagram shows the typical usage of an MSR device during
the device authentication process.
:ClientApp :MSRControl :MSRService :MSRDevice
2: setDeviceEnabled(true) Service retrieves a challenge token from

the device and returns it to the
application. The challenge token is
typically encrypted with an encryption
3: retrieveDeviceAuthenticationData() key stored in the hardware.
4: retrieveDeviceAuthenticationData()
5:
6:
7:
8:
9:
A response token is generated
from the challenge token. This is
typically performed by an external
The response token is validated by the
security module with knowledge of
device and the device enters the
the encryption key
authenticated state. At this time, the
device is active and will report card
swipes to the service until it exits the
10: authenticateDevice(responseToken)
authenticated state.
11: authenticateDevice(responseToken)
12:
13:
Service sets DeviceAuthenticated property to

true and enqueues a Status Update Event with
status = SUE_DEVICE_AUTHENTICATED
14: deAuthenticateDevice(responseToken)
15: deAuthenticateDevice(responseToken)
16:
17:
Service sets DeviceAuthenticated property to false The response token is validated by the device and the
and enqueues a Status Update Event with status = device exits the authenticated state. At this time, the
SUE_DEVICE_DEAUTHENTICATED device will no longer report card swipes to the service.

MSR State Diagrams

The following state diagrams depict the MSR Control device model.
Error Occurred
entry/ { DataEventEnabled = false, enqueue ErrorEvent, State = UPOS_S_ERROR }
user input[ DeviceEnabled == false ]
done delivering error event
open, claim &

enable
done clearing input

ClearInput Processing
error
entry/ { DataCount = 0, empty data queue }
user input[ DeviceEnabled == true ]

clearInput()
The details of
the "Event
Event Processing Processing"
state are
describe in a
separate
diagram below

Event Processing
[ DataEventEnabled == false and DataCount > 0 ]
Processing input
enqueue DataEvent
entry/ { increase DataCount }
[ Auto Disable == true ]
Disable
entry/ {DeviceEnabled = false}
[ DataCount > 0 and DataEventEnabled == true ]
Event Delivering
Pre-processing
entry/ {DataEventEnabled = false}
[ DecodeData == true ]
Process Data
[ DecodeData == false ]
[ ParseDecodeData == true ]
Parse Data
Deliver DataEvent to Listeners
done processing
entry/ [decrem ent DataCount]


AccountNumber Property Updated in Release 1.12
Remarks Holds the account number obtained from the most recently swiped card.
This property is initialized to the empty string if:
• The field was not included in the track data obtained, or,
• The track data format was not one of those listed in the ParseDecodeData
property description,
• DataEncryptionAlgorithm is not MSR_DE_NONE and
CapTrackDataMasking is false, or,
• ParseDecodeData is false.
This property may contain masked data if DataEncryptionAlgorithm is not
MSR_DE_NONE and CapTrackDataMasking is true.
See Also DataEncryptionAlgorithm Property, ParseDecodeData Property,
CapTrackDataMasking Property.
AdditionalSecurityInformation Property Added in Release 1.12

Syntax AdditionalSecurityInformation: binary { read-only, access after open }
Remarks Holds additional security/encryption information when a DataEvent is delivered.
The information content and internal format of this property will vary among
encryption algorithms. For example, if the encryption algorithm is DUKPT, then
this property will contain the “DUKPT sequence number”. If the selected
encryption algorithm does not require this property, its value will be set to empty.
See Also CapDataEncryption Property, DataEncryptionAlgorithm Property.
CapCardAuthentication Property Added in Release 1.12

Syntax CapCardAuthentication: string { read-only, access after open }
Remarks Holds the type, if any, of card authentication data that is supported by the device.
If it contains an empty string, the device does not support authentication data and
the CardAuthenticationData property will be empty. Otherwise, the service
supports card authentication data via the CardAuthenticationData property
when a DataEvent is delivered.
See Also CardAuthenticationData Property.

CapDataEncryption Property Added in Release 1.12

Syntax CapDataEncryption: int32 { read-only, access after open }
Remarks Holds a bitwise indication of the encryption algorithms supported by the device
and selectable via the DataEncryptionAlgorithm property.
Value Meaning
MSR_DE_NONE Data encryption is not enabled. If the
DataEncryptionAlgorithm property is also set to this
value, then the TrackXData and parsed properties will
contain unencrypted data.
MSR_DE_3DEA_DUKPT
Derived Unique Key Per Transaction (USA, Latin
America) using Triple DEA encryption (commonly
called Triple DES) based on ANS X9.24-2004.
Other Values Values 0x01000000 and above are reserved for
additional encryption algorithms supported by the
Service.
The inclusion of the setting MSR_DE_NONE does not necessarily mean that data
encryption is not supported, but rather that the Service supports returning
unencrypted data.
See Also DataEncryptionAlgorithm Property, TrackXEncryptedData Property,
updateKey Method.
CapDeviceAuthentication Property Added in Release 1.12

Syntax CapDeviceAuthentication: int32 { read-only, access after open }
Remarks Holds the level of device authentication supported by the service. If device
authentication is supported the service must keep the value of
DeviceAuthenticated current when the device is enabled. The service should also
enqueue a StatusUpdateEvent with status value set to
MSR_SUE_DEVICE_AUTHENTICATED or MSR_SUE_DEVICE_DEAUTHENTICATED
when the authentication status changes.
Value Meaning
MSR_DA_NOT_SUPPORTED
The service does not support device authentication.
MSR_DA_OPTIONAL The service supports device authentication but does not
require it.
MSR_DA_REQUIRED The service requires device authentication.
See Also DeviceAuthenticationProtocol Property, DeviceAuthenticated Property,
authenticateDevice Method, deauthenticateDevice Method,
retrieveDeviceAuthenticationData Method.

CapISO Property
Syntax CapISO: boolean { read-only, access after open }
Remarks If true, the MSR device supports ISO cards.
CapJISOne Property
Syntax CapJISOne: boolean { read-only, access after open }
Remarks If true, the MSR device supports JIS Type-I cards.
JIS-I cards are a superset of ISO cards. Therefore, if CapJISOne is true, then it is
implied that CapISO is also true.
CapJISTwo Property
Syntax CapJISTwo: boolean { read-only, access after open }
Remarks If true, the MSR device supports JIS type-II cards.
CapTrackDataMasking Property Added in Release 1.12
Syntax CapTrackDataMasking: boolean { read-only, access after open }
Remarks Contains true if the Service masks encrypted track data: When true and encryption
is enabled (via DataEncryptionAlgorithm), the Service will mask track data, so
that the TrackXData properties and the parsed track data properties will contain
masked data. (The extent and results of data masking is Service-dependent. A
Service may choose to provide configuration of the masking via directIO.)
CapTrackDataMasking can only be true if the device supports data encryption,
that is, if CapDataEncryption is not equal to MSR_DE_NONE.
See Also CapDataEncryption Property, DataEncryptionAlgorithm Property,
TrackXData Properties, ParseDecodeData Property, directIO Method.

CapTransmitSentinels Property Added in Release 1.5

Syntax CapTransmitSentinels: boolean { read-only, access after open }
Remarks If true, the device is able to transmit the start and end sentinels.
If false, these characters cannot be returned to the application.
See Also TransmitSentinels Property.
CapWritableTracks Property Added in Release 1.10

Syntax CapWritableTracks: int32 { read-only, access after open }
Remarks This capability indicates if the MSR device supports the writing of track data - and
which tracks are supported - or if this functionality is not supported. For example,
if set to MSR_TR_1_2_3 then the MSR device supports writing to tracks 1, 2, and
3; if set to MSR_TR_NONE then writing to MSR tracks is not supported.
Value Meaning
MSR_TR_NONE The MSR does not support writing track data.
MSR_TR_1 Track 1 is writable.
MSR_TR_1_2 Tracks 1 and 2 are writable.
MSR_TR_1_2_3 Tracks 1, 2, and 3 are writable.
MSR_TR_1_2_3_4 Tracks 1, 2, 3, and 4 are writable.
See Also TracksToWrite Property.

CardAuthenticationData Property Added in Release 1.12

Syntax CardAuthenticationData: binary { read-only, access after open }
Remarks Holds card authentication information when a DataEvent is delivered.
The information content and internal format of this property will vary among
services and depends on the value of the CapCardAuthentication property. This
property will be empty if CapCardAuthentication is an empty string. Otherwise,
the value of this property will be encrypted via the encryption algorithm contained
in the DataEncryptionAlgorithm property. The length of the raw (unencrypted)
value of this property is contained in the CardAuthenticationDataLength
property.
See Also CapCardAuthentication Property, CardAuthenticationDataLength Property,
DataEncryptionAlgorithm Property.
CardAuthenticationDataLength Property Added in Release 1.12

Syntax CardAuthenticationDataLength: int32 { read-only, access after open }
Remarks This property will be zero if CapCardAuthentication is an empty string.
Otherwise, holds the length of the raw CardAuthenticationData before it is
encrypted. Many encryption algorithms require padding of the input data before it
can be encrypted. This property contains the length of the original unpadded data
before it is encrypted. It may be needed to restore the original data after decryption
See Also CapCardAuthentication Property, CardAuthenticationData Property.
CardPropertyList Property Added in Release 1.12

Syntax CardPropertyList: string { read-only, access after open }
Remarks Holds a comma separated list of the names of the properties parsed from the most
recently swiped card. The values of these properties are allowed to be empty.
This property is initialized to an empty string if:
• The type of card swiped was not recognized, or,
See Also ParseDecodeData Property.

CardType Property Added in Release 1.12

Syntax CardType: string { read-only, access after open }
Remarks Holds the card type identifier for the most recently swiped card. If the card's
format is not recognized, this property will be empty. If this property's value
begins with an underscore ('_') the card type is vendor specific. If this property
does not begin with an underscore the card type is one of the standard card types.
The following list shows all currently defined standard card types:
• “BANK” Bank credit/debit card
• “AAMVA” American & Canadian Driver's License or ID Card
This property is initialized to empty by the open method.
CardTypeList Property Added in Release 1.12

Syntax CardTypeList: string { read-only, access after open }
Remarks Holds a comma separated list of string names of card types supported by the
Service. The vendor is allowed to support non-standard card type by specifying
names beginning with an underscore ('_'). All names not beginning with an
underscore are considered to be standard card types. The following list shows all
currently defined standard card types:
For bank cards, the following properties are parsed and can be accessed through
the retrieveCardProperty method:
• “AccountNumber”
• “ExpirationDate”
• “FirstName”
• “MiddleInitial”
• “ServiceCode”
• “Suffix”
• “Surname”
• “Title”
For AAMVA driver's licenses and ID cards, the following properties are parsed
and can be accessed through the retrieveCardProperty method:
• “Address”
• “BirthDate”
• “City”
• “Class”
• “Endorsements”
• “EyeColor”
• “FirstName”
• “Gender”
• “HairColor”
• “Height”

• “LicenseNumber”
• “PostalCode”
• “Restrictions”
• “State”
• “Suffix”
• “Surname”
• “Weight”
See Also ParseDecodeData property.
DataEncryptionAlgorithm Property Added in Release 1.12

Syntax DataEncryptionAlgorithm: int32 {read-write, access after open-claim}
Remarks Holds the encryption algorithm that will be used to encrypt the track data. This
property may be set to one of the supported encryption algorithms as defined in the
CapDataEncryption property. However, for security reasons, a Service (or the
device itself) may restrict the set of values that an application may select.
Note: This property can only be updated when the device is opened and claimed,
but not enabled.
This property is initialized by the open method. For devices that support
encryption, this property may be initialized to any value given by
CapDataEncryption.
Value Meaning
E_ILLEGAL The service does not support the specified encryption
algorithm or the device is currently enabled.
See Also CapDataEncryption Property, TrackXEncryptedData Property, updateKey
Method.

DecodeData Property Updated in Release 1.12

Syntax DecodeData: boolean { read-write, access after open }
Remarks If false, the Track1Data, Track2Data, Track3Data, and Track4Data properties
contain the original encoded bit sequences, known as “raw data format.”
If true, each byte of track data contained within the Track1Data, Track2Data,
Track3Data, and Track4Data, properties is mapped from its original encoded bit
sequence (as it exists on the magnetic card) to its corresponding decoded ASCII
bit sequence. This conversion is mainly of relevance for data that is NOT of the 7-
bit format, since 7-bit data needs no decoding to decipher its corresponding
alphanumeric and/or Katakana characters.
The decoding that takes place is as follows for each card type, track, and track data
format:
Track Data Raw Data
Card Type Raw Bytes Decoded Values
Property Format
Track1Data 6-Bit 0x00 - 0x3F 0x20 through 0x5F
ISO Track2Data 4-Bit 0x00 - 0x0F 0x30 through 0x3F
Track1Data 7-Bit 0x00 - 0x7F Data Unaltered
JIS-I Track2Data 4-Bit 0x00 - 0x0F 0x20 through 0x3F
JIS-II
AAMVA Track2Data 4-Bit 0x00 - 0x0F 0x30 through 0x3F

Setting this property to false automatically sets ParseDecodeData to false.
See Also ParseDecodeData Property.

DeviceAuthenticated Property Added in Release 1.12

Syntax DeviceAuthenticated: boolean { read-only, access after open-claim-enable }
Remarks If the device supports authentication (CapDeviceAuthentication not equal to
MSR_DA_NOT_SUPPORTED) the service must keep the value of this property
up to date when the device is enabled. When the authentication state of the device
changes the service should update the value of DeviceAuthenticated and enqueue
a StatusUpdateEvent with status value set to
MSR_SUE_DEVICE_AUTHENTICATED or MSR_SUE_DEVICE_DEAUTHENTICATED.
The primary reason for this is to notify the application in the event of an
authentication timeout or other action that may not have been initiated by the
application.
See Also CapDeviceAuthentication Property, authenticateDevice Method,
deauthenticateDevice Method, retrieveDeviceAuthenticationData Method.
DeviceAuthenticationProtocol Property Added in Release 1.12

Syntax DeviceAuthenticationProtocol: int32 { read-only, access after open }
Remarks Holds the device authentication protocol supported by the device.
Value Meaning
MSR_AP_NONE The service does not support device authentication.
MSR_AP_CHALLENGERESPONSE
The service supports the challenge response protocol.
See Also CapDeviceAuthentication Property, DeviceAuthenticated Property,
authenticateDevice Method, deauthenticateDevice Method,
EncodingMaxLength Property Added in Release 1.10

Syntax EncodingMaxLength: int32 { read-only, access after open-claim-enable }
Remarks The maximum length of data that can be written by the MSR to the track(s) defined
by the TracksToWrite property. If multiple tracks are selected in the
TracksToWrite property, the length of the shortest track should be reflected by
this property.
See Also TracksToWrite Property, writeTracks Method.

ErrorReportingType Property Updated in Release 1.12

Syntax ErrorReportingType: int32 { read-write, access after open }
Remarks Holds the type of errors to report via ErrorEvents. This property has one of the
following values:
Value Meaning
MSR_ERT_CARD Report errors at a card level.
MSR_ERT_TRACK Report errors at the track level
An error is reported by an ErrorEvent when a card is swiped, and one or more of
the tracks specified by the TracksToRead property contains data with errors.
When the ErrorEvent is delivered to the application, two types of error reporting
are supported:
• Card level: A general error status is given, with no data returned. This level
should be used when a simple pass/fail of the card data is sufficient.
• Track level: When the ErrorLocus is EL_INPUT and the ErrorCode value is
E_EXTENDED, then the ErrorCodeExtended value contains a status for each
of the tracks and the track’s properties are updated as with a DataEvent. For
those tracks that contain invalid data, the track’s properties are set to empty.
This level should be used when the application may be able to utilize a suc-
cessfully read track or tracks when another of the tracks contains errors. For
example, suppose TracksToRead is MSR_TR_1_2_3, and a swiped card
contains good track 1 and 2 data, but track 3 contains “random noise” that is
flagged as an error by the MSR. With track level error reporting, the Error-
Event sets the track 1 and 2 properties with the valid data, sets the track 3
properties to empty, and sets an error code indicating the status of each track.
The processing flow for handling track level error reporting would be as
follows:
* When the card read occurs and track error(s) are detected, then:
- If any DataEvents are enqueued for delivery, then create and enqueue
an ErrorEvent with ErrorLocus EL_INPUT_DATA before the oldest
DataEvent.
- Always create and enqueue an ErrorEvent with ErrorLocus
EL_INPUT at the end of the event queue. Associate the card's retrieved
data with this event.
* When the ErrorEvent with ErrorLocus EL_INPUT_DATA is delivered,
no other properties are changed.
* When the ErrorEvent with ErrorLocus EL_INPUT is delivered, set the
TrackXData or the TrackXEncryptedData properties to the card read
data. For those track(s) on which a read error occurred, the property is
empty.
This property is initialized to MSR_ERT_CARD by the open method.
See Also TracksToRead Property, TrackXData Properties, TrackXEncryptedData
Properties, DataEvent, ErrorEvent.

ExpirationDate Property Updated in Release 1.12

Syntax ExpirationDate: string { read-only, access after open }
Remarks Holds the expiration date obtained from the most recently swiped card, as four
ASCII decimal characters in the form YYMM. For example, February 1998 is
“9802” and August 2018 is “1808”.
See Also ParseDecodeData Property, CapTrackDataMasking Property.
FirstName Property Updated in Release 1.12

Syntax FirstName: string { read-only, access after open }
Remarks Holds the first name obtained from the most recently swiped card.
This property is initialized to an empty string if:

MiddleInitial Property Updated in Release 1.12

Syntax MiddleInitial: string { read-only, access after open }
Remarks Holds the middle initial obtained from the most recently swiped card. This
property is initialized to the empty string if:
ParseDecodeData Property Updated in Release 1.12

Syntax ParseDecodeData: boolean { read-write, access after open }
Remarks When true, the decoded data contained within the Track1Data and Track2Data
properties is further separated into fields for access via various other properties.
Track3Data is not parsed because its data content is of an open format defined by
the card issuer. JIS-I Track 1 Format C and ISO Track 1 Format C data are not
parsed for similar reasons. Track4Data is also not parsed.
The parsed data properties are the defined possible fields for cards with data
consisting of the following formats:
• JIS-I / ISO Track 1 Format A
• JIS-I / ISO Track 1 Format B
• JIS-I / ISO Track 1 VISA Format (a defacto standard)
• JIS-I / ISO Track 2 Format
Setting this property to true automatically sets DecodeData to true.
Note: If DataEncryptionAlgorithm is not MSR_DE_NONE and
CapTrackDataMasking is true, the Service will populate the TrackXData
properties with masked track data and this masked track data will be parsed and
used to populate the various other properties. The resulting parsed properties will
contain the same masked values that exist in the TrackXData properties.
Value Meaning
E_ILLEGAL This property can only be set to true when
DataEncryptionAlgorithm is MSR_DE_NONE or
CapTrackDataMasking is true.

See Also DecodeData Property, Surname Property, Suffix Property, AccountNumber

Property, FirstName Property, MiddleInitial Property, Title Property,
ExpirationDate Property, ServiceCode Property, Track1DiscretionaryData
Property, Track2DiscretionaryData Property.
ServiceCode Property Updated in Release 1.12

Syntax ServiceCode: string { read-only, access after open }
Remarks Holds the service code obtained from the most recently swiped card.
Suffix Property Updated in Release 1.12

Syntax Suffix: string { read-only, access after open }
Remarks Holds the suffix obtained from the most recently swiped card.

Surname Property Updated in Release 1.12

Syntax Surname: string { read-only, access after open }
Remarks Holds the surname obtained from the most recently swiped card.
Title Property Updated in Release 1.12

Syntax Title: string { read-only, access after open }
Remarks Holds the title obtained from the most recently swiped card.
Track1Data Property Updated in Release 1.12

Syntax Track1Data: binary { read-only, access after open }
Remarks Holds the track 1 data obtained from the most recently swiped card.
If TransmitSentinels is false, this property contains track data between but not
including the start and end sentinels. If TransmitSentinels is true, then the start
and end sentinels are included.
If DecodeData is true, then the data returned by this property has been decoded
from the “raw” format. The data may also be parsed into other properties when the
ParseDecodeData property is set.

If DataEncryptionAlgorithm is not MSR_DE_NONE the following additional

rules apply:
• If CapTrackDataMasking is true, the Service will attempt to mask or
otherwise conceal any potentially sensitive information contained in the track
data. Examples include but are not limited to account numbers and/or
discretionary data. When possible the Service will replace specific characters
with masked characters while attempting to maintain the original format of the
track data so it can be parsed normally,
• If CapTrackDataMasking is false this property will be empty.
A zero length array indicates that the track was not accessible.
See Also TracksToRead Property, TransmitSentinels Property, ParseDecodeData
Property, CapTrackDataMasking Property.
Track1DiscretionaryData Property Updated in Release 1.12

Syntax Track1DiscretionaryData: binary { read-only, access after open }
Remarks Holds the track 1 discretionary data obtained from the most recently swiped card.
The array will be zero length if:
The amount of data contained in this property varies widely depending upon the
format of the track 1 data.
Track1EncryptedData Property Added in Release 1.12

Syntax Track1EncryptedData: binary { read-only, access after open }
Remarks Holds the encrypted track 1 data obtained from the most recently swiped card. This
property is empty if DataEncryptionAlgorithm is MSR_DE_NONE.
The length of this property after it is decrypted is contained in the
Track1EncryptedDataLength property.
See Also DataEncryptionAlgorithm Property, Track1EncryptedDataLength Property.

Track1EncryptedDataLength Property Added in Release 1.12

Syntax Track1EncryptedDataLength: int32 { read-only, access after open }
Remarks Holds the length of the raw Track1Data before it is encrypted. Many encryption
algorithms require padding of the input data before it can be encrypted. This
property contains the length of the original unpadded track data before it is
encrypted. It may be needed to restore the original track data after decryption.
See Also DataEncryptionAlgorithm Property, Track1EncryptedData Property.

rules apply:

Track2DiscretionaryData Property Updated in Release 1.12

Syntax Track2DiscretionaryData: binary { read-only, access after open }
Remarks Holds the track 2 discretionary data obtained from the most recently swiped card.
The array will be zero length if:
The amount of data contained in this property varies widely depending upon the
format of the track 2 data.




rules apply:




Remarks Holds the track 4 data (JIS-II) obtained from the most recently swiped card.
from the “raw” format.
rules apply:
To maintain compatibility with previous versions, the Control may also continue
to store the JIS-II data in another TracknData property. However, it should be
noted that to ensure application portability, Track4Data should be used to access
JIS-II data.
See Also Track1Data Property, Track2Data Property, Track3Data Property,
TransmitSentinels Property, CapTrackDataMasking Property.



TracksToRead Property Updated in Release 1.5

Syntax TracksToRead: int32 { read-write, access after open }
Remarks Holds the track data that the application wishes to have placed into Track1Data,
Track2Data, Track3Data, and Track4Data properties following a card swipe.
Value Meaning
MSR_TR_1 Obtain track 1.
MSR_TR_1_2 Obtain tracks 1 and 2.
MSR_TR_1_2_3 Obtain tracks 1, 2, and 3.
MSR_TR_1_2_3_4 Obtain tracks 1, 2, 3, and 4.
Decreasing the required number of tracks may provide a greater swipe success rate
and somewhat greater responsiveness by removing the processing for unaccessed
data.

TracksToRead does not indicate a capability of the MSR hardware unit but
instead is an application configurable property representing which track(s) will
have their data obtained, potentially decoded, and returned if possible. Cases such
as an ISO card being swiped through a JIS-II read head, cards simply not having
data for particular tracks, and other factors may preclude the desired data from
being obtained.
This property is initialized to MSR_TR_1_2_3 by the open method.
See Also Track1Data Property, Track2Data Property, Track3Data Property,
Track4Data Property.
TracksToWrite Property Added in Release 1.10

Syntax TracksToWrite: int32 { read-write, access after open-claim-enable }
Remarks Holds the MSR track(s) that will be written to when the writeTracks method is
invoked and an MSR card is swiped. Valid values can be equal to or a subset of
those defined under CapWritableTracks. If CapWritableTracks contains
MSR_TR_NONE then writing to MSR tracks is not supported and an
E_ILLEGAL exception will be thrown on any attempt to update this property.
If an attempt is made to set a track that is not defined as writable in
CapWritableTracks the property will be left unchanged and an E_ILLEGAL
exception will be thrown.
Setting this property may also update EncodingMaxLength since each track may
have a different encoding limit.
This property is initialized to MSR_TR_NONE by the open method.
See Also CapWritableTracks Property, EncodingMaxLength Property, writeTracks
Method.
TransmitSentinels Property Added in Release 1.5
Syntax TransmitSentinels: boolean { read-write, access after open }
Remarks If true, the Track1Data, Track2Data, Track3Data, and Track4Data properties
contain start and end sentinel values.
If false, then these properties contain only the track data between these sentinels.
Value Meaning
E_ILLEGAL The CapTransmitSentinels property is false.
See Also CapTransmitSentinels Property, Track1Data Property, Track2Data Property,
Track3Data Property, Track4Data Property.

WriteCardType Property Added in Release 1.12

Syntax WriteCardType: string { read-write, access after open }
Remarks Holds the card type to be used the next time the writeTracks method is called. If
this property's value begins with an underscore ('_') the card type is vendor
specific. If this property does not begin with an underscore the card type is one of
the standard card types. The following list shows all currently defined standard
card types:
This property is initialized to “BANK” by the open method.
See Also writeTracks Method.


authenticateDevice Method Added in Release 1.12
Syntax authenticateDevice ( response: binary):
response A response token generated from the challenge token
retrieved from a previous call to the
retrieveDeviceAuthenticationData method.
Remarks To authenticate a device, the application first calls the
retrieveDeviceAuthenticationData method to retrieve a challenge token from
the device. The application then typically passes this token to another entity that
has special knowledge of a shared secret and is able to create a proper response
token. This response token is then passed as the response parameter to this method
and the service uses it to validate the authentication request. If this method
succeeds, the device enters the authenticated state and the service sets the
DeviceAuthenticated property to true.
Value Meaning
E_ILLEGAL One of the following conditions occurred:
• The service does not support device authentication
(CapDeviceAuthentication =
MSR_DA_NOT_SUPPORTED)
• The device is already in the authenticated state
EMSR_DEVICE_AUTHENTICATION_FAILED
The authentication request failed because the response
parameter was invalid.

deauthenticateDevice Method Added in Release 1.12

Syntax deauthenticateDevice ( response: binary):
response A response token generated from the challenge token
retrieved from a previous call to the
retrieveDeviceAuthenticationData method.
Remarks This method is used to deauthenticate a device that is currently in the authenticated
state (DeviceAuthenticated = true). The token is typically generated by passing
the challenge retrieved from the retrieveDeviceAuthenticationData method to
an entity that has special knowledge of a shared secret. If this method succeeds the
service sets DeviceAuthenticated to false and enqueues a StatusUpdateEvent
with status value set to MSR_SUE_DEVICE_DEAUTHENTICATED.
Value Meaning
• The service does not support device authentication
• The device is not in the authenticated state
EMSR_DEVICE_DEAUTHENTICATION_FAILED
The deauthentication request failed because the
response parameter was invalid.
retrieveCardProperty Method Added in Release 1.12

Syntax retrieveCardProperty ( name: string, inout value: string):
name Name of the property whose value is to be retrieved. The
CardPropertyList property can be parsed to determine
the set of valid properties for the most recently swiped
card.
value Location in which to return the value of the property
specified by the name parameter. If the name parameter
is not recognized or not supported for the current card
type, the value returned will be empty.

Remarks Retrieves the value of specific parsed properties from the last card swiped. Until a
card is swiped, all defined properties will return an empty string.
Note: If DataEncryptionAlgorithm is not MSR_DE_NONE and
CapTrackDataMasking is true the returned value may contain masked
information.
For bank cards, the following properties are parsed and can be accessed through
the retrieveCardProperty method:
• “AccountNumber”
• “FirstName”
• “MiddleInitial”
• “ServiceCode”
• “Suffix”
• “Surname”
• “Title”
For AAMVA driver’s licenses and ID cards, the following properties are parsed
and can be accessed through the retrieveCardProperty method:
• “Address”
• “BirthDate”
• “City”
• “Class”
• “Endorsements”
• “EyeColor”
• “FirstName”
• “Gender”
• “HairColor”
• “Height”
• “LicenseNumber”
• “PostalCode”
• “Restrictions”
• “State”
• “Suffix”
• “Surname”
• “Weight”
This property is initialized to empty by the open method.
Value Meaning
E_ILLEGAL The name parameter is not a valid value for the most
recently swiped card, or the ParseDecodeData property
is set to false.
See Also CardTypeList Property, ParseDecodeData Property

retrieveDeviceAuthenticationData Method Added in Release 1.12

Syntax retrieveDeviceAuthenticationData ( inout challenge: binary):
challenge A challenge generated by the device that will be used to
generate the authentication and deauthentication tokens.
Remarks Applications call this method to retrieve a challenge token that will subsequently
be used to generate response tokens that will be passed to the authenticateDevice
and deauthenticateDevice methods. The challenge token is typically sent to
another entity that has special knowledge of a shared secret that is required to
generate the proper response token(s).
Value Meaning
E_ILLEGAL The service does not support device authentication
See Also CapDeviceAuthentication Property, authenticateDevice Method,
deauthenticateDevice Method.
updateKey Method Added in Release 1.12

Syntax updateKey (key: string, keyName: string):
key A Hex-ASCII value for a new key.
keyName A name used to identify the key.
Remarks Provides a new encryption key to the device. It is used only for those encryption
algorithms in which new key values are sent to the terminal as a field in standard
messages from the host.
Value Meaning
• The selected DataEncryptionAlgorithm does not
support this function.
• The keyName specifies an unacceptable key name.
• The key contains a bad key (not Hex-ASCII or
wrong length or bad parity).
See Also CapDataEncryption Property, DataEncryptionAlgorithm Property.

writeTracks Method Updated in Release 1.12

Syntax writeTracks (data: array of binary, timeout: int32):
data1 Array containing the binary track data for all tracks to be
written during this method call. For simplicity, this array
should always be 4 elements long, with the first array
element being Track 1. Any tracks that are not going to
be written should be provided as a valid binary object of
length zero (0). The TracksToWrite property controls
which tracks are to be written, so to get a track written
correctly requires both a valid binary data object
provided in the array and the corresponding track bit set
in the TracksToWrite property.
timeout The number of milliseconds before failing the method.
If FOREVER (-1), the method initiates encoding the
data, then waits as long as needed until a card is swiped.
Remarks Initiates the encoding of data to the MSR track(s) selected in the TracksToWrite
property.
When called, data is prepared to be written on to the next card that is swiped within
the allotted timeout period. If no card is swiped within the timeout period then a
UposException is thrown. The next card swiped will be written in the format
specified by the WriteCardType property.
Data that is written to the card is read back from the card in the exact same format,
the Service must not decode/encode the data in any fashion.
This method is always performed synchronously, so that the write will be
attempted to the next card that is swiped.
Value Meaning
E_ILLEGAL The data to be written exceeds the
EncodingMaxLength property for the selected
TracksToWrite, or CapWritableTracks is set to
MSR_TR_NONE.
E_FAILURE A card was swiped within the allotted timeout, but that
card or track specified by TracksToWrite is not
writable
E_TIMEOUT A card was not swiped within the allotted timeout
period.
See Also TracksToWrite Property, WriteCardType Property, EncodingMaxLength
Property.


Description Notifies the application when input data from the MSR device is available.
The Status property is divided into four bytes representing information on up to
four tracks of data. The diagram below indicates how the Status property is
divided:
High Word Low Word

Track 4 Track 3 Track 2 Track 1
A value of zero for a track byte means that no data was obtained from the swipe
for that particular track. This might be due to the hardware device simply not
having a read head for the track, or perhaps the application intentionally precluded
incoming data from the track via the TracksToRead property.
A value greater than zero indicates the length in bytes of the corresponding
TrackxData Property or TrackxEncryptedData Property if encryption is
enabled.
Remarks Before this event is delivered, the swiped data is placed into the TrackxData and/
or TrackxEncryptedData properties. If DecodeData is true, then this track data
is decoded. If ParseDecodeData is true, then the data is parsed into several
additional properties.
See Also DecodeData Property, ParseDecodeData Property, TrackxData Properties,
TrackxEncryptedData Properties, TracksToRead Property.

DirectIOEvent
means for a vendor-specific MSR Service to provide events to the application that
Service.
from being used with other vendor’s MSR devices which may not have any

Description Notifies the application that an error has been detected at the MSR device and a
Codes on page 52.
ErrorCodeExtended
values below.

If the ErrorReportingType property is MSR_ERT_TRACK and ErrorLocus is

EL_INPUT and ErrorCode is E_EXTENDED, then ErrorCodeExtended contains
track-level statuses, broken down as follows:
High Word Low Word

Track 4 Track 3 Track 2 Track 1
Where each of the track status bytes has one of the following values:
Value Meaning
SUCCESS No error occurred.
EMSR_START Start sentinel error.
EMSR_END End sentinel error.
EMSR_PARITY Parity error.
EMSR_LRC LRC error.
E_FAILURE Other or general error.
Value Meaning
available.
available.
Value Meaning
Remarks Enqueued when an error is detected while trying to read MSR data. This error
event is not delivered until the DataEventEnabled property is true, so that proper
application sequencing occurs.
If the ErrorReportingType property is MSR_ERT_CARD, then the track that
caused the fault cannot be determined. The track data properties are not changed.

If the ErrorReportingType property is MSR_ERT_TRACK then the ErrorCode

and the ErrorCodeExtended properties may indicate the track-level status. Also,
the track data properties are updated as with a DataEvent, with the properties for
the track or tracks in error set to empty strings.
Unlike DataEvent, individual track lengths are not reported. However, the
application can determine their lengths by getting the length of each of the
TrackxData properties.
Also, since this is an ErrorEvent (even though it is reporting partial data), the
DataCount property is not incremented and the Control remains enabled,
regardless of the AutoDisable property value.
See Also “Device Behavior Models” on page 44 and ErrorReportingType Property.

Description Notifies the application that there is a change in the status of the MSR device.
Status int32 Indicates a status change, and has one of the following
values:
Value Meaning
MSR_SUE_DEVICE_AUTHENTICATED
The device has entered the authenticated state.
MSR_SUE_DEVICE_DEAUTHENTICATED
The device is no longer in the authenticated state.
process.
Remarks Enqueued when a significant status change event has occurred.


C H A P T E R 2 6
PIN Pad
This Chapter defines the PIN Pad device category.
Summary


836 PIN Pad
CapDisplay: int32 { read-only } 1.3 open
CapKeyboard: boolean { read-only } 1.3 open
CapLanguage: int32 { read-only } 1.3 open
CapMACCalculation: boolean { read-only } 1.3 open
CapTone: boolean { read-only } 1.3 open
AccountNumber: string { read-write } 1.3 open

AdditionalSecurityInformation: string { read-only } 1.3 open
Amount: currency { read-write } 1.3 open
AvailableLanguagesList: string { read-only } 1.3 open
AvailablePromptsList: string { read-only } 1.3 open
EncryptedPIN: string { read-only } 1.3 open
MaximumPINLength: int32 { read-write } 1.3 open
MerchantID: string { read-write } 1.3 open
MinimumPINLength: int32 { read-write } 1.3 open
PINEntryEnabled: boolean { read-only } 1.3 open
Prompt: int32 { read-write } 1.3 open
PromptLanguage: nls { read-write } 1.3 open
TerminalID: string { read-write } 1.3 open
Track1Data: binary { read-write } 1.3 open
TransactionType: string { read-write } 1.3 open

Summary 837

Common
Name Version
close ( ): 1.3
release ( ): 1.3
clearInput ( ): 1.3
void { } supported
Specific
Name
beginEFTTransaction ( PINPadSystem: string, transactionHost: int32 ): 1.3
computeMAC ( inMsg: string, outMsg: object ): 1.3
void { raises-exception, use after beginEFTTransaction }
enablePINEntry( ): 1.3
endEFTTransaction ( completionCode: int32 ): 1.3
updateKey ( keyNum: int32, key: string ): 1.3
verifyMAC ( message: string ): 1.3

838 PIN Pad

upos::events::OutputCompleteEvent Not supported

General Information
The PIN Pad programmatic name is “PINPad”.
A PIN Pad:
• Provides a mechanism for customers to perform PIN Entry.
• Acts as a cryptographic engine for communicating with an EFT
Transaction Host.
A PIN Pad will perform these functions by implementing one or more PIN Pad
Management Systems. A PIN Pad Management System defines the manner in
which the PIN Pad will perform functions such as PIN Encryption, Message
Authentication Code calculation, and Key Updating. Examples of PIN Pad
Management Systems include: Master-Session, DUKPT, APACS40,
HGEPOS, AS2805, and JDEBIT2, along with many others
Capabilities
The PIN Pad Control has the following minimal capability:

• Accept a PIN Entry at its keyboard and provide an Encrypted PIN to the
application.
The PIN Pad Control may have the following additional capabilities:
• Compute Message Authentication Codes.
• Perform Key Updating in accordance with the selected PIN Pad
Management System.
• Supports multiple PIN Pad Management Systems.
• Allow use of the PIN Pad Keyboard, Display, and Tone Generator for
application usage. If one or more of these features are available, then the
application opens and uses the associated POS Keyboard, Line Display, or
Tone Indicator Device Objects:

840 PIN Pad
PIN Pad Class Diagram

The following diagram shows the relationships between the PIN Pad classes.
<<utility>> <<utility>> <<Interface>>

<<uses>> BaseControl
PINPadConst UposConst
<<sends>>
<<exception>>
UposException
(from upos)
<<uses>>
<<uses>>
<<sends>>
<<event>>
<<Interface>>
DataEvent
(from events)
PINPadControl
(from upos)
<<capability>> CapDisplay : int32
fires
<<capability>> CapLanguage : int32
<<capability>> CapKeyboard : boolean
<<capability>> CapMACCalculation : boolean
<<event>> <<capability>> CapTone : boolean
ErrorEvent <<prop>> AccountNumber : string
(from events) <<prop>> AdditionalSecurityInformation : string
fires <<prop>> Amount : currency
<<prop>> AvailableLanguagesList : string
<<prop>> AvailablePromptsList : string
<<prop>> EncryptedPIN : string
<<prop>> MaximumPINLength : int32
<<prop>> MerchantID : string
<<prop>> MinimumPINLength : int32
<<event>> <<prop>> PINEntryEnabled : boolean
fires
StatusUpdateEvent <<prop>> Prompt : int32
(from events) <<prop>> PromptLanguage : int32
<<prop>> TerminalID : string
fires <<prop>> Track4Data : binary
<<event>> <<prop>> TransactionType : int32
DirectIOEvent
(from events) beginEFTTransaction(PINPadSystem : string, transactionHost : int32) : void
computeMAC(inMsg : string, outMsg : object) : void
enablePINEntry() : void
endEFTTransaction(completionCode : int32) : void
updateKey(keyNum : int32, key : string) : void
verifyMAC(message : string) : void

PIN Pad Sequence Diagram Added in Release 1.7

The following sequence diagram shows the typical usage of a PIN Pad device,
showing a general sequence of an application performing an EFT transaction with
message authentication.
NOTE: we are assuming that the :ClientApp already successfully opened, claimed and enabled the PINPad
device. This means that the Claimed, DeviceEnabled properties are == true
:ClientApp :PINPad :DataEvent :PINPadService
Without loss of generality we are assuming that CapTone : Customer

== false and CapDisplay == PPAD_DISP_NONE so that
tone and display functionality for the application are done via
other controls for some other tone and display devices.
1: setAccountNumber(accountNumber)
2: setAccountNumber(accountNumber)
3: setAmount(amount)
4: setAmount(amount)
5: setMerchantID(merchanID) 6: setMerchantID(merchanID)
7: setTerminalID(terminalID)
8: setTerminalID(terminalID)
9: setTrack1Data(track1Data)
13: setTrack3Data(track3Data) 14: setTrack3Data(track3Data)
This will be an empty array

except when the track data
is coming from a JIS-II card. At this point the device is
initialized to perform the
17: beginEFTTransaction() encryption functions for
18: beginEFTTransaction() the EFT transaction.
19: enablePINEntry()
20: enablePINEntry()
21: PINEntryEnabled property set to true
22: successfully entered PIN
23: PINEntryEnabled property set to false
24: create new DataEvent
25: enqueue DataEvent [DataEventEnabled == false]
26: deliver DataEvent to control [DataEventEnabled == true && FreezeEvents == false]
27: deliver event to all registered handlers Right before the DataEvent is
28: notify application of new event
delivered set DataEventEnabled
to false.
Assume message
authentication is required.
29: computeMAC(inMsg, outMsg) 30: computeMAC(inMsg, outMsg)
31: verifyMAC(message) 32: verifyMAC(message)
33: endEFTTransaction(PPA_EFT_NORMAL)
34: endEFTTransaction(PPA_EFT_NORMAL)

842 PIN Pad
Feature Not Supported
This specification does not include support for the following:

• Initial Key Loading. This operation usually requires downloading at least
one key in the clear and must be done in a secure location (typically either
the factory or at a Financial Institution). Thus, support for initial key
loading is outside the scope of this specification. However, this
specification does include support for updating keys while a PIN Pad unit
is installed at a retail site.
• Full EFT functionality. This specification addresses the functionality of a
PIN Pad that is used solely as a peripheral device by an Electronic Funds
Transfer application. It specifically does not define the functionality of an
Electronic Funds Transfer application that might execute within an
intelligent PIN Pad. This specification does not include support for
applications in which the PIN Pad application determines that a message
needs to be transmitted to the EFT Transaction Host. Consequently, this
specification will not apply in Canada, Germany, Netherlands, and
possibly other countries. It also does not apply to PIN Pad in which the
vendor has chosen to provide EFT Functionality in the PIN Pad.
• Smartcard Reader. Some PIN Pad devices will include a Smartcard reader.
Support for this device may be included in a future revision of this
specification. In the interim, the directIO method could be used to control
such added functionality.
Note on Terminology
For the PIN Pad device, clarification of the terminology used to describe the
data exchange with the device is necessary. “Hex-ASCII” is used to indicate
that the “standard” representation of bytes as hexadecimal ASCII characters is
used. For instance, the byte stream {0x15, 0xC7, 0xF0} would be represented
in hex-ASCII as “15C7F0”.

Model
A PIN Pad performs encryption functions under control of a PIN Pad

Management System. Some PIN Pads will support multiple PIN Pad
Management Systems. Some PIN Pad Management Systems support multiple
keys (sets) for different EFT Transaction Hosts. Thus, for each EFT
transaction, the application will need to select the PIN Pad Management
System and EFT Transaction Host to be used. Depending on the PIN Pad
Management System, one or more EFT transaction parameters will need to be
provided to the PIN Pad for use in the encryption functions. The application
should set the value of ALL EFT Transaction parameter properties to enable
easier migration to EFT Transaction Hosts that require a different PIN Pad
Management System.
After opening, claiming, and enabling the PIN Pad Control, an application
should use the following general scenario for each EFT Transaction.
• Set the EFT transaction parameters (AccountNumber, Amount,
MerchantID, TerminalID, Track1Data, Track2Data, Track3Data,
Track4Data, and TransactionType properties) and then call the
beginEFTTransaction method. This will initialize the Device to perform
the encryption functions for the EFT transaction.
• If PIN Entry is required, call the enablePINEntry method. Then set the
DataEventEnabled property and wait for the DataEvent.
• If Message Authentication Codes are required, use the computeMAC and
verifyMAC methods as needed.
• Call the endEFTTransaction method to notify the Device that all
operations for the EFT transaction have been completed.
• All input data enqueued by the Control may be deleted by calling the
clearInput method.
This specification supports two models of usage of the display. The
CapDisplay property indicates one of the following models.
• An application has complete control of the text that is to be displayed. For
this model, there is an associated Line Display Control that is used by the
application to interact with the display.
• An application cannot supply the text to be displayed. Instead, it can only
select from a list of pre-defined messages to be displayed. For this model,
there is a set of PIN Pad properties that are used to control the display.

844 PIN Pad
Device Sharing
The PIN Pad is an exclusive-use device, as follows:


PIN Pad State Diagram
The following state diagram depicts the PIN Pad Control device model.
close()
open() claim()

close() release()
/set DeviceEnabled( false )

close()
release()
/set DeviceEnabled( true )

Enabled
endEFTTransaction()
beginEFTTransaction()
EFT Transaction
Input Processing
PIN Input Processing
Idle
enablePINEntry()
Idle
Wait PIN Input
done Wait for PIN Input
done
computeMAC(), [DataEventEnabled == true]

verifyMAC() Error
Error Event
ErrorEvent Data Event
DataEvent
MAC Processing Processing
MAC Processing Processing
Processing
Processing

846 PIN Pad

Syntax AccountNumber: string { read-write, access after open }
Remarks Holds the account number to be used for the current EFT transaction. The
application must set this property before calling the beginEFTTransaction
method.
Value Meaning
E_ILLEGAL An attempt was made to change this property after the
beginEFTTransaction method has been called.
See Also beginEFTTransaction Method.
AdditionalSecurityInformation Property
Syntax AdditionalSecurityInformation: string { read-only, access after open }
Remarks Holds additional security/encryption information when a DataEvent is delivered.
This property will be formatted as a HEX-ASCII string. The information content
and internal format of this string will vary among PIN Pad Management Systems.
For example, if the PIN Pad Management System is DUKPT, then this property
will contain the “PIN Pad sequence number”. If the PIN Entry was cancelled, this
property will contain the empty string.
Amount Property Corrected in Release 1.8

Syntax Amount: currency { read-write, access after open }
Remarks Holds the amount of the current EFT transaction. The application must set this
property before calling the beginEFTTransaction method. This property is a
monetary value stored using an implied four decimal places. For example, an
actual value of 12345 represents 1.2345.
Value Meaning
See Also beginEFTTransaction Method.

AvailableLanguagesList Property
Syntax AvailableLanguagesList: string { read-only, access after open }
Remarks Holds a semi-colon separated list of a set of a “language definitions” that are
supported by the pre-defined prompts in the PIN Pad. A “language definition”
consists of an ISO-639 language code and an ISO-3166 country code. The two
codes are comma separated.
For example, the string “EN,US;FR,CAN” represents two supported language
definitions. US English and Canadian French where the variant of French used will
be dependent on what is available on the device.
If CapLanguage is PPAD_LANG_NONE, then this property will be the empty
string.
See Also PromptLanguage Property.
AvailablePromptsList Property
Syntax AvailablePromptsList: string { read-only, access after open }
Remarks Holds a comma-separated string representation of the supported values for the
Prompt property.
The full set of supported Prompt values are shown below:
Name (Value) Meaning
PPAD_MSG_ENTERPIN (1)
Enter pin number on the PIN Pad.
PPAD_MSG_PLEASEWAIT (2)
The system is processing. Wait.
PPAD_MSG_ENTERVALIDPIN (3)
The pin that was entered is not correct. Enter the correct
pin number.
PPAD_MSG_RETRIESEXCEEDED (4)
The user has failed to enter the correct pin number and
the maximum number of attempts has been exceeded.
PPAD_MSG_APPROVED (5)
The request has been approved.
PPAD_MSG_DECLINED (6)
The EFT Transaction Host has declined to perform the
requested function.

848 PIN Pad
PPAD_MSG_CANCELED (7)
The request is cancelled.
PAD_MSG_AMOUNTOK (8)
Enter Yes/No to approve the amount.
PPAD_MSG_NOTREADY (9)
PIN Pad is not ready for use.
PPAD_MSG_IDLE (10)
The System is Idle.
PPAD_MSG_SLIDE_CARD (11)
Slide card through the integrated MSR.
PPAD_MSG_INSERTCARD (12)
Insert (smart)card.
PPAD_MSG_SELECTCARDTYPE (13)
Select the card type (typically credit or debit).
Value 1000 and above are reserved for device specific defined values.
See Also Prompt Property.

CapDisplay Property
Syntax CapDisplay: int32 { read-only, access after open }
Remarks Defines the operations that the application may perform on the PIN Pad display.
Value Meaning
PPAD_DISP_UNRESTRICTED
The application can use the PIN Pad display in an
unrestricted manner to display messages. In this case, an
associated Line Display Control Object is the interface
to the PIN Pad display. The application must call Line
Display methods to manipulate the display.
PPAD_DISP_PINRESTRICTED
The application can use the PIN Pad display in an
unrestricted manner except during PIN Entry. The PIN
Pad will display a pre-defined message during PIN
Entry. If an attempt is made to use the associated Line
Display Control Object while PIN Entry is enabled, the
Line Display Control will throw a UposException with
an associated ErrorCode of E_BUSY.
PPAD_DISP_RESTRICTED_LIST
The application cannot specify the text of messages to
display. It can only select from a list of pre-defined
messages. There is no associated Line Display Device
Control.
PPAD_DISP_RESTRICTED_ORDER
The application cannot specify the text of messages to
display. It can only select from a list of pre-defined
messages. The selections must occur in a pre-defined
acceptable order. There is no associated Line Display
Device Control.
PPAD_DISP_NONE The PIN Pad does not have the PIN Pad display.

850 PIN Pad
CapKeyboard Property
Syntax CapKeyboard: boolean { read-only, access after open }
Remarks If true, the application can use the PIN Pad to obtain input. The application will
use an associated POS Keyboard Device Control object as the interface to the PIN
Pad keyboard. Note that the associated POS Keyboard Control is effectively
disabled while PINEntryEnabled is true.
If false, the application cannot obtain input directly from the PIN Pad keyboard.
CapLanguage Property Updated in Release 1.9
Syntax CapLanguage: int32 { read-only, access after open }
Remarks Defines the capabilities that the application has to select the language of pre-
defined messages (e.g., English, French, Arabic etc.).
Value Meaning
PPAD_LANG_NONE The PIN Pad supports no pre-defined prompt messages.

The property will be set to this value if CapDisplay =
PPAD_DISP_UNRESTRICTED. Any attempt to set the
value of the PromptLanguage property will cause a
UposException to be thrown with the associated
ErrorCode of E_ILLEGAL.
PPAD_LANG_ONE The PIN Pad supports pre-defined prompt messages in
one language. Any attempt to set the value of the
PromptLanguage property to other than the default
value will cause a UposException to be thrown with the
associated ErrorCode of E_ILLEGAL.
PPAD_LANG_PINRESTRICTED
The PIN Pad cannot change prompt languages during
PIN Entry. The application must set the desired value
into the PromptLanguage property before calling
enablePINEntry. Any attempt to set the value of the
PromptLanguage while PINEntryEnabled is true will
cause a UposException to be thrown with the associated
ErrorCode of E_BUSY.
PPAD_LANG_UNRESTRICTED
The application can change the language of pre-defined
prompt messages at anytime. The currently displayed
message will change immediately.

CapMACCalculation Property
Syntax CapMACCalculation: boolean { read-only, access after open }
Remarks If true, the PIN Pad supports MAC calculation.
CapTone Property
Syntax CapTone: boolean { read-only, access after open }
Remarks If true, the PIN Pad has a Tone Indicator. The Tone Indicator may be accessed by
use of an associated Tone Indicator Control. If false, there is no Tone Indicator.
EncryptedPIN Property
Syntax EncryptedPIN: string { read-only, access after open }
Remarks Holds the value of the Encrypted PIN after a DataEvent. This property will be
formatted as a hexadecimal ASCII string. Each character is in the ranges ‘0’
through ‘9’ or ‘A’ through ‘F’. Each pair of characters is the hexadecimal
representation for a byte.
For example, if the first four characters are “12FA”, then the first two bytes of the
PIN are 12 hexadecimal (18) and FA hexadecimal (250).
If the PIN Entry was cancelled, this property will contain the empty string.
MaximumPINLength Property
Syntax MaximumPINLength: int32 { read-write, access after open }
Remarks Holds the maximum acceptable number of digits in a PIN. This property must be
set to a default value by the open method. If the application wishes to change this
property, it should be set before the enablePINEntry method is called. Note that
in some implementations, this value cannot be changed by the application.
Value Meaning

enablePINEntry method has been called.

852 PIN Pad
MerchantID Property
Syntax MerchantID: string { read-write, access after open }
Remarks Holds the Merchant ID, as it is known to the EFT Transaction Host. The
method.
Value Meaning
MinimumPINLength Property
Syntax MinimumPINLength: int32 { read-only, access after open }
Remarks Holds the minimum acceptable number of digits in a PIN. This property will be set
to a default value by the open method. If the application wishes to change this
property, it should be set before the enablePINEntry method is called. Note that
in some implementations, this value cannot be changed by the application.
Value Meaning
enablePINEntry method has been called.
PINEntryEnabled Property Updated in Release 1.12

Syntax PINEntryEnabled: boolean { read-only, access after open }
Remarks If true, the PIN entry operation is enabled. It is set when the enablePINEntry
method is called. It will be set to false when the user has completed the PIN Entry
operation or when the endEFTTransaction method has completed.

Prompt Property
Syntax Prompt: int32 { read-write, access after open }
Remarks Holds the identifies a pre-defined message to be displayed on the PIN Pad. This
property is used if CapDisplay is PPAD_DISP_RESTRICTED_LIST or
PPAD_DISP_RESTRICTED_ORDER. It is also used during PIN Entry if
CapDisplay has a value of PPAD_DISP_PINRESTRICTED. The
AvailablePromptsList property lists the possible values for this property.
Value Meaning
E_ILLEGAL One of the following has occurred.

* An attempt was made to set the property to a value that
is not supported by the PIN Pad Service.
* An attempt was made to select prompt messages in an
unacceptable order (if CapDisplay is
PPAD_DISP_RESTRICTED_ORDER).

854 PIN Pad
PromptLanguage Property
Syntax PromptLanguage: nls { read-write, access after open }
Remarks Holds the “language definition” for the message to be displayed (as specified by
the Prompt property). This property is used if the Prompt property is begin used.
The exact effect of changing this property depends on the value of CapLanguage.
A “language definition” consists of an ISO-639 language code and an ISO-3166
country code. The two codes are comma separated.
The country code is optional and implies that the application does not care which
country variant of the language is used.
For example, the string “EN,US” represents a US English language definition, the
string “FR”, represents a French language definition where the variant of French
used will be dependent on what is available on the device.
The property is initialized to a default value by the open method.
Value Meaning
E_ILLEGAL One of the following occurred.
* An attempt was made to set the property to a value that
is not supported by the PIN Pad Service.
* CapLanguage is PPAD_LANG_NONE. and an
attempt was made to set the value of this property.
* CapLanguage is PPAD_LANG_ONE and an attempt
was made to set the value of this property to other than
the default value.
E_BUSY CapLanguage is PPAD_LANG_PINRESTRICTED
and PINEntryEnabled is true.
See Also CapLanguage Property, AvailableLanguagesList Property.
TerminalID Property
Syntax TerminalID: string { read-write, access after open }
Remarks Holds the terminal ID, as it is known to the EFT Transaction Host. The application
must set this property before calling the beginEFTTransaction method.
Value Meaning

Track1Data Property
Syntax Track1Data: binary { read-write, access after open }
Remarks Holds either the decoded track 1 data from the previous card swipe or an empty
array. An empty array indicates that the track was not physically read. The
method.
Value Meaning

Track2Data Property
method.
Value Meaning

Track3Data Property
method.
Value Meaning


856 PIN Pad
Track4Data Property Added in Release 1.5

Remarks Holds either the decoded track 4 (JIS-II) data from the previous card swipe or an
empty array. An empty array indicates that the track was not physically read. The
method.
To maintain compatibility with previous versions, the Control may also continue
to store the JIS-II data in another TracknData property. However, it should be
noted that to ensure application portability, Track4Data should be used to access
JIS-II data.
Value Meaning
TransactionType Property
Syntax TransactionType: int32 { read-write, access after open }
Remarks Holds the type of the current EFT Transaction. The application must set this
property before calling the beginEFTTransaction method.
This property have one of the following values:
Value Meaning
PPAD_TRANS_DEBIT Debit (decrease) the specified account
PPAD_TRANS_CREDITCredit (increase) the specified account
PPAD_TRANS_INQ (Balance) Inquiry
PPAD_TRANS_RECONCILE
Reconciliation/Settlement
PPAD_TRANS_ADMINAdministrative Transaction
Value Meaning

beginEFTTransaction Method
Syntax beginEFTTransaction ( PINPadSystem: string, transactionHost: int32 ):
Value Description
PINPadSystem Name of the desired PIN Pad Management System (see

below). The Service may support other PIN Pad
Management systems.
transactionHost Identifications particular EFT Transaction Host to be
used for this transaction.
The PINPadSystem Parameter has one of the following values:
Value Description
“M/S” Master/Session (U.S.A Latin America)

“DUKPT” Derived Unique Key Per Transaction (USA, Latin
America)
“APACS40” Standard 40 (UK and other countries)
“AS2805” Australian Standard 2805
“HGEPOS” (Italian)
“JDEBIT2” Japan Debit 2
Remarks Initialize the beginning of an EFT Transaction. The device will perform
initialization functions (such as computing session keys). No other PIN Pad
functions can be performed until this method is called.
Value Meaning
E_ILLEGAL The requested PIN Pad Management System is not

supported by the Control, or the requested EFT
Transaction Host is an illegal value for the selected PIN
Pad Management System.
E_BUSY The PIN Pad is already performing an EFT transaction.

858 PIN Pad
computeMAC Method Updated in Release 1.7
Syntax computeMAC ( inMsg: string, outMsg: object ):

void { raises-exception, use after beginEFTTransaction )
Value Description
inMsg1 The message that the application intends to send to an
EFT Transaction.
outMsg1 Contains the result of applying the MAC calculation to

inMsg. This output parameter will contain a reformatted
message that may actually be transmitted to an EFT
Transaction Host.
Remarks Computers a MAC value and appends it to the designated message. Depending on
the selected PIN Pad management system, the PIN Pad may also insert other fields
into the message. Note that this method cannot be used while PIN Pad input (PIN
Entry) is enabled.
Value Meaning
E_DISABLED A beginEFTTransaction method has not been
performed.
E_BUSY PINEntryEnabled is true. The PIN Pad cannot perform
a MAC calculation during PIN Entry.

enablePINEntry Method
Syntax enablePINEntry ():
void { raises-exception, use after beginEFTTransaction );
Remarks Enable PIN Entry at the PIN Pad device. When this method is called, the
PINEntryEnabled property will be changed to true. If the PIN Pad uses pre-
defined prompts for PIN Entry, then the Prompt property will be changed to
PPAD_MSG_ENTERPIN.
When the user has completed the PIN entry operation (either by entering their PIN
or by hitting Cancel), the PINEntryEnabled property will be changed to false. A
DataEvent will be delivered to provide the encrypted PIN to the application when
DataEventEnabled is set to true. Note that any data entered at the PIN Pad while
PINEntryEnabled is true will be supplied in encrypted form and will NOT be
provided to any associated Keyboard Control Object.
Value Meaning

performed.

860 PIN Pad
endEFTTransaction Method
Syntax endEFTTransaction (completionCode: int32):
The completionCode is one of the following values:

Value Description
PPAD_EFT_NORMAL The EFT transaction completed normally. Note that this

does not mean that the EFT transaction was approved. It
merely means that the proper sequence of messages was
transmitted and received.
PPAD_EFT_ABNORMAL
The proper sequence of messages was not transmitted
and received.
Remarks Ends an EFT Transaction. The Device will perform termination functions (such as
computing next transaction keys).
updateKey Method
Syntax updateKey ( keyNum: int32, key: string):
keyNum A key number.

key A Hex-ASCII value for a new key.
Remarks Provides a new encryption key to the PIN Pad. It is used only for those PIN Pad
Management Systems in which new key values are sent to the terminal as a field
in standard messages from the EFT Transaction Host.
Value Meaning
E_ILLEGAL One of the following conditions occurred.

* The selected PIN Pad Management System does not
support this function.
* The keyNum specifies an unacceptable key number.
* The key contains a bad key (not Hex-ASCII or wrong
length or bad parity).

verifyMAC Method Updated in Release 1.9
Syntax verifyMAC ( message: string ):

message Contains a message received from an EFT Transaction
Host.
Remarks Verify the MAC value in a message received from an EFT Transaction Host. This
method throws a UposException if it cannot verify the message. Note that this
method cannot be used while PIN Entry is enabled.
Value Meaning
E_BUSY PINEntryEnabled is true. The PIN Pad cannot perform
a MAC verification during PIN Entry.
performed.
E_FAILURE The Service failed to verify the MAC value in message.

862 PIN Pad
DataEvent
Description Notifies the application when a PIN Entry operation has completed.

The Status property has one of the following values:
Value Meaning
PPAD_SUCCESS PIN Entry has occurred and values have been stored into
the EncryptedPIN and
AdditionalSecurityInformation properties.
PPAD_CANCEL The user hit the cancel button on the PIN Pad.
PPAD_TIMEOUT A timeout condition occurred in the PIN Pad. (Not all
PIN Pads will report this condition).

DirectIOEvent
means for a vendor-specific PIN Pad Service to provide events to the application
that are not otherwise supported by the Device Control.
Service event.
from being used with other vendor’s PIN Pad devices which may not have any

Description Notifies the application that an error was detected while trying to perform a PIN
encryption function.
Codes on page 52.
ErrorCodeExtended
ErrorLocus int32 Location of the error, and is set to EL_INPUT indicating
that the error occurred while gathering or processing
event-driven input.

864 PIN Pad

values below.
following values:
Value Meaning
EPPAD_BAD_KEY An Encryption Key is corrupted or missing.

Value Meaning
available.
The application’s error processing may change ErrorResponse to the following
value:
Value Meaning
error state. This event is not delivered until DataEventEnabled is true, so that
proper application sequencing occurs.
See Also “Device Behavior Models” on page 44 and ErrorReportingType Property.
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a PIN Pad.
Status int32 Reports a change in the power state of a PIN Pad.
process.
Remarks Enqueued when the PIN Pad detects a power state change.

C H A P T E R 2 7
Point Card Reader / Writer

This Chapter defines the Point Card Reader / Writer device category.
Summary

866 Point Card Reader / Writer
CapBold: boolean { read-only } 1.5 open
CapCardEntranceSensor: int32 { read-only } 1.5 open
CapCleanCard: boolean { read-only } 1.5 open
CapClearPrint: boolean { read-only } 1.5 open
CapDhigh: boolean { read-only } 1.5 open
CapDwide: boolean { read-only } 1.5 open
CapDwideDhigh: boolean { read-only } 1.5 open
CapItalic: boolean { read-only } 1.5 open
CapLeft90: boolean { read-only } 1.5 open
CapPrint: boolean { read-only } 1.5 open
CapPrintMode: boolean { read-only } 1.5 open
CapRight90: boolean { read-only } 1.5 open
CapRotate180: boolean { read-only } 1.5 open
CapTracksToRead: int32 { read-only } 1.5 open
CapTracksToWrite: int32 { read-only } 1.5 open
CardState: int32 { read-only } 1.5 open

FontTypeFaceList: string { read-only } 1.5 open
LineChars: int32 { read-only } 1.5 open, claim, & enable
LineCharsList: string { read-only } 1.5 open
LineHeight: int32 { read-only } 1.5 open, claim, & enable
LineSpacing: int32 { read-only } 1.5 open, claim, & enable
LineWidth: int32 { read-only } 1.5 open, claim, & enable
MapMode: int32 { read-only } 1.5 open, claim, & enable
MaxLine: int32 { read-only } 1.5 open, claim, & enable
PrintHeight: int32 { read-only } 1.5 open, claim, & enable
ReadState1: int32 { read-only } 1.5 open
ReadState2: int32 { read-only } 1.5 open
RecvLength1: int32 { read-only } 1.5 open, claim, & enable
RecvLength2: int32 { read-only } 1.5 open, claim, & enable
SidewaysMaxChars: int32 { read-only } 1.5 open
SidewaysMaxLines: int32 { read-only } 1.5 open

Summary 867
TracksToRead: int32 { read-write } 1.5 open, claim, & enable
TracksToWrite: int32 { read-write } 1.5 open, claim, & enable
Track3Data: binary { read-only ) 1.5 open
WriteState1: int32 { read-only } 1.5 open
WriteState2: int32 { read-only } 1.5 open
Write1Data: binary { read-write } 1.5 open


Common
Name Version
close ( ): 1.5
release ( ): 1.5
clearInput ( ): 1.5
Specific
Name
void{ raises-exception, use after open, claim, enable }
cleanCard ( ): 1.5
clearPrintWrite ( kind: int32, hposition: int32, vposition: int32, width: 1.5
int32, height: int32 ):

Summary 869
endRemoval ( ): 1.5
printWrite ( kind: int32, hposition: int32,vposition: int32,data: string ): 1.5
rotatePrint ( rotation: int32 ): 1.5
validateData ( data: string ): 1.5


General Information
The Point Card Reader / Writer programmatic name is “PointCardRW”.
Capabilities
The Point Card Reader / Writer has the following capabilities.

• Both reading and writing of the point card magnetic data are possible.
• Supports reading and writing of data from up to 6 tracks.
• The data on the tracks is in a device specific format, see the device manual
for specific definition. The data is usually in ASCII format.
• Supports point cards with or without a printing area. Actual printing support
depends upon the capabilities of the device.
• Supports both card insertion and ejection.
• No special security capabilities (e.g., encryption) are supported.

Point Card Reader Writer Class Diagram
The following diagram shows the relationships between the Point Card Reader
Writer classes.
<<Interface>>
PointCardRWControl
<<event>> (from upos) <<exception>>
DataEvent <<capability>> CapBold : boolean UposException
(from events) <<capability>> CapCardEntranceSensor : boolean (from upos)
<<capability>> CapCharacterSet : int32
<<capability>> CapCleanCard : boolean
<<capability>> CapClearPrint : boolean
<<capability>> CapDhigh : boolean
<<capability>> CapDwide : boolean
<<sends>>
<<capability>> CapDwideDhigh : boolean
fires <<capability>> CapItalic : boolean
<<capability>> CapLeft90 : boolean
<<capability>> CapPrint : boolean
<<capability>> CapPrintMode : boolean
<<capability>> CapRight90 : boolean <<sends>>
<<capability>> CapRotate180 : boolean
<<capability>> CapTracksToRead : int32
<<capability>> CapTracksToWrite : int32
<<prop>> CardState : int32 <<utility>>
<<prop>> CharacterSet : int32 UposConst
<<prop>> CharacterSetList : string
<<prop>> FontTypeFaceList : string (from upos)
<<event>>
<<prop>> LineChars : int32
StatusUpdateEvent <<prop>> LineCharsList : string
(from events) <<prop>> LineHeight : int32
<<prop>> LineSpacing : int32
fires <<prop>> LineWidth : int32 <<uses>>
<<prop>> MapMode : int32
<<prop>> MaxLines : int32
<<prop>> PrintHeight : int32
<<prop>> RecvLength1 : int32 <<uses>>
<<prop>> RecvLength2 : int32
<<event>> <<prop>> ReadState1 : int32
fires <<prop>> ReadState2 : int32
ErrorEvent <<prop>> SidewaysMaxChars : int32
(from events) <<prop>> SidewaysMaxLines : int32 <<Interface>>
<<prop>> Tracks1Data : binary
<<prop>> Tracks2Data : binary BaseControl
<<prop>> Tracks3Data : binary (from upos)
fires <<prop>> TracksToRead : int32
<<prop>> TracksToWrite : int32
<<prop>> Write1Data : binary
<<event>> <<prop>> Write3Data : binary
DirectIOEvent <<prop>> Write5Data : binary <<uses>>
(from events) <<prop>> Write6Data : binary
<<prop>> WriteState1 : int32
<<prop>> WriteState2 : int32
beginInsertion()
<<utility>>
beginRemoval() PointCardRWConst
cleanCard()
(from upos)
clearPrintWrite()
endInsertion()
endRemoval()
printWrite()
rotatePrint()
validateData()

Model
The general model of Point Card Reader Writer is as follows:
• The Point Card Reader Writer reads all the magnetic stripes on a point card.
The data length and reading information are placed in the property
corresponding to the track.
• The Point Card Reader Writer follows the input model of event driven input
during the card insertion processing. Also, writing to the printing area and the
magnetic stripe follows the output model.
Input Model
• An application must call open and claim, then set DeviceEnabled to true.
• When an application wants a card inserted, it calls the beginInsertion
method, specifying a timeout value.
• If a card is not inserted before the timeout period elapses, the Point Card
Reader Writer fires an exception.
• Even if a timeout occurs, the Point Card Reader Writer remains in insertion
mode. If the application still wants a card inserted, it must call the
beginInsertion method again.
• To exit insertion mode, either after a card was inserted or the application
wishes to abort insertion, the application calls the endInsertion method.
• If there is a point card in the Point Card Reader Writer when endInsertion is
called, the point card’s data tracks are automatically read and a DataEvent is
enqueued. When the application sets the DataEventEnabled property to
true, the DataEvent will be delivered.
• If an error occurs while reading the point card’s data tracks, an ErrorEvent
is enqueued instead of a DataEvent. When the application sets the
DataEventEnabled property to true, the ErrorEvent will be delivered.
• The application can obtain the current number of enqueued data events by
reading the DataCount property.
• All enqueued but undelivered input may be deleted by calling the clearInput
method.

Output Model Updated in Release 1.7
• To write data to a card, the application calls the printWrite method. The
ability to write data depends upon the capabilities of the device.
• The printWrite method is always performed asynchronously. All
asynchronous output is performed on a first-in, first-out basis.
• When the application calls printWrite, the Point Card Reader Writer buffers
the request in program memory, for delivery to the Physical Device as soon
as the Physical Device can receive and process it, assigns a unique
identification number for this request. This ID is stored in the property
OutputID. The Point Card Reader Writer then either queues the request or
starts its processing. Either way, the Point Card Reader Writer returns to the
application quickly.
• When the printWrite method completes, an OutputCompleteEvent is
delivered to the application. The OutputID associated with the completed
request is passed in the OutputCompleteEvent.
• If the printWrite method fails during its processing, an ErrorEvent will be
delivered to the application. If the application had multiple outstanding
output requests, the OutputID of the request that failed can be determined by
watching which requests have successfully completed by monitoring
OutputCompleteEvents. The request that failed is the one that was issued
immediately after the last request that successfully completed.
• All buffered output data, including all asynchronous output, may be deleted
by calling clearOutput. This method also stops any output that is in
progress, if possible. No OutputCompleteEvents will be delivered for
output requests terminated in this manner.
• When done accessing the point card, the application calls the beginRemoval
method, specifying a timeout value.
• If the card is not removed before the timeout period elapses, the Point Card
Reader Writer fires an exception.
• Even if a timeout occurs, the Point Card Reader Writer remains in removal
mode. If the application still wants the card removed, it must call the
beginRemoval method again.
• To exit removal mode, either after the card was physically removed or the
application wishes to abort removal, the application calls the endRemoval
method.

Card Insertion Diagram

The processing from card insertion to card removal is shown below. All methods,
other than printWrite, are performed synchronously.
Point Card
Application Reader Writer
beginInsertion
(1)
beginInsertion
Card
endInsertion insertion
DataEventEnabled = true
DataEvent
printWrite
Card
OutputCompleteEvent write
beginRemoval
(2)
beginRemoval
Card
endRemoval removal
(1) If the card is not inserted into the Point Card Reader Writer before the
application specified timeout elapses, an exception is fired. The application
needs to call beginInsertion again to confirm that a point card has been
inserted or call endInsertion to cancel the card insertion. After a successful
beginInsertion, the application must call endInsertion to cause the Point
Card Reader Writer to exit insertion mode and to read the magnetic stripe
data from the point card.
(2) If the card is not removed from the Point Card Reader Writer before the
application specified timeout elapses, an exception is fired. The application
needs to call beginRemoval again to confirm that the point card has been
removed, or call endRemoval to cancel the card removal. After a successful
beginRemoval, the application must call endRemoval to cause the Point
Card Reader Writer to exit removal mode.

Printing Capability
• The Point Card Reader Writer supports devices that allow for rewriting the
print area of a card.
• The Point Card Reader Writer supports printing specified either by dot units
or by line units. When CapPrintMode is true, the unit type is determined by
the value of the MapMode property. When CapPrintMode is false, the unit
type is defined as lines.
• The data to print is passed to the printWrite method as the data parameter.
Special character modifications, such as double height, are dependent upon
the capabilities of the device. The starting print location is specified by the
vposition and hposition parameters respectively indicating the vertical and
horizontal start position expressed in units defined by the MapMode
property value.
• When using line units, the start position for lines containing both single and
double high characters is the top of a single high character for horizontal
printing and the bottom of all characters for vertical printing. See the diagram
below for further clarification.
Horizontal printing Vertical printing
hposition hposition
0 0
0 0
vposition vposition
A B
A
B
direction of
direction of
insertion
insertion
Line feed
Line feed

Cleaning Capability
• Cleaning of the Point Card Reader Writer is necessary to prevent errors
caused by dirt build up inside the device.
• A special cleaning card is used. There are two types of cleaning card: a wet
card (such as a card wet with ethanol before use) and a dry card.
• Cleaning is carried out by having the inserted cleaning card make several
passes over the read heads inside the device.
• Some Point Card Reader Writers perform the cleaning operation by use of a
switch on the device. Others perform the cleaning operation entirely under
control of the application.
Initialization of Magnetic Stripe Data

• Some Point Card Reader Writers can initialize the magnetic stripe data to
prevent the illegal use of a point card.
• There are three initialization techniques in use for Point Card Reader Writers:
• Initialize all of the data, including the start sentinel, end sentinel, and a
correct LRC.
• Write an application specific code into the data area using no sentinels.
• Initialize all tracks to empty by just writing start and end sentinels.
• Initialization of the magnetic stripe is dependent upon the capability of the
device.
Device Sharing
The Point Card Reader Writer is an exclusive-use device, as follows:

Point Card Reader Writer specific properties.

Data Characters and Escape Sequences Updated in Release 1.7

The default character set of all Point Card Reader Writers is assumed to support at
least the ASCII characters 20-hex through 7F-hex, which include spaces, digits,
uppercase, lowercase, and some special characters. If the Point Card Reader
Writer does not support lowercase characters, then the Service may translate them
to uppercase.
decimal, followed by a vertical bar (‘|’). This is followed by zero or more digits
and/or lowercase alphabetic characters. The escape sequence is terminated by an
If a sequence does not begin with ESC “|”, or it begins with ESC “|” but is not a
valid UnifiedPOS escape sequence, the Service will make a reasonable effort to
pass it through to the Point Card Reader Writer. However, not all such sequences
can be distinguished from printable data, so unexpected results may occur.
Starting with Release 1.7, the application can use the ESC|#E escape sequence
to ensure more reliable handling of the amount of data to be passed through to the
Point Card Reader Writer. Use of this escape sequence will make an application
non-portable. The application may, however, maintain portability by performing
Embedded Data Escape sequence calls within conditional code. This code may be
based upon the value of the DeviceServiceDescription, the
PhysicalDeviceDescription, or the PhysicalDeviceName property.
NOTE: This command sequence definition and the corresponding
definition in the POS Printer Chapter, are the only known deviations
from preserving the interchangeability of devices defined in this
specification. If an application finds it necessary to utilize this command
sequence, please inform the UnifiedPOS Committee (www.nrf-arts.org)
with the details of its usage, so that a possible standard/generic
Application Interface may be incorporated into a future release of the
UnifiedPOS Standard. In order to preserve peripheral independence and
interoperability at the Application level, it is the Committee’s position
that this command sequence should be used only as a “last resort”.
To determine if escape sequences or data can be performed on Point Card Reader
Writer, the application can call the validateData method. (For some escape
sequences, corresponding capability properties can also be used.)
The following escape sequences are recognized. If an escape sequence specifies
an operation that is not supported by the Point Card Reader Writer, then it is
ignored.
Commands Perform indicated action. Added in Release1.7
Name Data Remarks
Send the following # characters of data through to the
hardware without modifying it. The character '#' is
Pass through embedded data
ESC |#E replaced by an ASCII decimal string telling the number of
(See a below.)
bytes following the escape sequence that should be
passed through as-is to the hardware.
a. This escape sequence is only available in Version 1.7 and later.

Print Mode Characteristics that are remembered until explicitly changed.
Name Data Remarks

Selects a new typeface for the following data. Values for the
character ‘#’ are:
0 = Default typeface.
Font typeface selection ESC |#fT
1 = Select first typeface from the FontTypefaceList property.
2 = Select second typeface from the FontTypefaceList property.
And so on.
Print Line Characteristics that are reset at the end of each print method or by a
“Normal” sequence.
Name Data Remarks
Bold ESC |bC Prints in bold or double-strike.
Underline ESC |#uC Prints with underline. The character ‘#’ is replaced by
an ASCII decimal string telling the thickness of the
underline in printer dot units. If ‘#’ is omitted, then a
printer-specific default thickness is used.
Italic ESC |iC Prints in italics.
Reverse video ESC |rvC Prints in a reverse video format.
Single high and wide ESC |1C Prints normal size.
Double wide ESC |2C Prints double-wide characters.
Double high ESC |3C Prints double-high characters.
Double high and wide ESC |4C Prints double-high/double-wide characters.
Scale horizontally ESC |#hC Prints with the width scaled ‘#’ times the normal size,
where ‘#’ is replaced by an ASCII decimal string.
Scale vertically ESC |#vC Prints with the height scaled ‘#’ times the normal size,
Center ESC |cA Aligns following text in the center.
Right justify ESC |rA Aligns following text at the right.
Normal ESC |N Restores printer characteristics to normal condition.

Point Card Reader Writer Sequence Diagram Added in Release 1.7
OCE=OutputCompleteEvent
ClientApp DataEventHandler cd:PCRW DataEvent PCRWService
new OCEHandler
Create and register a DataEventHandler with the control
claim(timeOut)
claim(timeOut)
setDeviceEnabled(true) setDeviceEnabled(true)
beginInsertion(timeout)
beginInsertion(timeout)
endInsertion()
endInsertion()
new
enqueue DataEvent to service's internal queue
copy data to DataEvent

deliver DataEvent to each handler deliver DataEvent
parse and set PCRW properties
set TrackXData properties
printWrite(kind, hposition, vposition, data)

printWrite(kind, hposition, vposition, data)
OutputID++
new
enqueue OCE to service's internal queue
copy data to OCE
deliver OutputCompleteEvent
deliver OutputCompleteEvent to each handler
beginRemoval(timeout)
endRemoval()
endRemoval()

Point Card Reader Writer State Diagram

Close()
Close() Claim()
Open() Release()
DataEventEn
abled==true
Release()
&
error ClearInput()
SetDeviceEnable(true)
SetDeviceEnable(false)
Clearinput
[DeviceEnable==true,and,Card out] Processing
Enable
ClearInput()
BeginRemoval()[Card in]
BeginInsertion()
EndInsertion()
Card Inserting Ejected Mode
EndRemoval()
Insert Card Eject Card
Eject Card
Input
EndInsertion() Card in PointCard R/W BeginRemoval()

DataEventEnabled==true
&
error
ErrorEvent ClearInput()
Queuing
DataEvent
&
error
PrintWrite()
Writing and Printing Mode
Setting
Outputdata
&
error OutputCompleteEvent
Write and Print Mode
Write and Print

ErrorEvent
&
error

CapBold Property
Syntax CapBold: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can print bold characters, false if it
cannot.
CapCardEntranceSensor Property
Syntax CapCardEntranceSensor: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer has an entrance sensor, false if it does
not.
CapCharacterSet Property
Remarks Holds the default character set capability. It may be one of the following:
Value Meaning
PCRW_CCS_ALPHA The default character set supports upper case

alphabetic plus numeric, space, minus, and period.
PCRW_CCS_ASCII The default character set supports all ASCII
characters between 20-hex and 7F-hex.
PCRW_CCS_KANA The default character set supports partial code page
932, including ASCII characters 20-hex through 7F-
hex and the Japanese Kana characters A1-hex through
DF-hex, but excluding the Japanese Kanji characters.
PCRW_CCS_KANJI The default character set supports code page 932,
including the Shift-JIS Kanji characters, Levels 1 and
2.
PCRW_CCS_UNICODE The default character set supports Unicode.

CapCleanCard Property
Syntax CapCleanCard: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer supports cleaning under application
control, false if it does not.
CapClearPrint Property
Syntax CapClearPrint: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer supports clearing (erasing) the printing
area, false if it does not.
CapDhigh Property
Syntax CapDhigh: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can print double high characters, false
if it cannot.
CapDwide Property
Syntax CapDwide: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can print double wide characters, false
if it cannot.

CapDwideDhigh Property
Syntax CapDwideDhigh: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can print double high / double wide
characters, false if it cannot.
CapItalic Property
Syntax CapItalic: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can print italic characters, false if it
cannot.
CapLeft90 Property
Syntax CapLeft90: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can print in rotated 90° left mode, false
if it cannot.

selected character set when printing data.
Property.

CapPrint Property
Syntax CapPrint: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer has printing capability; false if it does
not.
CapPrintMode Property
Syntax CapPrintMode: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can designate a printing start position
with the MapMode property, false if it cannot.
CapRight90 Property
Syntax CapRight90: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can print in a rotated 90° right mode,
false if it cannot.
CapRotate180 Property
Syntax CapRotate180: boolean { read-only, access after open }
Remarks If true, then the Point Card Reader Writer can print in a rotated upside down mode,
false if it cannot.

CapTracksToRead Property
Syntax CapTracksToRead: int32 { read-only, access after open }
Remarks A bitmask indicating which magnetic tracks are accessible on the inserted point
card. The value contained in this property is a bitwise OR of the constants
PCRW_TRACK1 through PCRW_TRACK6.
For example, access to track 1 is possible when PCRW_TRACK1 is set.
Value Meaning
PCRW_TRACK1 Track1
PCRW_TRACK2 Track2
PCRW_TRACK3 Track3
PCRW_TRACK4 Track4
PCRW_TRACK5 Track5
PCRW_TRACK6 Track6
CapTracksToWrite Property
Syntax CapTracksToWrite: int32 { read-only, access after open }
Remarks A bitmask indicating which magnetic tracks are writable on the inserted point
card. The value contained in this property is a bitwise OR of the constants
PCRW_TRACK1 through PCRW_TRACK6.
For example, access to track 1 is possible when PCRW_TRACK1 is set.
Value Meaning
PCRW_TRACK1 Track1
PCRW_TRACK2 Track2
PCRW_TRACK3 Track3
PCRW_TRACK4 Track4
PCRW_TRACK5 Track5
PCRW_TRACK6 Track6

CardState Property
Syntax CardState: int32 { read-only, access after open }
Remarks If CapCardEntranceSensor is true, the current card entrance sensor status is
stored in this property. The value will be one of the following.
Value Meaning
PCRW_STATE_NOCARD No card or card sensor position indeterminate

PCRW_STATE_REMAINING Card remaining at the entrance
PCRW_STATE_INRW There is a card in the device
If CapCardEntranceSensor is false, then CardState will always be set to
PCRW_STATE_NOCARD.
See Also CapCardEntranceSensor Property.


Remarks The character set for printing characters.
Value Meaning
PCRW_CS_UNICODE The character set supports Unicode. The value of this
constant is 997.
PCRW_CS_ASCII The ASCII character set, supporting the ASCII
characters between 0x20 and 0x7F. The value of this
constant is 998.
PCRW_CS_ANSI The ANSI character set. The value of this constant is
999.

method.
Value Meaning
E_ILLEGAL An invalid property value was specified.

See Also CharacterSetList Property.
Remarks Holds the string of character set numbers. The string consists of an ASCII numeric
set numbers separated by commas.
For example, if the string is “101,850,999”, then the device supports a device

FontTypefaceList Property
Syntax FontTypefaceList: string { read-only, access after open }
Remarks A string that specifies the fonts and/or typefaces that are supported by the Point
Card Reader Writer.
The string consists of font or typeface names separated by commas. The
application selects a font or typeface for the Point Card Reader Writer by using the
font typeface selection escape sequence (ESC |#fT). The “#” character is replaced
by the number of the font or typeface within the list: 1, 2, and so on.
In Japan, this property will frequently include the fonts “Mincho” and “Gothic”.
Other fonts or typefaces may be commonly supported in other countries.
An empty string indicates that only the default typeface is supported.
See Also “Data Characters and Escape Sequences” on page 877.
LineChars Property
Syntax LineChars: int32 { read-write, access after open-claim-enable }
Remarks The number of characters that may be printed on a line on the Point Card Reader
Writer.
If changed to a line character width that can be supported, then the width is set to
the specified value. If the exact width cannot be supported, then subsequent lines
will be printed with a character size that most closely supports the specified
characters per line. (For example, if set to 36 and the Point Card Reader Writer can
print either 30 or 40 characters per line, then the Service should select the character
size “40” and print up to 36 characters on each line.)
If the character width cannot be supported, then an exception is thrown. (For
example, if set to 42 and Point Card Reader Writer can print either 30 or 40
characters per line, then the Service cannot support the request.)
Setting LineChars may also update LineWidth, LineHeight, and LineSpacing,
since the character pitch or font may be changed.
The value of LineChars is initialized to the Point Card Reader Writer’s default
line character width when the device is first enabled following the open method.
Value Meaning
E_ILLEGAL An invalid line character width was specified.

See Also LineCharsList Property.

LineCharsList Property
Syntax LineCharsList: string { read-only, access after open }
Remarks A string containing the line character widths supported by the Point Card Reader
Writer.
The string consists of an ASCII numeric set numbers separated by commas. For
example, if the string is “32,36,40”, then the station supports line widths of 32, 36,
and 40 characters.
See Also LineChars Property.
LineHeight Property
Syntax LineHeight: int32 { read-write, access after open-claim-enable }
Remarks The Point Card Reader Writer print line height. If CapPrintMode is true, this is
expressed in the unit of measure given by MapMode.
If changed to a height that can be supported with the current character width, then
the line height is set to this value. If the exact height cannot be supported, then the
height is set to the closest supported value.
When LineChars is changed, LineHeight is updated to the default line height for
the selected width.
The value of LineHeight is initialized to the Point Card Reader Writer’s default
line height when the device is first enabled following the open method.
LineSpacing Property
Syntax LineSpacing: int32 { read-write, access after open-claim-enable }
Remarks The spacing of each single-high print line, including both the printed line height
plus the white space between each pair of lines. Depending upon the Point Card
Reader Writer and the current line spacing, a multi-high print line might exceed
this value. If CapPrintMode is true, line spacing is expressed in the unit of
measure given by MapMode.
If changed to a spacing that can be supported by the Point Card Reader Writer, then
the line spacing is set to this value. If the spacing cannot be supported, then the
spacing is set to the closest supported value.
When LineChars or LineHeight is changed, LineSpacing is updated to the
default line spacing for the selected width or height.
The value of LineSpacing is initialized to the Point Card Reader Writer’s default
line spacing when the device is first enabled following the open method.

LineWidth Property
Syntax LineWidth: int32 { read-only, access after open-claim-enable }
Remarks The width of a line of LineChars characters. If CapPrintMode is true, expressed
in the unit of measure given by MapMode.
Setting LineChars may also update LineWidth.
The value of LineWidth is initialized to the Point Card Reader Writer’s default
line width when the device is first enabled following the open method.
CharacterSet property for printing data.
MapMode Property
Syntax MapMode: int32 { read-write, access after open-claim-enable }
Remarks Contains the mapping mode of the Point Card Reader Writer. The mapping mode
defines the unit of measure used for other properties, such as line heights and line
spacings. The following map modes are supported:
Value Meaning
PCRW_MM_DOTS The Point Card Reader Writer’s dot width. This
width may be different for each Point Card Reader
Writer.
PCRW_MM_TWIPS 1/1440 of an inch.
PCRW_MM_ENGLISH 0.001 inch.
PCRW_MM_METRIC 0.01 millimeter.
Setting MapMode may also change LineHeight, LineSpacing, and LineWidth.
The value of MapMode is initialized to PCRW_MM_DOTS when the device is
Value Meaning
E_ILLEGAL An invalid mapping mode value was specified.

MaxLine Property
Syntax MaxLine: int32 { read-only, access after open-claim-enable }
Remarks When the CapPrintMode property is false, MaxLine contains the maximum
printable line number.
In the case where there is a double-high character in the same line, this is
dependent upon the capability of the device.
When the LineHeight property and/or the LineSpacing property change, the
MaxLine property may be changed.
See Also LineHeight Property.
PrintHeight Property
Syntax PrintHeight: int32 { read-only, access after open-claim-enable }
Remarks When the CapPrintMode property is true, the height of the largest character in the
character set is stored in this property expressed in MapMode units.
When the MapMode property is changed the value of the PrintHeight property
changes.
See Also CapPrintMode Property, MapMode Property.

ReadState1 Property
Syntax ReadState1: int32 { read-only, access after open }
Remarks The property is divided into four bytes with each byte containing status
information about the first four tracks. The diagram below indicates how the
property value is divided:
The Control sets a value to this property immediately before it enqueues the
ErrorEvent or DataEvent.
High Word Low Word
Track4 Track 3 Track 2 Track 1
The following values can be set:

Value Meaning
SUCCESS Successful read of the data.

EPCRW_START It is a start sentinel error.
EPCRW_END It is a end sentinel error.
EPCRW_PARITY It is a parity error.
EPCRW_ENCODE There is no encoding.
EPCRW_LRC It is a LRC error.
EPCRW_VERIFY It is a verify error.
E_FAILURE It is other error.
See Also ReadState2 Property.

ReadState2 Property
Syntax ReadState2: int32 { read-only, access after open }
Remarks The property is divided into four bytes with two bytes containing status
information about the fifth and sixth tracks. The diagram below indicates how the
property value is divided:
The Point Card Reader Writer sets a value to this property immediately before it
enqueues the ErrorEvent or DataEvent.
High Word Low Word
Unused Unused Track 6 Track 5
The following values can be set.

Value Meaning
SUCCESS Successful read of the data.

EPCRW_ENCODE There is no encoding.
See Also ReadState1 Property.

RecvLength1 Property
Syntax RecvLength1: int32 { read-only, access after open-claim-enable }
Remarks The property is divided into four bytes with each of the bytes representing
information about the first four tracks. The diagram below indicates how the value
is divided:
High Word Low Word
having a read head for the track, or STX, ETX and LRC only was obtained from
the swipe for that particular track, or reading of data without being made with
some errors, or perhaps the application intentionally precluded incoming data from
the track via the TracksToRead property.
TrackxData property.
See Also CapTracksToRead property, TracksToRead property, RecvLength2 Property.
RecvLength2 Property
Syntax RecvLength2: int32 { read-only, access after open-claim-enable }
Remarks The property is divided into four bytes with two of the bytes representing
information about the fifth and sixth tracks, while the third and fourth bytes are
unused. The diagram below indicates how the value is divided:
High Word Low Word
having a read head for the track, or STX, ETX, and LRC only was obtained from
the swipe for that particular track, or reading of data without being made with
some errors, or perhaps the application intentionally precluded incoming data from
the track via the TracksToRead property.
TrackxData property.
See Also CapTracksToRead property, TracksToRead property, RecvLength1 Property.

SidewaysMaxChars Property
Syntax SidewaysMaxChars: int32 { read-only, access after open-claim-enable }
Remarks Holds the maximum number of characters that may be printed on each line in
sideways mode.
If the capabilities CapLeft90 and CapRight90 are both false, then
SidewaysMaxChars is zero.
Changing the properties LineHeight, LineSpacing, and LineChars may cause
this property to change.
method.
See Also SidewaysMaxLines Property.
SidewaysMaxLines Property
Syntax SidewaysMaxLines: int32 { read-only, access after open-claim-enable }
Remarks Holds the maximum number of lines that may be printed in sideways mode.
If the capabilities CapLeft90 and CapRight90 are both false, then
SidewaysMaxLines is zero.
Changing the properties LineHeight, LineSpacing, and LineChars may cause
this property to change.
method.
See Also SidewaysMaxChars Property.

TracksToRead Property
Syntax TracksToRead: int32 { read-write, access after open-claim-enable }
Remarks Holds the tracks that are to be read from the point card. It contains a bitwise OR
of the constants PCRW_TRACK1 through PCRW_TRACK6. It may only contain
values that are marked as allowable by the CapTracksToRead property. For
example, to read tracks 1, 2, and 3, this property should be set to:
PCRW_TRACK1 | PCRW_TRACK2 | PCRW_TRACK3.
method.
Value Meaning
E_BUSY This operation cannot be performed because

asynchronous output is in progress.
E_ILLEGAL An illegal track was defined. The track is not
available for reading. Refer to CapTracksToRead.
See Also CapTracksToRead Property.
TracksToWrite Property
Syntax TracksToWrite: int32 { read-write, access after open-claim-enable }
Remarks Holds the tracks that are to be written to the point card. It contains a bitwise OR of
the constants PCRW_TRACK1 through PCRW_TRACK6. It may only contain
values that are marked as allowable by the CapTracksToWrite property. For
example, to write tracks 1, 2, and 3, this property should be set to:
PCRW_TRACK1 | PCRW_TRACK2 | PCRW_TRACK3.
method.
Value Meaning

E_ILLEGAL An illegal track was defined. The track is not
available for writing. Refer to CapTracksToWrite.
See Also CapTracksToWrite Property, printWrite Method.

Track1Data Property
Remarks Contains the track 1 data from the point card.
This property contains track data between but not including the start and end
sentinels.
An empty string indicates that the track was not accessible.
Track2Data Property
sentinels.
Track3Data Property
sentinels.
Track4Data Property
sentinels.

Track5Data Property
sentinels.
Track6Data Property
sentinels.

WriteState1 Property
Syntax WriteState1: int32 { read-only, access after open }
information about the first four tracks. The diagram below indicates how the
property is divided:
ErrorEvent.
High Word Low Word
The following value is set.

Value Meaning
SUCCESS Successful write of the data.

EPCRW_ENCODE There is not encoding.
See Also WriteState2 Property.

WriteState2 Property
Syntax WriteState2: int32 { read-only, access after open }
information about the fifth and sixth tracks. The diagram below indicates how the
property is divided:
ErrorEvent.
High Word Low Word
The following value is set.

Value Meaning
SUCCESS Successful write of the data.
EPCRW_ENCODE There is not encoding.
See Also WriteState1 Property.
Write1Data Property
Syntax Write1Data: binary { read-write, access after open }
Remarks The printWrite method writes this data to track 1 of a point card.
sentinels.

Write2Data Property
sentinels.
Write3Data Property
sentinels.
Write4Data Property
sentinels.
Write5Data Property
sentinels.
Write6Data Property
sentinels.


timeout The number of milliseconds before failing the method
If zero, the method initiates insertion mode and either returns immediately if
successful, or raises an exception. If FOREVER (-1), the method initiates the
begin insertion mode, then waits as long as needed until either the point card is
Remarks Called to initiate point card insertion processing.
When called, Point Card Reader Writer state is changed to allow the insertion of a
point card and the point card insertion mode is entered. This method is paired with
the endInsertion method for controlling point card insertion.
If the Point Card Reader Writer device cannot be placed into insertion mode an
exception is raised. Otherwise, the Control continues to monitor point card
insertion until either the point card is not inserted before timeout milliseconds have
elapsed, or an error is reported by the Point Card Reader Writer device. In the latter
case, the Control raises an exception with the appropriate error code. The Point
Card Reader Writer device remains in point card insertion mode. This allows an
application to perform some user interaction and reissue the beginInsertion
method without altering the point card handling mechanism.
Value Meaning

E_ILLEGAL The Point Card Reader Writer does not exist or an
invalid timeout parameter was specified.
E_TIMEOUT The specified time has elapsed without the point
card being properly inserted.
E_EXTENDED Refer to the definitions for ErrorCodeExtended in
the Events section “ErrorEvent” on page 911.

beginRemoval Method
If zero, the method initiates the begin removal mode and either returns
immediately or raises an exception. If FOREVER (-1), the method initiates the
begin removal mode, then waits as long as needed until either the form is removed
or an error occurs.
Remarks Called to initiate point card removal processing.
When called, the Point Card Reader Writer is made ready to eject a point card or
activating a point card ejection mode. This method is paired with the endRemoval
method for controlling point card removal.
The model that has the sensor in the entrance ends normally when a card is ejected
from Point Card Reader Writer. The model without the sensor ends normally when
that ejection processing is implemented.
If the Point Card Reader Writer cannot be placed into removal or ejection mode,
an exception is raised. Otherwise, the Control continues to monitor point card
removal until either the point card is not ejected before timeout milliseconds have
elapsed, or an error is reported by the Point Card Reader Writer. In this case, the
Control raises an exception with the appropriate error code. The Point Card Reader
Writer remains in point card ejection mode. This allows an application to perform
some user interaction and reissue the beginRemoval method without altering the
point card handling mechanism.
Value Meaning

E_ILLEGAL The Point Card Reader Writer does not exist or an
invalid timeout parameter was specified.
E_TIMEOUT The specified time has elapsed without the point
See Also CapCardEntranceSensor Property, CardState Property, beginInsertion
Method, endInsertion Method, endRemoval Method.

cleanCard Method
Syntax cleanCard( ):
Remarks This method is used to clean the read/write heads of the Point Card Reader Writer.
This method is only supported if the CapCleanCard property is true.
Value Meaning
E_ILLEGAL The Point Card Reader Writer does not exist or

CapCleanCard is false.
See Also CapCleanCard Property.

clearPrintWrite Method
Syntax clearPrintWrite ( kind: int32, hposition: int32, vposition: int32, width: int32,
height: int32 ):
kind Defines the parts of the point card that will be cleared.
1: Printing area
2: Magnetic tracks
3: Both printing area and magnetic tracks
hposition The horizontal start position for erasing the printing area.
The value is in MapMode units if CapPrintMode is true.
vposition The vertical start position for erasing the printing area. The
value is in MapMode units if CapPrintMode is true.
width The width used for erasing the printing area. The value is in
MapMode units if CapPrintMode is true.
height The height used for erasing the printing area. The value is in
Remarks Used to erase the printing area of a point card and/or erase the magnetic track data
on a point card.
When the CapPrint and CapClearPrint properties are both true, this method can
be used to clear the printing area of a point card. The hposition, vposition, width,
and height parameters define the rectangle that will be cleared. If these
parameters are 0, 0, -1, -1 respectively, this method will erase the entire printing
area.
The initialization of the magnetic track data relies upon the capability of the
device.
Value Meaning

See Also CapClearPrint Property, CapPrint Property, CapPrintMode Property,
MapMode Property.

endInsertion Method
Remarks Called to end point card insertion processing.
When called, the Point Card Reader Writer is taken out of point card insertion
mode. If no point card is present, an exception is raised.
This method is paired with the beginInsertion method for controlling point card
insertion.
Value Meaning
E_ILLEGAL The Point Card Reader Writer is not in point card

insertion mode.
E_FAILURE A card is not inserted in the Point Card Reader
Writer.
endRemoval Method
Remarks Called to end point card removal processing.
When called, the Point Card Reader Writer is taken out of point card removal or
ejection mode. If a point card is present, an exception is raised. This method is
paired with the beginRemoval method for controlling point card removal.
The application may choose to call this method immediately after a successful
beginRemoval if it wants to use the Point Card Reader Writer sensors to deter-
mine when the point card has been ejected. Alternatively, the application may
prompt the user and wait for a key being pressed before calling this method.
Value Meaning
E_ILLEGAL The Point Card Reader Writer is not in point card
removal mode.
E_FAILURE There is a card in the Point Card Reader Writer.

printWrite Method Updated in Release 1.7

Syntax printWrite ( kind: int32, hposition: int32, vposition: int32, data: string ):
kind Designates the effect of the point card.

1: Print 2: Write 3: Print+Write
hposition The horizontal start position for printing. The value is in
vposition The vertical start position for printing. The value is in
data1 The data to be printed. Any escape sequences in the data
are dependent upon the capabilities of the device.
Remarks This method will either print the specified data on the printing area of the point
card, write data from the WriteXData properties to the magnetic tracks, or both.
In order to print on a point card, the CapPrint property must be true. In order to
write the magnetic tracks on a point card, the WriteXData properties for each
desired track must be set to the desired value, the TracksToWrite property must
be set to a bitmask indicating which tracks to write (see TracksToWrite for a
complete description) and the CapTracksToWrite property must indicate that
each tracks specified in TracksToWrite is legal.
Value Meaning
E_ILLEGAL There is no card in the Point Card Reader Writer.

See Also CapPrint Property, CapPrintMode Property, CapTracksToWrite Property,
MapMode Property, TracksToWrite Property, WriteXData Property.

rotatePrint Method
Syntax rotatePrint ( rotation: int32 ):
rotation Direction of rotation. See values below.

Value Meaning
PCRW_RP_RIGHT90 Rotate printing 90º to the right (clockwise).
PCRW_RP_LEFT90 Rotate printing 90º to the left (counter-clockwise).
PCRW_RP_ROTATE180 Rotate printing 180º, that is print upside-down.
PCRW_RP_NORMAL End rotated printing.

Remarks Enters or exits rotated print mode.
The rotatePrint method designates the rotation of the printing area. After calling
this method, the application calls the printWrite method and the print data is
printed in the direction specified by the rotatePrint call. If rotation is
PCRW_RP_NORMAL, then rotated print mode is exited.
Changing the rotation mode may also change the Point Card Reader Writer’s line
height, line spacing, line width, and other metrics.
Value Meaning

E_ILLEGAL The Point Card Reader Writer does not support the
specified rotation.
See Also “Data Characters and Escape Sequences” on page 877, printWrite Method.

validateData Method Updated in Release 1.7

Syntax validateData ( data: string ):
data2 The data to be validated. May include printable data and
escape sequences.
Remarks Called to determine whether a data sequence, possibly including one or more
escape sequences, is valid for printing, prior to calling the printWrite method.
This method does not cause any printing, but is used to determine the capabilities
of the Point Card Reader Writer.
Value Meaning
E_ILLEGAL Some of the data is not precisely supported by the
device, but the Control can select valid alternatives.
E_FAILURE Some of the data is not supported. No alternatives can be
selected.
Cases which cause ErrorCode of E_ILLEGAL:
Escape Sequence Condition
Underline The thickness ‘#’ is not precisely supported: Control
will select the closest supported value.
Shading The percentage ‘#’ is not precisely supported: Control
Scale horizontally The scaling factor ‘#’ is not supported. Control will
select the closest supported value.
Scale vertically The scaling factor ‘#’ is not supported. Control will
Cases which will cause E_FAILURE to be returned are:
(General) The escape sequence format is not valid
Font typeface The typeface ‘#’ is not supported:
Bold Not supported.
Underline Not supported.
Italic Not supported.
Reverse video Not supported.
Single high and wide Not supported.
Double wide Not supported.
Double high Not supported.
Double high and wide Not supported.
See Also “Data Characters and Escape Sequences” on page 877, printWrite Method.


DataEvent
Description Fired to present input data from the device to the application.

Remarks The point card data is placed in each property before this event is delivered.
DirectIOEvent
means for a vendor-specific PointCard Service to provide events to the application
Service.
from being used with other vendor’s point card devices which may not have any


Description Notifies the application that a PointCard error has been detected and a suitable
Codes on page 52.
ErrorCodeExtended
values below.
following values:
Value Meaning
EPCRW_READ There was a read error.
EPCRW_WRITE There was a write error.
EPCRW_JAM There was a card jam.
EPCRW_MOTOR There was a conveyance motor error.
EPCRW_COVER The conveyance motor cover was open.
EPCRW_PRINTER The printer has an error.
EPCRW_RELEASE There is a card remaining in the entrance.
EPCRW_DISPLAY There was a display indicator error.
EPCRW_NOCARD There is no card in the reader.

Value Meaning
available.
available.

Value Meaning

EL_INPUT_DATA.
Remarks Input error events are generated when errors occur while reading the magnetic
track data from a newly inserted card. These error events are not delivered until
the DataEventEnabled property is set to true so as to allow proper application
sequencing. All error information is placed into the ReadStateX properties before
this event is delivered. The RecvLengthX property is set to 0 for each track that
had an error and the TrackXData property is set to empty for each track that had
an error.
asynchronous printWrite processing. The errors are placed into the WriteStateX
properties before the event is delivered.
See Also ReadStatex Property, RecvLengthx Property, TrackxData Property,
WriteStatex Property.

OutputCompleteEvent

is complete.
StatusUpdateEvent
Description Notifies the application that there is a change in the status of the PointCard device.
Status int32 Indicates a change in the status of the PointCard device.
Value Meaning
PCRW_SUE_NOCARD No card or card sensor position indeterminate.
PCRW_SUE_REMAINING Card remaining in the entrance.
PCRW_SUE_INRW There is a card in the device.
process.
Remarks Fired when the entrance sensor status of the Point Card Reader Writer changes. If
the capability CapCardEntranceSensor is false, then the device does not
support status reporting, and this event will never be fired to report card insertion
state changes.
See Also “Events” on page 51, CapCardEntranceSensor Property.


C H A P T E R 2 8
POS Keyboard
This Chapter defines the POS Keyboard device category.
Summary

916 POS Keyboard
CapKeyUp: boolean { read-only } 1.2 open
EventTypes: int32 { read-write } 1.2 open
POSKeyData: int32 { read-only } 1.1 open
POSKeyEventType: int32 { read-only } 1.2 open

Common
Name Version
close ( ): 1.1
release ( ): 1.1
clearInput ( ): 1.1
void { } supporteda
void { } supported
Specific
None
a. Only a single key value is stored at any one time.

Summary 917


918 POS Keyboard
General Information
The POS Keyboard programmatic name is “POSKeyboard”.
Capabilities
The POS Keyboard has the following capability:

• Reads keys from a POS keyboard. A POS keyboard may be an auxiliary
keyboard, or it may be a virtual keyboard consisting of some or all of the keys
on the system keyboard.
POS Keyboard Class Diagram
The following diagram shows the relationships between the POS Keyboard
classes.
<<event>> <<exception>> <<Interface>> <<utility>>

UposException <<sends>> <<uses>>
DataEvent BaseControl UposConst
(from events) (from upos) (from upos) (from upos)
fires
<<event >> <<sends>> <<utility>>
DirectIOEvent POS KeyboardConst
<<prop>> EventNumber : int32 <<Interfac e>> <<uses>>
fires
<<prop>> Data : int32 POSKeyboardControl
<<prop>> Obj : object (from upos)
<<capability>> CapKeyUp : boolean
<<prop>> EventTypes : int32
<<prop>> POSKeyData : int32
fires <<prop>> POSKeyEventType : int32
<<event >>
ErrorEvent
(from events)
<<prop>> ErrorLocus : int32 fires
<<event>>
StatusUpdateEvent
(from events)

POS Keyboard Sequence Diagram Updated in Release 1.8

The following sequence diagram shows the typical usage of the POS Keyboard
device.
NOTE: we are assuming that the :ClientApp already successfully registered event handlers and opened, claimed
and enabled the POSKeyboard device. This means that the Claimed, DeviceEnabled properties are == true
:ClientApp :POSKeyboard :DataEvent :POSKeyboardService
1: setDataEventEnabled(true) : Operator
4: new 3: key pressed
5: copy data info and enqueue DataEvent for delivery
6: DataCount++
7: key pressed
8: new
9: copy data info and enqueue DataEvent for delivery
10: DataCount++
Depending on how fast the :Operator presses key, it might be that DataEvent
are delivered as soon as enqueued (but conceptually this detail is not important)
At this point the
:ClientApp event 11: deliver each DataEvent to control [DataEventEnabled == true && FreezeEvents == false]
handler code executes
12: deliver DataEvents to all registered handlers delivered set DataEventEnabled
to false and DataCount--.
14: clearInput()
15: clearInput()
16: all enqueued DataEvent are cleared from queue
17: DataCount is set to 0

920 POS Keyboard
Model
The POS Keyboard follows the general “Device Input Model” for input devices:
• When input is received from the POS Keyboard a DataEvent is enqueued.
• If the AutoDisable property is true, then the Device automatically disables
itself when a DataEvent is enqueued.
• A queued DataEvent can be delivered to the application when the
met. Just before firing this event, data is copied into the properties, and further
current input and associated properties. When the application has finished the
current input and is ready for more data, it reenables events by setting
DataEvents.
• All queued input may be deleted by calling clearInput.
Keyboard Translation
The POS Keyboard Control must supply a mechanism for translating its internal
key codes into user-defined codes which are returned by the DataEvents. Note
that this translation must be end-user configurable.
Device Sharing
The POS keyboard is an exclusive-use device, as follows:

reading input.

CapKeyUp Property
Syntax CapKeyUp: boolean { read-only, access after open }
Remarks If true, then the device is able to generate both key down and key up events,
depending upon the setting of the EventTypes. If false, then the device is only able
to generate the key down event.
See Also EventTypes Property.
EventTypes Property
Syntax EventTypes: int32 { read-write, access after open }
Remarks Holds the type of events that the application wants to receive. It has one of the
following values:
Value Meaning
KBD_ET_DOWN Generate key down events.

KBD_ET_DOWN_UP Generate key down and key up events.
This property is initialized to KBD_ET_DOWN by the open method.
POSKeyData Property
Syntax POSKeyData: int32 { read-only, access after open }
Remarks Holds the value of the key from the last DataEvent. The application may treat this
value as device independent, assuming that the system installer has configured the
Service to translate internal key codes to the codes expected by the application.
Such configuration is inherently Service-specific.
This property is set just before delivering the DataEvent.
See Also DataEvent.

922 POS Keyboard
POSKeyEventType Property
Syntax POSKeyEventType: int32 { read-only, access after open }
Remarks Holds the type of the last keyboard event: Is the key being pressed or released? It
has one of the following values:
Value Meaning
KBD_KET_KEYDOWN The key in POSKeyData was pressed.

KBD_KET_KEYUP The key in POSKeyData was released.
This property is set just before delivering the DataEvent.
See Also POSKeyData Property, DataEvent.

DataEvent
Description Notifies the application that input data is available from the POS Keyboard device.

Status int32 Contains zero.

Remarks The logical key number is placed in the POSKeyData property and the event type
is placed in the POSKeyEventType property before this event is delivered.
See Also POSKeyData Property, POSKeyEventType Property, “Events” on page 51
DirectIOEvent
means for a vendor-specific POS Keyboard Service to provide events to the
Service.
from being used with other vendor’s POS Keyboard devices which may not have

924 POS Keyboard

Description Notifies the application that an error was detected trying to read POS Keyboard
data.
ErrorCode int32 Error Code causing the error event. See list of
ErrorCodeExtended int32 Extended Error Code causing the error event. It
may contain a Service-specific value.
ErrorResponse int32 Error response, whose default value may be
overridden by the application (i.e., this property
is settable). See values below.
Value Meaning
available.
available.
Value Meaning
EL_INPUT.

Remarks Enqueued when an error is detected while trying to read POS Keyboard data. This
event is not delivered until DataEventEnabled is true, so that proper application
sequencing occurs.
page 62
StatusUpdateEvent
Description Notifies the application when the working status of the POS Keyboard changes.

Status int32 The status reported from the POS Keyboard.
process.
Remarks Enqueued when the POS Keyboard needs to alert the application of a device state
change.
See Also “Events” on page 51

926 POS Keyboard

C H A P T E R 2 9
POS Power
This Chapter defines the POS Power device category.
Summary


928 POS Power
BatteryCapacityRemaining: int32 { read-only } 1.9 open
BatteryCriticallyLowThreshold: int32 { read-write } 1.9 open
BatteryLowThreshold: int32 { read-write } 1.9 open
CapBatteryCapacityRemaining: boolean { read-only } 1.9 open
CapFanAlarm: boolean { read-only } 1.5 open
CapHeatAlarm: boolean { read-only } 1.5 open
CapQuickCharge: boolean { read-only } 1.5 open
CapRestartPOS: boolean { read-only } 1.9 open
CapShutdownPOS: boolean { read-only } 1.5 open
CapStandbyPOS: boolean { read-only } 1.9 open
CapSuspendPOS: boolean { read-only } 1.9 open
CapUPSChargeState: int32 { read-only } 1.5 open
CapVariableBatteryCriticallyLowThreshold: boolean { read-only } 1.9 open
CapVariableBatteryLowThreshold: boolean { read-only } 1.9 open
EnforcedShutdownDelayTime: int32 { read-write } 1.5 open
PowerFailDelayTime: int32 { read-only } 1.5 open
PowerSource: int32 { read-only } 1.9 open
QuickChargeMode: boolean { read-only } 1.5 open
QuickChargeTime: int32 { read-only } 1.5 open
UPSChargeState: int32 { read-only } 1.5 open & enable

Common
Name Version
close ( ): 1.5
release ( ): 1.5
clearInput ( ): Not
void { } supported
void { } supported

Summary 929
void { } supported
Specific
Name
restartPOS ( ): 1.9
shutdownPOS ( ): 1.5
standbyPOS (reason: int32 ): 1.9
suspendPOS (reason: int32 ): 1.9


930 POS Power
General Information Updated in Release 1.9
The POS Power programmatic name is “POSPower”.
Capabilities
The POSPower device class has the following capabilities:

• Supports a command to “shut down” the system.
• Supports a command to restart the system.
• Supports a command to “suspend” the system.
• Supports a command to have the system go to standby.
• Supports accessing a power handling mechanism of the underlying operating
system and hardware.
• Informs the application if a power fail situation has occurred.
• Informs the application about battery level.
• Informs the application if the UPS charge state has changed.
• Informs the application about high CPU temperature.
• Informs the application about stopped CPU fan.
• Informs the application if an operating system dependent enforced shutdown
mechanism is processed.
• Allows the application after saving application data locally or transferring
application data to a server to shut down the POS terminal.
• Informs the application about an initiated shutdown.
Device Sharing
The POSPower is a sharable device. Its device sharing rules are:

• If more than one application has opened and enabled the device, all
fired to all of the applications.
• If one application claims the POSPower, then only that application may call
the shutdownPOS, standbyPOS, or suspendPOS methods. This feature
provides a degree of security, such that these methods may effectively be
restricted to the main POS application if that application claims the device at
startup.

The general model of POSPower is based on the power model of each device in
version 1.3 or later. The same common properties are used but all states relate to
the POS terminal itself and not to a peripheral device.
There are three states of the POSPower:
• ONLINE. The POS terminal is powered on and ready for use. This is the
• OFF. The POS terminal is powered off or detached from the power supplying
net. The POS terminal runs on battery power support. This is the powerfail
situation.
• OFFLINE. The POS terminal is powered on but is running in a “lower-power-
consumption” mode. It may need to be placed online by pressing a button or
key or something else which may wake up the system.
Power reporting only occurs while the device is open, enabled and power
notification is switched on.
In a powerfail situation - that means the POSPower is in the state OFF - the POS
terminal will be shut down automatically after the last application has closed the
POSPower device or the time specified by the EnforcedShutdownDelayTime
property has been elapsed.
A call to the shutdownPOS method will always shut down the POS terminal
independent of the system power state.
Version 1.9 or later
Support of battery powered devices is added. In addition to adding properties to
report battery levels and power sources, properties are added to allow for the
setting of low and critically low battery levels. The POSPower device also
includes the ability to request or respond to request to enter the standby and
suspend states. The model does not attempt to duplicate other power management
models such as APM and ACPI, but leaves those implementation details to the
provider. As a rule, the suspend state will consume less power than the standby
state, which in turn will consume less power than the on state. A suggested
mapping of these states to other power management models is:
State ACPI APM Description

On S0 ON Active, Powered On
Displays and drives off, CPU,
Standby S1 SUSPEND
RAM and fans powered on
Suspend S3 SUSPEND Only RAM powered
Off S5 OFF Completely powered off

932 POS Power
POSPower Class Diagram Updated in Release 1.10

The following diagram shows the relationships between the POSPower classes.
<<utility>>
POSPowerConst
(f rom upos) <<utility>>
PWR_UPS_FULL : int32 {frozen} UposConst
(f rom upos)
PWR_UPS_LOW : int32 {frozen}
<<uses>>
PWR_UPS_CRITICAL : in32 {frozen}
PWR_UPS_WARING : int32 {frozen}
PWR_SUE_UPS_FULL : int32 {frozen}
PWR_SUE_UPS_LOW : int32 {frozen}
PWR_SUE_UPS_CRITICAL : in32 {frozen} <<Interface>>
PWR_SUE_UPS_WARING : int32 {frozen} BaseControl
PWR_SUE_FAN_STOPPED : int32 {frozen} (from upos)
PWR_SUE_FAN_RUNNING : int32 {frozen}
PWR_SUE_TEMPERATURE_HIGH : int32 {frozen}
PWR_SUE_TEMPERATURE_OK : int32 {frozen} <<sends>>
PWR_SUE_SHUTDOWN : int32 {frozen}
PWR_SOURCE_NA : int32 {frozen}
PWR_SOURCE_AC : int32 {frozen} <<uses>>
PWR_SOURCE_BATTERY : int32 {frozen} <<exception>>
PWR_SOURCE_BACKUP : int32 {frozen} UposException
(f rom upos)
PWR_SUE_BAT_LOW : int32 {frozen}
PWR_SUE_BAT_CRITICAL : in32 {frozen}
PWR_SUE_BAT_CAPACITY_REMAINING : in32 {frozen}
PWR_SUE_RESTART : int32 {frozen}
PWR_SUE_STANDBY : int32 {frozen}
PWR_SUE_USER_STANDBY : int32 {frozen} <<sends>>
PWR_SUE_SUSPEND : int32 {frozen}
PWR_SUE_USER_SUSPEND : int32 {frozen}
PWR_SUE_POWER_SOURCE : int32 {frozen}
<<uses>>
<<event>>
DirectIOEvent
(f rom ev ents)
<<Interface>>
POSPowerControl
<<prop>> EventNumber : int32 (f rom upos)
<<prop>> BatteryCapacityRemaining : int32
<<prop>> BatteryCriticallyLowThreshold : int32
fires <<prop>> BatteryLowThreshold : int32
<<capability>> CapBatteryCapacityRem aining : boolean
<<capability>> CapFanAlarm : boolean
<<capability>> CapHeatAlarm : boolean
<<capability>> CapQuickCharge : boolean
<<event>>
<<capability>> CapRestartPOS : boolean
StatusUpdateEvent
(f rom ev ents) fires <<capability>> CapShutdownPOS : boolean
<<capability>> CapStandbyPOS : boolean
<<capability>> CapSuspendPOS : boolean
<<capability>> CapUPSChargeState : int32
<<capability>> CapVariableBatteryCriticallyLowThreshold : boolean
<<capability>> CapVariableBatteryLowThreshold : boolean
<<prop>> EnforcedShutdownDelayTime : int32
<<prop>> PowerFailDelayTime : int32
<<prop>> PowerSource : int32
<<prop>> QuickChargeMode : boolean
<<prop>> QuickChargeTime : int32
<<prop>> UPSChargeState : int32
restartPOS() : void
shutdownPOS() : void
standbyPOS(reason : int32) : void
suspendPOS(reason : int32) : void

POSPower Sequence Diagram Added in Release 1.7

The following sequence diagram shows the typical usage of the POSPower device
for registering for StatusUpdateEvents and an atypical case of initiating a
shutdownPOS call.
POSPower device and also PowerNotify property is set to PN_ENABLED.
:ClientApp :POSPower :StatusUpdateEvent :POSPowerService Some Critical Situation

(like power failure)
1: setPowerNotify(true)
5: getUPSChargeState()
6: getUPSChargeState()
7: getPowerFailDelayTime() 8: getPowerFailDelayTime()
:ClientApp might access other properties and setup

internal condition to handle events and power situation
9: UPS battery LOW
such as decision to shutdown... 10: create new SUE
:ClientApp will execute

some SUE handling code 11: deliver SUE to POSPower control
and if conditions for
shutdown are met and
CapShutdownPOS == true.
Initiates shutdown, as below. 12: deliver SUE to all handlers
14: prepare for shutdown by releasing resources and saving appropriate data
Assuming that claim was
successful (that is no
15: claim(timeout) other application has
claimed the service).
16: shutdownPOS() 17: claim(timeout)
18: shutdownPOS()

934 POS Power
POSPower Standby Sequence Diagram Added in Release 1.9
NOTE: we are assuming that the :ClientApp already successfully opened and enabled
the POSPower device and also PowerNotify property is set to PN_ENABLED.
:ClientApp :POSPower :StatusUpdateEvent : Some Battery Level

POSPowerSe... Situation : Event
1: s etPowerNotify(true)
5: getCapBatteryLowThreshold()
6: getCapBatteryLowThreshold()
7: setBatteryLowThreshold(10)
8: s etBatteryLowThreshold(10)
:ClientApp will execute 9: battery less than 10%

some SUE handling code
and if conditions for 10: create new SUE
shutdown are met and
CapShutdownPOS == true.
Initiates shutdown,... 11: deliver SUE to POSPower control
12: deliver SUE to all handlers
14: prepare for standby
15: claim(timeout)
16: claim(timeout)
17: standbyPOS(reason)
18: standbyPOS(reason)
19: create new SUE
20: deliver SUE to POSPower control
21: deliver SUE to all handlers

POSPower State Diagram
The following state diagram depicts the POSPower Control device model.
The State Diagram shows

the states when the device is
opened, claimed, enabled and
additionally when PowerNotify is enabled.
Claiming the device is optional since
POSPower is a sharable device.
Additionally, for CapPowerReporting only

the value PR_ADVANCED is possible.
/open(…) /close()
[ CapPowerReporting==PR_ADVANCED ]
/ setPowerNotify(PR_ENABLED]
Opened Opened & PowerEnabled

/ setDevice-
State = S_IDLE [ CapPowerReporting==PR_ADVANCED ] State == S_IDLE
Enabled(true)
Claimed=false / setPowerNotify(PR_DISABLED] Claimed == false
DeviceEnabled=false DeviceEnabled == false
PowerNotify=PN_DISABLED PowerNotify == PN_ENABLED
/ setDevice-
/ release() / claim(...) / release() / claim(...) Enabled(false)
/ setDevice- [ CapPowerReporting==PR_ADVANCED ]
Enabled(false) / setPowerNotify(PR_ENABLED]
The
Opened & Claimed Opened, Claimed & PowerEnabled details of
State == S_IDLE State == S_IDLE these
Claimed == true Claimed == true states are
/ setPowerNotify(PR_DISABLED]
DeviceEnabled == false DeviceEnabled == false described
PowerNotify == PN_DISABLED PowerNotify == PN_ENABLED in
separate
diagrams
below.
/ setDevice- / setDevice- / setDevice- / setDevice- / setDevice-
Enabled (true) Enabled(false) Enabled (true) Enabled(false) Enabled(true)
Opened, Claimed & Enabled Opened, Claimed, Enabled
State == S_IDLE & PowerEnabled
Claimed == true State == S_IDLE
DeviceEnabled == true Claimed == true
PowerNotify == PN_DISABLED DeviceEnabled == true
/ setPowerNotify(PR_DISABLED]
PowerNotify == PN_ENABLED
/ claim(...) / release() / claim(...) / release()

Opened & Enabled Opened, Enabled
State == S_IDLE & PowerEnabled
Claimed == false State == S_IDLE
DeviceEnabled == true [ CapPowerReporting==PR_ADVANCED ] Claimed == false
PowerNotify == PN_DISABLED / setPowerNotify(PR_DISABLED] DeviceEnabled == true
PowerNotify == PN_ENABLED
Shutdown Operating System

[ CapShutdownPOS == true ] entry / {Deliver StatusUpdateEvent
/ Application saves all data and (PWR_SUE_SHUTDOWN) }
sets itself to a defined state.
/ shutdownPOS()
OS / application stopped.

936 POS Power
POSPower PowerState Diagram - part 1
The following state diagram depicts the POSPower Power States.

the states when the POS terminal
changes its power state.
The details of these

states are described
in separate diagrams
below.
Opened, Enabled & PowerEnabled OR Opened, Claimed, Enabled & PowerEnabled
PowerState ONLINE
____________________ [ The POS terminal is powered off or
detached from the power supplying net. ]
The POS terminal is powered on and ready for use
__________________________
PowerState= = PS_ONLINE [The POS terminal is
[ The POS again powered on
entry / {Deliver StatusUpdateEvent (SUE_POWER_ONLINE) }
terminal is or attached to the
placed online by power supplying net. ]
pressing a
button or key or
due to a power [ PowerFailDelayTime >0 && The POS terminal is
fail situation or powered off or detached from the power supplying
some-thing else net
which may wake ONLINE OFF
up the system.] [The POS terminal is again powered on or attached
to the power supplying net within the time specified in PowerState OFF
PowerFailDelayTime. ] (Power Fail Situation)
____________________
[The POS terminal is running in a
“lower-power-consumption” mode ] The POS terminal runs on battery power
support. This is the powerfail situation.
__________________________
PowerState OFFLINE PowerState == PS_OFF
____________________ entry / {Deliver StatusUpdateEvent
Application saves all (SUE_POWER_OFF) }
The POS terminal is powered on but is running
data and sets itself
is a “lower-power-consumption” mode
to a defined state.
__________________________ [ EnforcedShutdown-
PowerState= = PS_OFFLINE [ last POSPower DelayTime >0 ]
entry / {Deliver StatusUpdateEvent Device instance
(SUE_POWER_OFFLINE) } opened ] After the time specified in
/ close () EnforcedShutdown-DelayTime
Shutdown Operating System

entry / {Deliver StatusUpdateEvent
(PWR_SUE_SHUTDOWN) }
OS/ application stopped.

The following state diagram depicts the POSPower PowerState ONLINE.

the sub states in the
PowerState ONLINE state
when charging the UPS battery.
PowerState ONLINE
[ (CapUPSChargeState & PWR_UPS_CRITICAL) != 0
&& physical battery charge state is critical ]
UPSChargeState PWR_UPS_CRITICAL
____________________
UPS battery is in a critical state
__________________________
PowerState= = PS_ONLINE
entry / {Deliver StatusUpdateEvent (PWR_SUE_UPS_CRITICAL) }
[ (CapUPSChargeState & PWR_UPS_LOW) != 0 [ (CapUPSChargeState &

&& physical battery charge state is near empty ] PWR_UPS_LOW) != 0
&& physical battery
charge state is near empty ]
/ Battery is loading
UPSChargeState PWR_UPS_LOW
____________________
UPS battery UPS battery is near empty.
__________________________
entry / {Deliver StatusUpdateEvent (PWR_SUE_UPS_LOW) }
[ (CapUPSChargeState &
PWR_UPS_WARNING) != 0
[ (CapUPSChargeState & && physical battery charge state
PWR_UPS_WARNING) != 0 && is near 50% ]
physical battery charge state is / Battery is loading
near 50% charge ]
UPSChargeState PWR_UPS_WARNING
____________________
UPS battery UPS battery is near 50% charge
[ (CapUPSChargeState & __________________________
PWR_UPS_FULL) != 0 && PowerState= = PS_ONLINE
physical battery charge state entry / {Deliver StatusUpdateEvent (PWR_SUE_UPS_WARNING) }
is near full ]
PWR_UPS_FULL) != 0
&& physical battery charge
state is near full ]
/ Battery is loading
UPSChargeState PWR_UPS_FULL
____________________
UPS battery UPS battery is near full charge
__________________________
entry / {Deliver StatusUpdateEvent (PWR_SUE_UPS_FULL) }

938 POS Power

The following state diagram depicts the POSPower PowerState OFF.

the sub states in the
PowerState OFF state
when unloading the UPS battery.
PowerState OFF
[ (CapUPSChargeState & PWR_UPS_CRITICAL) != 0
&& physical battery charge state is critical ]
UPSChargeState PWR_UPS_CRITICAL
____________________
UPS battery is in a critical state
__________________________
PowerState= = PS_OFF
entry / {Deliver StatusUpdateEvent (PWR_SUE_UPS_CRITICAL) }
[ (CapUPSChargeState & PWR_UPS_LOW) != 0 PWR_UPS_CRITICAL) != 0
&& physical battery charge state is near empty ] && physical battery charge
state is critical ]
/ Battery is unloading
UPSChargeState PWR_UPS_LOW
____________________
UPS battery UPS battery is near empty.
__________________________
entry / {Deliver StatusUpdateEvent (PWR_SUE_UPS_LOW) }
PWR_UPS_LOW) != 0
[ (CapUPSChargeState & && physical battery charge
PWR_UPS_WARNING) != 0 && state is near empty ] / Battery
physical battery charge state is is unloading
near 50% charge ]
UPSChargeState PWR_UPS_WARNING
____________________
UPS battery UPS battery is near 50% charge
__________________________
[ (CapUPSChargeState & entry / {Deliver StatusUpdateEvent (PWR_SUE_UPS_WARNING) }
PWR_UPS_FULL) != 0 &&
physical battery charge state [ (CapUPSChargeState &
is near full ] PWR_UPS_WARNING) != 0
&& physical battery charge
state is near 50% ]
/ Battery is unloading
UPSChargeState PWR_UPS_FULL
____________________
UPS battery UPS battery is near full charge
__________________________
entry / {Deliver StatusUpdateEvent (PWR_SUE_UPS_FULL) }

POSPower State chart Diagram for Fan and Temperature
The following state diagram depicts the handling of fan and temperature alarms.
The State Diagrams shows

the states for handling
high CPU temperature and
stopped CPU fan.
[ (CapHeatAlarm == true &&

CPU temperature is critical ]
CPU temperature is high

(PWR_SUE_TEMPERATURE_HIGH) }
CPU temperature
[ (CapHeatAlarm == true && increases and reaches CPU temperature
CPU temperature is uncritical ] a critical state decrease and leaves
the critical state
CPU temperature is low

(PWR_SUE_TEMPERATURE_OK) }
[ (CapFanAlarm == true &&

fan is stopped ]
The CPU fan is stopped.

(PWR_SUE_FAN_STOPPED) }
Fan stops running

[ (CapFanAlarm == true && Fan starts running
fan works properly ]
CPU fan is running

(PWR_SUE_FAN_RUNNING) }

940 POS Power
POSPower Battery State Diagram Added in Release 1.9
Illustrates the transition of states when the POS

is only powered by the battery. It is assumed
that the battery threshold is already set.
Opened, Enabled and PowerEnabled OR Opened, Claimed, Enabled and PowerEnabled (Battery)
disconnected from power, battery is fully charged Battery is fully charged
entry/ PowerSource is set to PWR_SOURCE_BATTERY
disconnected from power, battery is low Battery capacity falls below BatteryLowThreshold returns to AC power
Battery is low

entry/ Fires PWR_SUE_BAT_LOW
disconnected from power, battery is critically low do/ Update BatteryCapacityRemaining and sends PWR_SUE_BAT_CAPACITY_REMAINING when changed
returns to AC power
Battery capacity falls below BatteryCriticallyLowThreshold
Battery is critically low

returns to AC power
entry/ Fires PWR_SUE_BAT_CRITICAL
do/ Update BatteryCapacityRemaining and sends PWR_SUE_BAT_CAPACITY_REMAINING when changed

POSPower Power Transitions State Diagram Added in Release 1.9
The state diagram

illustrates the changes
when the POS is
powered by battery
Opened, Enabled and PowerEnabled OR Opened, Claimed, Enabled and PowerEnabled
running on AC power
POS attached and receiving AC Power
entry/ PowerSource is set to PWR_SOURCE_AC

entry/ PWR_SUE_POWER_SOURCE fired
running on UPS power

Loss of AC power
AC restored
POS running on UPS Power
attached to AC Power
do/ See previous diagrams
running on battery power entry/ PowerSource is set to PWR_SOURCE_BACKU...
entry/ PWR_SUE_POWER_SOURCE fired
UPS restored
Loss of UPS power
POS running on battery

application request shutdown entry/ PWR_SUE_POWER_SOURCE fired
POS is shutdown
entry/ PWR_SUE_SHUTDOWN Fired application request restart
application request standby application request suspend
POS is restarted
POS is in standby
entry/ PWR_SUE_RESTART fired
entry/ PWR_SUE_STANDBY or PWR_SUE_USER_STANDBY fired
POS is suspended
entry/ PWR_SUE_SUSPEND or PWR_SUE_USER_SUSPEND fired

942 POS Power
BatteryCapacityRemaining Property Added in Release 1.9

Syntax BatteryCapacityRemaining: int32 { read-only, access after open }
Remarks A value of 0 to 100 represents percent of battery capacity remaining.
See Also CapBatteryCapacityRemaining Property
BatteryCriticallyLowThreshold Property Added in Release 1.9

Syntax BatteryCriticallyLowThreshold: int32 { read-write, access after open }
Remarks If not zero, this property holds the threshold at which a
PWR_SUE_BAT_CRITICAL Status Update Event is generated. The values 1
through 99 represent the percentage of the capacity remaining. The value 0
indicates that Battery Critically Low reporting is not supported or is disabled.
See Also CapVariableBatteryCriticallyLowThreshold Property, StatusUpdateEvent
BatteryLowThreshold Property Added in Release 1.9

Syntax BatteryLowThreshold: int32 { read-write, access after open }
Remarks If not zero, this property holds the threshold at which a PWR_SUE_BAT_LOW
Status Update Event is generated. The value 1 to 99 represents the percent capacity
remaining. The value 0 indicates that battery low reporting is not supported or is
disabled. If variable battery low threshold is supported, setting a value between 1
and 99 sets the threshold to that value. Setting a value of zero disables battery low
reporting.
See Also CapVariableBatteryLowThreshold Property, StatusUpdateEvent

CapBatteryCapacityRemaining Property Added in Release 1.9

Syntax CapBatteryCapacityRemaining: boolean { read-only, access after open }
Remarks If true the device is able to provide battery capacity information. Otherwise it is
false.
See Also BatteryCapacityRemaining Property
CapFanAlarm Property
Syntax CapFanAlarm: boolean { read-only, access after open }
Remarks If true the device is able to detect whether the CPU fan is stopped. Otherwise it is
false.
CapHeatAlarm Property
Syntax CapHeatAlarm: boolean { read-only, access after open }
Remarks If true the device is able to detect whether the CPU is running at too high of a
temperature. Otherwise it is false.
CapQuickCharge Property
Syntax CapQuickCharge: boolean { read-only, access after open }
Remarks If true the power management allows the charging of the UPS battery in quick
mode. The time for charging the battery is shorter than usual. Otherwise it is false.
See Also QuickChargeMode Property, QuickChargeTime Property.

944 POS Power
CapRestartPOS Property Added in Release 1.9

Syntax CapRestartPOS: boolean { read-only, access after open }
Remarks If true the device is able to explicitly restart the POS. Otherwise it is false.
See Also restartPOS Method.
CapShutdownPOS Property
Syntax CapShutdownPOS: boolean { read-only, access after open }
Remarks If true the device is able to explicitly shut down the POS. Otherwise it is false.
See Also shutdownPOS Method.
CapStandbyPOS Property Added in Release 1.9

Syntax CapStandbyPOS: boolean { read-only, access after open }
Remarks If true the device is able to request that the POS System enter the Standby state.
Otherwise it is false.
See Also standbyPOS Method.
CapSuspendPOS Property Added in Release 1.9

Syntax CapSuspendPOS: boolean { read-only, access after open }
Remarks If true the device is able to request that the POS System enter the Suspend state.
Otherwise it is false.
See Also suspendPOS Method.

CapUPSChargeState Property
Syntax CapUPSChargeState: int32 { read-only, access after open }
Remarks If not equal to zero, the UPS can deliver one or more charge states. It can contain
any of the following values logically ORed together.
Value Meaning
PWR_UPS_FULL UPS battery is near full charge.
PWR_UPS_WARNING UPS battery is near 50% charge.
PWR_UPS_LOW UPS battery is near empty. Application shutdown
should be started to ensure that is can be completed
before the battery charge is depleted. A minimum of
2 minutes of normal system operation can be
assumed when this state is entered unless this is the
first state reported upon entering the “Off” power
state.
PWR_UPS_CRITICAL UPS battery is in a critical state and could be
disconnected at any time without further warning.
See Also UPSChargeState Property.
CapVariableBatteryCriticallyLowThreshold Property Added in Release 1.9

Syntax CapVariableBatteryCriticallyLowThreshold: boolean { read-only, access
after open }
Remarks If true the device supports a variable threshold for critically low battery. Otherwise
it is false.
See Also BatteryCriticallyLowThreshold Property, StatusUpdateEvent
CapVariableBatteryLowThreshold Property Added in Release 1.9

Syntax CapVariableBatteryLowThreshold: boolean { read-only, access after open }
Remarks If true the device supports a variable threshold for battery low. Otherwise it is
false.
See Also BatteryLowThreshold Property, StatusUpdateEvent

946 POS Power
EnforcedShutdownDelayTime Property
Syntax EnforcedShutdownDelayTime: int32 { read-write, access after open }
Remarks If not equal to zero the system has a built-in mechanism to shut down the POS
terminal after a determined time in a power fail situation. This property contains
the time in milliseconds when the system will shut down automatically after a
power failure. A power failure is the situation when the POS terminal is powered
off or detached from the power supplying net and runs on UPS.
If zero no automatic shutdown is performed and the application has to call itself
the shutdownPOS method.
Applications will be informed about an initiated automatic shutdown.
See Also shutdownPOS Method.
PowerFailDelayTime Property
Syntax PowerFailDelayTime: int32 { read-only, access after open }
Remarks This property contains the time in milliseconds for power fail intervals which will
not create a power fail situation. In some countries the power has sometimes short
intervals where the power supply is interrupted. Those short intervals are in the
range of milliseconds up to a few seconds and are handled by batteries or other
electric equipment and should not cause a power fail situation. The power fail
interval starts when the POS terminal is powered off or detached from the power
supplying net and runs on UPS. The power fail interval ends when the POS
terminal is again powered on or attached to the power supplying net. However, if
the power fail interval is longer than the time specified in the
PowerFailDelayTime property a power fail situation is created.
Usually this parameter is a configuration parameter of the underlying power
management. So, the application can only read this property.

PowerSource Property Added in Release 1.9

Syntax PowerSource: int32 { read-only, access after open }
Remarks This property holds the current power source if power source reporting is
available. A StatusUpdateEvent is generated each time this property is updated.
Value Meaning
PWR_SOURCE_NA Power source reporting is not available.

PWR_SOURCE_AC The current power source is the AC line.
PWR_SOURCE_BATTERY The current power source is a system battery. This
value is only presented for systems that operate
normally on battery.
PWR_SOURCE_BACKUP The current power source is a backup source such as
an UPS or backup battery.
See Also StatusUpdateEvent
QuickChargeMode Property
Syntax QuickChargeMode: boolean { read-only, access after open }
Remarks If true, the UPS battery is being recharged in a quick charge mode.
If false, it is being charged in a normal mode.
This property is only set if CapQuickCharge is true.
See Also CapQuickCharge Property, QuickChargeTime Property.
QuickChargeTime Property
Syntax QuickChargeTime: int32 { read-only, access after open }
Remarks This time specifies the remaining time for charging the UPS battery in quick
charge mode. After the time has elapsed, the UPS battery charging mechanism of
power management usually switches into normal mode.
This time is specified in milliseconds.
This property is only set if CapQuickCharge is true.
See Also CapQuickCharge Property, QuickChargeMode Property.

948 POS Power
UPSChargeState Property
Syntax UPSChargeState: int32 { read-only, access after open-enable }
Remarks This property holds the actual UPS charge state.
Value Meaning
PWR_UPS_FULL UPS battery is near full charge.

PWR_UPS_WARNING UPS battery is near 50% charge.
PWR_UPS_LOW UPS battery is near empty. Application shutdown
should be started to ensure that is can be completed
before the battery charge is depleted. A minimum of
2 minutes of normal system operation can be
assumed when this state is entered unless this is the
first state reported upon entering the “Off” power
state.
PWR_UPS_CRITICAL UPS battery is in a critical state and could be
disconnected at any time without further warning.
See Also CapUPSChargeState Property.


restartPOS Method Added in Release 1.9
Syntax restartPOS ( ):
Remarks Call to restart the POS terminal. This method will always restart the system
independent of the system power state.
If the POSPower is claimed, only the application which claimed the device is able
to restart the POS terminal.
Applications will be informed about an initiated restart.
Value Meaning
E_ILLEGAL This method is not supported (see the CapRestartPOS
property)
See Also CapRestartPOS Property
shutdownPOS Method
Syntax shutdownPOS ( ):
Remarks Call to shut down the POS terminal. This method will always shut down the
system independent of the system power state.
If the POSPower is claimed, only the application which claimed the device is able
to shut down the POS terminal.
Applications will be informed about an initiated shutdown.
It is recommended that in a power fail situation an application has to call this
method after saving all data and setting the application to a defined state.
If the EnforcedShutdownDelayTime property specifies a time greater than zero
and the application did not call the shutdownPOS method within the time
specified in EnforcedShutdownDelayTime, the system will be shut down
automatically. This mechanism may be provided by an underlying operating
system to prevent the battery from being emptied before the system is shut down.
This method is only supported if CapShutdownPOS is true.
Value Meaning
E_ILLEGAL This method is not supported (see the
CapShutdownPOS property)
See Also CapShutdownPOS Property, EnforcedShutdownDelayTime Property.

950 POS Power
standbyPOS Method Updated in Release 1.10
Syntax standbyPOS (reason: int32 ):

Remarks Call to request that the system be placed into the Standby state or to respond to a
request from the system, OS or other application that the system be put into
Standby state.
The reason parameter indicates the reason the POS terminal should enter a standby
state:
Value Description
PWR_REASON_REQUEST Call is to request that the system enter the
standby state.
PWR_REASON_ALLOW Call is a response to a standby Status Update
Event and specifies that the request should be
allowed.
PWR_REASON_DENY Call is a response to a standby Status Update
denied.
Value Meaning
E_ILLEGAL This method is not supported (see the CapStandbyPOS
property)
See Also CapStandbyPOS Property.

suspendPOS Method Updated in Release 1.10
Syntax suspendPOS (reason: int32 ):

Remarks Call to request that the system be placed into the Suspend state or to respond to a
request from the system, OS or other application that the system be put into
Suspend state.
The reason parameter indicates the reason the POS terminal should enter a standby
state:
Value Description
PWR_REASON_REQUEST Call is to request that the system enter the
suspend state.
PWR_REASON_ALLOW Call is a response to a suspend Status Update
allowed.
PWR_REASON_DENY Call is a response to a suspend Status Update
denied.
Value Meaning
E_ILLEGAL This method is not supported (see the CapSuspendPOS
property)
See Also CapSuspendPOS Property.

952 POS Power
DirectIOEvent
means for a vendor-specific POSPower Service to provide events to the
Service.
from being used with other vendor’s POSPower devices which may not have any


Description Delivered when UPSChargeState changes or an alarm situation occurs.
The Status property contains the updated power status or alarm status.
Value Meaning
PWR_SUE_UPS_FULL UPS battery is near full charge. Can be returned
if CapUPSChargeState contains
PWR_UPS_FULL.
PWR_SUE_UPS_WARNING UPS battery is near 50% charge. Can be
returned if CapUPSChargeState contains
PWR_UPS_WARNING.
PWR_SUE_UPS_LOW UPS battery is near empty. Application
shutdown should be started to ensure that it can
be completed before the battery charge is
depleted. A minimum of 2 minutes of normal
system operation can be assumed when this
state is entered unless this is the first charge
state reported upon entering the “Off” state.
Can be returned if CapUPSChargeState
contains PWR_UPS_LOW.
PWR_SUE_UPS_CRITICAL UPS is in critical state, and will in short time be
disconnected. Can be returned if
CapUPSChargeState contains
PWR_UPS_CRITICAL.
PWR_SUE_FAN_STOPPED The CPU fan is stopped. Can be returned if
CapFanAlarm is true.
PWR_SUE_FAN_RUNNING The CPU fan is running. Can be returned if
CapFanAlarm is true.
PWR_SUE_TEMPERATURE_HIGH
The CPU is running on high temperature. Can
be returned if CapHeatAlarm is true.
PWR_SUE_TEMPERATURE_OK
The CPU is running on normal temperature.
Can be returned if CapHeatAlarm is true.
PWR_SUE_SHUTDOWN The system will shutdown immediately.
Note that Release 1.9 added the following status update events:
PWR_SUE_BAT_LOW The system remaining battery capacity is at or

below the low battery threshold and the system
is operating from the battery.

954 POS Power
PWR_SUE_BAT_CRITICAL The system remaining battery capacity is at or

below the critically low battery threshold and
the system is operating from the battery.
PWR_SUE_BAT_CAPACITY_REMAINING.
The BatteryCapacityRemaining property has
been updated
PWR_SUE_RESTART The system will restart immediately.
PWR_SUE_STANDBY The system is requesting a transition to the
Standby state
PWR_SUE_USER_STANDBY The system is requesting a transition to the
Standby state as a result of user input.
PWR_SUE_SUSPEND The system is requesting a transition to the
Suspend state.
PWR_SUE_USER_SUSPEND The system is requesting a transition to the
Suspend state as a result of user input.
PWR_SUE_PWR_SOURCE The PowerSource property has been updated.

process.
See Also CapFanAlarm Property, CapHeatAlarm Property, CapUPSChargeState

Property, UPSChargeState Property.

C H A P T E R 3 0
POS Printer
This Chapter defines the POS Printer device category.
Summary


956 POS Printer
CapConcurrentJrnRec: boolean { read-only } 1.0 open
CapConcurrentJrnSlp: boolean { read-only } 1.0 open
CapConcurrentPageMode: boolean { read-only } 1.9 open
CapConcurrentRecSlp: boolean { read-only } 1.0 open
CapCoverSensor: boolean { read-only } 1.0 open
CapJrnPresent: boolean { read-only } 1.0 open

CapJrn2Color: boolean { read-only } 1.0 open
CapJrnBold: boolean { read-only } 1.0 open
CapJrnDhigh: boolean { read-only } 1.0 open
CapJrnDwide: boolean { read-only } 1.0 open
CapJrnDwideDhigh: boolean { read-only } 1.0 open
CapJrnEmptySensor: boolean { read-only } 1.0 open
CapJrnItalic: boolean { read-only } 1.0 open
CapJrnNearEndSensor: boolean { read-only } 1.0 open
CapJrnUnderline: boolean { read-only } 1.0 open
CapJrnCartridgeSensor: int32 { read-only } 1.5 open
CapJrnColor: int32 { read-only } 1.5 open
CapRecPresent: boolean { read-only } 1.0 open

CapRec2Color: boolean { read-only } 1.0 open
CapRecBarCode: boolean { read-only } 1.0 open
CapRecBitmap: boolean { read-only } 1.0 open
CapRecBold: boolean { read-only } 1.0 open
CapRecDhigh: boolean { read-only } 1.0 open
CapRecDwide: boolean { read-only } 1.0 open
CapRecDwideDhigh: boolean { read-only } 1.0 open
CapRecEmptySensor: boolean { read-only } 1.0 open
CapRecItalic: boolean { read-only } 1.0 open
CapRecLeft90: boolean { read-only } 1.0 open
CapRecNearEndSensor: boolean { read-only } 1.0 open
CapRecPapercut: boolean { read-only } 1.0 open
CapRecRight90: boolean { read-only } 1.0 open
CapRecRotate180: boolean { read-only } 1.0 open
CapRecStamp: boolean { read-only } 1.0 open
CapRecUnderline: boolean { read-only } 1.0 open
CapRecCartridgeSensor: int32 { read-only } 1.5 open
CapRecColor: int32 { read-only } 1.5 open
CapRecMarkFeed: int32 { read-only } 1.5 open

Summary 957
CapRecPageMode: boolean { read-only } 1.9 open
CapSlpPresent: boolean { read-only } 1.0 open

CapSlpFullslip: boolean { read-only } 1.0 open
CapSlp2Color: boolean { read-only } 1.0 open
CapSlpBarCode: boolean { read-only } 1.0 open
CapSlpBitmap: boolean { read-only } 1.0 open
CapSlpBold: boolean { read-only } 1.0 open
CapSlpDhigh: boolean { read-only } 1.0 open
CapSlpDwide: boolean { read-only } 1.0 open
CapSlpDwideDhigh: boolean { read-only } 1.0 open
CapSlpEmptySensor: boolean { read-only } 1.0 open
CapSlpItalic: boolean { read-only } 1.0 open
CapSlpLeft90: boolean { read-only } 1.0 open
CapSlpNearEndSensor: boolean { read-only } 1.0 open
CapSlpRight90: boolean { read-only } 1.0 open
CapSlpRotate180: boolean { read-only } 1.0 open
CapSlpUnderline: boolean { read-only } 1.0 open
CapSlpBothSidesPrint: boolean { read-only } 1.5 open
CapSlpCartridgeSensor: int32 { read-only } 1.5 open
CapSlpColor: int32 { read-only } 1.5 open
CapSlpPageMode: boolean { read-only } 1.9 open

CartridgeNotify: int32 { read-write } 1.5 open
CoverOpen: boolean { read-only } 1.0 open, claim, & enable
ErrorLevel: int32 { read-only } 1.1 open
ErrorStation: int32 { read-only } 1.0 open
FontTypefaceList: string { read-only } 1.1 open
FlagWhenIdle: boolean { read-write } 1.0 open
MapMode: int32 { read-write } 1.0 open
PageModeArea: string { read-only } 1.9 open
PageModeDescriptor: int32 { read-only } 1.9 open
PageModeHorizontalPosition: int32 { read-write } 1.9 open

958 POS Printer
PageModePrintArea: string { read-write } 1.9 open
PageModePrintDirection: int32 { read-write } 1.9 open
PageModeStation: int32 { read-write } 1.9 open
PageModeVerticalPosition: int32 { read-write } 1.9 open
RotateSpecial: int32 { read-write } 1.1 open
JrnLineChars: int32 { read-write } 1.0 open, claim, & enable

JrnLineCharsList: string { read-only } 1.0 open
JrnLineHeight: int32 { read-write } 1.0 open, claim, & enable
JrnLineSpacing: int32 { read-write } 1.0 open, claim, & enable
JrnLineWidth: int32 { read-only } 1.0 open, claim, & enable
JrnLetterQuality: boolean { read-write } 1.0 open, claim, & enable
JrnEmpty: boolean { read-only } 1.0 open, claim, & enable
JrnNearEnd: boolean { read-only } 1.0 open, claim, & enable
JrnCartridgeState: int32 { read-only } 1.5 open, claim, & enable
JrnCurrentCartridge: int32 ( read-write } 1.5 open, claim, & enable
RecLineChars: int32 { read-write } 1.0 open, claim, & enable

RecLineCharsList: string { read-only } 1.0 open
RecLineHeight: int32 { read-write } 1.0 open, claim, & enable
RecLineSpacing: int32 { read-write } 1.0 open, claim, & enable
RecLineWidth: int32 { read-only } 1.0 open, claim, & enable
RecLetterQuality: boolean { read-write } 1.0 open, claim, & enable
RecEmpty: boolean { read-only } 1.0 open, claim, & enable
RecNearEnd: boolean { read-only } 1.0 open, claim, & enable
RecSidewaysMaxLines: int32 { read-only } 1.0 open, claim, & enable
RecSidewaysMaxChars: int32 { read-only } 1.0 open, claim, & enable
RecLinesToPaperCut: int32 { read-only } 1.0 open, claim, & enable
RecBarCodeRotationList: string { read-only } 1.0 open
RecBitmapRotationList: string { read-only } 1.7 open
RecCartridgeState: int32 { read-only } 1.5 open, claim, & enable
RecCurrentCartridge: int32 { read-write } 1.5 open, claim, & enable
SlpLineChars: int32 { read-write } 1.0 open, claim, & enable

SlpLineCharsList: string { read-only } 1.0 open
SlpLineHeight: int32 { read-write } 1.0 open, claim, & enable
SlpLineSpacing: int32 { read-write } 1.0 open, claim, & enable
SlpLineWidth: int32 { read-only } 1.0 open, claim, & enable

Summary 959
SlpLetterQuality: boolean { read-write } 1.0 open, claim, & enable
SlpEmpty: boolean { read-only } 1.0 open, claim, & enable
SlpNearEnd: boolean { read-only } 1.0 open, claim, & enable
SlpSidewaysMaxLines: int32 { read-only } 1.0 open, claim, & enable
SlpSidewaysMaxChars: int32 { read-only } 1.0 open, claim, & enable
SlpMaxLines: int32 { read-only } 1.0 open, claim, & enable
SlpLinesNearEndToEnd: int32 { read-only } 1.0 open, claim, & enable
SlpBarCodeRotationList: string { read-only } 1.1 open
SlpBitmapRotationList: string { read-only } 1.7 open
SlpPrintSide: int32 { read-only } 1.5 open, claim, & enable
SlpCartridgeState: int32 { read-only } 1.5 open, claim, & enable
SlpCurrentCartridge: int32 { read-write } 1.5 open, claim, & enable

Common
Name Version
close ( ): 1.0
release ( ): 1.0
clearInput ( ): Not
void { } supported
void { } supported

960 POS Printer

Specific
Name Version
changePrintSide ( side: int32 ): 1.5
clearPrintArea ( ): 1.9
cutPaper ( percentage: int32 ): 1.0
endRemoval ( ): 1.0
markFeed ( side: int32 ): 1.5
pageModePrint ( control: int32 ): 1.9
printBarCode ( station: int32, data: string, symbology: int32, height: int32, 1.0
width: int32, alignment: int32, textPosition: int32 ):
printBitmap ( station: int32, fileName: string, width: int32, alignment: int32 ): 1.0
printImmediate ( station: int32, data: string ): 1.0
printMemoryBitmap (station: int32, data: binary, type: int32, width: int32, 1.10
alignment: int32):
printNormal ( station: int32, data: string ): 1.0
printTwoNormal ( station: int32, data1: string, data2: string ): 1.0
rotatePrint ( station: int32, rotation: int32 ): 1.0
setBitmap ( bitmapNumber: int32, station: int32, fileName: string, width: 1.0
int32, alignment: int32 ):
setLogo ( location: int32, data: string ): 1.0
transactionPrint ( station: int32, control: int32 ): 1.1
validateData ( station: int32, data: string ): 1.1

Summary 961


962 POS Printer
General Information
The POS Printer programmatic name is “POSPrinter”.
The POS Printer Service does not attempt to encapsulate the behavior of a generic
graphics printer. Rather, for performance and ease of use considerations, the
interfaces are defined to directly control a POS printer. Usually, an application will
print one line to one station per method, for ease of use and accuracy in recovering
from errors.
The printer model defines three stations with the following general uses:
• Journal: Used for simple text to log transaction and activity information.
Kept by the store for audit and other purposes.
• Receipt: Used to print transaction information. Usually given to the customer.
Also often used for store reports. Contains either a knife to cut the paper
between transactions, or a tear bar to manually cut the paper.
• Slip: Used to print information on a form. Usually given to the customer.
Also used to print “validation” information on a form. The form type is
typically a check or credit card slip.
Sometimes, limited forms-handling capability is integrated with the receipt or
journal station to permit validation printing. Often this limits the number of
print lines, due to the station’s forms-handling throat depth. The Printer
Service nevertheless addresses this printer functionality as a slip station.
The POS printer has the following capability:

• The default character set can print ASCII characters (0x20 through 0x7F),
which includes space, digits, uppercase, lowercase, and some special
characters. (If the printer does not support all of these, then it should translate
them to close approximations – such as lowercase to uppercase.)
The POS printer may have several additional capabilities. See the capabilities
properties for specific information.
The following capabilities are not addressed in this version of the specification. A
Service may choose to support them through the directIO mechanism.
• Downloadable character sets.
• Character substitution.
• Pixel-level printing is only supported through bitmaps when the printBitmap
or setBitmap method is called with the width parameter set to PTR_BM_ASIS.
Therefore, it is possible for the application to programmatically prepare and
print bitmaps with the required pixels set.

POS Printer Class Diagram
The following diagram shows the relationships between the POS Printer classes.
<<utility>> <<utility>> <<Interface>> <<exception>>

<<uses>> BaseControl <<sends>> UposException
POSPrinterConst UposConst
(from upos)
<<sends>>
<<uses>>
<<uses>>
<<Interface>>
POSPrinterControl
(from upos)
beginInsertion(timeout : int32) : void

beginRemoval(timeout : int32) : void
changePrintSide(side : int32) : void
cutPaper(percentage : int32) : void
endInsertion() : void
endRemoval() : void
markFeed(type : int32) : void
printBarCode(station : int32, data : string, symbology : int32, height : int32, width : int32, alignment : int32, textPosition : int32) : void
printBitmap(station : int32, fileName : string, width : int32, alignment : int32) : void
printImmediate(station : int32, data : string) : void
printNormal(station : int32, data : string) : void
printTwoNormal(stations : int32, data1 : string, data2 : string) : void
rotatePrint(station : int32, rotation : int32) : void
setBitmap(bitmapNumber : int32, station : int32, fileName : string, width : int32, alignment : int32) : void
setLogo(location : int32, data : string) : void
transactionPrint(station : int32, control : int32) : void
validateData(station : int32, data : string) : void
fires fires fires fires
<<event>> <<event>> <<event>> <<event>>

StatusUpdateEvent ErrorEvent OutputCompleteEvent DirectIOEvent
(from events) (from events) (from events) (from events)
Only the methods of the

POSPrinterControl are shown in
order to avoid cluttering the diagram.

964 POS Printer
POS Printer Class Diagram Updates Updated in Release 1.10
The following diagram shows the relationships between the POS Printer classes
that were updated/added in versions 1.5 and later of the specification.
<<utility>> <<utility>> <<exception>>

UposConst POSPrinterConst UposException
<<event>>
ErrorEvent <<uses>>
<<sends>>
(from events)
<<Interface>>
fires POSPrinterControl
<<event>> (from upos)
DirectIOEvent
<<capability>> CapConcurrentPageMode : boolean
(from events)
<<capability>> CapJrnCartridgeSensor : int32
<<capability>> CapJrnColor : int32
fires <<capability>> CapMapCharacterSet : boolean
<<capability>> CapRecCartridgeSensor : int32
<<event>> <<capability>> CapRecColor : int32
OutputCompleteEvent <<capability>> CapRecMarkFeed : int32
(from events)
<<capability>> CapRecPageMode : boolean
fires
<<capability>> CapSlpBothSidesPrint : boolean
<<capability>> CapSlpCartridgeSensor : int32
<<event>> <<capability>> CapSlpColor : int32
StatusUpdateEvent <<capability>> CapSlpPageMode : boolean
fires <<prop>> CartridgeNotify : int32
(from events)
<<prop>> JrnCartridgeState : int32
<<prop>> JrnCurrentCartridge : int32
<<prop>> MapCharacterSet : boolean
<<prop>> RecBitmapRotationList : string
<<prop>> RecCartridgeState : int32
<<prop>> RecCurrentCartridge : int32
<<prop>> PageModeArea : string
<<prop>> PageModeDescriptor : int32
<<prop>> PageModeHorizontalPosition : int32
<<prop>> PageModePrintArea : string
<<prop>> PageModePrintDirection : int32
<<prop>> PageModeStation : int32
<<prop>> PageModeVerticalPosition : int32
<<prop>> SlpBitmapRotationList : string
<<prop>> SlpCartridgeState : int32
<<prop>> SlpCurrentCartridge : int32
<<prop>> SlpPrintSide : int32
changePrintSide(side : int32) : void

clearPrintArea() : void
markFeed(type : int32) : void
pageModePrint(control : int32) : void
printMemoryBitmap(station : int32, data : binary, type : int32, width : int32, alignment : int32) : void
Only properties and methods

added at or after 1.5 of the
POSPrinterControl are shown
in order to avoid cluttering the
diagram.


The POS Printer follows the general device behavior model for output devices,
with some enhancements:
• The following methods are always performed synchronously:
beginInsertion, endInsertion, beginRemoval, endRemoval,
changePrintSide, and checkHealth. These methods will fail if asynchronous
output is outstanding.
• The printImmediate method is also always performed synchronously: This
method tries to print its data immediately (that is, as the very next printer
operation). It may be called when asynchronous output is outstanding. This
method is primarily intended for use in exception conditions when
asynchronous output is outstanding.
cutPaper, markFeed, printBarCode, printBitmap, printNormal,
printTwoNormal, rotatePrint, and transactionPrint. When AsyncMode is
false, then these methods are performed synchronously.
• When AsyncMode is true, then these methods operate as follows:
• The Service buffers the request in program memory, for delivery to the
as soon as possible. When the request completes successfully, an
OutputCompleteEvent is enqueued. A property of this event contains
the OutputID of the completed request.
• Asynchronous printer methods will not raise an exception due to a
printing problem, such as out of paper or printer fault. These errors will
only be reported by an ErrorEvent. An exception is raised only if the
printer is not claimed and enabled, a parameter is invalid, or the request
cannot be enqueued. The first two error cases are due to an application
error, while the last is a serious system resource error exception.
ErrorEvent is enqueued. The ErrorStation property is set to the station
or stations that were printing when the error occurred. The ErrorLevel
and ErrorString properties are also set.
• The event handler may call synchronous print methods (but not
asynchronous methods), then can either retry the outstanding output or
clear it.
• All asynchronous output is performed on a first-in first-out basis.
• All buffered output data, including all asynchronous output, may be
deleted by calling clearOutput. OutputCompleteEvents will not be
delivered for cleared output. This method also stops any output that may
be in progress (when possible).
• The property FlagWhenIdle may be set to cause a StatusUpdateEvent
to be enqueued when all outstanding outputs have finished, whether
successfully or because they were cleared.

966 POS Printer
• Transaction mode printing is supported. A transaction is a sequence of print

operations that are printed to a station as a unit. Print operations which may be
included in a transaction are printNormal, cutPaper, rotatePrint,
printBarCode, printBitmap, and markFeed. During a transaction, the print
operations are first validated. If valid, they are added to the transaction but not
printed yet. Once the application has added as many operations as required,
then the transaction print method is called.
If the transaction is printed synchronously and an exception is not raised, then
the entire transaction printing was successful. If the transaction is printed
asynchronously, then the asynchronous print rules listed above are followed.
If an error occurs and the Error Event handler causes a retry, the entire
transaction is retried.
The printer error reporting model is as follows:
• Printer out-of-paper, cover open, and various cartridge handling conditions
are reported by setting the exception’s (or ErrorEvent’s) ErrorCode to
E_EXTENDED and then setting the associated ErrorCodeExtended to one of
the following error conditions:
EPTR_JRN_EMPTY,
EPTR_REC_EMPTY,
EPTR_SLP_EMPTY,
EPTR_COVER_OPEN,
EPTR_JRN_CARTRIDGE_REMOVED,
EPTR_REC_CARTRIDGE_REMOVED,
EPTR_SLP_CARTRIDGE_REMOVED,
EPTR_JRN_CARTRIDGE_EMPTY,
EPTR_REC_CARTRIDGE_EMPTY,
EPTR_SLP_CARTRIDGE_EMPTY,
EPTR_JRN_HEAD_CLEANING,
EPTR_REC_HEAD_CLEANING, or
EPTR_SLP_HEAD_CLEANING.
• Other printer errors are reported by setting the exception’s (or ErrorEvent’s)
ErrorCode to E_FAILURE or another standard error status. These failures are
typically due to a printer fault or jam, or to a more serious error.
While the printer is enabled, the printer state is monitored, and changes are
reported to the application. Most printer statuses are reported by both firing a
StatusUpdateEvent and by updating a printer property. Statuses, as defined in the
later properties and events sections, are:
StatusUpdateEvent Property
PTR_SUE_COVER_OPEN CoverOpen = true
PTR_SUE_COVER_OK CoverOpen = false
PTR_SUE_JRN_EMPTY JrnEmpty = true
PTR_SUE_JRN_NEAREMPTY JrnNearEnd = true
PTR_SUE_JRN_PAPEROK JrnEmpty = JrnNearEnd = false
PTR_SUE_REC_EMPTY RecEmpty = true
PTR_SUE_REC_NEAREMPTY RecNearEnd = true

PTR_SUE_REC_PAPEROK RecEmpty = RecNearEnd = false

PTR_SUE_SLP_EMPTY SlpEmpty = true
PTR_SUE_SLP_NEAREMPTY SlpNearEnd = true
PTR_SUE_SLP_PAPEROK SlpEmpty = SlpNearEnd = false
Two properties are used to report cartridge statuses. One (such as
RecCurrentCartridge) selects a station’s cartridge, and a second (such as
RecCartridgeState) reports that cartridge’s status. When a cartridge
StatusUpdateEvent is delivered, it indicates the highest priority cartridge
condition. The cartridge state for at least one cartridge should match the
StatusUpdateEvent’s corresponding property value, while other cartridges may
have lower priority conditions or be OK.
PTR_SUE_JRN_CARTRIDGE_EMPTY
JrnCartridgeState = PTR_CART_EMPTY
or PTR_CART_REMOVED
PTR_SUE_JRN_HEAD_CLEANING
JrnCartridgeState =
PTR_CART_CLEANING
PTR_SUE_JRN_CARTRIDGE_NEAREMPTY
JrnCartridgeState =
PTR_CART_NEAREND
PTR_SUE_JRN_CARTRIDGE_OK
JrnCartridgeState = PTR_CART_OK
PTR_SUE_REC_CARTRIDGE_EMPTY
RecCartridgeState = PTR_CART_EMPTY
or PTR_CART_REMOVED
PTR_SUE_REC_HEAD_CLEANING
RecCartridgeState =
PTR_CART_CLEANING
PTR_SUE_REC_CARTRIDGE_NEAREMPTY
RecCartridgeState =
PTR_CART_NEAREND
PTR_SUE_REC_CARTRIDGE_OK
RecCartridgeState = PTR_CART_OK
PTR_SUE_SLP_CARTRIDGE_EMPTY
SlpCartridgeState = PTR_CART_EMPTY
or PTR_CART_REMOVED
PTR_SUE_SLP_HEAD_CLEANING
SlpCartridgeState =
PTR_CART_CLEANING
PTR_SUE_SLP_CARTRIDGE_NEAREMPTY
SlpCartridgeState =
PTR_CART_NEAREND
PTR_SUE_SLP_CARTRIDGE_OK
SlpCartridgeState = PTR_CART_OK

968 POS Printer

PTR_SUE_JRN_COVER_OPEN CoverOpen = true
PTR_SUE_JRN_COVER_OK CoverOpen = false if all covers closed;
CoverOpen = true if any other cover is open
PTR_SUE_REC_COVER_OPEN CoverOpen = true
PTR_SUE_REC_COVER_OK CoverOpen = false if all covers closed;
PTR_SUE_SLP_COVER_OPEN CoverOpen = true
PTR_SUE_SLP_COVER_OK CoverOpen = false if all covers closed;
Release 1.8 – Clarification

The printer’s slip station statuses must be reported independently from the slip
insertion and removal methods – beginInsertion / endInsertion and
beginRemoval / endRemoval. This is important because some applications base
logic decisions upon printer state changes. That is, the application will only
perform slip insertion after knowing that a slip has been placed at the entrance to
the slip station. An example: After the Total key is pressed, the application enters
tendering mode. It begins to monitor peripherals and the keyboard to determine the
type of tender to perform. If a credit or debit card is swiped at an MSR, then its
DataEvent causes the application to begin credit/debit tender. But if a form is
placed at the slip station, then its StatusUpdateEvent or SlpEmpty property
change causes the application to begin a check MICR read.
When a form is placed at the entrance to the slip station, the printer must fire a
PTR_SUE_SLP_PAPEROK StatusUpdateEvent and set the SlpEmpty and
SlpNearEnd properties to false. The application may then call the beginInsertion
and endInsertion methods with reasonable confidence that they will succeed.
Note that it must not be assumed that the form is ready for printing after the
PTR_SUE_SLP_PAPEROK is received. Only after successful beginInsertion
and endInsertion calls is the form ready for printing.
When a form is removed from the slip station, the printer must fire a
PTR_SUE_SLP_EMPTY StatusUpdateEvent and set the SlpEmpty property to
true. If the beginInsertion and endInsertion method sequence has not been
called, then removing the form from the slip station entrance will cause this to
occur. If this method sequence has successfully completed, then the event and
property change will typically occur after a beginRemoval and endRemoval
method sequence. But they would also occur if the slip prints beyond the end of
the form or if the form is forcibly removed.
Exception: The design of some printers makes it impossible for a service to
determine the presence of a form until the printer “jaws” are opened, which occurs
when beginInsertion is called. This exception is largely limited to cases where the
CapSlpFullslip property is false, indicating a “validation” type of slip station.
Validation stations typically use the same printer mechanism as the receipt and/or
journal stations. In these cases, the slip status events must be fired as soon as
possible, given the constraints of the device.

Release 1.5 and later – Print cartridge support added

The print cartridge model is as follows:
• The CapJrnCartridgeSensor, CapRecCartridgeSensor, and the
CapSlpCartridgeSensor capabilities are used to determine whether the
printer has the ability to detect the operating condition of the cartridge.
• Prior to determining a cartridge’s operating condition, a cartridge is selected
by using one of the following properties: JrnCurrentCartridge,
RecCurrentCartridge, or SlpCurrentCartridge.
• The condition of the selected cartridge is set up using one of the
JrnCartridgeState, RecCartridgeState or SlpCartridgeState properties.
The values that these properties can take in order of high priority to low
priority are as follows: PTR_CART_UNKNOWN,
PTR_CART_REMOVED, PTR_CART_EMPTY,
PTR_CART_CLEANING, PTR_CART_NEAREND, PTR_CART_OK.
• CapJrnColor, CapRecColor, and CapSlpColor capabilities are used to
determine the color capabilities of the station.
Mono Color
• CapJrnColor, CapRecColor, and CapSlpColor capabilities are set to
PTR_COLOR_PRIMARY.
Two Color
• CapJrnColor, CapRecColor, and CapSlpColor capabilities are a logical
OR combination of PTR_COLOR_PRIMARY and
PTR_COLOR_CUSTOM1.
• PTR_COLOR_CUSTOM1 refers to the secondary color, usually red.
• Secondary color printing can be done by using the ESC|rC escape sequence.
Custom Color
OR combination of PTR_COLOR_PRIMARY and any of the following bit
values:
PTR_COLOR_CUSTOM1, PTR_COLOR_CUSTOM2,
PTR_COLOR_CUSTOM3, PTR_COLOR_CUSTOM4,
PTR_COLOR_CUSTOM5, PTR_COLOR_CUSTOM6.
• Selection of a custom color can be done using the ESC|#rC escape sequence.
Full Color
OR combination of PTR_COLOR_FULL and the following values:
PTR_COLOR_CYAN, PTR_COLOR_MAGENTA,
PTR_COLOR_YELLOW.
• PTR_COLOR_FULL is not used to indicate that a print cartridge is currently
installed in the printer. Rather, it is used to indicate that the printer has the
ability to print in full color mode.
• Full color printing is accomplished by using the ESC|#fC escape sequence.
Full Color with Custom Color(s)
• CapJrnColor, CapRecColor, and CapSlpColor are a logical OR
combination of the settings for Custom Color and Full Color.

970 POS Printer
Release 1.5 and later – Cartridge State Reporting Requirements for

DeviceEnabled
The print cartridge state reporting model is:
• CartridgeNotify property: The application may set this property to enable
cartridge state reporting via StatusUpdateEvents and JrnCartridgeState,
RecCartridgeState, and SlpCartridgeState properties. This property may
only be set before the device is enabled (that is, before DeviceEnabled is set
to true). This restriction allows simpler implementation of cartridge status
notification with no adverse effects on the application. The application is
either prepared to receive notifications or doesn’t want them, and has no need
to switch between these cases. This property may be one of:
PTR_CN_DISABLED, or PTR_CN_ENABLED
The following semantics are added to DeviceEnabled when the
CapJrnCartridgeSensor, CapRecCartridgeSensor, and
CapSlpCartridgeSensor capabilities are not zero, and CartridgeNotify is set to
PTR_CN_ENABLED:
• Monitoring the cartridge state begins when DeviceEnabled changes from
false to true.
• When DeviceEnabled changes from true to false, the state of the cartridge is
no longer valid. Therefore, JrnCartridgeState, RecCartridgeState, and
SlpCartridgeState properties are set to PTR_CART_UNKNOWN.
Release 1.8 and later – Synchronous Printing – Updated in Release 1.10
Prior to Release 1.8 the behavior of line printers, such as thermal printers, when in
synchronous mode was not clearly defined. For example, when an application
called printNormal (PTR_S_RECEIPT, “UnifiedPOS”), the synchronous model
stated that the method should not return successfully unless the text was printed on
the paper. However, this example would not print on paper unless a line feed or
carriage return is included in the printed data or unless the current print line was
full.
Starting with Release 1.8, each call to printNormal, printTwoNormal, or
printImmediate when in synchronous mode must completely print its data (that
is, no unprinted partial line of text may remain) or an exception will be raised. For
example, calling these APIs with the C- or Java-formatted strings “UnifiedPOS\n”
(text followed by a line feed) or “\x1B|3B” (escape sequence to print bitmap #3) is
correct, while “UnifiedPOS” (text without a line feed) will result in an exception.
It is recommended that the application follow this practice for all print modes.
Release 1.9 and later – Page Mode Printing
Page Mode printing support is modeled after Transaction Mode printing support,
i.e., all activities within Page Mode are handled and recovered as a single entity.
Page Mode support is designed to allow the user to dynamically compose
elaborate page printouts using the printNormal, printBitmap, and printBarcode
methods as well as additional Page Mode methods and properties. Composed
pages can be printed, saved, and modified multiple times as long as Page Mode is
active.

Device Sharing
The POS Printer is an exclusive-use device, as follows:
printer-specific properties.

972 POS Printer
POS Printer State Diagram

The following diagram illustrates the various state transitions within the POS
Printer device category.

Page Mode Printing State Diagram Added in Release 1.9

The following illustrates the various state transitions within the full Page Mode
support.
Normal
Mode pageModePrint( PTR_PM_NORMAL|PTR_PM_CANCEL )
setPageModeStation( PTR_S_RECEIPT ) / pageModePrint(PTR_PM_PAGE_MODE)
Page Mode
pageModePrint( PTR_PM_PRINT_SAVE )
printNormal/printBitmap/printBarcode
Note that when the slip station is being used in Page Mode, beginInsertion/
endInsertion should be used to control the slip handling process as normal.

974 POS Printer
“Both sides printing” sequence Diagram
The following sequence diagram is a representation of the typical usage of the

“Both sides printing” feature.
Example on how to print some string on both

side with a POSPrinter service s upporting both
sides printing.
:Client NOTE: the sequence below assumes no errors :POSPrinterControl
beginInsertion( 1000 )
endInsertion()
changePrintSide( PTR_PS_SIDE1 ) [ CapSlpBothSidesPrint == true ]

Prints "Some
String Data"
on the Side1 printNormal( PTR_S_SLIP, "Some String Data" )
of the Slip of
POSPrinter
Prints "Some changePrintSide( PTR_PS_SIDE2 ) [ CapSlpBothSidesPrint == true ]

String Data"
on the Side2 printNormal( PTR_S_SLIP, "Some String Data" )
of the Slip of
POSPrinter
beginRemoval( 5000 )
endRemoval()

Page Mode printing sequence Diagram Added in Release 1.9

Various sequence diagrams are used to illustrate how the Full Page Mode support
API can be used. These scenarios are designed to show the rationale and key
concepts behind the structure of the Page Mode API. There are two main scenarios
for Page Mode support:
• Page Mode invoked on a single station
• Page Mode invoked simultaneously on multiple stations
The following sequence diagram is a representation of Page Mode printing to a
single print station.
Application :POSPrinterControl
1: setPageModeStation(PTR_S_RECEIPT)
2: pageModePrint(PTR_PM_PAGE_MODE)
3: getPageModeArea(buffer)
4: "200,200"
5: setPageModePrintArea("1,1,100,100")
6: printNormal(PTR_S_RECEIPT, "1st line\0d\0a")
7: setPageModePrintDirection(PTR_PD_TOP_TO_BOTTOM)
8: printNormal(PTR_S_RECEIPT, "2nd Line printed Right 90\0d\0a")
9: pageModePrint(PTR_PM_NORMAL)

976 POS Printer
Data Characters and Escape Sequences Updated in Release 1.12
The default character set of all POS printers is assumed to support at least the
ASCII characters 0x20 through 0x7F, which include spaces, digits, uppercase,
lowercase, and some special characters. If the printer does not support lowercase
characters, then the Service may translate them to uppercase.
decimal, followed by a vertical bar (‘|’). This is followed by zero or more digits
and/or lowercase alphabetic characters. The escape sequence is terminated by an
In the escape sequences tables below, the digits forming a non-negative number
are denoted by the place holder “#”. If a part of the escape sequence is optional
then this part is enclosed by brackets “[...]”. E.g., the UnifiedPOS escape sequence
for paper cut is “ESC|[#]P” which means that the ‘#’ placeholder is optional. For
this pattern the escape sequence “ESC|75P” - meaning a 75% cut is requested - will
be valid as well as “ESC|P” - meaning a full cut is requested.
If a sequence does not begin with ESC “|”, or it begins with ESC “|” but is not a
valid UnifiedPOS escape sequence, the Service will make a reasonable effort to
pass it through to the printer. However, not all such sequences can be distinguished
from printable data, so unexpected results may occur.
Starting with Release 1.7, the application can use the ESC|#E escape sequence to
ensure more reliable handling of the amount of data to be passed through to the
printer. Use of this escape sequence will make an application non-portable. The
application may, however, maintain portability by performing Embedded Data
Escape sequence calls within conditional code. This code may be based upon the
value of the DeviceServiceDescription, the PhysicalDeviceDescription, or the
PhysicalDeviceName property.
NOTE: This command sequence definition and the corresponding
definition in the Point Card Reader Writer Chapter, are the only known
deviations from preserving the interchangeability of devices defined in
this specification. If an application finds it necessary to utilize this
command sequence, please inform the UnifiedPOS Committee (www.nrf-
arts.org) with the details of its usage, so that a possible standard/generic
Application Interface may be incorporated into a future release of the
UnifiedPOS Standard. In order to preserve peripheral independence and
interoperability at the Application level, it is the Committee’s position
that this command sequence should be used only as a “last resort”.
To determine if escape sequences or data can be performed on a printer station, the
application can call the validateData method. (For some escape sequences,
corresponding capability properties can also be used.) To avoid unpredictable
printing results due to escape sequence parameter scope violations or unsupported
parameter values it is recommended to verify escape sequences by calling the
validateData method.
The following escape sequences are recognized. If an escape sequence specifies an
operation that is not supported by the printer station, then it is ignored.

Commands Perform indicated action. Updated in Release 1.12
Name Data Remarks

Cuts receipt paper. The placeholder ‘#’ is replaced by an
ASCII decimal string telling the percentage cut desired. If
‘#’ is omitted, then a full cut is performed. For example:
Paper cut ESC |[#]P The C string “\x1B|75P” requests a 75% partial cut.
If the printer does not support the requested cut value then
the service implementation will choose the most suitable
cutting behavior depending on the underlying hardware.
Cuts receipt paper, after feeding the paper by the
Feed and Paper cut ESC |[#]fP RecLinesToPaperCut lines. The placeholder ‘#’ is
defined by the “Paper cut” escape sequence.
Cuts and stamps receipt paper, after feeding the paper by
Feed, Paper cut, and Stamp ESC |[#]sP the RecLinesToPaperCut lines. The placeholder ‘#’ is
defined by the “Paper cut” escape sequence.
Fires the stamp solenoid, which usually contains a
Fire stamp ESC |sL
graphical store emblem.
Prints the pre-stored bitmap. The placeholder ‘#’ is
replaced by the bitmap number. See setBitmap method.
Print bitmap ESC |#B If the given bitmap number has not been set successfully
by the setBitmap method then the printing results may be
unpredictable.
Print top logo ESC |tL Prints the pre-stored top logo.
Print bottom logo ESC |bL Prints the pre-stored bottom logo.
Feed the paper forward by lines. The placeholder ‘#’ is
Feed lines ESC |[#]lF replaced by an ASCII decimal string telling the number of
lines to be fed. If ‘#’ is omitted, then one line is fed.
Feed the paper forward by mapping mode units. The
placeholder ‘#’ is replaced by an ASCII decimal string
Feed units ESC |[#]uF
telling the number of units to be fed. If ‘#’ is omitted, then
one unit is fed.
Feed the paper backward. The placeholder ‘#’ is replaced
Feed reverse ESC |[#]rF by an ASCII decimal string telling the number of lines to
be fed. If ‘#’ is omitted, then one line is fed.
Send the following # characters of data through to the
hardware without modifying it. The placeholder '#' is
Pass through embedded data
ESC |#E replaced by an ASCII decimal string telling the number of
(See a below.)
bytes following the escape sequence that should be
passed through as-is to the hardware.
Prints the defined barcode in-line. The placeholder ‘#’ is
Print in-line barcode the number of characters following the R to use in the
ESC |#R
(See b below.) definition of the characteristics of the barcode to be
printed. See details below.
a. This escape sequence is only available in Version 1.7 and later.
b. This escape sequence is only available in Version 1.10 and later.

978 POS Printer
In-line BarCode printing Updated in Release 1.12
Starting with Release 1.10, the application can use the ESC|#R escape sequence
to print barcodes in-line with other print commands. The character ‘#’ is the
number of characters following the R to use in the definition of the characteristics
of the barcode to be printed.
In the data following the R, other lower case letters and numbers are used to
identify different values. The same value definitions as defined for the
printBarCode method headers and definitions are used for the various barcode
values. Converting to string the values from the definitions are consistent.
The attribute symbols are defined as follows:
s symbology
h height
w width
a alignment
t human readable text position
d start of data
e end of sequence
The attributes must appear in the order specified in the above list. All attributes
are mandatory. If one of these two conditions is violated or the parameters contain
unsupported values then the printing results may be unpredictable.
Using a basic UPCA, center aligned, with bottom text, 200 dots height and ~400
dots wide, the command is as follows:
ESC|33Rs101h200w400a-2t-13d123456789012e
Print Mode Characteristics that are remembered until explicitly changed.
Name Data Remarks

Selects a new typeface for the following
data. Values for the placeholder ‘#’ are:
0 = Default typeface.
1 = Select first typeface from the
FontTypefaceList property.
2 = Select second typeface from the
Font typeface selection ESC |#fT
FontTypefaceList property.
And so on.
If the given font typeface number exceeds
the number of font typefaces defined in the
FontTypefaceList property then the printing
results may be unpredictable.

Print Line Characteristics that are reset at the end of each print method, by an explicit
reset (where applicable), or by a “Normal” sequence. Updated in Release 1.12
Name Data Remarks

Prints in bold or double-strike. If ‘!’ is specified then
Bold ESC |[!]bC
bold is disabled, see a below.
Prints with underline. The placeholder ‘#’ is replaced
by an ASCII decimal string telling the thickness of the
underline in printer dot units. If ‘#’ is omitted, then a
Underline ESC |[!][#]uC
printer-specific default thickness is used. If ‘!’ is
specified then underline mode is switched off, see c
below.
Prints in italics. If ‘!’ is specified then italic is disabled,
Italic ESC |[!]iC
see a below.
Prints using an alternate custom color. The placeholder
‘#’ is replaced by an ASCII decimal string indicating
the desired color. The value of the decimal string is
equal to the value of the cartridge constant used in the
printer device properties. If ‘#’ is omitted, then the
Alternate color (Custom) ESC |[#]rC secondary color (Custom Color 1) is selected. Custom
Color 1 is usually red.
If the given color value specifies an unsupported
cartridge number then the printing results may be
unpredictable.
Prints in a reverse video format. If ‘!’ is specified then
Reverse video ESC |[!]rvC
reverse video is disabled, see a below.
Prints in a shaded manner. The placeholder ‘#’ is
replaced by an ASCII decimal string telling the
Shading ESC |[#]sC
percentage shading desired. If ‘#’ is omitted, then a
printer-specific default level of shading is used.
Single high and wide ESC |1C Prints normal size.
Double wide ESC |2C Prints double-wide characters.
Double high ESC |3C Prints double-high characters.
Double high and wide ESC |4C Prints double-high/double-wide characters.
Prints with the width scaled ‘#’ times the normal size,
Scale horizontally ESC |#hC
If the scaled printout would exceed the printable area
then the printing results may be unpredictable.
Prints with the height scaled ‘#’ times the normal size,
Scale vertically ESC |#vC
If the scaled printout would exceed the printable area
then the printing results may be unpredictable.

980 POS Printer
Prints in # color. The placeholder ‘#’ is replaced by an

ASCII decimal string indicating the additive amount of
RGB to produce the desired color. There are 3 digits
each of Red, Green, and Blue elements. Valid values
range from “000” to “255”. (E.g., “255255000”
represents yellow). Color Matching to the subtractive
RGB Color percentage of CMY (Cyan, Magenta and Yellow color
ESC |[#]fC components) to produce the desired color matching
(See b below)
specified by RGB is up to the Service. If ‘#’ is omitted,
then the primary color is used. Bitmap printing is not
affected.
If the specified RGB color element values exceed the
allowed RGB range then the printing results may be
unpredictable.
Prints SubScript characters. If ‘!’ is specified then
SubScript (See b below) ESC |[!]tbC
SubScript is disabled, see a below.
Prints SuperScript characters. If ‘!’ is specified then
SuperScript (See b below) ESC |[!]tpC
SuperScript is disabled, see a below.
Center ESC |cA Aligns following text in the center.
Right justify ESC |rA Aligns following text at the right.
Left justify (see a below) ESC |lA Aligns following text at the left.
Prints in strike-through mode. The placeholder ‘#’ is
replaced by an ASCII decimal string telling the
thickness of the strike-through in printer dot units. If
‘#’ is omitted, then a printer-specific default thickness
Strike-through
ESC |[!][#]stC is used. If ‘!’ is specified then strike-through mode is
(see c below) switched off.
If the given thickness exceeds the maximum thickness
supported by the printer then the printing results may
be unpredictable.
Normal ESC |N Restores printer characteristics to normal condition.
a. These escape sequences and variations are only available in Version 1.10 and later.
b. These escape sequences are only available in Version 1.5 and later.
c. These escape sequences and variations are only available in Version 1.12 and later.

POS Printer State Diagrams (Low Level)
Purpose:
The Low level state diagrams show a simplified, implementable flow of the
POSPrinter.
They are intended to be used by Service implementers as an example of how a
Service may be designed. It uses multiple threads of execution to separate
initiation of requests (via the POSPrinter APIs) with their processing and event
delivery.
They are also intended to be used by application developers to show more details
on processing of their API calls than can be given in the high level state diagram.
These diagrams assume:
- A separate request thread that processes print request.
Print requests are placed on a request queue (RequestQ) for the request thread to
access. The request thread has some mechanism to report request completion
and results.
- A separate event thread that delivers events.
Events are placed on an event queue (EventQ) for the event thread to access. The
event thread has some mechanism to report error event results.
Print Commands: changePrintSide, cutPaper, markFeed, printBarCode,

printBitmap, printNormal, printTwoNormal, rotatePrint.
Not Shown: Validation of APIs. If an API fails during validation, then it may
return an error result and return prematurely to the “Wait for API“ state.

982 POS Printer
POS Printer State Diagram (Low Level): API
[Opened && [Closed ||

Claimed && Released ||
Enabled] Disabled]
Wait For API
[request
/ printImmediate complete]
Print Immediate Request Complete
do { Add print request to beginning do { Raise exception
of RequestQ } if error }
/ transactionPrint (begin)
Begin Transaction
do { Init transaction buffer;
Set Transaction-Mode (TM) flag }
[(AsyncMode == false)
/ transactionPrint (end) && request complete]
End Transaction
do { Make print request from
transaction buffer; Reset TM flag }
[ no TM ] / Print Command
Print Async Request Started

do { Add print request to do { Assign & Set OutputID }
end of RequestQ }
[ TM ]
[AsyncMode == true]
/ Print Command
Print Transaction
do { Add print request to
transaction buffer }
/ clearOutput
Clear Output [request complete]

do { Add clear request to end of RequestQ; cancel TM }
/ beginInsertion [No form in before timeout ||

other failure] Insertion
Begin Insertion
Mode
do { Wait for up to app specified / beginInsertion
timeout for form in }
/ endInsertion
[Form in] / endInsertion End Insertion

do { If form in, then close “jaws”; else error}
/ beginRemoval [No form out before timeout ||

other failure] Removal
Begin Removal
Mode
do { Wait for up to app specified / beginRemoval
timeout for form out }
/ endRemoval
[Form out] / endRemoval End Removal
/ Other Command
do { If form not out, then error }
Other
do { Process command }

POS Printer State Diagram (Low Level):

Request Thread
[Started
by main [Stopped before
Service
Service terminates]
Thread]
Wait For Work
/ RequestQ: Clear
Clear
do { Stop printer; clear
RequestQ & InProgressQ;
mark as complete }
[response == clear]
[async request error]
Error Retry
do { Stop printer; do { Resend requests in
[response
enqueue ErrorEvent } the InProgressQ }
== retry]
[async request done]

false]
ode ==
[A syncM
Done
do { Set print request [Asyn
cMod
result; mark as complete; e ==
true] OutputCompleteEvent
remove from InProgressQ } do { Enqueue
[(AsyncMode == false) OutputCompleteEvent }
/ RequestQ: Print && (done || error)]
Print Request
do { Send to printer; move
from PrintQ to [AsyncMode == true]
InProgressQ }
[status change]
StatusUpdateEvent
do { Enqueue
StatusUpdateEvent }
[RequestQ Empty && FlagWhenIdle == true]
Idle SUE
do { Enqueue Idle
StatusUpdateEvent; set
FlagWhenIdle = false }

984 POS Printer
POS Printer State Diagram (Low Level):

Event Delivery Thread
[Started
by main [Stopped before
Service
Service terminates]
Thread]
Idle
[EventQ Not [EventQ

Empty] Empty]
Events to Deliver
[FreezeEvents [FreezeEvents
== false] == true]
Events to Deliver and

Events Not Frozen
[DataEvent &&
DataEventEnabled == true]
Fire DataEvent
do { Set DataEventEnabled =
false; Fire event }
[Input ErrorEvent &&

DataEventEnabled == true] Fire ErrorEvent
do { Fire event; Return response
[Output ErrorEvent] to Request Thread }
[OutputCompleteEvent ||
StatusUpdateEvent ||
DirectIOEvent] Fire Other Event
do { Fire event }

POS Printer Slip Handling State Diagram
Non-Slip Printing (Receipt and/or Journal)
/ beginInsertion
[(no form in before timeout (E_TIMEOUT)) ||

(Other failure (E_ILLEGAL, E_BUSY, E_FAILURE, etc.))]
beginInsertion (timeout)
[Form in before
timeout
(SUCCESS)] / beginInsertion Insertion
/ endInsertion Mode
endInsertion
/ endInsertion
[Form in [Failure (EPTR_SLP_EMPTY, E_FAILURE, etc.)]

(SUCCESS)]
Slip Inserted: Perform Slip Printing (printNormal, etc…)
/ beginRemoval
[(Form not out before timeout (E_TIMEOUT)) ||

(Other failure (E_ILLEGAL, E_BUSY, E_FAILURE, etc.))]
beginRemoval (timeout)
[Form out before

timeout / beginRemoval
(SUCCESS)] Removal
/ endRemoval Mode
endRemoval / endRemoval
[Form out [Failure (EPTR_SLP_FORM, E_FAILURE, etc.)]

(SUCCESS)]

986 POS Printer

AsyncMode Property
Remarks If true, then the print methods cutPaper, markFeed, printBarCode,
printBitmap, printNormal, printTwoNormal, rotatePrint, and
transactionPrint will be performed asynchronously.
If false, they will be printed synchronously.
CapCharacterSet Property Updated in Release 1.5

Remarks Holds the default character set capability. It has one of the following values:
Value Meaning
PTR_CCS_ALPHA The default character set supports uppercase alphabetic
plus numeric, space, minus, and period.
PTR_CCS_ASCII The default character set supports all ASCII characters
0x20 through 0x7F.
PTR_CCS_KANA The default character set supports partial code page 932,
including ASCII characters 0x20 through 0x7F and the
Japanese Kana characters 0xA1 through 0xDF, but
excluding the Japanese Kanji characters.
PTR_CCS_KANJI The default character set supports code page 932,
including the Shift-JIS Kanji characters, Levels 1 and 2.
PTR_CCS_UNICODE The default character set supports Unicode.

CapConcurrentJrnRec Property
Syntax CapConcurrentJrnRec: boolean { read-only, access after open }
Remarks If true, then the Journal and Receipt stations can print at the same time.
The printTwoNormal method may be used with the
PTR_TWO_RECEIPT_JOURNAL and PTR_S_JOURNAL_RECEIPT station
parameter. If false, the application should print to only one of the stations at a time,
and minimize transitions between the stations. Non-concurrent printing may be
required for reasons such as:
• Higher likelihood of error, such as greater chance of paper jams when moving
between the stations.
• Higher performance when each station is printed separately.
CapConcurrentJrnSlp Property
Syntax CapConcurrentJrnSlp: boolean { read-only, access after open }
Remarks If true, then the Journal and Slip stations can print at the same time. The
printTwoNormal method may be used with the
PTR_TWO_RECEIPT_JOURNAL and PTR_S_JOURNAL_SLIP station
parameter. If false, the application must use the sequence beginInsertion/
endInsertion followed by print requests to the Slip followed by beginRemoval/
endRemoval before printing on the Journal. Non-concurrent printing may be
• Physical constraints, such as the Slip form being placed in front of the Journal
station.
CapConcurrentPageMode Property Added in Release 1.9

Syntax CapConcurrentPageMode: boolean { read-only, access after open }
Remarks If true, then the printer is capable of supporting Page Mode concurrently for both
the receipt and slip stations. If Page Mode is not supported on either station, only
on one station, or only on one station at a time, then this value should be false.

988 POS Printer
CapConcurrentRecSlp Property
Syntax CapConcurrentRecSlp: boolean { read-only, access after open }
Remarks If true, then the Receipt and Slip stations can print at the same time. The
printTwoNormal method may be used with the
PTR_TWO_RECEIPT_JOURNAL and PTR_S_RECEIPT_SLIP station
parameter. If false, the application must use the sequence beginInsertion/
endInsertion followed by print requests to the Slip followed by beginRemoval/
endRemoval before printing on the Receipt. Non-concurrent printing may be
• Physical constraints, such as the Slip form being placed in front of the Receipt
station.
CapCoverSensor Property
Syntax CapCoverSensor: boolean { read-only, access after open }
Remarks If true, then the printer has a “cover open” sensor.
CapJrn2Color Property
Syntax CapJrn2Color: boolean { read-only, access after open }
Remarks If true, then the journal can print dark plus an alternate color.
CapJrnBold Property
Syntax CapJrnBold: boolean { read-only, access after open }
Remarks If true, then the journal can print bold characters.

CapJrnCartridgeSensor Property Added in Release 1.5

Syntax CapJrnCartridgeSensor: int32 { read-only, access after open}
Remarks This bit mapped parameter is used to indicate the presence of Journal Cartridge
monitoring sensors.
If CapJrnPresent is false, this property is “0”. Otherwise it is a logical OR
combination of any of the following values:
Value Meaning
PTR_CART_REMOVED There is a function to indicate that the Cartridge
has been removed.
PTR_CART_EMPTY There is a function to indicate that the Cartridge
is empty.
PTR_CART_CLEANING There is a function to indicate that the head is
being cleaned.
PTR_CART_NEAREND There is a function to indicate that the color
Cartridge is near end.
Note that the above mentioned values are arranged according to their priority level.
See Also JrnCartridgeState Property, JrnCurrentCartridge Property,
CartridgeNotify Property.
CapJrnColor Property Added in Release 1.5
Syntax CapJrnColor: int32 { read-only, access after open}
Remarks This capability indicates the availability of Journal color cartridges.
If CapJrnPresent is false, this property is “0”. Otherwise, this property indicates
the supported color cartridges.
CapJrnColor is a logical OR combination of any of the following values:
Value Meaning
PTR_COLOR_PRIMARY Supports Primary Color (Usually Black)
PTR_COLOR_CUSTOM1 Supports 1st Custom Color (Secondary Color,
usually Red)
PTR_COLOR_CUSTOM2 Supports 2nd Custom Color
PTR_COLOR_CUSTOM3 Supports 3rd Custom Color
PTR_COLOR_CUSTOM4 Supports 4th Custom Color
PTR_COLOR_CYAN Supports Cyan Color for full color printing
PTR_COLOR_MAGENTA Supports Magenta Color for full color printing
PTR_COLOR_YELLOW Supports Yellow Color for full color printing
PTR_COLOR_FULL Supports Full Color.

990 POS Printer
CapJrnDhigh Property
Syntax CapJrnDhigh: boolean { read-only, access after open }
Remarks If true, then the journal can print double high characters.
CapJrnDwide Property
Syntax CapJrnDwide: boolean { read-only, access after open }
Remarks If true, then the journal can print double wide characters.
CapJrnDwideDhigh Property
Syntax CapJrnDwideDhigh: boolean { read-only, access after open }
Remarks If true, then the journal can print double high / double wide characters.
CapJrnEmptySensor Property
Syntax CapJrnEmptySensor: boolean { read-only, access after open }
Remarks If true, then the journal has an out-of-paper sensor.
CapJrnItalic Property
Syntax CapJrnItalic: boolean { read-only, access after open }
Remarks If true, then the journal can print italic characters.

CapJrnNearEndSensor Property
Syntax CapJrnNearEndSensor: boolean { read-only, access after open }
Remarks If true, then the journal has a low paper sensor.
CapJrnPresent Property
Syntax CapJrnPresent: boolean { read-only, access after open }
Remarks If true, then the journal print station is present.
CapJrnUnderline Property
Syntax CapJrnUnderline: boolean { read-only, access after open }
Remarks If true, then the journal can underline characters.
selected character set when printing data.
Property.
CapRec2Color Property
Syntax CapRec2Color: boolean { read-only, access after open }
Remarks If true, then the receipt can print dark plus an alternate color.

992 POS Printer
CapRecBarCode Property
Syntax CapRecBarCode: boolean { read-only, access after open }
Remarks If true, then the receipt has bar code printing capability.
CapRecBitmap Property
Syntax CapRecBitmap: boolean { read-only, access after open }
Remarks If true, then the receipt can print bitmaps.
CapRecBold Property
Syntax CapRecBold: boolean { read-only, access after open }
Remarks If true, then the receipt can print bold characters.
CapRecCartridgeSensor Property Added in Release 1.5
Syntax CapRecCartridgeSensor: int32 { read-only, access after open}
Remarks This bit mapped parameter is used to indicate the presence of Receipt Cartridge
monitoring sensors.
If CapRecPresent is false, this property is “0”. Otherwise it is a logical OR
Value Meaning
PTR_CART_REMOVED There is a function to indicate that the Cartridge
has been removed.
PTR_CART_EMPTY There is a function to indicate that the Cartridge
is empty.
PTR_CART_CLEANING There is a function to indicate that the head is
being cleaned.
PTR_CART_NEAREND There is a function to indicate that the color
See Also RecCartridgeState Property, RecCurrentCartridge Property,

CapRecColor Property Added in Release 1.5

Syntax CapRecColor: int32 { read-only, access after open }
Remarks This capability indicates the availability of Receipt color cartridges.
If CapRecPresent is false, this property is “0”. Otherwise, this property indicates
CapRecColor is a logical OR combination of any of the following values:
Value Meaning
usually Red)
CapRecDhigh Property
Syntax CapRecDhigh: boolean { read-only, access after open }
Remarks If true, then the receipt can print double high characters.
CapRecDwide Property
Syntax CapRecDwide: boolean { read-only, access after open }
Remarks If true, then the receipt can print double wide characters.

994 POS Printer
CapRecDwideDhigh Property
Syntax CapRecDwideDhigh: boolean { read-only, access after open }
Remarks If true, then the receipt can print double high /double wide characters.
CapRecEmptySensor Property
Syntax CapRecEmptySensor: boolean { read-only, access after open }
Remarks If true, then the receipt has an out-of-paper sensor.
CapRecItalic Property
Syntax CapRecItalic: boolean { read-only, access after open }
Remarks If true, then the receipt can print italic characters.
CapRecLeft90 Property
Syntax CapRecLeft90: boolean { read-only, access after open }
Remarks If true, then the receipt can print in a rotated 90° left mode.

CapRecMarkFeed Property Added in Release 1.5

Syntax CapRecMarkFeed: int32 { read-only, access after open }
Remarks This parameter indicates the type of mark sensed paper handling available.
CapRecMarkFeed is a logical OR combination of the following values. (The
values are identical to those used with the markFeed method.)
Value Meaning
PTR_MF_TO_TAKEUP Feed the Mark Sensed paper to the paper take-
up position.
PTR_MF_TO_CUTTER Feed the Mark Sensed paper to the autocutter
cutting position.
PTR_MF_TO_CURRENT_TOF Feed the Mark Sensed paper to the present
paper’s top of form. (Reverse feed if required)
PTR_MF_TO_NEXT_TOF Feed the Mark Sensed paper to the paper’s next
top of form.
If CapRecMarkFeed equals “0”, mark sensed paper handling is not supported.
See Also markFeed Method.
CapRecNearEndSensor Property
Syntax CapRecNearEndSensor: boolean { read-only, access after open }
Remarks If true, then the receipt has a low paper sensor.
CapRecPageMode Property Added in Release 1.9
Syntax CapRecPageMode: boolean { read-only, access after open }
Remarks If true, then the printer is capable of supporting Page Mode for the receipt station.

996 POS Printer
CapRecPapercut Property
Syntax CapRecPapercut: boolean { read-only, access after open }
Remarks If true, then the receipt can perform paper cuts.
CapRecPresent Property
Syntax CapRecPresent: boolean { read-only, access after open }
Remarks If true, then the receipt print station is present.
CapRecRight90 Property
Syntax CapRecRight90: boolean { read-only, access after open }
Remarks If true, then the receipt can print in a rotated 90° right mode.
CapRecRotate180 Property
Syntax CapRecRotate180: boolean { read-only, access after open }
Remarks If true, then the receipt can print in a rotated upside down mode.
CapRecStamp Property
Syntax CapRecStamp: boolean { read-only, access after open }
Remarks If true, then the receipt has a stamp capability.

CapRecUnderline Property
Syntax CapRecUnderline: boolean { read-only, access after open }
Remarks If true, then the receipt can underline characters.
CapSlp2Color Property
Syntax CapSlp2Color: boolean { read-only, access after open }
Remarks If true, then the slip can print dark plus an alternate color.
CapSlpBarCode Property
Syntax CapSlpBarCode: boolean { read-only, access after open }
Remarks If true, then the slip has bar code printing capability.
CapSlpBitmap Property
Syntax CapSlpBitmap: boolean { read-only, access after open }
Remarks If true, then the slip can print bitmaps.
CapSlpBold Property
Syntax CapSlpBold: boolean { read-only, access after open }
Remarks If true, then the slip can print bold characters.

998 POS Printer
CapSlpBothSidesPrint Property Added in Release 1.5

Syntax CapSlpBothSidesPrint: boolean { read-only, access after open }
Remarks If true, then the slip station can automatically print on both sides of a check, either
by flipping the check or through the use of dual print heads.
CapSlpCartridgeSensor Property Added in Release 1.5
Syntax CapSlpCartridgeSensor: int32 { read-only, access after open }
Remarks This bit mapped parameter is used to indicate the presence of Slip Cartridge
monitoring sensors.
If CapSlpPresent is false, this property is “0”. Otherwise it is a logical OR
Value Meaning
PTR_CART_REMOVED There is a function to indicate the Cartridge has
been removed.
PTR_CART_EMPTY There is a function to indicate the Cartridge is
empty.
PTR_CART_CLEANING There is a function to indicate head is being
cleaned.
PTR_CART_NEAREND There is a function to indicate the color
See Also SlpCartridgeState Property, SlpCurrentCartridge Property,

CapSlpColor Property Added in Release 1.5

Syntax CapSlpColor: int32 { read-only, access after open }
Remarks This capability indicates the availability of Slip printing color cartridges.
If CapSlpPresent is false, this property is “0”. Otherwise, this property indicates
CapSlpColor is a logical OR combination of any of the following values:
Value Meaning
usually Red)
CapSlpDhigh Property
Syntax CapSlpDhigh: boolean { read-only, access after open }
Remarks If true, then the slip can print double high characters.
CapSlpDwide Property
Syntax CapSlpDwide: boolean { read-only, access after open }
Remarks If true, then the slip can print double wide characters.

1000 POS Printer
CapSlpDwideDhigh Property
Syntax CapSlpDwideDhigh: boolean { read-only, access after open }
Remarks If true, then the slip can print double high / double wide characters.
CapSlpEmptySensor Property
Syntax CapSlpEmptySensor: boolean { read-only, access after open }
Remarks If true, then the slip has a “slip in” sensor.
CapSlpFullslip Property
Syntax CapSlpFullslip: boolean { read-only, access after open }
Remarks If true, then the slip is a full slip station. It can print full-length forms. If false, then
the slip is a “validation” type station. This usually limits the number of print lines,
and disables access to the receipt and/or journal stations while the validation slip
is being used.
CapSlpItalic Property
Syntax CapSlpItalic: boolean { read-only, access after open }
Remarks If true, then the slip can print italic characters.
CapSlpLeft90 Property
Syntax CapSlpLeft90: boolean { read-only, access after open }
Remarks If true, then the slip can print in a rotated 90° left mode.

CapSlpNearEndSensor Property
Syntax CapSlpNearEndSensor: boolean { read-only, access after open }
Remarks If true, then the slip has a “slip near end” sensor.
CapSlpPageMode Property Added in Release 1.9
Syntax CapSlpPageMode: boolean { read-only, access after open }
Remarks If true, then the printer is capable of supporting Page Mode for the slip station.
CapSlpPresent Property
Syntax CapSlpPresent: boolean { read-only, access after open }
Remarks If true, then the slip print station is present.
CapSlpRight90 Property
Syntax CapSlpRight90: boolean { read-only, access after open }
Remarks If true, then the slip can print in a rotated 90° right mode.
CapSlpRotate180 Property
Syntax CapSlpRotate180: boolean { read-only, access after open }
Remarks If true, then the slip can print in a rotated upside down mode.

1002 POS Printer
CapSlpUnderline Property
Syntax CapSlpUnderline: boolean { read-only, access after open }
Remarks If true, then the slip can underline characters.
Remarks If true, then printer transactions are supported by each station.
CartridgeNotify Property Added in Release 1.5
Syntax CartridgeNotify: int32 { read-write, access after open }
Remarks Contains the type of cartridge state notification selected by the application.
The CartridgeNotify values are:
Value Meaning
PTR_CN_DISABLED The Control will not provide any cartridge state
notifications to the application or set any cartridge
related ErrorCodeExtended values. No cartridge state
notification StatusUpdateEvents will be fired, and
JrnCartridgeState, RecCartridgeState, and
SlpCartridgeState may not be set.
PTR_CN_ENABLED The Control will fire cartridge state notification
StatusUpdateEvents and update JrnCartridgeState,
RecCartridgeState and SlpCartridgeState, beginning
when DeviceEnabled is set true. The level of
functionality depends upon CapJrnCartridgeSensor,
CapRecCartridgeSensor and
CapSlpCartridgeSensor.
CartridgeNotify may only be set while the device is disabled, that is, while
This property is initialized to PTR_CN_DISABLED by the open method. This
value provides compatibility with earlier releases.

Value Meaning
The device is already enabled.
CapJrnCartridgeSensor, CapRecCartridgeSensor,
and CapSlpCartridgeSensor = “0”.
See Also CapJrnCartridgeSensor Property, CapRecCartridgeSensor Property,
CapSlpCartridgeSensor Property, JrnCartridgeState Property,
RecCartridgeState Property, SlpCartridgeState Property.

Remarks Holds the character set for printing characters. It has one of the following values:
Value Meaning
PTR_CS_UNICODE The character set supports Unicode. The value of this
constant is 997.
PTR_CS_ASCII The ASCII character set, supporting the ASCII
constant is 998.
PTR_CS_ANSI The ANSI character set. The value of this constant is
999.
method.
See Also CharacterSetList Property.

1004 POS Printer
Remarks Holds the character set numbers. It consists of ASCII numeric set numbers
separated by commas.
For example, if the string is “101,850,999”, then the device supports a device-
CoverOpen Property
Syntax CoverOpen: boolean { read-only, access after open-claim-enable }
Remarks If true, then the printer’s cover is open.
If CapCoverSensor is false, then the printer does not have a cover open sensor,
and this property always returns false.
ErrorLevel Property
Syntax ErrorLevel: int32 { read-only, access after open }
Remarks Holds the severity of the error condition. It has one of the following values:
Value Meaning
PTR_EL_NONE No error condition is present.
PTR_EL_RECOVERABLE
A recoverable error has occurred.
(Example: Out of paper.)
PTR_EL_FATAL A non-recoverable error has occurred.
(Example: Internal printer failure.)
This property is set just before delivering an ErrorEvent. When the error is
cleared, then the property is changed to PTR_EL_NONE.

ErrorStation Property
Syntax ErrorStation: int32 { read-only, access after open }
Remarks Holds the station or stations that were printing when an error was detected.
This property will be set to one of the following values:
PTR_S_JOURNAL PTR_S_RECEIPT
PTR_S_SLIP PTR_S_JOURNAL_RECEIPT
PTR_S_JOURNAL_SLIP PTR_S_RECEIPT_SLIP
PTR_TWO_RECEIPT_JOURNAL PTR_TWO_SLIP_JOURNAL
PTR_TWO_SLIP_RECEIPT
This property is only valid if the ErrorLevel is not equal to PTR_EL_NONE. It is
set just before delivering an ErrorEvent.
Remarks Holds a vendor-supplied description of the current error.
This property is set just before delivering an ErrorEvent. If no description is
available, the property is set to an empty string. When the error is cleared, then the
property is changed to an empty string.

1006 POS Printer
FontTypefaceList Property
Syntax FontTypefaceList: string { read-only, access after open }
Remarks Holds the fonts and/or typefaces that are supported by the printer. The string
consists of font or typeface names separated by commas. The application selects a
font or typeface for a printer station by using the font typeface selection escape
sequence (ESC |#fT). The “#” character is replaced by the number of the font or
typeface within the list: 1, 2, and so on.
In Japan, this property will frequently include the fonts “Mincho” and “Gothic.”
Other fonts or typefaces may be commonly supported in other countries.
An empty string indicates that only the default typeface is supported.
JrnCartridgeState Property Added in Release 1.5

Syntax JrnCartridgeState: int32 { read-only, access after open-claim-enable }
Remarks This property contains the status of the currently selected Journal cartridge (ink,
ribbon or toner).
It contains one of the following values:
Value Meaning
PTR_CART_UNKNOWN Cannot determine the cartridge state, for one of
the following reasons:
CapJrnCartridgeSensor = “0”.
Device does not support cartridge state
reporting.
CartridgeNotify = PTR_CN_DISABLED.
Cartridge state notifications are disabled.
DeviceEnabled = FALSE.
Cartridge state monitoring does not occur until
the device is enabled.
PTR_CART_REMOVED The cartridge selected by JrnCurrentCartridge
has been removed.
PTR_CART_EMPTY The cartridge selected by JrnCurrentCartridge
is empty.
PTR_CART_CLEANING The head selected by JrnCurrentCartridge is
being cleaned.
PTR_CART_NEAREND The cartridge selected by JrnCurrentCartridge
is near end.
PTR_CART_OK The cartridge selected by JrnCurrentCartridge
is in normal condition.

See Also JrnCurrentCartridge Property, CapJrnCartridgeSensor Property,
JrnCurrentCartridge Property Updated in Release 1.9

Syntax JrnCurrentCartridge: int32 { read-write, access after open-claim-enable }
Remarks This property specifies the currently selected Journal cartridge.
method call. If CapJrnPresent is false, this property is initialized to zero.
Otherwise, this value is guaranteed to be one of the color cartridges specified by
the CapJrnColor property. (PTR_COLOR_FULL cannot be set.)
Setting JrnCurrentCartridge may also update JrnCartridgeState.
Value Meaning
See Also CapJrnPresent property, JrnCartridgeState Property.
JrnEmpty Property
Syntax JrnEmpty: boolean { read-only, access after open-claim-enable }
Remarks If true, the journal is out of paper. If false, journal paper is present.
If CapJrnEmptySensor is false, then the value of this property is always false.
See Also JrnNearEnd Property.
JrnLetterQuality Property
Syntax JrnLetterQuality: boolean { read-write, access after open-claim-enable }
Remarks If true, prints in high quality mode. If false, prints in high speed mode.
This property advises the Service that either high quality or high speed printing is
desired. For example, printers with bi-directional print capability may be placed in
unidirectional mode for high quality, so that column alignment is more precise.
Setting this property may also update JrnLineWidth, JrnLineHeight, and

1008 POS Printer
JrnLineSpacing if MapMode is PTR_MM_DOTS. (See the footnote at

MapMode.)
This property is initialized to false when the device is first enabled following the
open method.
JrnLineChars Property
Syntax JrnLineChars: int32 { read-write, access after open-claim-enable }
Remarks Holds the number of characters that may be printed on a journal line.
If changed to a line character width that is less than or equal to the maximum value
allowed for the printer, then the width is set to the specified value. If the exact
width cannot be supported, then subsequent lines will be printed with a character
size that most closely supports the specified characters per line. (For example, if
set to 36 and the printer can print either 30 or 40 characters per line, then the
Service should select the 40 characters per line size and print only up to 36
characters per line.)
If the character width is greater than the maximum value allowed for the printer,
then an exception is thrown. (For example, if set to 42 and the printer can print
either 30 or 40 characters per line, then the Service cannot support the request.)
Setting this property may also update JrnLineWidth, JrnLineHeight, and
JrnLineSpacing, since the character pitch or font may be changed.
This property is initialized to the printer’s default line character width when the
device is first enabled following the open method.
See Also JrnLineCharsList Property.
JrnLineCharsList Property
Syntax JrnLineCharsList: string { read-only, access after open }
Remarks Holds the line character widths supported by the journal station. The string
consists of ASCII numeric set numbers separated by commas.
For example, if the string is “32,36,40”, then the station supports line widths of 32,
36, and 40 characters.
See Also JrnLineChars Property.

JrnLineHeight Property
Syntax JrnLineHeight: int32 { read-write, access after open-claim-enable }
Remarks Holds the journal print line height. Expressed in the unit of measure given by
MapMode.
When JrnLineChars is changed, this property is updated to the default line height
for the selected width.
This property is initialized to the printer’s default line height when the device is
JrnLineSpacing Property
Syntax JrnLineSpacing: int32 { read-write, access after open-claim-enable }
Remarks Holds the spacing of each single-high print line, including both the printed line
height plus the whitespace between each pair of lines. Depending upon the printer
and the current line spacing, a multi-high print line might exceed this value. Line
spacing is expressed in the unit of measure given by MapMode.
If changed to a spacing that can be supported by the printer, then the line spacing
is set to this value. If the spacing cannot be supported, then the spacing is set to the
closest supported value.
When JrnLineChars or JrnLineHeight is changed, this property is updated to
the default line spacing for the selected width or height.
This property is initialized to the printer’s default line spacing when the device is
JrnLineWidth Property
Syntax JrnLineWidth: int32 { read-only, access after open-claim-enable }
Remarks Holds the width of a line of JrnLineChars characters. Expressed in the unit of
Setting JrnLineChars may also update this property.
This property is initialized to the printer’s default line width when the device is

1010 POS Printer
JrnNearEnd Property
Syntax JrnNearEnd: boolean { read-only, access after open-claim-enable }
Remarks If true, the journal paper is low. If false, journal paper is not low.
If CapJrnNearEndSensor is false, then this property is always false.
See Also JrnEmpty Property.
CharacterSet property for printing data.
MapMode Property
Syntax MapMode: int32 { read-write, access after open }
Remarks Holds the mapping mode of the printer. The mapping mode defines the unit of
measure used for other properties, such as line heights and line spacings. It has one
Value Meaning
PTR_MM_DOTS The printer’s dot width. This width may be different for
each printer station.1
PTR_MM_TWIPS 1/1440 of an inch.
PTR_MM_ENGLISH 0.001 inch.
PTR_MM_METRIC 0.01 millimeter.
Setting this property may also change JrnLineHeight, JrnLineSpacing,
JrnLineWidth, RecLineHeight, RecLineSpacing, RecLineWidth,
SlpLineHeight, SlpLineSpacing, and SlpLineWidth.
1. From the POS Printer perspective, the exact definition of a “dot” is not significant. It is a
Printer/Service unit used to express various metrics. For example, some printers define a “half-
dot” that is used in high-density graphics printing, and perhaps in text printing. A POS Printer
Service may handle this case in one of these ways:
(a) Consistently define a “dot” as the printer’s smallest physical size, that is, a half-dot.
(b) If the Service changes bitmap graphics printing density based on the XxxLetterQuality
setting, then alter the size of a dot to match the bitmap density (that is, a physical printer
dot when false and a half-dot when true). Note that this choice should not be used if the
printer’s text metrics are based on half-dot sizes, since accurate values for the metrics may
not then be possible.

This property is initialized to PTR_MM_DOTS when the device is first enabled

PageModeArea Property Added in Release 1.9
Syntax PageModeArea: string { read-only, access after open }
Remarks Holds the page area for the selected PageModeStation expressed in the unit of
measure given by MapMode. This page area can be different than the print area
and is determined by the hardware capability of the printer. The string consists of
two ASCII numbers separated by a comma, in the following order: horizontal size,
vertical size.
For example, if the string is “450,800”, then the page size is 450 horizontal units
by 800 vertical units, and the station print area is a rectangle beginning at the top
left point (0,0), and continuing up to but not including the bottom right point
(450,800).
The PageModeStation property must be set to a valid station before accessing this
property, otherwise an empty string is returned.
See Also MapMode Property, PageModeStation Property.
PageModeDescriptor Property Added in Release 1.9

Syntax PageModeDescriptor: int32 { read-only, access after open }
Remarks This is a bitmask indicating the basic Page Mode functionality of the printer for
the selected PageModeStation.
Value Meaning
PTR_PM_BITMAP Printing of bitmaps on the PageModeStation is
supported
PTR_PM_BARCODE Printing of barcodes on the PageModeStation is
supported
PTR_PM_BM_ROTATE
Rotation of bitmaps on the PageModeStation is
supported
PTR_PM_BC_ROTATE
Rotation of barcodes on the PageModeStation is
supported
PTR_PM_OPAQUE Text, graphics, and background are opaque, meaning
items already placed on the page area in the specified
print area will not be visible after being printed over.
property, otherwise the value zero (0) is returned.
See Also PageModeStation Property.

1012 POS Printer
PageModeHorizontalPosition Property Added in Release 1.9

Syntax PageModeHorizontalPosition: int32 { read-write, access after open }
Remarks Holds the horizontal start position offset within the print area for the selected
PageModeStation, expressed in the unit of measure given by MapMode.
The horizontal direction is the same as the actual PageModePrintDirection
property. If the exact position cannot be supported then the position is set to the
A read/get on this property will return the horizontal position offset set by the last
write/set and not the current position. The PageModeStation property must be set
to a valid station before accessing this property, otherwise the value zero (0) is
returned.
The following code sample shows usage of PageModeHorizontalPosition.
myptr.setMapMode(PTR_MM_ENGLISH);
myptr.setPageModeStation(PTR_S_RECEIPT);
myptr.pageModePrint(PTR_PM_PAGE_MODE);
// Set print area to 2 inches by 0.5 inches
myptr.setPageModePrintArea(“0,0,2000,500”);
myptr.setPageModePrintDirection(PTR_PD_LEFT_TO_RIGHT);
myptr.setPageModeHorizontalPosition(1500);
myptr.printNormal(PTR_S_RECEIPT, “123456789012345678901234567890\n”);
The above code sample will generate the following receipt.
PageModeHorizontalPosition = 1.5 inches 123456789

012345678901234567890 0.5 inches
2 inches
See Also MapMode Property, PageModePrintDirection Property, PageModeStation
Property.
PageModePrintArea Property Added in Release 1.9

Syntax PageModePrintArea: string { read-write, access after open }
Remarks Holds the print area for the selected PageModeStation expressed in the unit of
measure given by MapMode. The maximum print area is the page area.
The string consists of four ASCII numbers separated by commas, in the following
order: horizontal start, vertical start, horizontal size, vertical size. For example, if
the string is “50,100,200,400”, then the station print area is a rectangle beginning
at the point (50,100), and continuing up to but not including the point (250,500).
This property is initialized to “0,0,0,0”.

Text written to the right edge of the print area will wrap to the next line. Any text
or image written beyond the bottom of the print area will be truncated. For
example:
// Set print area to half inch square block
myptr.printNormal(PTR_S_RECEIPT,“123456789012345678901234567890\n”);
12345678
90123456 0.5 inches
78901234
0.5 inches
property, otherwise an empty string is returned.
See Also MapMode Property, PageModeStation Property.
PageModePrintDirection Property Added in Release 1.9

Syntax PageModePrintDirection: int32 { read-write, access after open }
Remarks Holds the print direction. The print direction shall be as follows:
Value Meaning
PTR_PD_LEFT_TO_RIGHT Print left to right, starting at top left position of
the print area, i.e., normal printing.
PTR_PD_BOTTOM_TO_TOP Print bottom to top, starting at the bottom left
position of the print area, i.e., rotated left 90°
printing.
PTR_PD_RIGHT_TO_LEFT Print right to left, starting at the bottom right
position of the print area, i.e., upside down
printing.
PTR_PD_TOP_TO_BOTTOM Print top to bottom, starting at the top right
position of the print area, i.e., rotated right 90°
printing.
This property is initialized to PTR_PD_LEFT_TO_RIGHT when the device is

1014 POS Printer
Setting this property may also change PageModeHorizontalPosition and

PageModeVerticalPosition. Setting this property will have an effect on the
current print area. By changing the print area, it is possible to generate a receipt or
slip with text printed in multiple rotations. For example:
// Set print area to half inch square block
myptr.setPageModePrintDirection(PTR_PD_BOTTOM_TO_TOP);
myptr.setPageModePrintDirection(PTR_PD_RIGHT_TO_LEFT);
myptr.setPageModePrintDirection(PTR_PD_TOP_TO_BOTTOM);
78901234
90123456
12345678
12345678
90123456
78901234
12345678
78901234
90123456 0.5 inches
90123456
78901234
12345678
0.5 inches 0.5 inches 0.5 inches 0.5 inches
It is also possible to generate rotated text.

myptr.pageModeVerticalPosition(100);
myptr.pageModeHorizontalPosition(200);
myptr.printNormal(PTR_S_RECEIPT, “Normal print.\n”);
myptr.setPageModePrintDirection(PTR_PD_TOP_TP_BOTTOM);
myptr.printNormal(PTR_S_RECEIPT, “Rotated right 90 print.\n”);
myptr.setPageModePrint(PTR_PM_NORMAL);


PageModeVerticalPosition = 0.1 inches
90 print.
ed right
Normal print. 0.5 inches
Rotat
1.0 inch 1.0 inch
PageModeHorizontalPosition = 0.2 inches
See Also PageModeHorizontalPosition Property, PageModeStation Property,
PageModeVerticalPosition Property.
PageModeStation Property Added in Release 1.9

Syntax PageModeStation: int32 { read-write, access after open }
Remarks Set the print station for subsequent Page Mode properties. Note that
pageModePrint will allow for the selection of the print station that the output will
be generated on. This value will only contain one Page Mode station at a time,
PTR_S_RECEIPT or PTR_S_SLIP. If Page Mode is not supported on any station,
the value should be zero. To control Page Mode for more than one station, this
value will need to be changed between the stations.
This property is initialized to zero by the open method, and must be set to a valid
value before Page Mode properties or methods are used.
See Also pageModePrint Method.

1016 POS Printer
PageModeVerticalPosition Property Added in Release 1.9

Syntax PageModeVerticalPosition: int32 { read-write, access after open }
Remarks Holds the vertical start position offset within the print area for the selected
PageModeStation, expressed in the unit of measure given by MapMode. The
vertical direction is perpendicular to the direction specified in the actual
PageModePrintDirection property. If the exact position cannot be supported then
the position is set to the closest supported value. A read/get on this property will
return the vertical position offset set by the last write/set and not the current
position.
The following code sample shows usage of PageModeVerticalPosition.
// Set print area to 2 inches by 0.5 inches
myptr.setPageModeVerticalPosition(250);
PageModeVerticalPosition = 0.25 inches

0.5 inches
123456789012345678901234567890
2 inches
See Also MapMode Property, PageModePrintDirection Property, PageModeStation
Property.

RecBarCodeRotationList Property Updated in Release 1.7

Syntax RecBarCodeRotationList: string { read-only, access after open }
Remarks Holds the directions in which a receipt bar code may be rotated. The string consists
of rotation strings separated by commas. An empty string indicates that bar code
printing is not supported. The legal rotation strings are:
Value Meaning
0 Bar code may be printed in the normal orientation.
R90 Bar code may be rotated 90° to the right.
L90 Bar code may be rotated 90° to the left.
180 Bar code may be rotated 180° - upside down.
For example, if the string is “0,180”, then the printer can print normal bar codes
and upside down bar codes.
See Also RotateSpecial Property, printBarCode Method, rotatePrint Method.
RecBitmapRotationList Property Added in Release 1.7

Syntax RecBitmapRotationList: string { read-only, access after open }
Remarks Holds the directions in which a receipt bitmap may be rotated. The string consists
of rotation strings separated by commas. An empty string indicates that bitmap
Value Meaning
0 Bitmap may be printed in the normal orientation.
R90 Bitmap may be rotated 90° to the right.
L90 Bitmap may be rotated 90° to the left.
180 Bitmap may be rotated 180° - upside down.
For example, if the string is “0,180”, then the printer can print normal bitmaps and
upside down bitmaps.
See Also printBitmap Method, rotatePrint Method.

1018 POS Printer
RecCartridgeState Property Added in Release 1.5

Syntax RecCartridgeState: int32 { read-only, access after open-claim-enable }
Remarks This property contains the status of the currently selected Receipt cartridge (ink,
ribbon or toner).
Value Meaning
CapRecCartridgeSensor = “0”.
reporting.
PTR_CART_REMOVED The cartridge selected by
RecCurrentCartridge has been removed.
PTR_CART_EMPTY The cartridge selected by
RecCurrentCartridge is empty.
PTR_CART_CLEANING The head selected by RecCurrentCartridge is
being cleaned.
PTR_CART_NEAREND The cartridge selected by
RecCurrentCartridge is near end.
PTR_CART_OK The cartridge selected by
RecCurrentCartridge is in normal condition.
See Also RecCurrentCartridge Property, CapRecCartridgeSensor Property,
RecCurrentCartridge Property Updated in Release 1.9

Syntax RecCurrentCartridge: int32 { read-write, access after open-claim-enable }
Remarks This property specifies the currently selected Receipt cartridge.
method call. If CapRecPresent is false, this property is initialized to zero.
the CapRecColor property. (PTR_COLOR_FULL cannot be set.)
Setting RecCurrentCartridge may also update RecCartridgeState.

Value Meaning
See Also CapRecPresent property, RecCartridgeState Property.
RecEmpty Property
Syntax RecEmpty: boolean { read-only, access after open-claim-enable }
Remarks If true, the receipt is out of paper. If false, receipt paper is present.
If CapRecEmptySensor is false, then this property is always false.
See Also RecNearEnd Property.
RecLetterQuality Property
Syntax RecLetterQuality: boolean { read-write, access after open-claim-enable }
This property advises the Service that either high quality or high speed printing is
desired. For example:
• Printers with bi-directional print capability may be placed in unidirectional
mode for high quality, so that column alignment is more precise.
• Bitmaps may be printed in a high-density graphics mode for high-quality, and
in a low-density mode for high speed.
Setting this property may also update RecLineWidth, RecLineHeight, and
RecLineSpacing if MapMode is PTR_MM_DOTS. (See the footnote at
MapMode.)
open method.
See Also MapMode Property, RecLineHeight Property, RecLineSpacing Property,
RecLineWidth Property.

1020 POS Printer
RecLineChars Property
Syntax RecLineChars: int32 { read-write, access after open-claim-enable }
Remarks Holds the number of characters that may be printed on a receipt line.
size that most closely supports the specified characters per line. (For example, if
set to 36 and the printer can print either 30 or 40 characters per line, then the
Service should select the 40 characters per line size and print only up to 36
characters per line.)
then an exception is thrown. (For example, if set to 42 and the printer can print
either 30 or 40 characters per line, then the Service cannot support the request.)
Setting this property may also update RecLineWidth, RecLineHeight, and

RecLineSpacing, since the character pitch or font may be changed.
See Also RecLineCharsList Property.
RecLineCharsList Property
Syntax RecLineCharsList: string { read-only, access after open }
Remarks Holds the line character widths supported by the receipt station. The string consists
of ASCII numeric set numbers, separated by commas.
See Also RecLineChars Property.

RecLineHeight Property
Syntax RecLineHeight: int32 { read-write, access after open-claim-enable }
Remarks Holds the receipt print line height, expressed in the unit of measure given by
MapMode.
When RecLineChars is changed, this property is updated to the default line height
See Also RecLineChars Property.
RecLineSpacing Property
Syntax RecLineSpacing: int32 { read-write, access after open-claim-enable }
When RecLineChars or RecLineHeight are changed, this property is updated to
This property is initialized to the printer’s default line spacing when the device is
RecLinesToPaperCut Property
Syntax RecLinesToPaperCut: int32 { read-only, access after open-claim-enable }
Remarks Holds the number of lines that must be advanced before the receipt paper is cut.
If CapRecPapercut is true, then this is the line count before reaching the paper
cut mechanism. Otherwise, this is the line count before the manual tear-off bar.
Changing the properties RecLineChars, RecLineHeight, and RecLineSpacing
may cause this property to change.
method.

1022 POS Printer
RecLineWidth Property
Syntax RecLineWidth: int32 { read-only, access after open-claim-enable }
Remarks Holds the width of a line of RecLineChars characters, expressed in the unit of
Setting RecLineChars may also update this property.
RecNearEnd Property
Syntax RecNearEnd: boolean { read-only, access after open-claim-enable }
Remarks If true, the receipt paper is low. If false, receipt paper is not low.
If CapRecNearEndSensor is false, then this property is always false.
See Also RecEmpty Property.
RecSidewaysMaxChars Property
Syntax RecSidewaysMaxChars: int32 { read-only, access after open-claim-enable }
sideways mode.
If CapRecLeft90 and CapRecRight90 are both false, then this property is zero.
Changing the properties RecLineHeight, RecLineSpacing, and RecLineChars
method.
See Also RecSidewaysMaxLines Property.

RecSidewaysMaxLines Property
Syntax RecSidewaysMaxLines: int32 { read-only, access after open-claim-enable }
If CapRecLeft90 and CapRecRight90 are both false, then this property is zero.
Changing the properties RecLineHeight, RecLineSpacing, and RecLineChars
method.
See Also RecSidewaysMaxChars Property.
RotateSpecial Property
Syntax RotateSpecial: int32 { read-write, access after open }
Remarks Holds the rotation orientation for bar codes. It has one of the following values:
Value Meaning
PTR_RP_NORMAL Print subsequent bar codes in normal orientation.
PTR_RP_RIGHT90 Rotate printing 90° to the right (clockwise)
PTR_RP_LEFT90 Rotate printing 90° to the left (counter-clockwise)
PTR_RP_ROTATE180 Rotate printing 180°, that is, print upside-down
This property is initialized to PTR_RP_NORMAL by the open method.
See Also printBarCode Method.
SlpBarCodeRotationList Property Updated in Release 1.7

Syntax SlpBarCodeRotationList: string { read-only, access after open }
Remarks Holds the directions in which a slip barcode may be rotated. The string consists of
rotation strings separated by commas. An empty string indicates that bar code
Value Meaning
0 Bar code may be printed in the normal orientation.
R90 Bar code may be rotated 90° to the right.
L90 Bar code may be rotated 90° to the left.
180 Bar code may be rotated 180° - upside down.
For example, if the string is “0,180”, then the printer can print normal bar codes
and upside down bar codes.
See Also RotateSpecial Property, printBarCode Method, rotatePrint Method.

1024 POS Printer
SlpBitmapRotationList Property Added in Release 1.7

Syntax SlpBitmapRotationList: string { read-only, access after open }
Remarks Holds the directions in which a slip bitmap may be rotated. The string consists of
rotation strings separated by commas. An empty string indicates that bitmap
Value Meaning
0 Bitmap may be printed in the normal orientation.
R90 Bitmap may be rotated 90° to the right.
L90 Bitmap may be rotated 90° to the left.
180 Bitmap may be rotated 180° - upside down.
For example, if the string is “0,180”, then the printer can print normal bitmaps and
upside down bitmaps.
See Also printBitmap Method, rotatePrint Method.
SlpCartridgeState Property Added in Release 1.5

Syntax SlpCartridgeState: int32 { read-only, access after open-claim-enable }
Remarks This property contains the status of the currently selected Slip cartridge (ink,
ribbon or toner).
Value Meaning
CapSlpCartridgeSensor = “0”.
reporting.
PTR_CART_REMOVED The cartridge selected by
SlpCurrentCartridge has been removed.
PTR_CART_EMPTY The cartridge selected by
SlpCurrentCartridge is empty.
PTR_CART_CLEANING The head selected by SlpCurrentCartridge is
being cleaned.
PTR_CART_NEAREND The cartridge selected by
SlpCurrentCartridge is near end.
PTR_CART_OK The cartridge selected by
SlpCurrentCartridge is in normal condition.

See Also SlpCurrentCartridge Property, CapSlpCartridgeSensor Property,
SlpCurrentCartridge Property Updated in Release 1.9

Syntax SlpCurrentCartridge: int32 { read-write, access after open-claim-enable }
Remarks This property specifies the currently selected slip cartridge.
method call. If CapSlpPresent is false, this property is initialized to zero.
the CapSlpColor property. (PTR_COLOR_FULL cannot be set.)
Setting SlpCurrentCartridge may also update SlpCartridgeState.
Value Meaning
See Also CapSlpPresent property, SlpCartridgeState Property.
SlpEmpty Property
Syntax SlpEmpty: boolean { read-only, access after open-claim-enable }
Remarks If true, a slip form is not present. If false, a slip form is present.
If CapSlpEmptySensor is false, then this property is always false.
Note
The “slip empty” sensor should be used primarily to determine whether a form has been
inserted before printing, and can be monitored to determine whether a form is still in place.
This sensor is usually placed one or more print lines above the slip print head.
However, the “slip near end” sensor (when present) should be used to determine when
nearing the end of the slip. This sensor is usually placed one or more print lines below the
slip print head.
See Also SlpNearEnd Property.

1026 POS Printer
SlpLetterQuality Property
Syntax SlpLetterQuality: boolean { read-write, access after open-claim-enable }
This property advises that either high quality or high speed printing is desired.
For example:
• Printers with bi-directional print capability may be placed in unidirectional
mode for high quality, so that column alignment is more precise.
• Bitmaps may be printed in a high-density graphics mode for high-quality, and
in a low-density mode for high speed.
Setting this property may also update SlpLineWidth, SlpLineHeight, and
SlpLineSpacing if MapMode is PTR_MM_DOTS. (See the footnote at
MapMode.)
open method.
SlpLineChars Property
Syntax SlpLineChars: int32 { read-write, access after open-claim-enable }
Remarks Holds the number of characters that may be printed on a slip line.
size that most closely supports the specified characters per line. (The Service
should print the requested characters in the column positions closest to the side of
the slip table at which the slip is aligned. (For example, if the operator inserts the
slip with the right edge against the table side and if SlpLineChars is set to 36 and
the printer prints 60 characters per line, then the Service should add 24 spaces at
the left margin and print the characters in columns 25 through 60.)
then an exception is thrown. (For example, if set to 65 and the printer can only print
60 characters per line, then the Service cannot support the request.)
Setting this property may also update SlpLineWidth, SlpLineHeight, and
SlpLineSpacing, since the character pitch or font may be changed.
See Also SlpLineCharsList Property.

SlpLineCharsList Property
Syntax SlpLineCharsList: string { read-only, access after open }
Remarks Holds the line character widths supported by the slip station. The string consists of
ASCII numeric set numbers, separated by commas.
See Also SlpLineChars Property.
SlpLineHeight Property
Syntax SlpLineHeight: int32 { read-write, access after open-claim-enable }
Remarks Holds the slip print-line height, expressed in the unit of measure given by
MapMode.
When SlpLineChars is changed, this property is updated to the default line height
See Also SlpLineChars Property.
SlpLinesNearEndToEnd Property.
Syntax SlpLinesNearEndToEnd: int32 { read-only, access after open-claim-enable }
Remarks Holds the number of lines that may be printed after the “slip near end” sensor is
true but before the printer reaches the end of the slip.
This property may be used to optimize the use of the slip, so that the maximum
number of lines may be printed.
Changing the SlpLineHeight, SlpLineSpacing, or SlpLineChars properties may
cause this property to change.
method.
See Also SlpEmpty Property, SlpNearEnd Property.

1028 POS Printer
SlpLineSpacing Property
Syntax SlpLineSpacing: int32 { read-write, access after open-claim-enable }
When SlpLineChars or SlpLineHeight are changed, this property is updated to
The value of this property is initialized to the printer’s default line spacing when
SlpLineWidth Property
Syntax SlpLineWidth: int32 { read-only, access after open-claim-enable }
Remarks Holds the width of a line of SlpLineChars characters, expressed in the unit of
Setting SlpLineChars may also update this property.
SlpMaxLines Property
Syntax SlpMaxLines: int32 { read-only, access after open-claim-enable }
Remarks Holds the maximum number of lines that can be printed on a form.
When CapSlpFullslip is true, then this property will be zero, indicating an
unlimited maximum slip length. When CapSlpFullslip is false, then this value
will be non-zero.
Changing the SlpLineHeight, SlpLineSpacing, or SlpLineChars properties may
cause this property to change.
method.

SlpNearEnd Property
Syntax SlpNearEnd: boolean { read-only, access after open-claim-enable }
Remarks If true, the slip form is near its end. If false, the slip form is not near its end.
The “near end” sensor is also sometimes called the “trailing edge” sensor, referring
to the bottom edge of the slip.
If CapSlpNearEndSensor is false, then this property is always false.
Note
The “slip empty” sensor should be used primarily to determine whether a form has been
inserted before printing, and can be monitored to determine whether a form is still in place.
This sensor is usually placed one or more print lines above the slip print head.
However, the “slip near end” sensor (when present) should be used to determine when
nearing the end of the slip. This sensor is usually placed one or more print lines below the
slip print head.
See Also SlpEmpty Property, SlpLinesNearEndToEnd Property.
SlpPrintSide Property Added in Release 1.5

Syntax SlpPrintSide: int32 { read-only, access after open-claim-enable }
Remarks This property holds the current side of the slip document on which printing will
occur.
If the Slip is not inserted, the value of the property is PTR_PS_UNKNOWN.
If the printer has both side print capability, CapSlpBothSidesPrint is true, then
when a slip is inserted, the value stored here will be either PTR_PS_SIDE1 or
PTR_PS_SIDE2. This property value may be changed when the changePrintSide
method is executed.
If a printer does not have both side print capability, CapSlpBothSidesPrint is
false, then when a slip is inserted, the property is always set to PTR_PS_SIDE1.
If a printer has both side print capability, the value of SlpPrintSide property is
PTR_PS_SIDE1 after beginInsertion/endInsertion methods are executed.
However, after beginInsertion/endInsertion methods for MICR processing are
executed, the value of SlpPrintSide property is not limited to PTR_PS_SIDE1. In
this case, SlpPrintSide property indicates the side of the validation printing.
Value Meaning
PTR_PS_UNKNOWN Slip is not inserted.
PTR_PS_SIDE1 Default Print side. (After slip paper
insertion, printer can print this side
immediately.)
PTR_PS_SIDE2 The other side of the document to print
on. (Reverse side of default.)

1030 POS Printer
See Also CapSlpBothSidesPrint Property, changePrintSide Method.
SlpSidewaysMaxChars Property
Syntax SlpSidewaysMaxChars: int32 { read-only, access after open-claim-enable }
sideways mode.
If CapSlpLeft90 and CapSlpRight90 are both false, then this property is zero.
Changing the properties SlpLineHeight, SlpLineSpacing, and SlpLineChars
method.
See Also SlpSidewaysMaxLines Property.
SlpSidewaysMaxLines Property
Syntax SlpSidewaysMaxLines: int32 { read-only, access after open-claim-enable }
If CapSlpLeft90 and CapSlpRight90 are both false, then this property is zero.
Changing the properties SlpLineHeight, SlpLineSpacing, and SlpLineChars
method.
See Also SlpSidewaysMaxChars Property.


If zero, the method initiates the begin insertion mode, then returns the appropriate
status immediately. If FOREVER (-1), the method initiates the begin insertion
mode, then waits as long as needed until either the form is inserted or an error
occurs.
Remarks Initiates slip processing.
When called, the slip station is made ready to receive a form by opening the form’s
handling “jaws” or activating a form insertion mode. This method is paired with
the endInsertion method for controlling form insertion.
If the printer device cannot be placed into insertion mode, an exception is raised.
Otherwise, form insertion is monitored until either:
• The form is successfully inserted.
• The form is not inserted before timeout milliseconds have elapsed, or an error
is reported by the printer device. In this case, an exception is raised with an
ErrorCode of E_TIMEOUT or another value. The printer device remains in
form insertion mode. This allows an application to perform some user
interaction and reissue the beginInsertion method without altering the form
handling mechanism.
Value Meaning
E_BUSY Cannot perform request while output is in progress.

properly inserted.

1032 POS Printer
beginRemoval Method
If zero, the method initiates the begin removal mode, then returns the appropriate
status immediately. If FOREVER (-1), the method initiates the begin removal
mode, then waits as long as needed until either the form is removed or an error
occurs.
Remarks Initiates form removal processing.
When called, the printer is made ready to remove a form by opening the form
handling “jaws” or activating a form ejection mode. This method is paired with the
endRemoval method for controlling form removal.
If the printer device cannot be placed into removal or ejection mode, an exception
is raised. Otherwise, form removal is monitored until either:
• The form is successfully removed.
• The form is not removed before timeout milliseconds have elapsed, or an error
is reported by the printer device. In this case, an exception is raised with an
ErrorCode of E_TIMEOUT or another value. The printer device remains in
form removal mode. This allows an application to perform some user
interaction and reissue the beginRemoval method without altering the form
handling mechanism.
Value Meaning

properly removed.

changePrintSide Method Updated in Release 1.9

Syntax changePrintSide ( side: int32 ):
The side parameter indicates the side on which to print. Valid values are:
Value Description
PTR_PS_SIDE1 Indicates that the default print side of the document is
selected. (Default print side is the side where printing
will occur immediately after a document has been
inserted. Therefore, PTR_PS_SIDE1 is selected after
beginInsertion/endInsertion is executed.)
PTR_PS_SIDE2 Indicates that the opposite side of the document from the
one that the printer defaults to is to be selected. (Reverse
side of PTR_PS_SIDE1.)
PTR_PS_OPPOSITE Indicates that the current printing side is switched and
printing will now occur on the opposite side of the slip.
(e.g., if SlpPrintSide was PTR_PS_SIDE1, it is to be
changed to PTR_PS_SIDE2.)
Remarks Selects the side of the document where printing is to occur.
This allows a print operation to occur on both sides of a document. This may be
accomplished by mechanical paper handling of the document or by using multiple
print heads that are positioned to print on each side of the document.
If a document is not inserted, an error is returned.
If side is not SlpPrintSide or side is PTR_PS_OPPOSITE, the side of the
document is changed and the document is fed to TOF. If side is SlpPrintSide,
nothing occurs and method returns.
Executing the method may cause the SlpPrintSide property to change.
Value Meaning
E_BUSY Cannot be performed while output is in progress.
(Can only apply if AsyncMode is false.)
* The slip station does not exist (see the
CapSlpPresent property)
* the printer does not support both sides printing (see
the CapSlpBothSidesPrint property)
* an invalid side parameter was specified
E_EXTENDED ErrorCodeExtended = EPTR_COVER_OPEN:
The printer cover is open.

1034 POS Printer
ErrorCodeExtended = EPTR_SLP_EMPTY:
ErrorCodeExtended = EPTR_SLP_CARTRIDGE_EMPTY:
A slip station cartridge is empty.
ErrorCodeExtended = EPTR_SLP_CARTRIDGE_REMOVED:
A slip station cartridge has been removed.
ErrorCodeExtended = EPTR_SLP_HEAD_CLEANING:
A slip station head is being cleaned.
See Also CapSlpBothSidesPrint Property, CapSlpPresent Property, SlpPrintSide
Property, cutPaper Method.
clearPrintArea Method Added in Release 1.9

Syntax clearPrintArea ( ):
Remarks Clear the area defined by the PageModePrintArea property.
The entire page may be cleared by setting the PageModePrintArea to be the same
as the PageModeArea and then using clearPrintArea or by exiting Page Mode
with pageModePrint with PTR_PM_CANCEL.
The PageModeStation property must be set to a valid station prior to invoking this
method.
See Also PageModeArea Property, PageModePrintArea Property, PageModeStation
Property, pageModePrint Method.
cutPaper Method Updated in Release 1.9

Syntax cutPaper ( percentage: int32 ):
percentage The percentage of paper to cut.
The constant identifier PTR_CP_FULLCUT or the value 100 causes a full paper
cut. Other values request a partial cut percentage.
Remarks Cuts the receipt paper.
Many printers with paper cut capability can perform both full and partial cuts.
Some offer gradations of partial cuts, such as a perforated cut and an almost-full
cut. Although the exact type of cut will vary by printer capabilities, the following
general guidelines apply:

Value Meaning
100 Full cut.
90 Leave only a small portion of paper for very easy final
separation.
70 Perforate the paper for final separation that is somewhat
more difficult and unlikely to occur by accidental
handling.
50 Partial perforation of the paper.
The Service will select an appropriate type of cut based on the capabilities of its
device and these general guidelines.
An escape sequence embedded in a printNormal or printImmediate method call
may also be used to cause a paper cut.
Value Meaning
E_BUSY Cannot perform while output is in progress. (Can only
apply if AsyncMode is false.)
E_ILLEGAL An invalid percentage was specified, the receipt station
does not exist (see the CapRecPresent property), the
receipt printer does not have paper cutting ability (see
the CapRecPapercut property), or Page Mode for the
receipt station is active.
ErrorCodeExtended = EPTR_REC_EMPTY:

1036 POS Printer
endInsertion Method
Remarks Ends form insertion processing.
When called, the printer is taken out of form insertion mode. If the slip device has
forms “jaws,” they are closed by this method. If no form is present, an exception
is raised with its ErrorCodeExtended property set to EPTR_SLP_EMPTY.
This method is paired with the beginInsertion method for controlling form
insertion. The application may choose to call this method immediately after a
successful beginInsertion if it wants to use the printer sensors to determine when
a form is positioned within the slip printer. Alternatively, the application may
prompt the user and wait for a key press before calling this method.
Value Meaning
E_ILLEGAL The printer is not in slip insertion mode.
The device was taken out of insertion mode while the
printer cover was open.
form being inserted.

endRemoval Method
Remarks Ends form removal processing.

When called, the printer is taken out of form removal or ejection mode. If a form
is present, an exception is raised with its ErrorCodeExtended property set to
EPTR_SLP_FORM.
This method is paired with the beginRemoval method for controlling form
removal. The application may choose to call this method immediately after a
successful beginRemoval if it wants to use the printer sensors to determine when
the form has been removed. Alternatively, the application may prompt the user and
wait for a key press before calling this method.
Value Meaning

E_ILLEGAL The printer is not in slip removal mode.
E_EXTENDED ErrorCodeExtended = EPTR_SLP_FORM:
The device was taken out of removal mode while a form
was still present.

1038 POS Printer
markFeed Method Added in Release 1.5

Syntax markFeed ( type: int32 ):
The type parameter indicates the type of mark sensed paper handling. Valid values
are:
Value Description
PTR_MF_TO_TAKEUP
Feed the Mark Sensed paper to the paper take-up
position.
PTR_MF_TO_CUTTER
Feed the Mark Sensed paper to the auto cutter cutting
position.
PTR_MF_TO_CURRENT_TOF
Feed the Mark Sensed paper to the present paper’s top of
form. (Reverse feed.)
PTR_MF_TO_NEXT_TOF
Feed the Mark Sensed paper to the next paper’s top of
form.
Remarks This method is used to utilize the printer’s mark sensor for receipt paper.
If type is PTR_MF_TO_TAKEUP, the printer will feed the mark sensed paper so
that the present form is moved so that it can be manually removed by the operator.
If type is PTR_MF_TO_CUTTER, the printer will feed the mark sensed paper so
that the present form is in position to be cut off by the auto cutter. This will usually
be followed by a call to the cutPaper method.
If type is PTR_MF_TO_CURRENT_TOF, the printer will feed the mark sensed
paper (backwards if necessary) so that the print head points to the top of the present
form.
If type is PTR_MF_TO_NEXT_TOF, the printer will feed the mark sensed paper
so that print head points to the top of the next form.
The following diagram provides a pictorial representation of the functions
performed by this method.

Outside of the Printer

1
Inside of the Printer
Auto Cutter
1
2
Print Head
PTR_MF_TO_CUTTER
PTR_MF_TO_TAKEUP PTR_MF_TO_CURRENT_TOF
Inside of the Printer 1

2
Auto Cutter
Print Head
2
PTR_MF_TO_
CURRENT_TOF
PTR_MF_TO_NEXT_TOF
Inside of the Printer 2
Auto Cutter
Print Head
3

1040 POS Printer
Value Meaning
E_BUSY Cannot be performed while output is in progress.
E_ILLEGAL The receipt print station does not support the given mark
sensed paper handling function. (Refer to the
CapRecMarkFeed property)
The receipt paper is empty.
See Also CapRecMarkFeed Property.
pageModePrint Method Updated in Release 1.11

Syntax pageModePrint ( control: int32 ):
control Page Mode control. See values below:
Value Meaning
PTR_PM_PAGE_MODE
Enter Page Mode.
PTR_PM_PRINT_SAVE
Print PageModePrintArea and save the canvas. Page
Mode is not exited. Use for printing of repeated pages.
PTR_PM_NORMAL Print the print area and destroy the canvas and exit Page
Mode.
PTR_PM_CANCEL Clear the page and exit the Page Mode without any
printing of any print area.
Remarks Enters or exits Page Mode for the station specified in the PageModeStation
property.
If control is PTR_PM_PAGE_MODE, then Page Mode is entered. Subsequent
calls to printNormal, printBarCode, printBitmap, and printMemoryBitmap
will buffer the print data (either at the printer or the Service, depending on the
printer capabilities) until pageModePrint is called with the control parameter set
to PTR_PM_PRINT_SAVE, PTR_PM_NORMAL, or PTR_PM_CANCEL. (In
this case, the print methods only validate the method parameters and buffer the
data – they do not initiate printing. Also, the value of the AsyncMode property
does not affect their operation: No OutputID will be assigned to the request, nor
will an OutputCompleteEvent be enqueued.)

If control is PTR_PM_PRINT_SAVE, then Page Mode is not exited. If some data

is buffered by calls to the methods printNormal, printBarCode, printBitmap,
and printMemoryBitmap, then the buffered data is saved and printed. This
control is used to print the same page layout with additional print items inside of
the page.
If control is PTR_PM_NORMAL, then Page Mode is exited. If some data is
buffered by calls to the methods printNormal, printBarCode, printBitmap, and
printMemoryBitmap, then the buffered data is printed. The buffered data will not
be saved.
If control is PTR_PM_CANCEL, then Page Mode is exited. If some data is
buffered by calls to the methods printNormal, printBarCode, printBitmap, and
printMemoryBitmap, then the buffered data is not printed and is not saved.
Note that when the pageModePrint method is called, all of the data that is to be
printed in the PageModePrintArea will be printed and the paper is fed to the end
of the PageModePrintArea. If more than one PageModePrintArea is defined,
then after the pageModePrint method is called, all of the data that is to be printed
in the respective PageModePrintArea(s) will be printed and the paper will be fed
to the end of the PageModePrintArea located the farthest “down” the sheet of
paper. (See figure below).
Paper
PageModeArea
Paper Feed Direction PageModePrintArea
(Second)
PageModePrintArea
(First)
Feed End Position

1042 POS Printer
The entire Page Mode transaction is treated as one message. This method is
AsyncMode is true.
Calling the clearOutput method cancels Page Mode. Any buffered print lines are
also cleared.
Page Mode can be used within a transaction print, but not within a rotate print.
The PageModeStation property must be set to a valid station prior to invoking this
method.
Value Meaning
E_ILLEGAL The specified PageModeStation does not exist (see the
CapRecPresent and CapSlpPresent properties), or
CapxxxPageMode is false, or the specified
PageModeStation is not in Page Mode and control is
set to PTR_PM_NORMAL, PTR_PM_PRINT_SAVE,
or PTR_PM_CANCEL.
apply if AsyncMode is false and control is
PTR_PM_NORMAL, PTR_PM_PRINT_SAVE, or
PTR_PM_CANCEL.)
See Also CapXxxPageMode Properties, PageModePrintArea Property,
PageModeStation Property.

printBarCode Method Updated in Release 1.12

Syntax printBarCode ( station: int32, data: string, symbology: int32, height: int32,
width: int32, alignment: int32, textPosition: int32 ):
station The printer station to be used. May be either
PTR_S_RECEIPT or PTR_S_SLIP.
data2 Character string to be bar coded.
symbology Bar code symbol type to use. See values below.
height Bar code height. Expressed in the unit of measure given
by MapMode.
width Bar code width. Expressed in the unit of measure given
by MapMode.
alignment Placement of the bar code. See values below.
textPosition Placement of the readable character string. See values
below.
The alignment parameter has one of the following values:
Value Meaning
PTR_BC_LEFT Align with the left-most print column.
PTR_BC_CENTER Align in the center of the station.
PTR_BC_RIGHT Align with the right-most print column.
Other Values Distance from the left-most print column to the start of
the bar code. Expressed in the unit of measure given by
MapMode.
The textPosition parameter has one of the following values:
Value Meaning
PTR_BC_TEXT_NONE No text is printed. Only print the bar code.
PTR_BC_TEXT_ABOVE Print the text above the bar code.
PTR_BC_TEXT_BELOW Print the text below the bar code.
The symbology parameter has one of the following values:
Value Meaning
One Dimensional Symbologies
PTR_BCS_UPCA UPC-A
PTR_BCS_UPCA_S UPC-A with supplemental barcode
PTR_BCS_UPCE UPC-E
PTR_BCS_UPCE_S UPC-E with supplemental barcode
PTR_BCS_UPCD1 UPC-D1

1044 POS Printer
PTR_BCS_EAN8 EAN 8 (= JAN 8)
PTR_BCS_JAN8 JAN 8 (= EAN 8)
PTR_BCS_EAN8_S EAN 8 with supplemental barcode
PTR_BCS_EAN13 EAN 13 (= JAN 13)
PTR_BCS_JAN13 JAN 13 (= EAN 13)
PTR_BCS_EAN13_S EAN 13 with supplemental barcode
PTR_BCS_EAN128 EAN-128
PTR_BCS_TF Standard (or discrete) 2 of 5
PTR_BCS_ITF Interleaved 2 of 5
PTR_BCS_Codabar Codabar
PTR_BCS_Code39 Code 39
PTR_BCS_OCRA OCR “A”
PTR_BCS_OCRB OCR “B”
PTR_BCS_Code128_Parsed Code 128 with parsing.
PTR_BCS_RSS14 Reduced Space Symbology - Deprecated v1.12;
replaced by PTR_BCS_GS1DATABAR
(which has the same value)
PTR_BCS_RSS_EXPANDED Reduced Space Symbology - Expanded -
Deprecated v1.12; replaced by
PTR_BCS_GS1DATABAR_E (which has the
same value)
PTR_BCS_GS1DATABAR GS1 DataBar Omnidirectional
PTR_BCS_GS1DATABAR_S GS1 DataBar Stacked Omnidirectional
PTR_BCS_GS1DATABAR_E GS1 DataBar Expanded
PTR_BCS_GS1DATABAR_E_S
GS1 DataBar Expanded Stacked
Two Dimensional Symbologies
PTR_BCS_PDF417 PDF 417
PTR_BCS_MAXICODE MAXICODE
Special Cases
PTR_BCS_OTHER If a Service defines additional symbologies, they will be
greater or equal to this value.

Special Considerations for Code 128

The Code 128 Bar Code Symbology is comprised of three code sets and also
includes some special characters that denote either a change in code set, a function
code, or a shift code. The characters for each code set are:
Code Set Character Set

Code A 0x00-0x5f, FNC1, FNC2, FNC3, FNC4, SHIFT, CODE B, CODE C
Code B 0x20-0x7f, FNC1, FNC2, FNC3, FNC4, SHIFT, CODE A, CODE C
Code C 0x00-0x63 for decimal values 00-99, FNC1, CODE A, CODE B
Release 1.7 and earlier
The data format to be supplied by the application was not specified in these
releases. Therefore, the default code set and data content varies by vendor. An
application that sends Code 128 data to a 1.7 or earlier service will need to conform
to that service's requirements.
For migration of current applications, the symbology PTR_BCS_Code128 is
maintained so that a service may continue to support the data format that it used
with earlier releases. (New service implementations should handle this symbology
as with PTR_BCS_Code128_Parsed.)
The new symbology PTR_BCS_Code128_Parsed standardizes the data format
with consistent parsing. Data is comprised of ASCII characters, which the service
maps to the corresponding value for the selected code set. In Code Sets A and B,
this will be a one to one mapping. In Code Set C, each pair of digits is converted
to a single Code C data character in the range 0x00 through 0x63 (99). (If the Code
Set C data contains an odd number of digits, then a leading zero digit is added by
the service before conversion.) A sentinel character, the left curly bracket “{”,
followed by a certain value, is used to indicate a special character. The following
table lists the character pairs for encoding the special characters:
Special Characters ASCII Representation
SHIFT {S
CODE A {A
CODE B {B
CODE C {C
FNC1 {1
FNC2 {2
FNC3 {3
FNC4 {4
{ {{
The default Code Set may differ by vendor, so a starting code set is required at the
start of the data.

1046 POS Printer
Remarks Prints a bar code on the specified printer station.

If RotateSpecial indicates that the bar code is to be rotated, then perform the
rotation. The height, width, and textPosition parameters are applied to the bar code
before the rotation. For example, if PTR_BC_TEXT_BELOW is specified and the
bar code is rotated left, then the text will appear on the paper to the right of the bar
code.
Value Meaning
E_ILLEGAL One of the following parameter errors occurred:
* station does not exist
* station does not support bar code printing
* height or width is zero or too big
* symbology is not supported
* not all characters in data are supported by
symbology
* alignment is invalid or too big
* Code Set is not specified for
PTR_BCS_Code128_Parsed at start of data
* textPosition is invalid, or
* the RotateSpecial rotation is not supported.
ErrorCodeExtended =
EPTR_REC_CARTRIDGE_REMOVED:
A receipt cartridge has been removed.
ErrorCodeExtended =
EPTR_REC_CARTRIDGE_EMPTY:
A receipt cartridge is empty.
ErrorCodeExtended =
EPTR_REC_HEAD_CLEANING:
A receipt cartridge head is being cleaned.

ErrorCodeExtended =
EPTR_SLP_CARTRIDGE_REMOVED:
A slip cartridge has been removed.
ErrorCodeExtended =
EPTR_SLP_CARTRIDGE_EMPTY:
A slip cartridge is empty.
ErrorCodeExtended =
EPTR_SLP_HEAD_CLEANING:
A slip cartridge head is being cleaned.
See Also MapMode Property, RotateSpecial Property.
printBitmap Method Updated in Release 1.7

Syntax printBitmap ( station: int32, fileName: string, width: int32, alignment: int32 ):
width Printed width of the bitmap to be performed. See values
below.
alignment Placement of the bitmap. See values below.
Value Meaning
PTR_BM_ASIS Print the bitmap with one bitmap pixel per printer dot.
Other Values Bitmap width expressed in the unit of measure given by
MapMode.
3.
white) uncompressed Windows bitmaps. Black pixels are printed, while white
pixels are not printed. Additional formats may be supported.

1048 POS Printer

Value Meaning
PTR_BM_LEFT Align with the left-most print column.
PTR_BM_CENTER Align in the center of the station.
PTR_BM_RIGHT Align with the right-most print column.
the bitmap. Expressed in the unit of measure given by
MapMode.
Remarks Prints a bitmap on the specified printer station. If a partial text line has been sent
(for example, via printNormal) but not yet printed, then an implicit line feed is
added to this text and the line is printed before the bitmap is printed. Text data sent
after this printBitmap begins on the line following the bitmap.
PTR_BM_ASIS, then no transformation is performed. The bitmap is printed with
one bitmap pixel per printer dot. Advantages of this option are that it:
• Provides the highest performance bitmap printing.
• Works well for bitmaps tuned for a specific printer’s aspect ratio between
horizontal dots and vertical dots.
ratio is unchanged. Advantages of this option are:
• Sizes a bitmap to fit a variety of printers.
• Maintains the bitmap’s aspect ratio.
Disadvantages are:
• Lowers performance than untransformed data.
some “ratcheting.”
Value Meaning
* station does not support bitmap printing
* width parameter is invalid or too big

E_EXTENDED ErrorCodeExtended = EPTR_TOOBIG:

The bitmap is either too wide to print without
ErrorCodeExtended = EPTR_COVER_OPEN:
ErrorCodeExtended = EPTR_BADFORMAT:
The specified file is either not a bitmap file, or it is in an
unsupported format.
ErrorCodeExtended =
ErrorCodeExtended =
ErrorCodeExtended =
ErrorCodeExtended =
ErrorCodeExtended =
ErrorCodeExtended =
See Also MapMode Property.

1050 POS Printer
printImmediate Method Updated in Release 1.9

Syntax printImmediate ( station: int32, data: string ):
PTR_S_JOURNAL, PTR_S_RECEIPT or
PTR_S_SLIP.
data4 The characters to be printed. May consist of printable
characters, escape sequences, carriage returns (13
decimal), and line feeds (10 decimal).
Remarks Prints data on the printer station immediately.
This method tries to print its data immediately – that is, as the very next printer
operation. It may be called when asynchronous output is outstanding. This method
is primarily intended for use in exception conditions when asynchronous output is
outstanding, such as within an error event handler.
Value Meaning
Line Feed (10) Print any data in the line buffer, and feed to the next print
Carriage Return (13) If a Carriage Return immediately precedes a Line Feed,
Otherwise, the line buffer is printed and the printer does
not feed to the next print line. On some printers, print
without feed may be directly supported. On others, a
print may always feed to the next line, in which case the
Service will print the line buffer and perform a reverse
line feed if supported. If the printer does not support
either of these features, then Carriage Return acts like a
Line Feed.
The validateData method may be used to determine
whether a Carriage Return without Line Feed is
possible, and whether a reverse line feed is required to
support it.
Value Meaning
E_ILLEGAL The specified station does not exist (see the CapJrnPresent,
CapRecPresent, and CapSlpPresent properties.), or the station
is in Page Mode and the device does not support direct printing
in Page Mode.


ErrorCodeExtended = EPTR_JRN_EMPTY:
ErrorCodeExtended = EPTR_JRN_CARTRIDGE_REMOVED:
A journal cartridge has been removed.
ErrorCodeExtended = EPTR_JRN_CARTRIDGE_EMPTY:
A journal cartridge is empty.
ErrorCodeExtended = EPTR_JRN_HEAD_CLEANING:
A journal cartridge head is being cleaned.
ErrorCodeExtended =EPTR_REC_CARTRIDGE_REMOVED:
ErrorCodeExtended = EPTR_REC_CARTRIDGE_EMPTY:
ErrorCodeExtended = EPTR_REC_HEAD_CLEANING:
See Also printNormal Method, printTwoNormal Method.
printMemoryBitmap Method Added in Release 1.12
Syntax printMemoryBitmap (station: int32, data: binary, type: int32, width: int32,
alignment: int32):
data5 Memory byte array representation of the bitmap.

1052 POS Printer
type Various bitmap formats may be supported, such as bmp,

gif, or jpeg files.6 See values below.
width Printed width of the bitmap to be performed. See values
below.
alignment Placement of the bitmap. See values below.
The type parameter has one of the following values:
Value Meaning
PTR_BMT_BMP The data parameter contains a BMP format bitmap.
PTR_BMT_JPEG The data parameter contains a JPEG format bitmap.
PTR_BMT_GIF The data parameter contains a GIF format bitmap.
Value Meaning
PTR_BM_ASIS Print the bitmap with one bitmap pixel per printer dot.
Other Values Bitmap width expressed in the unit of measure given by
MapMode.
Value Meaning
PTR_BM_LEFT Align with the left-most print column.
PTR_BM_CENTER Align in the center of the station.
PTR_BM_RIGHT Align with the right-most print column.
the bitmap. Expressed in the unit of measure given by
MapMode.
Remarks Prints a memory-stored bitmap on the specified printer station. If a partial text line
has been sent (for example, via printNormal) but not yet printed, then an implicit
line feed is added to this text and the line is printed before the bitmap is printed.
Text data sent after this printMemoryBitmap begins on the line following the
bitmap.
PTR_BM_ASIS, then no transformation is performed. The bitmap is printed with
one bitmap pixel per printer dot. Advantages of this option are that it:
• Provides the highest performance bitmap printing.
• Works well for bitmaps tuned for a specific printer’s aspect ratio between
horizontal dots and vertical dots.
ratio is unchanged. Advantages of this option are:
• Sizes a bitmap to fit a variety of printers.
• Maintains the bitmap’s aspect ratio.
Disadvantages are:
• Lowers performance compared to untransformed data.
6.

some “ratcheting.”
Value Meaning
* width parameter is invalid or too big
ErrorCodeExtended = EPTR_COVER_OPEN:
unsupported format.
ErrorCodeExtended =
ErrorCodeExtended =
ErrorCodeExtended =
ErrorCodeExtended =
ErrorCodeExtended =
ErrorCodeExtended =
See Also MapMode Property.

1054 POS Printer
printNormal Method Updated in Release 1.7

Syntax printNormal ( station: int32, data: string ):
PTR_S_SLIP.
data7 The characters to be printed. May consist of printable
characters, escape sequences, carriage returns (13
decimal), and line feeds (10 decimal).
Remarks Prints data on the printer station.
Value Meaning
Line Feed (10) Print any data in the line buffer, and feed to the next print
Carriage Return (13) If a Carriage Return immediately precedes a Line Feed,
Otherwise, the line buffer is printed and the printer does
not feed to the next print line. On some printers, print
without feed may be directly supported. On others, a
print may always feed to the next line, in which case the
Service will print the line buffer and perform a reverse
line feed if supported. If the printer does not support
either of these features, then Carriage Return acts like a
Line Feed.
The validateData method may be used to determine
whether a Carriage Return without Line Feed is
possible, and whether a reverse line feed is required to
support it.

Value Meaning
E_ILLEGAL The specified station does not exist. (See the CapJrnPresent,
CapRecPresent, and CapSlpPresent properties.)
E_BUSY Cannot perform while output is in progress.(Can only apply if
See Also printImmediate Method, printTwoNormal Method.

1056 POS Printer
printTwoNormal Method Updated in Release 1.9

Syntax printTwoNormal ( stations: int32, data1: string, data2: string ):
stations Release 1.2
The printer stations to be used may be:
PTR_S_JOURNAL_RECEIPT, PTR_S_JOURNAL_SLIP, or
PTR_S_RECEIPT_SLIP.
Release 1.3 and later:
Select one of the following:
First Second
stations Parameter
Station Station
PTR_TWO_RECEIPT_JOURNAL Receipt Journal
PTR_TWO_SLIP_JOURNAL Slip Journal
PTR_TWO_SLIP_RECEIPT Slip Receipt
data1 8 The characters to be printed on the first station. May consist of

printable characters and escape sequences as listed in the “Print
Line” table under “Data Characters and Escape Sequences” on
page 976. The characters must all fit on one printed line, so that
the printer may attempt to print on both stations simultaneously.
data2 7 The characters to be printed on the second station. (Restrictions
are the same as for data1.) If this string is the empty string (“”),
then print the same data as data1. On some printers, using this
format may give additional increased print performance.
Remarks Prints two strings on two print stations simultaneously. When supported, this may
give increased print performance.
Release 1.2
Documentation release 1.2 was not sufficiently clear as to the meaning of “first”
and “second” station so Service implementations varied between the following:
• Assign stations based on order within the constants. For example,
PTR_S_JOURNAL_RECEIPT prints data1 on the journal and data2 on the
receipt.
• Assign stations based upon physical device characteristics or internal print
order.
Due to this inconsistency, the application should use the new constants if the
Control and Service versions indicate Release 1.3 or later.
8. In the OPOS environment, the format of data1 and data2 depends upon the value of
the BinaryConversion property. See BinaryConversion property on page A-29.


Service for Release 1.3 or later should support both sets of constants. The vendor
should define and document the behavior of the obsolete constants.
The sequence of stations in the constants does not imply the physical printing
sequence on the stations. The physical sequence depends on the printer and may
be different based on the bi-directional printing multiple print heads and so on.
Value Meaning
E_ILLEGAL The specified stations do not support concurrent printing (see the
CapConcurrentJrnRec, CapConcurrentJrnSlp, and
CapConcurrentRecSlp properties.), or Page Mode is active for
either station specified in stations.
E_BUSY Cannot perform while output is in progress. (Can only apply if
A journal cartridge has been removed. (Can only apply if
A journal cartridge is empty. (Can only apply if AsyncMode is
false.)
A journal cartridge head is being cleaned. (Can only apply if
The receipt station was specified but is out of paper. (Can only
A receipt cartridge has been removed. (Can only apply if
A receipt cartridge is empty. (Can only apply if AsyncMode is
false.)
A receipt cartridge head is being cleaned. (Can only apply if
The slip station was specified, but a form is not inserted. (Can
only apply if AsyncMode is false.)

1058 POS Printer
A slip cartridge has been removed. (Can only apply if
A slip cartridge is empty. (Can only apply if AsyncMode is
false.)
A slip cartridge head is being cleaned. (Can only apply if
See Also printNormal Method

rotatePrint Method Updated in Version 1.11

Syntax rotatePrint ( station: int32, rotation: int32 ):
station The printer station to be used. May be
rotation Direction of rotation. See values below.
Value Meaning
PTR_RP_RIGHT90 Start rotated printing 90° to the right (clockwise)
PTR_RP_LEFT90 Start rotated printing 90° to the left (counter-clockwise)
PTR_RP_ROTATE180 Start rotated printing 180°, that is, print upside-down
PTR_RP_BARCODE Start rotated bar code printing. This value is ORed with
one of the above start rotated print values.
PTR_RP_BITMAP Start rotated bitmap printing. This value is ORed with
one of the above start rotated print values.
PTR_RP_NORMAL End rotated printing.
Remarks Enters or exits rotated print mode.
This method is performed synchronously if AsyncMode is false, asynchronously
if AsyncMode is true.
If rotation includes PTR_RP_ROTATE180, then upside-down print mode is
entered. Subsequent calls to printNormal or printImmediate will print the data
upside-down until rotatePrint is called with rotation set to PTR_RP_NORMAL.
Each print line is rotated by 180°. Lines are printed in the order that they are sent,
with the start of each line justified at the right margin of the printer station. If
rotation does not include PTR_RP_BARCODE and/or PTR_RP_BITMAP, then
only the print methods printNormal and printImmediate may be used while in
upside-down print mode.
If rotation includes PTR_RP_RIGHT90 or PTR_RP_LEFT90, then sideways
print mode is entered. Subsequent calls to printNormal will buffer the print data
(either at the printer or the Service, depending on the printer capabilities) until
rotatePrint is called with rotation set to PTR_RP_NORMAL. (In this case,
printNormal only buffers the data – it does not initiate printing. Also, the value
of the AsyncMode property does not affect its operation: No OutputID will be
assigned to the request, nor will an OutputCompleteEvent be enqueued.) Each
print line is rotated by 90°. If the lines are not all the same length, then they are
justified at the start of each line. If rotation does not include PTR_RP_BARCODE
and/or PTR_RP_BITMAP, then only printNormal may be used while in
sideways print mode.
If rotation includes PTR_RP_NORMAL, then rotated print mode is exited. If
sideways-rotated print mode was in effect and some data was buffered by calls to
the printNormal method, then the buffered data is printed. The entire rotated
block of lines are treated as one message.
If rotation includes PTR_RP_BARCODE and/or PTR_RP_BITMAP, then any
bar codes (printed with printBarCode or printed with the Escape Sequence “|#R”)
and/or bitmaps (printed with printBitmap or printed with the Escape Sequence
“|#B”) submitted for printing during the rotatePrint processing cycle will also be

1060 POS Printer
rotated. Such rotation will be within the limitations that may be specified by the
RecBarCodeRotationList, SlpBarCodeRotationList,
RecBitmapRotationList, and SlpBitmapRotationList properties respectively.
If rotation includes PTR_RP_BARCODE, then the contents of RotateSpecial are
ignored.
Changing the rotation mode may also change the station’s line height, line spacing,
line width, and other metrics.
Calling the clearOutput method cancels rotated print mode. Any buffered
sideways rotated print lines are also cleared.
Value Meaning
CapRecPresent, and CapSlpPresent properties), or the station
does not support the specified rotation (see the station’s rotation
capability properties).
See Also “Data Characters and Escape Sequences” on page 976, RotateSpecial Property.

setBitmap Method Updated in Release 1.7

Syntax setBitmap ( bitmapNumber: int32, station: int32, fileName: string, width:
int32, alignment: int32 ):
bitmapNumber The number to be assigned to this bitmap. Valid bitmap

numbers are 1 through 20.
Release 1.6 and earlier: Valid bitmap numbers are 1
and 2.
If set to an empty string (“”), then the bitmap is unset.
width Printed width of the bitmap to be performed. See
printBitmap for values.
alignment Placement of the bitmap. See printBitmap for values.
Remarks Saves information about a bitmap for later printing.

The bitmap may then be printed by calling the printNormal or printImmediate
method with the print bitmap escape sequence in the print data. The print bitmap
escape sequence will typically be included in a string for printing top and bottom
transaction headers.
If a partial text line has been sent before the print bitmap escape sequence is
encountered, then an implicit line feed is added to this text and the line is printed
before the bitmap is printed. Text data sent after the print bitmap escape sequence
begins on the line following the bitmap.
A Service may choose to cache the bitmap for later use to provide better
performance. Regardless, the bitmap file and parameters are validated for
correctness by this method.
The most frequently used bitmaps should be assigned a small bitmapNumber (close
to 1), while occasionally used bitmaps should be assigned the larger
bitmapNumbers. The Service will use these subsets to determine how best to store
the bitmaps. It may download them to the device when possible, or cache them in
Service memory, or simply remember the fileName and associated properties for
use when it is printed.
The application must ensure that the printer station metrics, such as character
width, line height, and line spacing are set for the station before calling this
method. The Service may perform transformations on the bitmap in preparation
for later printing based upon the current values.
The application may set bitmaps numbered 1 through 20 for each of the two valid
9.

1062 POS Printer
stations. If desired, the same bitmap fileName may be set to the same
bitmapNumber for each station, so that the same print bitmap escape sequence may
be used for either station.
Value Meaning
* bitmapNumber is invalid
* width is too big
unsupported format.
See Also “Data Characters and Escape Sequences” on page 976, printBitmap Method.
setLogo Method Updated in Release 1.10
Syntax setLogo ( location: int32, data: string ):
location The logo to be set. May be PTR_L_TOP or
PTR_L_BOTTOM.
data10 The characters that produce the logo. May consist of
printable characters, escape sequences (except logos),
carriage returns (13 decimal), and line feeds (10
decimal).
Remarks Saves a data string as the top or bottom logo.
A logo may then be printed by calling the printNormal, printTwoNormal, or
printImmediate method with the print top logo or print bottom logo escape
sequence in the print data.
Value Meaning
E_ILLEGAL An invalid location was specified.
10. In
the OPOS environment, the format of this data depends upon the value of the

transactionPrint Method
Syntax transactionPrint ( station: int32, control: int32 ):
station The printer station to be used. May be

PTR_S_JOURNAL, PTR_S_RECEIPT, or
PTR_S_SLIP.
control Transaction control. See values below:
Value Meaning
PTR_TP_TRANSACTION Begin a transaction.

PTR_TP_NORMAL End a transaction by printing the buffered data.
Remarks Enters or exits transaction mode.

If control is PTR_TP_TRANSACTION, then transaction mode is entered.
Subsequent calls to printNormal, cutPaper, rotatePrint, printBarCode, and
printBitmap will buffer the print data (either at the printer or the Service,
depending on the printer capabilities) until transactionPrint is called with the
control parameter set to PTR_TP_NORMAL. (In this case, the print methods only
validate the method parameters and buffer the data – they do not initiate printing.
Also, the value of the AsyncMode property does not affect their operation: No
OutputID will be assigned to the request, nor will an OutputCompleteEvent be
enqueued.)
If control is PTR_TP_NORMAL, then transaction mode is exited. If some data
was buffered by calls to the methods printNormal, cutPaper, rotatePrint,
printBarCode, and printBitmap, then the buffered data is printed. The entire
transaction is treated as one message. This method is performed synchronously if
AsyncMode is false, and asynchronously if AsyncMode is true.
Calling the clearOutput method cancels transaction mode. Any buffered print
lines are also cleared.
Value Meaning
CapRecPresent, and CapSlpPresent properties), or
CapTransaction is false.
AsyncMode is false and control is PTR_TP_NORMAL.)

1064 POS Printer

(Can only apply if AsyncMode is false and control is
PTR_TP_NORMAL.)
See Also CapTransaction Property, cutPaper Method, printBarCode Method,
printBitmap Method, printNormal Method, rotatePrint Method.

validateData Method Updated in Release 1.9

Syntax validateData ( station: int32, data: string ):
PTR_S_SLIP.
data11 The data to be validated. May include printable data and
escape sequences.
Remarks Determines whether a data sequence, possibly including one or more escape
sequences, is valid for the specified station, before calling the printImmediate,
printNormal, or printTwoNormal methods.
This method does not cause any printing, but is used to determine the capabilities
of the station.
Value Meaning
E_ILLEGAL Some of the data is not precisely supported by the
printer station, but the Service can select valid
alternatives. This exception can also be thrown if an
escape sequence is not supported while either Page
Mode or rotate sideways is active.
E_FAILURE Some of the data is not supported. No alternatives
can be selected.
Cases which cause ErrorCode of E_ILLEGAL:
Paper cut The percentage ‘#’ is not precisely supported:
Service will select the closest supported value.
Feed and Paper cut The percentage ‘#’ is not precisely supported:
Feed, Paper cut, and Stamp The percentage ‘#’ is not precisely supported:
Feed units The unit count ‘#’ is not precisely supported:
Feed reverse The line count ‘#’ is too large: Service will select
the maximum supported value.
Underline The thickness ‘#’ is not precisely supported: Service
Shading The percentage ‘#’ is not precisely supported:
11. In
the OPOS environment, the format of this data depends upon the value of the

1066 POS Printer
Scale horizontally The scaling factor ‘#’ is not supported: Service will
Scale vertically The scaling factor ‘#’ is not supported: Service will
Alternate Color The color ‘#’ is not supported: Service will select
the closest supported value.
RGB Color The color ‘#’ is not supported: Service will select
the closest supported value.
Data Condition
data1CRdata2LF (Where CR is a Carriage Return and LF is a Line
Feed.) In order to print data data1 and remain on the
same line, the Service will print with a line advance,
then perform a reverse line feed. The data data2 will
then overprint data1.
Cases which will cause ErrorCode of E_FAILURE:
(General) The escape sequence format is not valid.
Paper cut Not supported.
Feed and Paper cut Not supported.
Feed, Paper cut, and Stamp Not supported.
Fire stamp Not supported.
Print bitmap Bitmap printing is not supported, or the bitmap
number ‘#’ is out of range.
Feed reverse Not supported.
Font typeface The typeface ‘#’ is not supported.
Bold Not supported.
Underline Not supported.
Italic Not supported.
Alternate color Not supported.
RGB color Not supported.
Reverse video Not supported.
SubScript Not supported.
SuperScript Not supported.
Shading Not supported.
Single high and wide Not supported.
Double wide Not supported.
Double high Not supported.
Double high and wide Not supported.
Data Condition
data1CRdata2LF (Where CR is a Carriage Return and LF is a Line
Feed.) Not able to print data and remain on the same
line. The data data1 will print on one line, and the
data data2 will print on the next line.

DirectIOEvent
means for a vendor-specific POS Printer Service to provide events to the
Service.
from being used with other vendor’s POS Printer devices which may not have any

1068 POS Printer

Description Notifies the application that a POS Printer error has been detected and that a
Codes on page 52.
ErrorCodeExtended
ErrorLocus int32 Location of the error, and is set to EL_OUTPUT
indicating that the error occurred while processing
values below.
following values:
Value Meaning
EPTR_COVER_OPEN The printer cover is open.

EPTR_JRN_EMPTY The journal station is out of paper.
EPTR_REC_EMPTY The receipt station is out of paper.
EPTR_SLP_EMPTY A form is not inserted in the slip station.
EPTR_JRN_CARTRIDGE_REMOVED:
EPTR_JRN_CARTRIDGE_EMPTY:
EPTR_JRN_HEAD_CLEANING:

Value Meaning

asynchronous output. (The effect is the same as when
clearOutput is called.) The error state is exited.
The default.
error state.
page 62
OutputCompleteEvent


is complete.

1070 POS Printer

Description Notifies the application that a printer has had an operation status change.
Status int32 Indicates the status change, and has one of the
following values:
Value Meaning
PTR_SUE_COVER_OPEN Printer cover is open.
PTR_SUE_COVER_OK Printer cover is closed.
PTR_SUE_JRN_EMPTY No journal paper.
PTR_SUE_JRN_NEAREMPTY Journal paper is low.
PTR_SUE_JRN_PAPEROK Journal paper is ready.
PTR_SUE_REC_EMPTY No receipt paper.
PTR_SUE_REC_NEAREMPTY Receipt paper is low.
PTR_SUE_REC_PAPEROK Receipt paper is ready.
PTR_SUE_SLP_EMPTY No slip form is inserted, and no slip form has
(See “Model” on page 965 for further details on
slip properties and events.)
PTR_SUE_SLP_NEAREMPTY Almost at the bottom of the slip form.
PTR_SUE_SLP_PAPEROK Slip form is inserted.
PTR_SUE_IDLE All asynchronous output has finished, either
successfully or because output has been
cleared. The printer State is now S_IDLE. The
FlagWhenIdle property must be true for this
event to be delivered, and the property is
automatically reset to false just before the event
is delivered.

process.

Release 1.5 and later – Cartridge State Reporting

If CartridgeNotify = PTR_CN_ENABLED, StatusUpdateEvents with the
following status parameter values may be fired.
Value Meaning
PTR_SUE_JRN_CARTRIDGE_EMPTY
A journal cartridge needs to be replaced. Cartridge is
empty ornot present.
PTR_SUE_JRN_HEAD_CLEANING
A journal cartridge has begun cleaning.
PTR_SUE_JRN_CARTRIDGE_NEAREMPTY
A journal cartridge is near end.
PTR_SUE_JRN_CARTRIDGE_OK
All journal cartridges are ready. It gives no indication of
the amount of media in the cartridge.
PTR_SUE_REC_CARTRIDGE_EMPTY
A receipt cartridge needs to be replaced. Cartridge is
empty or not present.
PTR_SUE_REC_HEAD_CLEANING
A receipt cartridge has begun cleaning.
PTR_SUE_REC_CARTRIDGE_NEAREMPTY
A receipt cartridge is near end.
PTR_SUE_REC_CARTRIDGE_OK
All receipt cartridges are ready. It gives no indication of
the amount of media in the cartridge.
PTR_SUE_SLP_CARTRIDGE_EMPTY
A slip cartridge needs to be replaced. Cartridge is empty
or not present.
PTR_SUE_SLP_HEAD_CLEANING
A slip cartridge has begun cleaning.
PTR_SUE_SLP_CARTRIDGE_NEAREMPTY
A slip cartridge is near end.
PTR_SUE_SLP_CARTRIDGE_OK
All slip cartridges are ready. It gives no indication of the
amount of media in the cartridge.
Release 1.8 and later – Specific Cover State Reporting
Starting with Release 1.8, StatusUpdateEvents for specific stations’ covers are
supported. If a printer has only one cover or if the printer cannot determine/report
which covers are open, then only the original PTR_SUE_COVER_OPEN and
PTR_SUE_COVER_OK events should be fired.
For printers supporting multiple covers, the original events should also be fired for
compatibility with current applications. In these cases, the station-specific event
should be fired first, followed by the original event.
If more than one cover is open, the original PTR_SUE_COVER_OPEN event
should only be fired once after a cover is opened. A PTR_SUE_COVER_OK

1072 POS Printer
event should only be fired after all the covers are closed.
The event’s Status attribute can contain one of the following additional values to
indicate a status change.
Value Meaning
PTR_SUE_JRN_COVER_OPEN Journal station cover is open.
PTR_SUE_JRN_COVER_OK Journal station cover is closed.
PTR_SUE_REC_COVER_OPEN Receipt station cover is open.
PTR_SUE_REC_COVER_OK Receipt station cover is closed.
PTR_SUE_SLP_COVER_OPEN Slip station cover is open.
PTR_SUE_SLP_COVER_OK Slip station cover is closed.
Example A: Suppose that a printer includes two cover sensors, but reports “cover
open” if either is open. Then here are the actions and StatusUpdateEvents that
should be fired.
Action StatusUpdateEvent
Open front cover PTR_SUE_COVER_OPEN
Open rear cover (no additional SUE)
Close front cover (no additional SUE)
Close rear cover PTR_SUE_COVER_OK
Example B: Suppose that a printer includes two sensors which report their statuses
independently. Then here are the actions and StatusUpdateEvents that should be
fired.
Action StatusUpdateEvent(s)
Open front cover PTR_SUE_SLP_COVER_OPEN, then
PTR_SUE_COVER_OPEN
Open rear cover PTR_SUE_REC_COVER_OPEN
Close front cover PTR_SUE_SLP_COVER_OK
Close rear cover PTR_SUE_REC_COVER_OK, then
PTR_SUE_COVER_OK
This status reporting allows the migration of applications written to earlier

releases, plus additional functionality for applications written to the new release:
• An application that either ignores the new statuses or was written before 1.8
continues to respond to the PTR_SUE_COVER_OPEN and
PTR_SUE_COVER_OK StatusUpdateEvents. (It is assumed that the
application will ignore statuses that are not expected.)
• An application written to support the new statuses can respond to the station-
specific status (PTR_SUE_xxx_COVER_OK), and the general status
(PTR_SUE_COVER_OK) will not provide any additional information. But if
it receives a general status without a preceding station-specific status, then it
processes the general status.
Remarks Enqueued when a significant status event has occurred.

C H A P T E R 3 1
Remote Order Display

This Chapter defines the Remote Order Display device category.
Summary

1074 Remote Order Display
CapSelectCharacterSet: boolean { read-only } 1.3 open, claim, & enable
CapTone: boolean { read-only } 1.3 open, claim, & enable
CapTouch: boolean { read-only } 1.3 open, claim, & enable
AsyncMode: boolean { read-write } 1.3 open, claim, & enable

AutoToneDuration: int32 { read-write } 1.3 open, claim, & enable
AutoToneFrequency: int32 { read-write } 1.3 open, claim, & enable
CharacterSet: int32 { read-only } 1.3 open, claim, & enable
CharacterSetList: string { read-only } 1.3 open, claim, & enable
Clocks: int32 { read-only } 1.3 open, claim, & enable
CurrentUnitID: int32 { read-write } 1.3 open, claim, & enable
ErrorUnits: int32 { read-only } 1.3 open
EventString: string { read-only } 1.3 open & claim
EventType: int32 { read-write } 1.3 open
EventUnitID: int32 { read-only } 1.3 open & claim
EventUnits: int32 { read-only } 1.3 open & claim
SystemClocks: int32 { read-only } 1.3 open, claim, & enable
SystemVideoSaveBuffers: int32 { read-only } 1.3 open, claim, & enable
Timeout: int32 { read-write } 1.3 open
UnitsOnline: int32 { read-only } 1.3 open, claim, & enable
VideoDataCount: int32 { read-only } 1.3 open, claim, & enable
VideoMode: int32 { read-write } 1.3 open, claim, & enable
VideoModesList: string { read-only } 1.3 open, claim, & enable
VideoSaveBuffers: int32 { read-only } 1.3 open, claim, & enable

Summary 1075

Common
Name Version
close ( ): 1.3
release ( ): 1.3
clearInput ( ): 1.3
void { } supporteda
Specific
Name
clearVideo ( units: int32, attribute: int32 ): 1.3
clearVideoRegion (units: int32, row: int32, column: int32, height: int32, 1.3
width: int32, attribute: int32 ):
controlClock ( units: int32, function: int32, clockId: int32, hour: int32, min: 1.3
int32, sec: int32, row: int32, column: int32, attribute: int32, mode:
int32 ):
controlCursor ( units: int32, function: int32 ): 1.3
copyVideoRegion ( units: int32, row: int32, column: int32, height: int32, 1.3
width: int32, targetRow: int32, targetColumn: int32 ):

Methods (Continued)
displayData ( units: int32, row: int32, column: int32, attribute: int32, data: 1.3
string ):
drawBox ( units: int32, row: int32, column: int32, height: int32, width: int32, 1.3
attribute: int32, bordertype: int32 ):
freeVideoRegion ( units: int32, bufferId: int32 ): 1.3
resetVideo ( units: int32 ): 1.3
restoreVideoRegion ( units: int32, targetRow: int32, targetColumn: int32, 1.3
bufferId: int32 ):
saveVideoRegion ( units: int32, row: int32, column: int32, height: int32, 1.3
width: int32, bufferId: int32 ):
selectCharacterSet ( units: int32, characterSet: int32 ): 1.3
setCursor ( units: int32, row: int32, column: int32 ): 1.3
transactionDisplay ( units: int32, function: int32 ): 1.3
updateVideoRegionAttribute ( units: int32, function: int32, row: int32, col- 1.3
umn: int32, height: int32, width: int32, attribute: int32 ):
videoSound ( units: int32, frequency: int32, duration: int32, 1.3

Summary 1077


General Information
The Remote Order Display programmatic name is “RemoteOrderDisplay”.
Capabilities
The Remote Order Display has the following minimal set of capabilities:
• Supports color or monochrome text character displays.
• Supports 8 foreground colors (or gray scale on monochrome display) with the
option of using the intensity attribute.
• Supports 8 background colors (or gray scale on monochrome display) with the
option of using only a blinking attribute.
• The individual event types support disabling such that the application only
receives a subset of data events if requested.
• Supports video region buffering.
• Supports cursor functions.
• Supports clock functions.
• Supports resetting a video unit to power on state.
The Remote Order Display may also have the following additional capabilities:
• Supports multiple video displays each with possibly different video modes.
• Supports touch video input for a touch screen display unit.
• Supports video enunciator output with frequency and duration.
• Supports tactile feedback via an automatic tone when a video display unit is
touched (for touch screen only).
• Supports downloading alternate character sets to one or many video units.
• Supports transaction mode display output to one or many video units.
The following capability is not supported:

• Support for graphical displays, where the video display is addressable by
individual pixels or dots. The addition of this support is under investigation for
future revisions.

Remote Order Display Class Diagram
The following diagram shows the relationships between the Remote Order Display
classes.
<<uses>>
<<exception>> <<Interface>> <<utility>>
<<event>> UposException BaseControl UposConst
DataEvent (from upos) (from upos) (from upos)
(from event s)
<<sends>>
<<utility>>
<<sends>> RemoteOrderDisplayConst
(from upos)
<<event>>
<<Interface>>
DirectIOEvent fires RemoteOrderDisplayControl
(from events)
(from upos)
<<capability>> CapSelectCharacterSet : boolean
<<prop>> Data : int32 <<uses>>
<<capability>> CapTone : boolean
<<capability>> CapTouch : boolean
<<capability>> CapTransaction : boolean
<<prop>> AutoToneDuration : int32
fires <<prop>> AutoToneFrequency : int32
<<event >> <<prop>> CharacterSet : int32
ErrorEvent <<prop>> CharacterSetList : string
(from events) <<prop>> Clocks : int32
<<prop>> ErrorCode : int32 <<prop>> CurrentUnitID : int32
<<prop>> ErrorCodeExtended : int32 <<prop>> ErrorString : string
<<prop>> ErrorLocus : int32 <<prop>> ErrorUnits : int32
<<prop>> ErrorResponse : int32 fires <<prop>> EventString : string
<<prop>> EventType : int32
<<prop>> EventUnitID : int32
<<prop>> EventUnits : int32
<<prop>> SystemClocks : int32
<<prop>> SystemVideoSaveBuffers : in32
<<event>> fires <<prop>> Timeout : int32
OutputCompleteEvent <<prop>> UnitsOnline : int32
(from event s) <<prop>> VideoDataCount : int32
<<prop>> OutputID : int32 <<prop>> VideoMode : in32
<<prop>> VideoModesList : string
fires <<prop>> VideoSaveBuffers : int32
clearVideo()
<<event>> clearVideoRegion()
StatusUpdateEvent controlClock()
(from events) controlCursor()
copyVideoRegion()
displayData()
drawBox()
freeVideoRegion()
resetVideo()
restoreVideoRegion()
saveVideoRegion()
selectCharacterSet()
setCursor()
transactionDisplay()
updateVideoRegionAttribute()
videoSound()

The general model of a Remote Order Display:

The Remote Order Display device class is a subsystem of video units. The initial
targeted environment is food service, to display order preparation and fulfillment
information. Remote Order Displays are often used in conjunction with Bump
Bars.
The general model of a Remote Order Display is an output device but may also be
an input device when, in some implementations, the device can report additional
status or user input data back to the application program.
• The subsystem can support up to 32 video units.
Typically, one application on one workstation (or POS Terminal) would

manage and control the entire subsystem of Remote Order Displays.
However, if applications on the same or other workstations (or POS
Terminals) would need to access the subsystem, then one of the applications
must act as a subsystem server and expose the necessary interfaces to other
applications.
• All specific methods are broadcast methods. This means that the method can
apply to one unit, a selection of units or all online units. The units parameter
is an int32, with each bit identifying an individual video unit. The Service will
attempt to satisfy the method for all units indicated in the units parameter. If
an error is received from one or more units, the ErrorUnits property is
updated with the appropriate units in error. The ErrorString property is
updated with a description of the error or errors received. The method will
then raise a UposException. In the case where two or more units encounter
different errors, the exception’s ErrorCode will indicate the more severe
error.
• The common methods checkHealth, clearInput, and clearOutput are not
broadcast methods and use the unit ID indicated in the CurrentUnitID
property. See the description of these common methods to understand how the
CurrentUnitID property is used.
• When the CurrentUnitID property is set by the application, all the
corresponding properties are updated to reflect the settings for that unit.
If the CurrentUnitID property is set to a unit ID that is not online, the

dependent properties will contain non-initialized values.
The CurrentUnitID uniquely represent a single video unit. The definitions

range from ROD_UID_1 to ROD_UID_32. These definitions are also used to
create the bitwise parameter, units, used in the broadcast methods.

• The rows and columns are numbered beginning with (0,0) at the top-left
corner of the video display. The dimensions are defined by the height and
width parameters. The region depicted below would have the parameters
row = 1, column = 2, height = 3, and width = 4.
0 1 2 3 4 5 6
0
1
2
3
4
All position parameters are expressed in text characters.
• The VGA-like attribute parameter, that is used in various methods, is an

int32. Bits 7-0 define the text attribute and bits 31-8 are reserved and must be
0, otherwise an E_ILLEGAL exception is raised. The following table defines
bits 7-0:
Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0

Blinking Background and Color Intensity Foreground Color
If a foreground or background color is requested, but the Service does not

support that color, it chooses the best fit from the colors supported.
The following constants may be used, with up to one constant selected from
each category:
• Blinking: ROD_ATTR_BLINK
• Background Color: ROD_ATTR_BG_color, where color is replaced by
BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, or
GRAY
• Intensity: ROD_ATTR_INTENSITY
• Foreground Color: ROD_ATTR_FG_color, where color is replaced by
BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, or
GRAY

For touch video input, the Remote Order Display Control follows the general “In-
put Model” for event-driven input with some differences:
• When input is received a DataEvent is enqueued.
• This device does not support the AutoDisable property, so will not
automatically disable itself when a DataEvent is enqueued.
• An enqueued DataEvent is delivered to the application when the
met. Just before delivering this event, data is copied into the properties, and
further data events are disabled by setting the DataEventEnabled property to
false. This causes subsequent input data to be enqueued while the application
processes the current input and associated properties. When the application
has finished the current input and is ready for more data, it reenables events
by setting DataEventEnabled to true.
• An ErrorEvent is enqueued if an error occurs while gathering or processing
input, and is delivered to the application when the DataEventEnabled
property is true and other event delivery requirements are met.
• The VideoDataCount property may be read to obtain the number of video
DataEvents for a specific unit ID enqueued. The DataCount property can be
read to obtain the total number of data events enqueued.
• Input enqueued may be deleted by calling the clearInput method. See
For video and tone output, the Remote Order Display follows the general Output
Model, with some enhancements:
• The following methods are always performed synchronously: controlClock,
controlCursor, selectCharacterSet, resetVideo, and setCursor. These
methods will fail if asynchronous output is outstanding. The following method
is also always performed synchronously but without regard to outstanding
asynchronous output: freeVideoRegion.
clearVideo, clearVideoRegion, copyVideoRegion, displayData, drawBox,
restoreVideoRegion, saveVideoRegion, transactionDisplay,
updateVideoRegionAttribute, and videoSound. When AsyncMode is false,
then these methods operate synchronously.
When AsyncMode is true, then these methods operate as follows:
• The request is buffered in program memory for delivery to the Physical
Device as soon as the Physical Device can receive and process it, the
OutputID property is set to an identifier for this request, and returns as
soon as possible. When the device completes the request successfully,
then the EventUnits property is updated and an OutputCompleteEvent
is enqueued. A property of this event contains the output ID of the
completed request.
Asynchronous methods will not raise a UposException due to a display
problem, such as communications failure. These errors will only be
reported by an ErrorEvent. A UposException is raised only if the display
is not claimed and enabled, a parameter is invalid, or the request cannot
be enqueued. The first two error cases are due to an application error,
while the last is a serious system resource exception.


ErrorEvent is enqueued. The EventUnits property is set to the unit or
units in error. The EventString property is also set.
Note: ErrorEvent updates EventUnits and EventString. If an error is
reported by a synchronous broadcast method, then ErrorUnits and
ErrorString are set instead.
The event handler may call synchronous display methods (but not
asynchronous methods), then can either retry the outstanding output or
clear it.
• All unit buffered output data, including all asynchronous output, may be
deleted by setting the CurrentUnitID property and calling clearOutput.
OutputCompleteEvents will not be delivered for cleared output. This
When AsyncMode is false, then these methods operate synchronously

and the Service returns to the application after completion. When
operating synchronously, a UposException is raised if the method could
not complete successfully.
• The Remote Order Display device may support transaction mode. A
transaction is a sequence of display operations that are sent to a video unit as
a single unit. Display operations which may be included in a transaction are
clearVideo, clearVideoRegion, copyVideoRegion, displayData, drawBox,
restoreVideoRegion, saveVideoRegion, and
updateVideoRegionAttribute. During a transaction, the display operations
are first validated. If valid, they are added to the transaction but not displayed
yet. Once the application has added as many operations as required, then the
transaction display method is called.
If the transaction is displayed synchronously, then any exception raised

indicates that an error occurred during the display. If the transaction is
displayed asynchronously, then the asynchronous display rules listed above
are followed. If an error occurs and the ErrorEvent handler causes a retry, the
entire transaction is retried.

Device Sharing
The Remote Order Display is an exclusive-use device. Its device sharing rules are:

Remote Order Display specific properties.
• When a claim method is called again, settable device characteristics are
restored to their condition at release. Examples of restored characteristics are
character set, video mode, and tone frequency. Region memory buffers, clock
and cursor settings are considered state characteristics and are not restored.


AsyncMode Property Updated in Release 1.11
Syntax AsyncMode: boolean { read-write, access after open-claim-enable }
Remarks If true, then the clearVideo, clearVideoRegion, copyVideoRegion,
displayData, drawBox, restoreVideoRegion, saveVideoRegion,
transactionDisplay, updateVideoRegionAttribute, and videoSound methods
will be performed asynchronously.
AutoToneDuration Property Updated in Release 1.11

Syntax AutoToneDuration: int32 { read-write, access after open-claim-enable }
Remarks Holds the duration (in milliseconds) of the automatic tone for the video unit
indicated in the CurrentUnitID property.
This property is initialized to the default value for each online video unit when the
Value Meaning
E_ILLEGAL An illegal value was specified. The ErrorString
property is updated.
AutoToneFrequency Property
Syntax AutoToneFrequency: int32 { read-write, access after open-claim-enable }
Remarks Holds the frequency (in Hertz) of the automatic tone for the video unit indicated
in the CurrentUnitID property.
This property is initialized to the default value for each online video unit when the
Value Meaning
E_ILLEGAL An illegal value was specified. The ErrorString


selected character set when displaying data.
Property.
CapSelectCharacterSet Property
Syntax CapSelectCharacterSet: boolean {read-only, access after open-claim-enable}
Remarks If true, the video unit indicated in the CurrentUnitID property may be loaded
with an alternate, user supplied character set.
This property is initialized for each video unit online when the device is first
enabled following the open method.
CapTone Property
Syntax CapTone: boolean { read-only, access after open-claim-enable }
Remarks If true, the video unit indicated in the CurrentUnitID property supports an
enunciator.

CapTouch Property
Syntax CapTouch: boolean { read-only, access after open-claim-enable }
Remarks If true, the video unit indicated in the CurrentUnitID property supports the
ROD_DE_TOUCH_UP, ROD_DE_TOUCH_DOWN, and
ROD_DE_TOUCH_MOVE event types.
Remarks If true, then transactions are supported by each video unit.
Syntax CharacterSet: int32 { read-only, access after open-claim-enable }
Remarks Holds the character set for displaying characters for the video unit indicated by
CurrentUnitID. When CapSelectCharacterSet is true, this property can be set
to one of the following values:
Value Meaning
ROD_CS_UNICODE The character set supports Unicode. The value of this
constant is 997.
ROD_CS_ASCII The ASCII character set, supporting the ASCII
constant is 998.
ROD_CS_ANSI The ANSI character set. The value of this constant is
999.
This property is initialized to the default video character set used by each video
unit online when the device is first enabled following the open method.
This is updated during the selectCharacterSet method.
See Also CurrentUnitID Property, CharacterSetList Property, CapSelectCharacterSet
Property, selectCharacterSet method.

Syntax CharacterSetList: string { read-only, access after open-claim-enable }
Remarks Holds a string of character set numbers for the video unit indicated in the
If CapSelectCharacterSet is true, this property is initialized for each video unit
online when the device is first enabled following the open method.
The character set number string consists of an ASCII numeric set of numbers,
separated by commas.
For example, if the string is “101, 850, 999”, the video unit supports a device-
See Also CurrentUnitID Property, CharacterSet Property, CapSelectCharacterSet
Property, selectCharacterSet Method.
Clocks Property
Syntax Clocks: int32 { read-only, access after open-claim-enable }
Remarks Holds the number of clocks the video unit, indicated in the CurrentUnitID
property, can support.
This property is initialized for each online video unit when the device is first
See Also CurrentUnitID Property

CurrentUnitID Property
Syntax CurrentUnitID: int32 { read-write, access after open-claim-enable }
Remarks Holds the current video unit ID. Up to 32 units are allowed on one Remote Order
Display device. The unit ID definitions range from ROD_UID_1 to
ROD_UID_32.
The following properties and methods apply only to the selected video unit ID:
• Properties: AutoToneDuration, AutoToneFrequency,
CapSelectCharacterSet, CapTone, CapTouch, CharacterSet,
CharacterSetList, Clocks, VideoDataCount, VideoMode,
VideoModesList, VideoSaveBuffers.
Setting CurrentUnitID will update these properties to the current values for
the specified unit.
Methods: checkHealth, clearInput, clearOutput.
This property is initialized to ROD_UID_1 when the device is first enabled

Value Meaning
E_ILLEGAL An illegal unit id was specified. The ErrorString

DataCount Property (Common)

Syntax DataCount: int32 { read-only, access after open }
Remarks Holds the total number of DataEvents enqueued. All units online are included in
this value. The number of enqueued events for a specific unit ID is stored in the
VideoDataCount property.
See Also “Device Input Model” on page 54, VideoDataCount Property, DataEvent.

ErrorUnits property, when an error occurs for any method that acts on a bitwise
set of video units.
updates the property EventString instead.
See Also ErrorUnits Property.
ErrorUnits Property
Syntax ErrorUnits: int32 { read-only, access after open }
Remarks Holds a bitwise mask of the unit(s) that encountered an error, when an error occurs
for any method that acts on a bitwise set of video units.
updates the property EventUnits instead.
See Also ErrorString Property.
EventString Property
Syntax EventString: string { read-only, access after open-claim }
EventUnits property, when an ErrorEvent is delivered.
See Also EventUnits Property, ErrorEvent.

EventType Property
Syntax EventType: int32 { read-write, access after open }
Remarks Holds a bitwise mask that is used to selectively indicate which event types are to
be delivered by the DataEvent, for all video units online. See the DataEvent
description for event type definitions.
This property is initialized to all defined event types by the open method.
Value Meaning
See Also DataEvent.
EventUnitID Property
Syntax EventUnitID: int32 { read-only, access after open-claim }
Remarks Holds the video unit ID of the last delivered DataEvent. The unit ID definitions
range from BB_UID_1 to BB_UID_32.
See Also DataEvent.
EventUnits Property
Syntax EventUnits: int32 { read-only, access after open-claim }
Remarks Holds a bitwise mask of the unit(s) when an OutputCompleteEvent, output
ErrorEvent, or StatusUpdateEvent is delivered.
See Also OutputCompleteEvent, ErrorEvent, StatusUpdateEvent.


CharacterSet property for displaying data.
SystemClocks Property
Syntax SystemClocks: int32 { read-only, access after open-claim-enable }
Remarks Holds the total number of clocks the Remote Order Display device can support at
one time.
method.
See Also Clocks Property.
SystemVideoSaveBuffers Property
Syntax SystemVideoSaveBuffers: int32 { read-only, access after open-claim-enable }
Remarks Holds the total number of video save buffers the Remote Order Display device can
support at one time.
method.
See Also VideoSaveBuffers Property.

Timeout Property
Syntax Timeout: int32 { read-write, access after open }
Remarks Holds the timeout value in milliseconds used by the Remote Order Display device
to complete all output methods supported. If the device cannot successfully
complete an output method within the timeout value, then the method throws a
UposException if AsyncMode is false, or enqueues an ErrorEvent if
AsyncMode is true.
This property is initialized to a Service dependent default timeout following the
open method.
Value Meaning

UnitsOnline Property
Syntax UnitsOnline: int32 { read-only, access after open-claim-enable }
Remarks Holds a bitwise mask indicating the video units online. Bit 0 is ROD_UID_1. 32
video units are supported. See “Model” on page 1080.
method. This property is updated as changes are detected, such as before a
StatusUpdateEvent is enqueued and during the checkHealth method.
See Also “Model” on page 1080, checkHealth Method, StatusUpdateEvent.
VideoDataCount Property
Syntax VideoDataCount: int32 { read-only, access after open-claim-enable }
Remarks Holds the number of DataEvents enqueued for the video unit indicated in the
enqueued from a video unit, but has not yet been delivered because of other
application processing, freeing of events, or other causes.

VideoMode Property
Syntax VideoMode: int32 { read-write, access after open-claim-enable }
Remarks Holds the video ModeId selected for the video unit indicated by the
CurrentUnitID property. The ModeId represents one of the selections in the
VideoModesList property.
This property is initialized to the Service dependent default video ModeId used by
each video unit online when the device is first enabled following the open method.
Value Meaning
E_FAILURE An error occurred while communicating with the video
unit indicated in the CurrentUnitID property. The
ErrorString property is updated.
See Also CurrentUnitID Property, VideoModesList Property.
VideoModesList Property
Syntax VideoModesList: string { read-only, access after open-claim-enable }
Remarks Holds the video modes supported for the video unit indicated in the
CurrentUnitID property. The video modes are listed in a comma delineated string
with the following format:
<ModeId>:<Height>x<Width>x<NumberOfColors><M|C>.
The ModeId values are determined by the Remote Order Display system.
M = Monochrome (and gray scales) and C = Color.
For example, if the string is “1:40x25x16C,2:80x25x16C”, then the video unit
supports two video modes, ModeId 1 and ModeId 2. ModeId 1 has 40 rows, 25
columns, 16 colors, and is Color. ModeId 2 has 80 rows, 25 columns, 16 colors,
and is Color.
The ModeId is used to initialize the VideoMode property for each video unit
online.
This property is initialized to the video modes list supported by each video unit
online when the device is first enabled following the open method.
See Also CurrentUnitID Property, VideoMode Property.

VideoSaveBuffers Property
Syntax VideoSaveBuffers: int32 { read-only, access after open-claim-enable }
Remarks Holds the number of save buffers for the video unit indicated in the
CurrentUnitID property. This property should be consulted when using the
saveVideoRegion, restoreVideoRegion and freeVideoRegion methods. When
set to 0, this indicates that buffering for the selected unit is not supported. When
this property is greater than 0, the Remote Order Display device can save at
minimum one entire video screen for the selected video unit.
See Also CurrentUnitID Property, saveVideoRegion Method, restoreVideoRegion
Method, freeVideoRegion Method.

checkHealth Method (Common)

The level parameter indicates the level of health check to be performed on the
Value Meaning

extent possible.
device. For example, a pattern may be displayed on the
video.
CH_INTERACTIVE Perform an interactive test of the device. The Service
will typically display a modal dialog box to present test
options and results.
Remarks When CH_INTERNAL or CH_EXTERNAL level is requested, the method
checks the health of the unit indicated in the CurrentUnitID property. If the
current unit ID property is zero, an EROD_NOUNITS error is set. When the
current unit ID property is set to a unit that is not currently online, the device will
attempt to check the health of the video unit and report a communication error if
necessary. The CH_INTERACTIVE health check operation is up to the Service
designer.
property.
The UnitsOnline property will be updated with any changes before returning to
the application.
Value Meaning
E_EXTENDED ErrorCodeExtended = EROD_NOUNITS: The

CurrentUnitID property is zero.
E_FAILURE An error occurred while communicating with the video
unit indicated in CurrentUnitID property.
See Also CurrentUnitID Property, UnitsOnline Property.

clearInput Method (Common)

Remarks Clears the device input that has been buffered for the unit indicated in the
CurrentUnitID property. If the current unit ID property is zero, an
EROD_NOUNITS is set.
Any data events that are enqueued – usually waiting for DataEventEnabled to be
set to true and FreezeEvents to be set to false – are also cleared.
Value Meaning

CurrentUnitID property is zero.
See Also CurrentUnitID Property, “Device Input Model” on page 54.
clearOutput Method (Common) Updated in Release 1.7

Remarks Clears all outputs that have been buffered, including all asynchronous output, for
the unit indicated in the CurrentUnitID property, including video and tone
outputs. If the current unit ID property is zero, an EROD_NOUNITS is set.
Any output complete and output error events that are enqueued – usually waiting
for DataEventEnabled to be set to true and FreezeEvents to be set to false – are
also cleared.
Value Meaning

CurrentUnitID property is set to zero.
See Also CurrentUnitID Property, “Device Output Models” on page 57.

clearVideo Method
Syntax clearVideo ( units: int32, attribute: int32 ):
units Bitwise mask indicating which video unit(s) to operate on.
attribute See Model on page 1080 in the General Information section.
Remarks Clears the entire display area for the video unit(s) indicated in the units parameter.
The display area will be cleared using the attribute placed in the attribute
parameter.
See Also AsyncMode Property, “Model” on page 1080
clearVideoRegion Method
Syntax clearVideoRegion ( units: int32, row: int32, column: int32, height: int32,
width: int32, attribute: int32 ):
row The region’s start row.
column The region’s start column.
height The number of rows in the region.
width The number of columns in the region.
attribute See “Model” on page 1080 in the General Information section.
Remarks Clears the specified video region for the video unit(s) indicated in the units
parameter. The display area will be cleared using the attribute placed in the
attribute parameter.
Value Meaning
E_FAILURE An error occurred while communicating with one of the video
units indicated in units. The ErrorUnits and ErrorString
properties are updated. (Can only occur if AsyncMode is false.)
See Also AsyncMode Property, ErrorString Property, ErrorUnits Property, “Model” on
page 1080.

controlClock Method
Syntax controlClock ( units: int32, function: int32, clockId: int32, hour: int32,
min: int32, sec: int32, row: int32, column: int32, attribute: int32,
mode: int32 ):

function The requested clock command. See values below.
clockId Clock identification number. The valid values can be from 1 -
Clocks. When the function parameter is
ROD_CLK_PAUSE, ROD_CLK_RESUME,
or ROD_CLK_STOP
then clockId can be ROD_CLK_ALL to specify all clocks started
on the specified video unit(s).
hour The initial hours for the clock display.
min The initial minutes for the clock display.
sec The initial seconds for the clock display.
row The clock’s row.
column The clock’s start column.
attribute See “Model” on page 1080 in the General Information section.
mode The type of clock to display. See values below.
The function parameter values are:
Value Meaning
ROD_CLK_START Starts a clock display assigned to the given clockId.

ROD_CLK_PAUSE Temporarily stops a clock from updating the display
until a ROD_CLK_RESUME requested.
ROD_CLK_RESUME Resumes a clock that was previously paused, such that
display updates continue.
ROD_CLK_STOP Permanently stops the clock from updating the display
and the clockId becomes free.
ROD_CLK_MOVE Moves an instantiated clock to a new position.
The mode parameter values are:

Value Meaning
ROD_CLK_SHORT Displays a clock with “M:SS” format.

ROD_CLK_NORMAL Displays a clock with “MM:SS” format.
ROD_CLK_12_int Displays a 12 hour clock with “HH:MM:SS” format.
ROD_CLK_24_int Displays a 24 hour clock with “HH:MM:SS” format.

Remarks Performs the clock command requested in the function parameter on the video
unit(s) indicated in the units parameter. The clock will be displayed in the
requested mode format at the location found in the row and column parameters.
The clock will start at the specified hour, min, and sec, time values and will be
updated every second until a ROD_CLK_PAUSE or ROD_CLK_STOP is
requested for this clockId.
When a ROD_CLK_PAUSE, ROD_CLK_RESUME, or ROD_CLK_STOP
command is issued, the hour, min, sec, row, column, attribute, and mode
parameters are ignored. During a ROD_CLK_PAUSE command, the clock
display updates are suspended. During a ROD_CLK_RESUME command, the
clock updates continue.
If a ROD_CLK_PAUSE, ROD_CLK_RESUME, ROD_CLK_STOP or
ROD_CLK_MOVE command is requested on an uninitialized clockId for any of
the video units indicated in the units parameter, a EROD_BADCLK error is
thrown. If a ROD_CLK_RESUME command is requested without doing a
ROD_CLK_PAUSE, this has no effect and no exception is thrown.
When a ROD_CLK_MOVE command is issued, the clock is moved to the new
location found in the row and column parameters. The hour, min, sec, attribute and
mode parameters are ignored for this command function.
Generally a video unit can support the number of clocks indicated in the Clocks
property. However, the ROD_CLK_START command will raise an exception
containing EROD_NOCLOCKS if it exceeds the number of SystemClocks even
though the Clocks property may indicate the unit can support more clocks than
allocated for that unit.
Value Meaning
E_EXTENDED ErrorCodeExtended = EROD_BADCLK:

A ROD_CLK_PAUSE, ROD_CLK_RESUME,
ROD_CLK_START, ROD_CLK_MOVE command was
requested and the specified clockId has not been initialized by the
ROD_CLK_START command.
ErrorCodeExtended = EROD_NOCLOCKS: The
ROD_CLK_START failed because the number of
SystemClocks has been reached.
The ErrorUnits and ErrorString properties are updated.
E_FAILURE An error occurred while communicating with one of the video
units indicated in the units parameter. The ErrorUnits and
ErrorString properties are updated.
E_BUSY When a ROD_CLK_START command is requested but the
specified clockId is in use. The ErrorUnits and ErrorString
properties are updated.
See Also Clocks Property, ErrorString Property, ErrorUnits Property, “Model” on page
1080.

controlCursor Method
Syntax controlCursor ( units: int32, function: int32 ):

function The cursor command, indicating the type of cursor to display.
See values below.
Value Meaning
ROD_CRS_LINE enable a solid underscore line.

ROD_CRS_LINE_BLINK enable a blinking solid underscore cursor.
ROD_CRS_BLOCK enable a solid block cursor.
ROD_CRS_BLOCK_BLINK enable a blinking solid block cursor.
ROD_CRS_OFF Disable cursor.
Remarks Enables or disables the cursor depending on the function parameter, for the video
unit(s) indicated in the units parameter.
When the function is ROD_CRS_OFF, the cursor is disabled, otherwise the cursor
is enabled as the requested cursor type. If the video unit cannot support the
requested cursor type, the Service will use the next closest cursor type.
The cursor attribute is taken from the current cursor location.
Value Meaning
E_FAILURE An error occurred communicating with one of the video

units indicated in units. The ErrorUnits and
See Also ErrorString Property, ErrorUnits Property.

copyVideoRegion Method
Syntax copyVideoRegion ( units: int32, row: int32, column: int32, height: int32,
width: int32, targetRow: int32, targetColumn: int32 ):

targetRow The start row of the target location.
targetColumn The start column of the target location.
Remarks Copies a region of the display area to a new location on the display area for the
video unit(s) indicated in the units parameter. The source area is defined by the
row, column, height, and width parameters. The top-left corner of the target
location is defined by the targetRow and targetColumn parameters. If the ranges
overlap the copy is done such that all original data is preserved.
Value Meaning

video units indicated in units. The ErrorUnits and
ErrorString properties are updated. (Can only occur if
page 1080.

displayData Method Updated in Release 1.7

Syntax displayData ( units: int32, row: int32, column: int32, attribute: int32,
data: string ):

row The start row for the text.
column The start column for the text.
attribute The video attribute. See Model on page 1080 in the General
Information section.
data1 The string of characters to display.
Remarks Displays the characters in data beginning at the location specified by row and
column, and continues in succeeding columns on the video unit(s) indicated in the
units parameter. Any characters that extend beyond the last column will be
discarded.
Value Meaning

page 1080.

drawBox Method
Syntax drawBox ( units: int32, row: int32, column: int32, height: int32, width: int32,
attribute: int32, bordertype: int32 ):

row The box’s start row.
column The box’s start column.
height The number of rows in the box.
width The number of columns in the box.
attribute The video attribute. See “Model” on page 1080 in the
General Information section.
bordertype The border type to be drawn. Can be any printable character
or a defined border type. See values below.
Value Meaning
ROD_BDR_SINGLE A single line border.

ROD_BDR_DOUBLE A double line border.
ROD_BDR_SOLID A solid block border.
Remarks Draws a box on the video unit(s) indicated in the units parameter.
The Remote Order Display will attempt to draw a box with the border type
specified. If the character set does not support the chosen border type, the Service
will choose the best fit from the given character set.
Value Meaning

page 1080.

freeVideoRegion Method
Syntax freeVideoRegion ( units: int32, bufferId: int32 ):

bufferId Number identifying the video buffer to free. Valid values
range from 1 to the VideoSaveBuffers property for a
selected unit(s).
Remarks Frees any buffer memory allocated for the video unit(s) indicated in the units
parameter. The number of video buffers supported is stored in the
VideoSaveBuffers property for each video unit online. If the bufferId was never
used in a previous saveVideoRegion method, no action is taken.
Value Meaning

See Also ErrorString Property, ErrorUnits Property, VideoSaveBuffers Property,
saveVideoRegion Method.
resetVideo Method
Syntax resetVideo ( units: int32 ):
units is a bitwise mask indicating which video unit(s) to operate on.
Remarks Sets the video unit(s) indicated in the units parameter to a power on state. All
Service buffers and clocks associated with the unit(s) are released. All settable
characteristics are set to default values.
Value Meaning


restoreVideoRegion Method
Syntax restoreVideoRegion ( units: int32, targetRow: int32, targetColumn: int32,
bufferId: int32 ):

targetRow The start row of the target location.
targetColumn The start column of the target location.
bufferId Number identifying the source video buffer to use. Valid
values range from 1 to the VideoSaveBuffers property for
the selected unit(s).
Remarks Restores a previously saved video region of the display area from the requested
bufferId for the video unit(s) indicated in the units parameter. A region can be
saved using the saveVideoRegion method. The number of video buffers supported
is stored in the VideoSaveBuffers property for each video unit online. The target
location is defined by the targetRow and targetColumn parameters. This method
doesn’t free the memory after restoring, therefore, this method can be used to copy
a video region to multiple locations on the display. Use the freeVideoRegion
method to free any memory allocated for a video buffer.
If the bufferId does not contain a previously saved video region for the units
selected, a EROD_NOREGION exception is raised.
Video regions cannot be restored between video units. For example, the
saveVideoRegion method is called with units = 0000 1000 and bufferId = 1. This
will save a video region for the Unit Id 4, in to Buffer 1 for that unit. If this method
is called with units = 0000 0100 and bufferId = 1 with the intention of restoring the
previously saved buffer to Unit Id 3, then either a UposException with ErrorCode
of EROD_NOREGION would be thrown, or an unwanted region would be
restored.
Value Meaning
E_EXTENDED ErrorCodeExtended = EROD_NOREGION: The
bufferId does not contain a previously saved video
region.
See Also AsyncMode Property, ErrorString Property, ErrorUnits Property,
VideoSaveBuffers Property, saveVideoRegion Method.

saveVideoRegion Method
Syntax saveVideoRegion ( units: int32, row: int32, column: int32, height: int32,
width: int32, bufferId: int32 ):

row The start row of the region to save.
column The start column of the region to save.
height The number of rows in the region to save.
width The number of columns in the region to save.
bufferId Number identifying the video buffer to use. Valid values
range from 1 to the VideoSaveBuffers property for a
selected unit(s).
Remarks Saves the specified video region of the display area to one of the provided video
buffers for the video unit(s) indicated in the units parameter. The number of video
buffers supported is stored in the VideoSaveBuffers property for each video unit
online. However, a UposException will be raised if the requested buffer exceeds
the number of SystemVideoSaveBuffers even though the VideoSaveBuffers
property may indicated the unit can support more save buffers than currently
allocated for that unit.
If VideoSaveBuffers is greater than 0, the Service will be able to support at
minimum one entire video screen. This does not guarantee that the Service can
save an entire video screen in each supported buffer for a single unit. A
UposException is raised when all the buffer memory has been allocated for a
specific unit.
The source area is defined by the row, column, height, and width parameters. The
video region can be restored to the screen by calling the restoreVideoRegion
method. If saveVideoRegion is called twice with the same bufferId, the previous
video data is lost, and any allocated memory is returned to the system.
Value Meaning
E_ILLEGAL bufferId, row, column, height, or width is out of range.

The ErrorUnits and ErrorString properties are
updated.
E_EXTENDED ErrorCodeExtended = EROD_NOBUFFERS:
Requested buffer exceeds the number of
SystemVideoSaveBuffers.

ErrorCodeExtended = EROD_NOROOM:
All the buffer memory has been allocated for a specific
unit. The ErrorUnits and ErrorString properties are
updated.
See Also AsyncMode Property, ErrorString Property, ErrorUnits Property,
SystemVideoSaveBuffers Property, VideoSaveBuffers Property,
restoreVideoRegion Method.
selectCharacterSet Method
Syntax selectCharacterSet ( units: int32, characterSet: int32 ):
characterSet Contain the character set for displaying characters. Values
are:
Value Meaning
Range 101 - 199 A device-specific character set that does not match a
code page, nor the ASCII or ANSI character sets.
ROD_CS_UNICODE The character set supports Unicode. The value of this
constant is 997.
ROD_CS_ASCII The ASCII character set, supporting the ASCII
characters between 20-hex and 7F-hex. The value of this
constant is 998.
ROD_CS_ANSI The ANSI character set. The value of this constant is
999.
Remarks Selects a compatible character set for the video unit(s) indicated in the units
parameter.
The CharacterSet property is updated for each video unit id that is successfully
assigned a new character set.
Value Meaning
See Also ErrorString Property, ErrorUnits Property, CapSelectCharacterSet Property,
CharacterSet Property.

setCursor Method
Syntax setCursor ( units: int32, row: int32, column: int32 ):
row Row to place the cursor on.
column Column to place the cursor on.
Remarks Updates the cursor position on the video unit(s) indicated in the units parameter.
Value Meaning

transactionDisplay Method
Syntax transactionDisplay ( units: int32, function: int32 ):

function Transaction control function. Valid values are:
Value Meaning
ROD_TD_TRANSACTION
Begin a transaction.
ROD_TD_NORMAL End a transaction by displaying the buffered data.
Remarks Enters or exits transaction mode for the video unit(s) indicated in the units
parameter.
If function is ROD_TD_TRANSACTION, then transaction mode is entered.
Subsequent calls to clearVideo, clearVideoRegion, copyVideoRegion,
displayData, drawBox, restoreVideoRegion, saveVideoRegion, and
updateVideoRegionAttribute will buffer the display data (either at the video unit
or the Service, depending on the display capabilities) until transactionDisplay is
called with the function parameter set to ROD_TD_NORMAL. (In this case, the
display methods only validate the method parameters and buffer the data – they do
not initiate displaying. Also, the value of the AsyncMode property does not affect
their operation: No OutputID will be assigned to the request, nor will an
OutputCompleteEvent be enqueued.)

If function is ROD_TD_NORMAL, then transaction mode is exited. If some data

was buffered by calls to the methods clearVideo, clearVideoRegion,
copyVideoRegion, displayData, drawBox, restoreVideoRegion,
saveVideoRegion, and updateVideoRegionAttribute, then the buffered data is
displayed. The entire transaction is treated as one message. This method is
AsyncMode is true.
Calling the clearOutput method cancels transaction mode for the unit indicated in
the CurrentUnitID property. Any buffered print lines are also cleared.
Value Meaning
E_BUSY Cannot perform while output is in progress for one of the

AsyncMode is false and function is
ROD_TD_NORMAL.)
AsyncMode is false and function is
ROD_TD_NORMAL.)
See Also clearVideo Method, clearVideoRegion Method, copyVideoRegion Method,
displayData Method, drawBox Method, restoreVideoRegion Method,
saveVideoRegion Method, updateVideoRegionAttribute Method.
updateVideoRegionAttribute Method
Syntax updateVideoRegionAttribute ( units: int32, function: int32, row: int32,
column: int32, height: int32, width: int32, attribute: int32 ):
function The attribute command. See values below.
attribute See Model on page 1080 in the General Information section.

The function parameter values are:

Value Meaning
ROD_UA_SET Set the region with the new attribute.
ROD_UA_INTENSITY_ON Turn on foreground intensity in the region.
ROD_UA_INTENSITY_OFF Turn off foreground intensity in the region.
ROD_UA_REVERSE_ON Reverse video the region.
ROD_UA_REVERSE_OFF Remove reverse video from the region.
ROD_UA_BLINK_ON Turn on blinking in the region.
ROD_UA_BLINK_OFF Turn off blinking in the region.
Remarks Modifies the attribute on the video unit(s) indicated in the units parameter in the
region defined by the row, column, height, and width parameters. When the
function parameter is ROD_UA_SET, the region’s attributes will be replaced with
the new value in the attribute parameter; otherwise the attribute parameter is
ignored and the region’s attributes will be modified.
Value Meaning

page 1080.

videoSound Method
Syntax videoSound ( units: int32, frequency: int32, duration: int32,

frequency Tone frequency in Hertz.
duration Tone duration in milliseconds.
numberOfCycles If FOREVER, then start tone sounding and, repeat
continuously. Else perform the specified number of cycles.
interSoundWait milliseconds before repeating the tone cycle
(before playing the tone again).
Remarks Sounds the video enunciator for the video(s) indicated in the units parameter.
The duration of a video tone cycle is:
duration parameter + interSoundWait parameter (except on the last tone cycle)
After the video has started an asynchronous sound, then the clearOutput method
will stop the sound. (When an interSoundWait value of FOREVER was used to
start the sound, then the application must use clearOutput to stop the continuous
sounding of tones.)
If CapTone is false for the selected unit(s), a UposException is raised.
Value Meaning

See Also AsyncMode Property, ErrorString Property, ErrorUnits Property, CapTone
Property, clearOutput Method.

DataEvent
Description Notifies the application when input data from a video touch unit is available.

Status int32 As described below

The Status attribute is divided into four bytes as indicated below:
High Word Low Word (Event Type)

High Byte Low Byte
ROD_DE_TOUCH_UP
Row Column ROD_DE_TOUCH_DOWN
ROD_DE_TOUCH_MOVE
The low word contains the Event type. The high word contains additional data
depending on the Event type. When the Event type is ROD_DE_TOUCH_UP,
ROD_DE_TOUCH_DOWN, or ROD_DE_TOUCH_MOVE, the high word
indicates where the touch occurred. The low byte contains the Column position
and the high byte contains the Row position, with valid values ranging from 0-255.
Remarks This event can be filtered at the Remote Order Display device by setting the
EventType property.
The EventUnitID property is updated before the event is delivered.
See Also “Device Input Model” on page 54, EventUnitID Property, DataEventEnabled

DirectIOEvent
means for a vendor-specific Remote Order Display Service to provide events to the
Service.
from being used with other vendor’s Remote Order Display devices which may
not have any knowledge of the Service’s need for this event.

Description Notifies the application that a Remote Order Display error has been detected and
ErrorCodeExtended
int32 Extended error code causing the error event. If


values below.
Value Meaning
available.
available.
Value Meaning
ER_RETRY Use only when locus is EL_OUTPUT.
state is exited.
Remarks Input error events are not delivered until the DataEventEnabled property is true,
so that proper application sequencing occurs.
The EventUnits and EventString properties are updated before the event is
delivered.
page 62, DataEventEnabled Property, EventUnits Property, EventString
Property.

OutputCompleteEvent
OutputID property has completed successfully.
is complete.
Remarks Enqueued when a previously started asynchronous output request completes
successfully. The EventUnits property is updated before the event is delivered.
See Also EventUnits Property, “Device Output Models” on page 57.
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a video unit.

Status int32 Reports a change in the power state of a display.
process.
Remarks Enqueued when the Remote Order Display detects a power state change.
Deviation from the standard StatusUpdateEvent (see page 108):
• Before delivering the event, the EventUnits property is set to the units for
which the new power state applies.
• When the Remote Order Display is enabled, then a StatusUpdateEvent is
enqueued to specify the bitmask of online units.
• While the Remote Order Display is enabled, a StatusUpdateEvent is
enqueued when the power state of one or more units change. If more than one
unit changes state at the same time, the Service may choose to either enqueue
multiple events or to coalesce the information into a minimal number of events
applying to EventUnits.
See Also EventUnits Property.

C H A P T E R 3 2
RFID Scanner
This Chapter defines the RFID Scanner device category.
Summary


1118 RFID Scanner
CapContinuousRead: boolean { read-only } 1.12 open
CapDisableTag: boolean { read-only } 1.12 open
CapLockTag: boolean { read-only } 1.12 open
CapMultipleProtocols: int32 { read-only } 1.12 open
CapReadTimer: boolean { read-only } 1.12 open
CapWriteTag: int32 { read-only } 1.12 open
ContinuousReadMode: boolean { read-only } 1.12 open

CurrentTagID: binary { read-only } 1.12 open
CurrentTagProtocol: int32 { read-only } 1.12 open
CurrentTagUserData: binary { read-only } 1.12 open
ProtocolMask: int32 { read-write } 1.12 open & claim
ReadTimerInterval: int32 { read-write } 1.12 open & claim
TagCount: int32 { read-only } 1.12 open

Common
Name Version
close ( ): 1.12
release ( ): 1.12

Summary 1119

Specific
Name
disableTag (tagID: binary, timeout: int32, password: binary): 1.12
firstTag ( ): 1.12
lockTag (tagID: binary, timeout: int32, password: binary): 1.12
nextTag ( ): 1.12
previousTag ( ): 1.12
readTags (cmd: int32, filterID: binary, filtermask: binary, start: int32, 1.12
length: int32, timeout: int32, password: binary):
startReadTags (cmd: int32, filterID: binary, filtermask: binary, start: int32, 1.12
length: int32, password: binary):
stopReadTags (password: binary): 1.12
writeTagData (tagID: binary, userdata: binary, start: int32, timeout: int32, 1.12
password: binary):
writeTagID (sourceID: binary, destID: binary, timeout: int32, password: 1.12
binary):

1120 RFID Scanner


General Information
The RFID Scanner device programmatic name is “RFIDScanner”.
Capabilities
The RFID Scanner device has the following capabilities:

• Reads TagID and UserData from RFID tags.
• Reading of partial UserData
The RFID Scanner device may also support the following capabilities:
• Continuous reading of tags.
• Writes TagID to RFID tags
• Locking a tag
• Writes UserData to specified RFID tags
• Disables (kills) RFID tags
• Writing of partial UserData

1122 RFID Scanner
RFID Scanner Class Diagram
The following diagram shows the relationships between the RFID Scanner
classes.
DataEvent
+Status : int32
RFID Scanner
+CapContinuousRead : bool <<fires>>
+CapDisableTag : bool
+CapLockTag : bool To indicate that the read
+CapMultipleProtocols : int32 operation completed successfully.
+CapReadTimer : bool
+CapWriteTag : int32
+ContinuousReadMode : bool
+CurrentTagID : binary <<fires>> OutputCompleteEvent
+CurrentTagProtocol : int32
+CurrentTagUserData : binary +OutputID : int32
+ProtocolMask : int32
+ReadTimerInterval : int32
+TagCount : int32
+disableTag() To indicate that the write
+firstTag() operation completed successfully.
+lockTag() <<fires>>
+nextTag()
+previousTag()
+readTags() ErrorEvent
+startReadTags() +ErrorCode : int32
+stopReadTags() +ErrorCodeExtended : int32
+writeTagData() +ErrorLocus : int32
+writeTagID() +ErrorResponse : int32
To indicate that the operation

failed.

Model
The RFID Scanner is both an event-driven input device and an output device.
Input and output are always asynchronous. The tag is considered to consist of
contiguous fields called the Tag ID and the User Data. This present standard does
not at this time define the Tag ID or User Data fields; they are determined in a
device specific manner by the RFID Scanner Service and may vary depending on
the protocol property setting.
Input
The RFID Scanner follows the general “Device Input Model”, with some
differences. In particular, only one DataEvent is delivered for the entire group of
tags read in one input operation:
• In its simplest form, readTags method can be invoked with the cmd
parameter serving as data selector (ID, FullData, PartialData, or
combinations) and other parameters holding corresponding default values, a
collection of tags that meet the parameterized criteria will be returned.
• Application can filter read tags by passing in two bit patterns: filterID and
filtermask. A filtered read operation should only return the tags whose TagID,
when bitwise AND’ed with the parameterized filtermask matches the bitwise
AND’ed result of filterID and filtermask. To request all tags in read range, the
application can pass in a filtermask with all zeros. When all tag data has been
collected, a DataEvent is enqueued. Tag filtering must be supported, either
in hardware or in the RFID Scanner Service.
• Partial UserData reading must also be supported, if not in the hardware then
in the RFID Scanner Service. For accessing a specific segment of the
UserData, the application can configure the cmd parameter by turning on the
RFID_RT_PARTIALUSERDATA bit, and then pass in the starting position
and the length of the targeted segment. The CurrentTagUserData property
that is populated by a navigation method such as nextTag will now contain
the segment that is specified.
• If the AutoDisable property is true, the device automatically disables itself
when a DataEvent is enqueued.
DataEventEnabled property is true and other event delivery requirements
are met. Just before delivering this event, TagCount is set to the total number
of tags that were read, the data from the first tag are placed into the
CurrentTagID, CurrentTagProtocol and CurrentTagUserData properties,
and further DataEvents are disabled by setting DataEventEnabled to false.
• After receiving a DataEvent the application determines the total number of
tags read by reading the TagCount property. The application can navigate
through the tags by calling firstTag, nextTag, and previousTag and can
retrieve tag information via the CurrentTagID, CurrentTagProtocol, and
CurrentTagUserData properties. The firstTag, nextTag, and previousTag
methods are synchronous and no physical input or output occurs when they
are called.
• When the application finishes processing all the current input and is ready for

1124 RFID Scanner
more data, it re-enables events by setting DataEventEnabled to true.

processing input, such as a timeout event, and is delivered to the application
when DataEventEnabled is true and other event delivery requirements are
met.
• A DataEvent or an ErrorEvent must be received before another readTags
method can be invoked. All enqueued input may be deleted by calling
clearInput.
• If CapContinuousRead is true, application can invoke startReadTags and
stopReadTags for continuously reading. startReadTags polls tags within
the range in the same manner as readTags, but it continuously queues tag
read DataEvent until it is interrupted by stopReadTags.
Output
The RFID Scanner follows the general “Device Output Model”, with some
differences and enhancements:
• The application can determine what is writable by querying CapWriteTag.
• If supported, the application can write to TagID and UserData by invoking
the writeTagID or the writeTagData method respectively.
• All write operations involving the tag’s UserData can be considered partial
writes (i.e. they will only overwrite the section of the tag’s UserData field
specified by the userData and start parameters of the writeTagData method).
Therefore, in order to overwrite the entire contents of the tag’s UserData
field, the application must ensure that the userData parameter contains
enough data to completely overwrite the tag’s UserData section. The
application may need to pad the userData parameter with null (0x0) bytes in
order to completely overwrite existing data and may need to first read the
tag’s UserData in order to determine amount of padding required.
• If CapLockTag is true, the application can also lock a tag by invoking the
lockTag method. When a tag is locked both the ID and UserData become
read-only. For the case where a password is required, it can be specified in
the parameter list.
• If CapDisableTag is true, the application can also call disableTag giving the
tagID of the tag it wants to permanently disable (kill).
• The RFID Scanner Service buffers the request for delivery to the RFID
hardware as soon as the RFID hardware can receive and process it, sets the
OutputID property to an identifier for this request, and returns as soon as
possible. When the Service completes the request successfully, an
OutputCompleteEvent is enqueued. A property of this event contains the
OutputID of the completed request.
• If an error occurs while performing an asynchronous request, such as a
timeout event, an ErrorEvent is enqueued.

RFID Scanner Sequence Diagrams

The following diagram shows a typical initialization sequence for a RFID
Scanner device.
: Client App : RFID Scanner : RFID Scanner Service
getCapMultipleProtocols()
getCapMultipleProtocols()
setProtocolMask()
setProtocolMask()

1126 RFID Scanner
The following diagram shows a typical usage of a RFID Scanner device reading
tags.
: ClientApp : RFID Scanner : RFID Scanner Service : RFID Hardware
setProtocolMask()
setProtocolMask()
readTag(RFID_READ_TAGID)
readTag(RFID_READ_TAGID)
issue read command
send tag data
collect data from all tags which match the tag mask
enqueue DataEvent
load data from first tag into CurrentTag* properties and deliver enqueued DataEvent to control
deliver DataEvent to application

notify client of new event
getTagCount() getTagCount()
getCurrentTagID() getCurrentTagID()
getCurrentTagUserData() getCurrentTagUserData()
nextTag()
nextTag()
load next tag data into CurrentTag* properties

The following diagram shows a typical usage of a RFID Scanner device writing
tags.
: RFID Output Complete

: Client App : RFID Scanner : RFID Scanner Service Event : RFID Hardware
writeTagData()
writeTagData()
generate OutputID(1)
getOutputID() send write cmd and associated user data
getOutputID()
write cmd complete
create
deliver enqueued OutputCompleteEvent to control
deliver OutputCompleteEvent to all event handlers
notify client of new event

1128 RFID Scanner
RFID Scanner State Diagram
The following diagram illustrates the various state transitions within the RFID
Scanner device category.
Closed
open()
Opened
close()
claim()
Claimed release()
SetDeviceEnabled(true)
SetDeviceEnabled(false)
startReadTags()
Continuous Read Mode Enabled
stopReadTags()
Busy State
ErrorEvent
readTags() Input Requested
DataEvent
clearInput()
disableTag()
lockTag() OutputCompleteEvent
Output Requested
writeTagID() ErrorEvent
writeTagData() clearOutput()
Device Sharing
The RFID Scanner is an exclusive-use device, as follows:

the RFID Scanner specific properties.


CapContinuousRead Property
Syntax CapContinuousRead: boolean { read-only, access after open }
Remarks If true, the device supports continuous reading. The application should query this
property before invoking startReadTags and other continuous read methods.
See Also ContinuousReadMode Property, startReadTags Method, stopReadTags
Method.
CapDisableTag Property
Syntax CapDisableTag: boolean { read-only, access after open }
Remarks If true, the device supports disabling a tag permanently. The application should
query this property before invoking the disableTag method.
See Also disableTag Method.
CapLockTag Property
Syntax CapLockTag: boolean { read-only, access after open }
Remarks Indicates whether this reader supports locking a tag. Application should query this
property before invoking lockTag method.
See Also lockTag Method.
CapMultipleProtocols Property
Syntax CapMultipleProtocols: int32 { read-only, access after open }
Remarks This property indicates the available predefined RFID tag protocols this device
supports. If the device supports more than one of these protocols, the value of this
property will be the bitwise sum of the values of the supported protocols.
Value Meaning
RFID_PR_EPC0 EPC class 0 read-only passive tags
RFID_PR_0PLUS Non-standard EPC class “0+” write once passive tags
RFID_PR_EPC1 EPC class 1 write once passive tags
RFID_PR_EPC1G2 EPC class 1 gen 2 (ISO 18000-6C) write once passive tags
RFID_PR_EPC2 EPC class 2 rewritable tags
RFID_PR_ISO14443A ISO 14443A HF tags
RFID_PR_ISO14443B ISO 14443B HF tags
RFID_PR_ISO15693 ISO 15693 HF tags
RFID_PR_ISO180006B ISO 18000-6B UHF tags
RFID_PR_OTHER A tag that does not fit into one of the defined protocols

1130 RFID Scanner
Based on this property, ProtocolMask can further filter the tags it wants to
exclude by turning off the bits.
See Also CurrentTagProtocol Property, ProtocolMask Property.
CapReadTimer Property
Syntax CapReadTimer: boolean { read-only, access after open }
Remarks If true, the device supports a read timer. Application should query this property
first before setting ReadTimerInterval.
See Also ReadTimerInterval Property.
CapWriteTag Property
Syntax CapWriteTag: int32 { read-only, access after open }
Remarks Indicates the writable fields in the tag. Possible values are:
Value Meaning
RFID_CWT_NONE No writable fields in the tag (0)
RFID_CWT_ID The ID field in the tag is writable (1)
RFID_CWT_USERDATA
The UserData field in the tag is writable (2)
RFID_CWT_ALL All fields in the tag are writable (3)
The value of this property indicates only the write capability of the device and does
not imply the writability of any specific tag. The application should query this
property before invoking writing methods.
See Also writeTagData Method, writeTagID Method.
ContinuousReadMode Property
Syntax ContinuousReadMode: boolean {read-only, access after open}
Remarks If true, the device is in continuous read mode. The ProtocolMask and
ReadTimerInterval properties are read-only when this property is true.
See Also CapContinuousRead Property.

CurrentTagID Property
Syntax CurrentTagID: binary { read-only, access after open }1
Remarks This property represents present tag’s TagID.
Just before a DataEvent is delivered, the service populates this property with data
from the first tag that was read. The service keeps this property up to date when
the application calls the firstTag, nextTag, and previousTag methods.
See Also firstTag Method, nextTag Method, previousTag Method, readTags Method,
startReadTags Method.
CurrentTagProtocol Property
Syntax CurrentTagProtocol: int32 { read-only, access after open }
Remarks The Service populates this property with the Protocol that this tag was read
through. The value here should match one of the selection in ProtocolMask. This
property may be updated by the Service for each individual tag.
See Also ProtocolMask Property, firstTag Method, nextTag Method, previousTag
Method, readTags Method, startReadTags Method.
CurrentTagUserData Property
Syntax CurrentTagUserData: binary { read-only, access after open }1
Remarks The Service populates this property with the data read from the physical tag. If it
is a partial read, it will populate it with the targeted segment.
See Also firstTag Method, nextTag Method, previousTag Method, readTags Method,
startReadTags Method.

1132 RFID Scanner
ProtocolMask Property
Syntax ProtocolMask: int32 { read-write, access after open-claim }
Remarks Holds a bit pattern wherein each bit signifies one predefined RFID tag protocol.
The nonzero bit entries indicate protocols for which the read is requested. Only
tags of the specified protocol type will be read. If the reader is in Continuous Read
mode, this property is read-only.
Value Tag Type
RFID_PR_EPC0 EPC class 0 read-only passive tags
RFID_PR_0PLUS Non-standard EPC class “0+” write once passive tags
RFID_PR_EPC1 EPC class 1 write once passive tags
RFID_PR_EPC1G2 EPC class 1 gen 2 (ISO 18000-6C) write once passive tags
RFID_PR_EPC2 EPC class 2 rewritable tags
RFID_PR_ISO14443A ISO 14443A HF tags
RFID_PR_ISO14443B ISO 14443B HF tags
RFID_PR_ISO15693 ISO 15693 HF tags
RFID_PR_ISO180006B ISO 18000-6B UHF tags
RFID_PR_OTHER A tag that does not fit into one of the defined protocols
RFID_PR_ALL Read all tags supported by the reader
This property is initialized to the same value as CapMultipleProtocols by the
open method, and is normally updated by the application during its initialization
phase.
See Also CapMultipleProtocols Property, CurrentTagProtocol Property.
ReadTimerInterval Property
Syntax ReadTimerInterval: int32 { read-write, access after open-claim }
Remarks Indicates the minimum time interval between tag reads in milliseconds. This
property only applies to continuous reading. A value of zero indicates no delay
between reads. The value of this property is zero if CapReadTimer is false.
Attempts to set this property when CapReadTimer is false or when
ContinuousReadMode is true will raise an exception.
See Also CapReadTimer Property.
TagCount Property
Syntax TagCount: int32 { read-only, access after open }
Remarks This property contains the total number of tags read by the corresponding read
operation. The service populates this property just before a DataEvent is delivered
to the application.
See Also readTags Method, startReadTags Method, DataEvent Event.


disableTag Method
Syntax disableTag (tagID: binary, timeout: int32, password: binary):
tagId2 the tagID of the tag it is disabling
timeout allowed execution time, in milliseconds, before the
method fails and a timeout ErrorEvent is sent to the
application. If FOREVER (-1) the service will wait as
long as needed until either the operation completes or an
error occurs.
password3 authorized key for reader that might be required for this
operation, zero length (or empty) if not applicable.
Remarks Permanently disables the specific tag matching the tagID parameter.
This method is always performed asynchronously and OutputID will be set on a
successful start plus an OutputCompleteEvent or ErrorEvent will be fired to
indicate completion.
firstTag Method
Syntax firstTag ():
Remarks Resets the Service’s counter to the first tag in the tag list, and copies that tag’s
information into the corresponding properties. Used if the application needs to re-
process the list of tags from its beginning. The method is synchronous, because no
physical input or output occurs when it is called.
information, See “Errors” on page 52.
See Also CurrentTagID Property, CurrentTagProtocol Property, CurrentTagUserData
Property, TagCount Property.
2.
In the OPOS environment, the format of tagId and password depends upon the
A-29.

1134 RFID Scanner
lockTag Method
Syntax lockTag (tagID: binary, timeout: int32, password: binary):
tagId3 the tagID of the tag it is locking
timeout allowed execution time, in milliseconds, before the
method fails and a timeout ErrorEvent is sent to the
application. If FOREVER (-1) the service will wait as
long as needed until either the operation completes or an
error occurs.
Remarks This operation will turn the tag into a read-only mode that both ID and UserData
fields are not writable. If invoking this method with CapLockTag being false, an
exception will the thrown.
See Also “Device Output Models” on page 57, CapLockTag Property.
nextTag Method
Syntax nextTag ():
Remarks Moves the Service’s counter to the next tag in the tag list, and copies that tag’s
information into the corresponding properties. Used in normal RFID read
processing. The method is synchronous, because no physical input or output
occurs when it is called, only memory to memory copies.
3.
In the OPOS environment, the format of tagID and password depends upon the
A-29.

previousTag Method
Syntax previousTag ():
Remarks Moves the Service’s counter to the previous tag in the tag list, and copies that tag’s
information into the corresponding properties. Used if the application needs to
process the list of tags in reverse order. The method is synchronous, because no
physical input or output occurs when it is called, only memory to memory copies.
readTags Method
Syntax readTags (cmd: int32, filterID: binary, filtermask: binary, start: int32, length:
int32, timeout: int32, password: binary):
cmd Possible values are:
Value Description
RFID_RT_ID Read only the ID data
RFID_RT_FULLUSERDATA
Read the full UserData
RFID_RT_PARTIALUSERDATA
Read the defined partial UserData
RFID_RT_ID_FULLUSERDATA
Read the ID and full UserData
RFID_RT_ID_PARTIALUSERDATA
Read the ID and the defined partial
UserData
Some readers allow for a faster read if only the ID is requested.
filterID4 It holds a bit pattern to be AND’ed with filtermask to determine
which tag(s) to read.
filtermask5 It holds a bit pattern to be AND’ed with filterID, only the tagIDs
that when AND’ed with this mask match the ANDing of filterID
and filtermask will be returned. To get all tags in the field, pass
in a filtermask of all 0’s.
start Indicates the zero-based position within the tags UserData field
to begin reading from. This parameter only applies when cmd is
set to RFID_RT_PARTIALUSERDATA or
RFID_RT_ID_PARTIALUSERDATA, otherwise it is ignored.
4.
In the OPOS environment, the format of filterID, filtermask, and password

1136 RFID Scanner
length Indicates the number of bytes of user data to read starting at the
position indicated by the start parameter. This parameter only
applies when cmd is set to RFID_RT_PARTIALUSERDATA or
timeout allowed execution time, in milliseconds, before the method fails
and a timeout ErrorEvent is sent to the application. If
FOREVER (-1) the service will wait as long as needed until
either the operation completes or an error occurs.
Remarks Performs a poll of all the tags within range that meet the parameterized criteria. A
DataEvent or an ErrorEvent has to be received before another readTags
invocation.
See Also TagCount Property, firstTag Method, nextTag Method, previousTag Method,
“Device Input Model”.
startReadTags Method
Syntax startReadTags ( cmd: int32, filterID: binary, filtermask: binary, start: int32,
length: int32, password: binary):
cmd Possible values are:
Value Description
RFID_RT_ID Read only the ID data
RFID_RT_FULLUSERDATA
Read the full UserData
RFID_RT_PARTIALUSERDATA
Read the defined partial UserData
RFID_RT_ID_FULLUSERDATA
Read the ID and full UserData
RFID_RT_ID_PARTIALUSERDATA
Read the ID and the defined partial
UserData
Some readers allow for a faster read if only the ID is requested.
filterID5 It holds a bit pattern to be AND’ed with filtermask to determine
which tag(s) to read.
filtermask6 It holds a bit pattern to be AND’ed with filterID, only the tagIDs
that when AND’ed with this mask match the ANDing of filterID
and filtermask will be returned. To get all tags in the field, pass
in a filtermask of all 0’s.
5.
In the OPOS environment, the format of filterID and filtermask depends upon the
A-29.

to begin reading from. This parameter only applies when cmd is
set to RFID_RT_PARTIALUSERDATA or
length Indicates the number of bytes of user data to read starting at the
position indicated by the start parameter. This parameter only
applies when cmd is set to RFID_RT_PARTIALUSERDATA or
Remarks Performs a continuous polling of tags that meet the parameterized criteria. Each
polling operation will result in either a DataEvent or an ErrorEvent being sent.
The service will continue polling until stopReadTags is invoked.
ContinuousReadMode is true during startReadTags execution, another
startReadTags invocation will trigger an exception.
This method is always performed asynchronously but OutputID is not set and
OutputCompleteEvents are not sent as a result of invoking this method.
See Also “Device Input Model”, stopReadTags Method.
stopReadTags Method
Syntax stopReadTags (password: binary):
Remarks Stops the continuous reading mode. All read-only properties due to continuous
reading mode are writable again. Invoking this method when not in continuous
reading mode will trigger an exception.
See Also “Device Input Model”, startReadTags Method.
6.
In the OPOS environment, the format of password depends upon the value of the

1138 RFID Scanner
writeTagData Method
Syntax writeTagData (tagID: binary, userdata: binary, start: int32, timeout: int32,
password: binary):
tagID7 tagID of the tag whose UserData it is writing to
userdata8 to-be-written data
to begin writing to.
Remarks Over-write the entire or part of the UserData field of targeted tag. Application
should query CapWriteTag for this operation’s supportability.
See Also “Device Output Model”, CapWriteTag Property.
7.
In the OPOS environment, the format of tagID, userData, and password depends
upon the value of the BinaryConversion property. See BinaryConversion property
on page A-29.

writeTagID Method
Syntax writeTagID (sourceID: binary, destID: binary, timeout: int32, password:
binary ):
sourceID8 tagID of the tag that it is writing the new ID to
destID9 new ID of the tag
Remarks Over-write the existing tagID with a new ID. Application should query
CapWriteTag to verify this is a supported method. Invoking this method with
CapWriteTag’s WRITE_TAG_ID bit off will trigger an exception.
See Also “Device Output Model”, CapWriteTag Property.
8.
In the OPOS environment, the format of sourceID, destID, and password depends
upon the value of the BinaryConversion property. See BinaryConversion property
on page A-29.

1140 RFID Scanner

DataEvent
Description Notifies the application that input data from the RFID Scanner is available.
Remarks The property TagCount is updated prior to this event being delivered to the
application. For tag details reported by this DataEvent, the application should
invoke the firstTag or nextTag method to enumerate each tag in the Event, then
query a series of CurrentTagXXX properties.
DirectIOEvent
means for a vendor-specific RFID Scanner Service to provide events to the
Service.
from being used with other vendors’ RFID Scanner devices which may not have

ErrorEvent

Description Notifies the application that an RFID Scanner device error has been detected and
Codes on page 52.
ErrorCodeExtended
int32 Extended Error code causing the error event. It may
values below.
Value Meaning
available.
available.
Value Meaning
ER_CONTINUEINPUT
EL_INPUT_DATA.

1142 RFID Scanner
Remarks Input error events are generated when errors occur while reading the data from
the RFID Scanner device. Such events are not delivered until the
sequencing.
asynchronous output processing.
OutputCompleteEvent
is complete.
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of an RFID
Scanner device.
Status int32 Reports a change in the power state of an RFID Scanner
device.
Remarks Enqueued when the RFID Scanner device detects a power state change.

C H A P T E R 3 3
Scale
This Chapter defines the Scale device category.
Summary

1144 Scale
CapDisplay: boolean { read-only } 1.2 open
CapDisplayText: boolean { read-only } 1.3 open
CapPriceCalculating: boolean { read-only } 1.3 open
CapStatusUpdate: boolean { read-only } 1.9 open
CapTareWeight: boolean { read-only } 1.3 open
CapZeroScale: boolean { read-only } 1.3 open
MaxDisplayTextChars: int32 { read-only } 1.3 open
MaximumWeight: int32 { read-only } 1.0 open
SalesPrice: currency { read-only } 1.3 open, claim, & enable
ScaleLiveWeight: int32 { read-only } 1.9 open
StatusNotify: int32 { read-write } 1.9 open
TareWeight: int32 { read-write } 1.3 open, claim, & enable
UnitPrice: currency { read-write } 1.3 open, claim, & enable
WeightUnit: int32 { read-only } 1.0 open

Common
Name Version
close ( ): 1.3
release ( ): 1.3
clearInput ( ): 1.3
void { } supporteda
void { } supported

Summary 1145

Specific
Name
displayText ( data: string ): 1.3
readWeight ( inout weightData: int32, timeout: int32 ): 1.3
zeroScale ( ): 1.3


1146 Scale
General Information
The Scale programmatic name is “Scale”.
Capabilities
The scale Device has the following capability:

• Provides item weight to the application. The measure of weight may be in
grams, kilograms, ounces, or pounds, depending upon the scale device.
The scale may have the following additional capabilities:

• Includes an integrated display with the current weight, or with the current
weight plus application-specified text.
• Performs price calculations (weight X unit price) and returns the sale price.
(This feature is mostly used in Europe at this time.)
• Supports application setting of tare weight.
• Supports application zeroing of the scale.
The following functionality is added for Release 1.9:

A scale device is used to obtain weight for two distinct purposes, legal weight for
calculating price, and live weight for updating customer displays. Prior to Release
1.9, a good interface is provided for an application to obtain a legal weight, but no
interface for obtaining a live weight existed. The following added functionality in
Release 1.9 formalizes an interface for obtaining scale status and live weight:
• A scale weight status update capability property, CapStatusUpdate.
• A scale weight status notify property, StatusNotify, to enable or disable
weight status event notification.
• A ScaleLiveWeight property containing a value to be used for updating a
customer display with the current scale weight.
• Extensions to the readWeight method and StatusUpdateEvent for scale
weight status.

Scale Class Diagram Updated in Release 1.12
The following diagram shows the relationships between the Scale classes.
<<event>> <<exception>>
DataEvent UposException <<utility>>
(from upos)
<<uses>> UposConst
(from events)
(from upos)
<<prop>> Status : int32 <<sends>>
<<Interface>>
BaseControl
(from upos)
<<event>>
DirectIOEvent
(from events) fires <<utility>>
<<prop>> EventNumber : int32 <<sends>> ScaleConst
(from upos)
<<uses>>
fires
<<Interface>>
<<event>> ScaleControl
ErrorEvent (from upos)
(from events) <<capability>> CapDisplay : boolean
<<prop>> ErrorCode : int32 <<capability>> CapDisplayText : boolean
<<prop>> ErrorCodeExtended : int32 <<capability>> CapPriceCalculating : boolean
<<prop>> ErrorLocus : int32 fires <<capability>> CapStatusUpdate : boolean
<<prop>> ErrorResponse : int32 <<capability>> CapTareWeight : boolean
<<capability>> CapZeroScale : boolean
<<prop>> MaxDisplayTextChars : int32
<<prop>> MaximumWeight : int32
<<prop>> SalesPrice : int32
<<prop>> ScaleLiveWeight : int32
<<prop>> StatusNotify : int32
fires <<prop>> TareWeight : int32
<<prop>> UnitPrice : int32
<<event>>
<<prop>> WeightUnit : int32
StatusUpdateEvent
(from events)
displayText(data : string) : void
readWeight(inout weightData : int32, timeout : int32) : void
zeroScale() : void

1148 Scale
Scale Sequence Diagram Added in Release 1.7
The following sequence diagram shows the typical synchronous usage of a Scale
device.
Scale device.
:ClientApp :Scale :ScaleService
: Operator
3: claim(timeout) 4: claim(timeout)
7: makes sure that scale is empty (ask :Operator if necessary)
8: zeroScale() [ CapZeroScale == true ] After successful

execution of this
9: zeroScale() [ CapZeroScale == true ] method the scale is
assumed to be
10: show message to place item on scale "zeroed"
11: place item on scale
12: readWeight(weightData, timeout)

13: readWeight(weightData, timeout)
14: displayText(data) [ CapDisplayText == true ]
15: displayText(data) [ CapDisplayText == true ]

Model
The general model of a scale is:

• A scale returns the weight of an item placed on its weighing surface.
• The primary scale method is readWeight. By default, it is performed
synchronously. It returns after reading data from the scale; the weight is
returned in the readWeight’s weightData parameter. If an error occurs or if
the timeout elapses, a UposException will be thrown.
• UnifiedPOS Release 1.3 and later - Asynchronous Input

If the AsyncMode property is true when readWeight is called, then the
method is performed asynchronously. It initiates event driven input and
returns immediately. The timeout parameter specifies the maximum time the
application wants to wait for a settled weight. Additional points are:
• If an error occurs while initiating event driven input (such as the device is
offline), then a UposException is thrown. Otherwise, readWeight returns
immediately to the application, and scale processing continues
asynchronously.
• If a settled weight is received, then a DataEvent is enqueued containing
the weight data in the Status property.
• If a scale error occurs (including a timeout with no settled weight), then
an ErrorEvent is enqueued. The application event handler may retry the
weighing process by setting the event’s ErrorResponse property to
ER_RETRY.
• Only one asynchronous call to readWeight can be in progress at a time.
An attempt to nest asynchronous scale operations will result in a
UposException being thrown.
• An asynchronous scale operation may be cancelled with the clearInput
method.
For price-calculating scales, the application should set the UnitPrice property
before calling readWeight. After a weight is read (and just before the DataEvent
is delivered to the application, for asynchronous mode), the SalesPrice property is
set to the calculated price of the item.
Device Sharing
The scale is an exclusive-use device, as follows:

• After opening the device, properties are readable.

1150 Scale
AsyncMode Property Added in Release 1.3

Remarks If true, then the readWeight method will be performed asynchronously. If false,
the readWeight method will be performed synchronously.

See Also readWeight Method.
CapDisplay Property
Syntax CapDisplay: boolean { read-only, access after open }
Remarks If true, the scale includes an integrated display that shows the current weight. If
false, the application may need to show the current weight on another display.

See Also CapDisplayText Property, MaxDisplayTextChars Property.
CapDisplayText Property Added in Release 1.3

Syntax CapDisplayText: boolean { read-only, access after open }
Remarks If true, the scale includes an integrated display that shows the current weight and
can also show text that describes the item being weighed. If false, extra text cannot
be shown on the display.
If true, then CapDisplay must also be true.
See Also CapDisplay Property, MaxDisplayTextChars Property.

CapPriceCalculating Property Added in Release 1.3

Syntax CapPriceCalculating: boolean { read-only, access after open }
Remarks If true, the scale can calculate prices. If false, the scale only returns a weight.
For price calculating scales the calculation unit is in the scale rather than in the
data-receiving terminal.
See Also readWeight Method, WeightUnit Property, UnitPrice Property, SalesPrice
Property.
CapStatusUpdate Property Added in Release 1.9
Syntax CapStatusUpdate: boolean { read-only, access after open }
Remarks If true, then the scale is capable of providing scale weight status with
StatusUpdateEvents. This property is initialized by the open method.
If true when the device is enabled, an immediate StatusUpdateEvent will be
generated to tell the application the current state of the scale.
information, see ““Errors” on page 52.
See Also ScaleLiveWeight Property, StatusNotify Property.
CapTareWeight Property Added in Release 1.3

Syntax CapTareWeight: boolean { read-only, access after open }
Remarks If true, the scale includes setting a tare value. If false, the scale does not support
tare values.
See Also TareWeight Property.
CapZeroScale Property Added in Release 1.3

Syntax CapZeroScale: boolean { read-only, access after open }
Remarks If true, the application can set the scale weight to zero. If false, the scale does not
support programmatic zeroing.
See Also zeroScale Method.

1152 Scale
MaxDisplayTextChars Property Added in Release 1.3

Syntax MaxDisplayTextChars: int32 { read-only, access after open }
Remarks Holds the number of characters that may be displayed on an integrated display for
the text which describes an article.
If CapDisplayText is false, then the device does not support text displaying and
this property is always zero.
See Also CapDisplay Property, CapDisplayText Property.
MaximumWeight Property
Syntax MaximumWeight: int32 { read-only, access after open }
Remarks Holds the maximum weight measurement possible from the scale. The
measurement unit is available via the WeightUnit property.
This property has an assumed decimal place located after the “thousands” digit
position. For example, an actual value of 12345 represents 12.345, and an actual
value of 5 represents 0.005.
Changing the WeightUnit property will also cause this property to change.
See Also WeightUnit Property.

SalesPrice Property Added in Release 1.3/Updated in Release 1.6
Syntax SalesPrice: currency { read-only, access after open }

Remarks Holds the sales price read from the scale for price calculating scales. For price
calculating scales the scale calculates this value during the process of weighing by
multiplying the UnitPrice property by the acquired weight. This property is a
monetary value stored using an implied four decimal places. For example, an
actual value of 12345 represents 1.2345.
This property is set before the readWeight method returns (in synchronous mode)
or the DataEvent is delivered (in asynchronous mode).
If CapPriceCalculating is false, then the device is not a price calculating scale
and SalesPrice is always zero.
This property is initialized to zero when the device is first enabled following the
open method. (In releases prior to 1.5, this description stated that initialization
took place by the open method. In Release 1.5, it was updated for consistency with
other devices.)
See Also readWeight Method, WeightUnit Property, CapPriceCalculating Property,
UnitPrice Property.
ScaleLiveWeight Property Updated in Release 1.10

Syntax ScaleLiveWeight: int32 { read-only, access after open-claim-enable }
Remarks Contains the returned value for the weight measured by the scale if the
StatusUpdateEvent Status is set to SCAL_SUE_STABLE_WEIGHT, else zero.
The weight has an assumed decimal place located after the “thousands” digit
position. For example, an actual value of 12345 represents 12.345, and an actual
value of 5 represents 0.005.
It is suggested that an application use the weight in this property only for display
purposes. For a weight to use for sale purposes, it is suggested that the application
call ReadWeight.
See Also “Device Input Model” on page 54, CapStatusUpdate Property, StatusNotify
Property.

1154 Scale
StatusNotify Property Added in Release 1.9/Updated in Release 1.10

Syntax StatusNotify: int32 { read-write, access after open }
Remarks Scale weight state notification can only be set by the application if the capability
CapStatusUpdate is true. The StatusNotify values are:
Value Meaning
SCAL_SN_DISABLED The Control will not provide any scale weight state
notifications to the application or set any related
ErrorCodeExtended values. No scale weight state
notification StatusUpdateEvents will be fired, and
ScaleLiveWeight may not be set.
SCAL_SN_ENABLED The Control will fire scale weight state notification
StatusUpdateEvents and update the ScaleLiveWeight
property beginning when DeviceEnabled is set true.
The level of functionality depends upon
CapStatusUpdate.
StatusNotify may only be set while the device is disabled, that is, while
DeviceEnabled is false. This property is initialized to SCAL_SN_DISABLED by
the open method. This value provides compatibility with earlier releases.
Value Meaning
• CapStatusUpdate is false.
See Also CapStatusUpdate Property, ScaleLiveWeight Property.

TareWeight Property Updated in Release 1.10

Syntax TareWeight: int32 { read-write, access after open-claim-enable }
Remarks Holds the tare weight of scale data. This property has an assumed decimal place
located after the “thousands” digit position. For example, an actual value of 12345
represents 12.345, and an actual value of 5 represents 0.005. The measured unit is
specified in the WeightUnit property. If CapTareWeight is false, then the device
does not support setting of a tare value and this property is always zero.
Tare weight is not included in the item weight returned by the readWeight
method.
This property is initialized to the scale’s default tare weight (usually zero), when
the device is first enabled following the open method. (In releases prior to 1.5, this
description stated that initialization took place by the open method. In Release 1.5,
it was updated for consistency with other devices.)
Value Meaning
E_ILLEGAL CapTareWeight is false or an invalid tare value was
specified.
See Also readWeight Method, WeightUnit Property, CapTareWeight Property.
UnitPrice Property Updated in Release 1.10

Syntax UnitPrice: currency { read-write, access after open-claim-enable }
Remarks Holds the unit price of the article to be weighed. For price calculating scales this
property is to be set before calling the readWeight method. During weighing, the
scale sets the SalesPrice property to the product of the item’s weight and this
property. This property is a monetary value stored using an implied four decimal
places. For example, an actual value of 12345 represents 1.2345.
If CapPriceCalculating is false, then setting of a unit price is not supported and
this property is always zero.
other devices.)
Value Meaning
E_ILLEGAL CapPriceCalculating is false or an invalid price was
specified.
See Also readWeight Method, WeightUnit Property, CapPriceCalculating Property,
SalesPrice Property.

1156 Scale
WeightUnit Property
Syntax WeightUnit: int32 { read-only, access after open }
Remarks Holds the unit of weight of scale data, and has one of the following values:
Value Meaning
SCAL_WU_GRAM Unit is a gram.
SCAL_WU_KILOGRAM Unit is a kilogram (= 1000 grams).
SCAL_WU_OUNCE Unit is an ounce.
SCAL_WU_POUND Unit is a pound (= 16 ounces).
This property is initialized to the scale’s weight unit by the open method.

displayText Method Updated in Release 1.7

Syntax displayText ( data: string ):
data1 The string of characters to display.
Remarks If CapDisplayText is true, updates the text shown on the integrated display.
Calling this method with an empty string (“”) will clear the display.
Value Meaning
E_ILLEGAL An invalid text was specified -- the text contains more

characters than MaxDisplayTextChars, or
CapDisplayText is false.
See Also CapDisplay Property, CapDisplayText Property, MaxDisplayTextChars
Property.
readWeight Method Updated in Release 1.10

Syntax readWeight ( inout weightData: int32, timeout: int32 ):
weightData If AsyncMode is false, contains the returned value for
the weight measured by the scale, else zero.
timeout The number of milliseconds to wait for a settled weight
before failing the method. If zero, the method attempts
to read the scale weight, then returns the appropriate
status immediately. If FOREVER (-1), the method waits
as long as needed until a weight is successfully read or
an error occurs.

1158 Scale
Remarks Reads a weight from the scale.

The weight returned, weightData, has an assumed decimal place located after the
“thousands” digit position. For example, an actual value of 12345 represents
12.345, and an actual value of 5 represents 0.005.
Release 1.2
The weighing process is performed synchronously and the method will return after
finishing the weighing process. The weight is returned in the weightData
parameter.
If AsyncMode is false, then readWeight operates synchronously, as with earlier
releases.
If AsyncMode is true, the weighing process is performed asynchronously. The
method will initiate a read, then return immediately. Once the weighing process is
complete, a DataEvent is delivered with the item’s weight contained in the event’s
Status property.
Value Meaning
E_BUSY An asynchronous readWeight is in progress.
E_TIMEOUT A stable non-zero weight was not available before
timeout milliseconds elapsed (only if AsyncMode is
false).
E_EXTENDED ErrorCodeExtended = ESCAL_OVERWEIGHT:
The weight was over MaximumWeight. This can only
be returned if AsyncMode is false.
The following standard extended error codes have been added in Release 1.9 as
possible values of the exception’s ErrorCode property:
E_EXTENDED ErrorCodeExtended = ESCAL_UNDER_ZERO:
The scale is reporting a weight that is less than zero due
to a calibration error. The scale should be recalibrated.
This can only be returned if AsyncMode is false.
E_EXTENDED ErrorCodeExtended = ESCAL_SAME_WEIGHT:
The scale is reporting that the item/weight on the scale
is identical to the previously reported item/weight; i.e.,
the item has not been removed from the scale. This can
only be returned if AsyncMode is false and the scale
hardware directly supports this capability.
See Also UnitPrice Property, WeightUnit Property, CapPriceCalculating Property,
SalesPrice Property, TareWeight Property.

zeroScale Method Updated in Release 1.10

Syntax zeroScale ( ):
Remarks If CapZeroScale is true, sets the current scale weight to zero. It may be used for
initial calibration, or to account for tare weight on the scale.
Value Meaning
E_ILLEGAL CapZeroScale is false.
E_BUSY An asynchronous readWeight is in progress.
See Also CapZeroScale Property.

1160 Scale
DataEvent Added in Release 1.3

Description Notifies the application that an asynchronous readWeight has completed.

Status int32 The weight of the item.

Remarks If the scale is a price calculating scale, the unit price is placed in the UnitPrice
property and the calculated sales price is placed in the SalesPrice property before
DirectIOEvent
means for a vendor-specific Scale Service to provide events to the application that
Service.
from being used with other vendor’s Scale devices which may not have any


Description Notifies the application that a scale device error has been detected and a suitable
ErrorCodeExtended
values below.
Value Meaning
available.
available.
Value Meaning
ER_RETRY Retry the asynchronous input. The error state is exited.
EL_INPUT.

1162 Scale
Remarks Enqueued when an error is detected while trying to read scale data. This event is
not delivered until DataEventEnabled is true, so that proper application
sequencing occurs.

Description Notifies the application that there is a change in the power status of a Scale device.
If the StatusNotify property is SCAL_SN_ENABLED, this event can also notify

the application that there is a change in the Scale device weight.
If the property StatusNotify is true when the scale is enabled, an immediate
StatusUpdateEvent should be generated to notify the application of the current
state of the scale.
Status int32 Reports a change in the power state of a Scale device.
process.
Added in Release 1.9 and delivered if StatusNotify is set to
SCAL_SN_ENABLED.
Value Meaning
SCAL_SUE_STABLE_WEIGHT Scale weight is stable. The
ScaleLiveWeight property is updated
before event delivery.
SCAL_SUE_WEIGHT_UNSTABLE Scale weight is unstable.
SCAL_SUE_WEIGHT_ZERO Scale weight is zero.
SCAL_SUE_WEIGHT_OVERWEIGHT Scale weight is overweight.
SCAL_SUE_NOT_READY Scale is not ready to weigh.
SCAL_SUE_WEIGHT_UNDER_ZERO Scale weight is under zero.
Remarks Enqueued when the Scale device detects a power state change or a status change.
See Also “Events” on page 51, ScaleLiveWeight Property, StatusNotify Property.

C H A P T E R 3 4
Scanner (Bar Code Reader)

This Chapter defines the Scanner device category.
Summary

1164 Scanner (Bar Code Reader)
DecodeData: boolean { read-write } 1.2 open
ScanData: binary { read-only } 1.0 open
ScanDataLabel: binary { read-only } 1.2 open
ScanDataType: int32 { read-only } 1.2 open

Common
Name Version
close ( ): 1.0
release ( ): 1.0
clearInput ( ): 1.0
void { } supported
Specific
None

Summary 1165


General Information
The Scanner programmatic name is “Scanner”.
Capabilities
The Scanner Device has the following capability:

• Reads encoded data from a label.
Scanner Class Diagram
The following diagram shows the relationships between the Scanner classes.
<<ex ception>> <<sends>> BaseControl <<utility>>
DirectIOEvent <<uses >>
Upos Exc eption (from upos) UposCons t
(from events)
<<utility>>
fires
<<sends>> ScannerConst
<<event>> (from upos)
<<uses>>
DataEvent
<<Interface>>
(from events) fires ScannerControl
<<prop>> Status : int32 (from upos)
<<prop>> DecodeDat a : boolean
<<prop>> ScanData : binary
f ires <<prop>> ScanDataLabel : binary
<<event>> <<prop>> ScanDataType : int32
ErrorEvent
(from events)
<<prop>> ErrorLocus : int32
<<prop>> ErrorResponse : int32 fires
<<event>>
StatusUpdateEvent
(from events)

Scanner Sequence Diagram Updated in Release 1.8

The following sequence diagram shows the typical usage of a Scanner device.
NOTE: we are assuming that the :ClientApp already successfully registered event handlers and opened,
claimed and enabled the Scanner device. This means that the Claimed, DeviceEnabled properties are == true
:ClientApp :Scanner :DataEvent :ScannerService
: Operator
3: setAutoDisable(true) 4: setAutoDisable(true)
8: service is notified of new event

9: create DataEvent
10: decode data
11: enqueue DataEvent and DataCount++
Typically this firing of events would

be done by some worker thread 12: set DeviceEnabled property to false [AutoDisable == true]
managed by the ScannerService
13: set Scanner data properties and deliver enqueued DataEvent to control

14: deliver DataEvent to all event handlers delivered set DataEventEnabled
to false and DataCount--.
16: getScanData() 17: getScanData()
18: getScanDataLabel() 19: getScanDataLabel()

Model
The Scanner follows the general “Device Input Model” for event-driven input:
• When input is received from the scanner, a DataEvent is enqueued.
• If the AutoDisable property is true, then the device automatically disables
itself when a DataEvent is enqueued.
properties, and further data events are disabled by setting DataEventEnabled
to false. This causes subsequent input data to be enqueued while the
application processes the current input and associated properties. When the
application has finished processing the current input and is ready for more
data, it reenables events by setting DataEventEnabled to true.
• The DataCount property may be read to obtain the total number of enqueued
DataEvents.
Scanned data is placed into the property ScanData. If the application sets the
property DecodeData to true, then the data is decoded into the ScanDataLabel
and ScanDataType properties.
Device Sharing
The scanner is an exclusive-use device, as follows:

reading input.

DecodeData Property
Syntax DecodeData: boolean { read-write, access after open }
Remarks If true, then ScanData will be decoded into the properties ScanDataLabel and
ScanDataType.
See Also “Device Input Model” on page 54

ScanData Property Updated in Release 1.7

Syntax ScanData: binary { read-only, access after open } 1
Remarks Holds the data read from the scanner.
Scan data is, in general, in the format as delivered from the scanner. Message
header and trailer information are removed, however, since they do not contain
useful information for an application and are likely to be scanner-specific.
Common header information is a prefix character (such as an STX character).
Common trailer information is a terminator character (such as an ETX or CR
character) and a block check character if one is generated by the scanner.
This property should include a symbology character if one is returned by the
scanner (for example, an ‘A’ for UPC-A). It should also include check digits if
they are present in the label and returned by the scanner. (Note that both
symbology characters and check digits may or may not be present, depending upon
the scanner configuration. The scanner will return them if present, but will not
generate or calculate them if they are absent.)
Some merchandise may be marked with a supplemental barcode. This barcode is
typically placed to the right of the main barcode, and consists of an additional two
or five characters of information. If the scanner reads merchandise that contains
both main and supplemental barcodes, the supplemental characters are appended
to the main characters, and the result is delivered to the application as one label.
(Note that a scanner may support configuration that enables or disables the reading
of supplemental codes.)
Some merchandise may be marked with multiple labels, sometimes called multi-
symbol labels or tiered labels. These barcodes are typically arranged vertically,
and may be of the same or different symbology. If the scanner reads merchandise
that contains multiple labels, each barcode is delivered to the application as a
separate label. This is necessary due to the current lack of standardization of these
barcode types. One is not able to determine all variations based upon the individual
barcode data. Therefore, the application will need to determine when a multiple
label barcode has been read based upon the data returned. (Note that a scanner may
or may not support reading of multiple labels.)

ScanDataLabel Property Updated in Release 1.10

Syntax ScanDataLabel: binary { read-only, access after open } 2
Remarks Holds the decoded bar code label.
When DecodeData is false, this property will have zero length. When
DecodeData is true, then ScanData is decoded into this property as follows:
• Scanner-generated symbology characters are removed, if present.
• If the label type can be determined to be a UPC/EAN label (a symbology
identifier was provided by the scanner), then the check digit must be present
in this property. If the scanner hardware does not return the UPC/EAN check
digit, then the Service must calculate it and include it in this property to ensure
that the data reflects a complete UPC/EAN label.
• For variable length bar codes, the length identification is removed, if present.
For example, the EAN-13 barcode which appears printed as “5 018374 827715”
on a label may be received from the scanner and placed into ScanData as the
following:
Received from scanner ScanData Comment
5018374827715 5018374827715 Complete barcode only

501837482771<CR> 501837482771 Without check digit
with carriage return
F5018374827715<CR> F5018374827715 With scanner-
dependent symbology
character and carriage
return
<STX>F5018374827715<ETX> F5018374827715 With header,
symbology character,
and trailer
For each of these cases (and any other variations), this property must always be set
to the string “5018374827715”, and ScanDataType must be set to
SCAN_SDT_EAN13.

ScanDataType Property Updated in Release 1.12
Syntax ScanDataType: int32 { read-only, access after open }

Remarks Holds the decoded bar code label type.
When DecodeData is false, this property is set to SCAN_SDT_UNKNOWN.
When DecodeData is true, the Service tries to determine the scan label type. The
following label types are defined:
Value Label Type
One Dimensional Symbologies
SCAN_SDT_UPCA UPC-A
SCAN_SDT_UPCA_S UPC-A with supplemental barcode
SCAN_SDT_UPCE UPC-E
SCAN_SDT_UPCE_S UPC-E with supplemental barcode
SCAN_SDT_UPCD1 UPC-D1
SCAN_SDT_EAN8 EAN 8 (= JAN 8)
SCAN_SDT_JAN8 JAN 8 (= EAN 8)
SCAN_SDT_EAN8_S EAN 8 with supplemental barcode
SCAN_SDT_EAN13 EAN 13 (= JAN 13)
SCAN_SDT_JAN13 JAN 13 (= EAN 13)
SCAN_SDT_EAN13_S EAN 13 with supplemental barcode
SCAN_SDT_EAN128 EAN-128
SCAN_SDT_TF Standard (or discrete) 2 of 5
SCAN_SDT_ITF Interleaved 2 of 5
SCAN_SDT_Codabar Codabar
SCAN_SDT_Code39 Code 39
SCAN_SDT_OCRA OCR “A”
SCAN_SDT_OCRB OCR “B”
Value Label Type
One Dimensional Symbologies - Added in Release 1.8
SCAN_SDT_RSS14 14 digit GTIN only - Deprecated v1.12;
replaced by SCAN_SDT_GS1DATABAR
SCAN_SDT_RSS_EXPANDED 14 digit GTIN plus additional defined fields
(e.g., price, weight) - Deprecated v1.12;
replaced by SCAN_SDT_GS1DATABAR_E

Value Label Type

One Dimensional Symbologies - Added in Release 1.12
SCAN_SDT_GS1DATABAR GS1 DataBar Omnidirectional (normal or
stacked)
SCAN_SDT_GS1DATABAR_E GS1 DataBar Expanded (normal or stacked)
Value Label Type
Composite Symbologies - Added in Release 1.8
SCAN_SDT_CCA Composite Component A.
Up to 56 characters of data.
SCAN_SDT_CCB Composite Component B.
SCAN_SDT_CCC Composite Component C.
A Composite Component may occur with any one of several different label types,
such as UPC, EAN, and GS1 DataBar. The composite component is read at the
same time as the linear component. When such a label is read, a DataEvent is
delivered that sets ScanDataType to SCAN_SDT_CCA, SCAN_SDT_CCB, or
SCAN_SDT_CCC. The next DataEvent always delivers the linear component.
(In other words, the Service enqueues two DataEvents at the same time: First the
composite component, then the linear component.) It is the application writer's
responsibility to merge the data associated with the two DataEvents.
Value Label Type
Two Dimensional Symbologies
SCAN_SDT_PDF417 PDF 417
SCAN_SDT_MAXICODE MAXICODE
Value Label Type
Special Cases
SCAN_SDT_OTHER If greater or equal to this type, then the Service
has returned an undefined symbology.
SCAN_SDT_UNKNOWN The Service cannot determine the barcode
symbology. ScanDataLabel may not be
properly formatted for the actual barcode type.
Value Label Type
Two Dimensional Symbologies - Added in Release 1.11
SCAN_SDT_DATAMATRIX Data Matrix
SCAN_SDT_QRCODE QR Code
SCAN_SDT_UQRCODE Micro QR Code
SCAN_SDT_AZTEC Aztec
SCAN_SDT_UPDF417 Micro PDF 417

DataEvent
Description Notifies the application that input data from the Scanner (Bar Code Reader) is
available.
Status int32 Always zero.

Remarks The scanner data is placed in the ScanData, ScanDataLabel, and ScanDataType
properties prior to a DataEvent being delivered to the application.
DirectIOEvent
means for a vendor-specific Scanner Service to provide events to the application
Service.
from being used with other vendor’s Scanner devices which may not have any


Description Notifies the application that a scanner device error has been detected and a suitable
ErrorCodeExtended
values below.
Value Meaning
available.
available.
Value Meaning
EL_INPUT.

Remarks Enqueued when an error is detected while trying to read scanner data. This event
is not delivered until DataEventEnabled is true, so that proper application
sequencing occurs.
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a Scanner
device.
Status int32 Reports a change in the power state of a Scanner device.

Remarks Enqueued when the Scanner device detects a power state change.

C H A P T E R 3 5
Signature Capture
This Chapter defines the Signature Capture device category.
Summary

1178 Signature Capture
CapDisplay: boolean { read-only } 1.0 open
CapRealTimeData: boolean { read-only } 1.2 open
CapUserTerminated: boolean { read-only } 1.0 open
MaximumX: int32 { read-only } 1.0 open
MaximumY: int32 { read-only } 1.0 open
array of
PointArray: { read-only } 1.0 open, claim, & enable
points
RawData: binary { read-only } 1.0 open, claim, & enable
RealTimeDataEnabled: boolean { read-write } 1.2 open

Common
Name Version
close ( ): 1.0
release ( ): 1.0
clearInput ( ): 1.0
void { } supported

Summary 1179
Specific
Name
beginCapture ( formName: string ): 1.0
endCapture ( ): 1.0


General Information
The Signature Capture programmatic name is “SignatureCapture”.
Capabilities
The Signature Capture Device has the following capability:

• Obtains a signature captured by a signature capture device. The captured
signature data is in the form of lines consisting of a series of points. Each point
lies within the co-ordinate system defined by the resolution of the device,
where (0, 0) is the upper-left point of the device, and (MaximumX,
MaximumY) is the lower-right point. The signature line points are presented
to the application by a DataEvent with a single array of line points
The Signature Capture Device may have the following additional capabilities:
• Provides a way for the user to terminate signature capture – that is, to tell the
device that she or he has completed the signature.
• Displays form/data on the signature capture device.
• Returns the signature in “real time” as it is entered on the device. If this
capability is true and has been enabled by application by setting the
RealTimeDataEnabled property to true, then a series of DataEvents are
enqueued, each with an array of one or more line points representing a partial
signature.

Signature Capture Class Diagram
The following diagram shows the relationships between the Signature Capture
classes.
<<utility>>
<<exception>>
UposConst
<<event>> UposException
(from upos)
DataEvent (from upos)
(from events)
<<prop>> Status : int 32
fires <<sends>>
<<event>> <<utility>>
DirectIOEvent SignatureCaptureConst
<<Interface>>
<<prop>> EventNumber : int32 SignatureCaptureControl <<uses>>
<<prop>> Data : int32 (from upos)
fires
<<capability>> CapDisplay : boolean
<<capability>> CapRealTimeData : boolean
<<capability>> CapUserTerminated : boolean
<<prop>> MaximumX : int32
<<event >> <<prop>> MaximumY : int32
fires
ErrorEvent <<prop>> PointArray : array of point
(from events) <<prop>> RawData : binary
<<prop>> ErrorCode : int32 <<prop>> RealTimeDataEnabled : boolean
<<prop>> ErrorLocus : int32 beginCapture(formName : string) : void
<<prop>> ErrorResponse : int32 endCapture() : void
fires
<<event>>
St atusUpdateEvent
(from events)

Signature Capture Sequence Diagram Updated in Release 1.8

The following sequence diagram shows the typical usage of gathering data from a
Signature Capture device.
NOTE: we are assuming that the :ClientApp already successfully registered event handlers and opened, claimed and
enabled the SignatureCapture device. This means that the Claimed, DeviceEnabled properties are == true
:ClientApp :SignatureCapture :DataEvent :SignatureCapture

Service
: Customer
We are assuming that this device support real time
data capture so that CapRealTimeData == true
3: beginCapture(formName)
4: beginCapture(formName)
If CapUserTerminate == true
then there is no need to
terminate capture with
endCapture()
5: sign name
6: create new DataEvent
7: DataCount++ and enqueue
8: update properties and deliver DataEvent

At this point the :ClientApp
will execute some event Right before the DataEvent
handling code as shown 9: deliver DataEvent to each registered handlers is delivered, set
below DataEventEnabled to false
and DataCount--.
11: getMaximumX()
12: getMaximumX()
13: getMaximumY()
14: getMaximumY()
15: getPointArray()
16: getPointArray()
17: application specific processing with gathered data

Model
The signature capture device usage model is:
• Open and claim the device.
• Enable the device and set the property DataEventEnabled to true.
• Begin capturing a signature by calling beginCapture. This method displays a
form or data screen (if the device has a display) and enables the stylus.
• If the device is capable of supplying signature data in real time as the signature
is entered (CapRealTimeData is true), and if RealTimeDataEnabled is true,
the signature is presented to the application as a series of partial signature data
events until the signature capture is terminated.
• If the device provides a way for the user to terminate the signature, then when
the user terminates, a DataEvent is enqueued. Otherwise, the application
must call endCapture to terminate the signature.
• Disable the device. If the device has a display, this also clears the display.
The Signature Capture follows the general “Device Input Model” for event-driven
input:
• When input is received by the Service, it enqueues a DataEvent.
• If AutoDisable is true, then the Device automatically disables itself when a
DataEvent is enqueued. However, note that setting AutoDisable probably is
not very useful for the Signature Capture control. If RealTimeDataEnabled
is true, then AutoDisable does not make sense. If RealTimeDataEnabled is
false, then the pacing of signatures is controlled by the application via the
beginCapture method. It is probably in the best interests of the application
not to use the AutoDisable property for this device class.
• A queued DataEvent can be delivered to the application when the property
Just before delivering this event, data is copied into properties, and further
current input and associated properties. When the application has finished
processing the current input and is ready for more data, it re-enables events by
setting DataEventEnabled to true.
• An ErrorEvent (or events) is enqueued if the an error occurs while gathering
or processing input, and is delivered to the application when
DataEvents.
Deviations from the general “Device Input Model” for event-driven input are:
• The capture of signature data begins when beginCapture is called.
• If signature capture is terminated by calling endCapture, then no DataEvent
will be enqueued.

Device Sharing
The Signature Capture is an exclusive-use device, as follows:

manipulate the device or before changing some writable properties.

CapDisplay Property
Syntax CapDisplay: boolean { read-only, access after open }
Remarks If true, the device is able to display a form or data entry screen.
Remarks If true, the device is able to supply signature data as the signature is being captured
(“real time”).
CapUserTerminated Property
Syntax CapUserTerminated: boolean { read-only, access after open }
Remarks If true, the user is able to terminate signature capture by checking a completion
box, pressing a completion button, or performing some other interaction with the
device. If false, the application must end signature capture by calling the
endCapture method.

DeviceEnabled Property (Common)

Syntax DeviceEnabled: boolean { read-write, access after open-claim }
Remarks If true, the signature capture device is enabled.
If CapDisplay is true, then the display screen of the device is cleared.
MaximumX Property
Syntax MaximumX: int32 { read-only, access after open }
Remarks Holds the maximum horizontal coordinate of the signature capture device. It must
be less than 65,536.
MaximumY Property
Syntax MaximumY: int32 { read-only, access after open }
Remarks Holds the maximum vertical coordinate of the signature capture device. It must be
less than 65,536.

PointArray Property Updated in Release 1.7

Syntax PointArray: array-of-points { read-only, access after open-claim-enable } 1
Remarks Holds the signature captured from the device. It consists of an array of (x, y)
coordinate points. Each point is represented by four characters: x (low 8 bits), x
(high 8 bits), y (low 8 bits), y (high 8 bits).
A special point value is (0xFFFF, 0xFFFF) which indicates the end of a line (that
is, a pen lift). Almost all signatures are comprised of more than one line.
If RealTimeDataEnabled is false, then this property contains the entire captured
signature. If RealTimeDataEnabled is true, then this property contains at least
one point of the signature. The actual number of points delivered at one time is
implementation dependent. The points from multiple data events are logically
concatenated to form the entire signature, such that the last point from a data event
is followed immediately by the first point of the next data event.
The point representation definition is the same regardless of whether the signature
is presented as a single PointArray, or as a series of real time PointArrays.
Reconstruction of the signature using the points is accomplished by beginning a
line from the first point in the signature to the second point, then to the third, and
so on. When an end-of-line point is encountered, the drawing of the line ends, and
the next line is drawn beginning with the next point. An end-of-line point is
assumed (but need not be present in PointArray) at the end of the signature.
This property is set prior to a DataEvent being delivered to the application or by
the endCapture method.
See Also RawData Property.

RawData Property Updated in Release 1.7

Syntax RawData: binary { read-only, access after open-claim-enable } 2
Remarks Holds the signature captured from the device in a device-specific format.
This data is often in a compressed form to minimize signature storage
requirements. Reconstruction of the signature from this data requires device-
specific processing.
This property is set prior to a DataEvent being delivered to the application or by
the endCapture method.
See Also PointArray Property.
Syntax RealTimeDataEnabled: boolean { read-write, access after open }
Remarks If true and CapRealTimeData is true, a series of partial signature data events is
enqueued as the signature is captured until signature capture is terminated.
Otherwise, the captured signature is enqueued as a single DataEvent when
signature capture is terminated.
Setting RealTimeDataEnabled will not cause any change in system behavior
until a subsequent beginCapture method is performed. This prevents confusion
regarding what would happen if it were modified between a beginCapture -
endCapture pairing.
Value Meaning
E_ILLEGAL Cannot set to true because CapRealTimeData is false.

See Also CapRealTimeData Property, beginCapture Method, endCapture Method.

beginCapture Method
Syntax beginCapture ( formName: string ):

formName The parameter contains the platform specific location

for obtaining form or data screen information for display
on the device screen.
Remarks Starts capturing a signature.
If CapDisplay is true, then formName is used to find information about the form
or data screen to be displayed. The format and features of each signature capture
device’s form/data screen varies widely and is often built with proprietary tools.
Therefore, this location’s data, and possibly additional values and data, contain
information that varies by Service. Typically, the contents of this data are set to a
form/data screen file name, and extra values and data are set as needed to control
its display.
After displaying the form or data screen, when applicable, the signature capture
stylus is enabled.
Value Meaning
E_NOEXIST formName was not found.

See Also CapDisplay Property, endCapture Method.

endCapture Method
Syntax endCapture ( ):
Remarks Stops (terminates) capturing a signature.
If RealTimeDataEnabled is false and a signature was captured, then it is placed
in the properties PointArray and RawData. If no signature was captured, then
PointArray and RawData are set to a length of zero.
If RealTimeDataEnabled is true and there are signature points remaining which
have not been delivered to the application by a DataEvent, then the remaining
signature is placed into the properties PointArray and RawData. If no signature
was captured or all signature points have been delivered to the application, then
PointArray and RawData are set to a length of zero.
Value Meaning
E_ILLEGAL Signature capture was not in progress.

See Also PointArray Property, RawData Property, RealTimeDataEnabled Property,
beginCapture Method, DataEvent.

DataEvent
Description Notifies the application that input data is available.

Status int32 Non-zero if the user has entered a signature before

terminating capture. Zero if the user terminated capture
with no signature.
Remarks This event can only be enqueued if the user can terminate signature capture – that
is, if CapUserTerminated is true or RealTimeDataEnabled is true.
The properties PointArray and RawData are set to appropriate values prior to a
See Also endCapture Method, “Events” on page 51.
DirectIOEvent
means for a vendor-specific Signature Capture Service to provide events to the
application that are not otherwise supported by the Device Control.
Service.
from being used with other vendor’s Signature Capture devices which may not
have any knowledge of the Service’s need for this event.


Description Notifies the application that a Signature Capture device error has been detected
and a suitable response by the application is necessary to process the error
condition.
ErrorCodeExtended
int32 Extended Error Code causing the error event. This may
values below.
Value Meaning
available.
available. (Very unlikely – see Remarks.)
Value Meaning
true, then another ErrorEvent is enqueued with locus
EL_INPUT.

Remarks Enqueued when an error is detected while trying to read signature capture data.
This event is not delivered until DataEventEnabled is true and other event
With proper programming, an ErrorEvent with locus EL_INPUT_DATA will
not occur. This is because each signature requires an explicit beginCapture
method, which can generate at most one DataEvent. The application would need
to defer the DataEvent by setting DataEventEnabled to false and request another
signature before an EL_INPUT_DATA would be possible.
page 62, “Events” on page 51.
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a Signature
Capture device.
Status int32 Reports a change in the power state of a Signature

Capture device.

process.
Remarks Enqueued when the Signature Capture device detects a power state change.


C H A P T E R 3 6
Smart Card Reader / Writer

This Chapter defines the Smart Card Reader / Writer (SCR/W) device category.
Summary

1196 Smart Card Reader / Writer
CapCardErrorDetection: boolean { read-only } 1.8 open
CapInterfaceMode: int32 { read-only } 1.8 open
CapIsoEmvMode: int32 { read-only } 1.8 open
CapSCPresentSensor: int32 { read-only } 1.8 open
CapSCSlots: int32 { read-only } 1.8 open
CapTransmissionProtocol: int32 { read-only } 1.8 open
InterfaceMode: int32 { read-write } 1.8 open, claim, & enable

IsoEmvMode: int32 { read-write } 1.8 open, claim, & enable
SCPresentSensor: int32 { read-only } 1.8 open, claim, & enable
SCSlot: int32 { read-write } 1.8 open, claim, & enable
TransactionInProgress: boolean { read-only } 1.8 open
TransmissionProtocol: int32 { read-only } 1.8 open

Summary 1197

Common
Name Version
close ( ): 1.8
release ( ): 1.8
clearInput ( ): 1.8
Specific
Name Version
void{ raises-exception, use after open, claim, enable }
endRemoval ( ): 1.8
readData ( action: int32, inout count: int32, inout data: string ): 1.8
writeData ( action: int32, count: int32, data: string ): 1.8



General Information
The Smart Card Reader / Writer programmatic name is “SmartCardRW”.
Capabilities
The Smart Card Reader / Writer (SCR/W) device has the following capabilities.
• Support for the reading and writing of Smart Cards that conform to the ISO/
IEC 7816 standard (contact type) and ISO/IEC 14443 (contactless type).
• Interface with simple memory cards, protected or segmented memory cards,
stored value memory cards, and CPU/MPU multifunction cards.
• Functions are limited to the actual Smart Card read and write operations only.
Full function type devices such as a “Payment Terminal” (defined as a unit
that incorporates a SCR/W plus additional devices such as a Pin Pad, Display,
Signature Capture, and MSR reader in an integrated device) are not covered
in this peripheral class.
• Support for Smart Cards that use physical electrical contacts and/or close
range Radio Frequency to exchange power and data.
• Ability to sense when a card is present or absent is supported.
• Optional support of Security Application Modules (SAM) for CPU/MPU
cards may be provided.
• Up to four types of API communication methods to the SCR/W may be
supported:
1. Command and Data Mode: Very basic ASCII format for commands
and data interchange.
2. Data Block Mode: A block of string data that contains commands and
data is sent to the SCR/W Device Service. The application and the SCR/W
Service need to agree upon a communication protocol and data format before
using this mode.
3. APDU Mode: Same as Data Block Mode except that the block of string
data that contains commands and data sent to the SCR/W Service conforms
to the ISO/IEC 7816 APDU (Application Protocol Data Units) standard for
smart cards. ISO and EMV messaging formats are supported and selectable
if the SCR/W has the capability to switch to one of these formats.
4. XML Data Block Mode: A block of string data that contains commands
and data is sent to the SCR/W Service. The application and the SCR/W
Service agree to use a communication protocol and data format defined in
this standard consistent with the XML Data Dictionary and XML schema
guidelines as outlined in the ARTS XML standard.

Smart Card Reader / Writer Class Diagram
The following diagram shows the relationships between the SCR/W classes.
«utility»
«event» «event» <<uses>> «utility»
SmartCardRWConst
UPOSException BaseControl UposConst
<<sends>>
<<sends>>
<<uses>>
«event»
DataEvent Smart Card R/W Control
«prop» Status : int32 «fires»
«capability» CapCardErrorDetection : boolean
«capability» CapInterfaceMode : int32
«capability» CapIsoEmvMode : int32
«capability» CapSCPresentSensor : int32
«event» «capability» CapSCSlots : int32
DirectIOEvent «capability» CapTransmissionProtocol : int32
«prop» EventNumber : int32 «prop» InterfaceMode : int32
«prop» Data : int32 «prop» IsoEmvMode : int32
«fires» «prop» SCPresentSensor : int32
«prop» Obj : object
«prop» SCSlot : int32
«prop» TransactionInProgress : boolean
«prop» TransmissionProtocol : int32
«fires»
«event» «method» beginInsertion ( )
ErrorEvent «method» beginRemoval ( )
«method» endInsertion ( )
«prop» ErrorCode : int32 «method» endRemoval ( )
«prop» ErrorCodeExtended : int32 «method» readData ( )
«prop» ErrorLocus : int32 «method» writeData ( )
«prop» ErrorResponse : int32
«fires»
«event»
StatusUpdateEvent
«prop» Status : int32

Model
The general model of Smart Card Reader / Writer is as follows:
• The Smart Card Reader / Writer (SCR/W) device has a wide range of usages
that depend upon a variety of ISO 7816 compliant smart cards. These include
cards with or without physical electrical contacts and proximity types that
may function as memory cards, processor cards (T0 and/or T1
TransmissionProtocol), electronic purse cards, security access module
(SAM) processor cards, and security cards. The SCR/W scope is limited to
providing access to the smart card so that data retrieval, data storage, or
program execution on the smart card can be implemented.
• It is the responsibility of the application to have knowledge of what type of

Smart Card transactions the SCR/W device will allow. To help facilitate a
wide range of possibilities of usage, four different communication command
and data interchange methods (InterfaceMode) are provided. As part of the
initialization sequence, the application should query the CapInterfaceMode
to determine what is allowed and set the InterfaceMode property to the
mode that will be used.
• To begin operation, the application must call the open and claim methods to
set up a communication path to the SCR/W device. When the application is
ready to interact with a smart card, the DeviceEnabled property must be set
to true. Then the SCR/W is able to accept a smart card; a
StatusUpdateEvent is fired when one has been detected.
The beginInsertion method, with its time-out value set to some finite value,
provides a way to allow the application to wait for a smart card to be
detected. If the time-out value expires, the program must call another
beginInsertion method to continue its quest for detecting a smart card. Once
the smart card has been detected, the application must call the endInsertion
method.

• Input Updated in Release 1.10

The application must invoke the readData method in order to request data
from the smart card. Notification of the availability of data from the smart
card is accomplished when a DataEvent is delivered. For this device,
notification of a DataEvent does not mean the data has been read, only that
the smart card is in a stable condition where any data that is available to be
read can in fact be read. The application must use the readData method to
actually retrieve the data that the smart card has available. The application
must set the DataEventEnabled property to true in order for the DataEvent
to be delivered.
If an error occurs while reading the smart card’s data, an ErrorEvent is
enqueued instead of a DataEvent. When the application sets the
DataEventEnabled property to true, the ErrorEvent will be delivered.
The application can obtain the current number of enqueued data events by
reading the DataCount property.
All enqueued but undelivered input may be deleted by calling the clearInput
method.
All data properties that are populated as a result of firing a DataEvent or

• Output
The writeData method is always performed asynchronously. All output data
is performed on a first-in, first-out basis. When the application calls the
writeData method, the SCR/W buffers the request and begins the
communication process through the SCR/W device to the smart card.
Depending upon the InterfaceMode property, the writeData method data is

either parsed by the Service or passed natively directly to the SCR/W device
and then on to the smart card. A unique identification number is assigned for
the data associated with the writeData call and is stored in the OutputID
property. The data is enqueued for delivery to the SCR/W device as soon as it
can receive and process it.
When the writeData method completes sending the data associated with the
current output request, an OutputCompleteEvent is delivered to the
application. The OutputID associated with this output request is contained in
the OutputCompleteEvent.
If the writeData method fails during data transfer, an ErrorEvent will be

delivered to the application. If the application had multiple outstanding
output requests, the OutputID of the failed request is determined by
evaluating the OutputID associated with the last successful
OutputCompleteEvent. The request that failed is the one that was issued
immediately after the last request that successfully completed.

All buffered output data may be deleted by calling the clearOutput method.
This also stops any output that is in progress, if possible. No
OutputCompleteEvents will be delivered for output requests terminated in
this manner.
• When done accessing the smart card, the application must call the
beginRemoval method, specifying a timeout value. If the card is not
removed before the timeout period elapses, the SCR/W fires an exception.
The application must call the beginRemoval method again until the smart
card is removed from the SCR/W device.
When the smart card is no longer detected in the SCR/W, a

StatusUpdateEvent is fired.
To exit the removal mode, either after the card was physically removed or the
application aborts the smart card removal process, the application must call
the endRemoval method.
When the application is finished using the SCR/W device, the application
must set the DeviceEnabled property to false and call the release method. If
no further interaction with the SCR/W device is required, the application
must call the close method.
There may be times when the smart card is extracted from the SCR/W device
before the normal usage sequence has been completed. This is referred to as
having the card “torn” from the SCR/W device. The application will receive
a StatusUpdateEvent indicating the card is no longer “present”. In addition
the SCPresentSensor property would have been set to false.

Card Insertion Diagram

The processing from card insertion to card removal is shown below. All methods,
other than writeData, are performed synchronously.
Application
SCR/W Device User : Actor1
1 : beginInsertion : \Timer\
Return if Timer Expires
2 : beginInsertion : \Timer\
3 : \Card Inserted...Note 1\
StatusUpdateEvent : \void\
4 : endInsertion : \void\
5 : setDataEventEnabled : \= true\
Read of Data Available from
DataEvent : \void\ Smart Card and Ready to
Transfer to Application
readData : \action, count, data\
6 : writeData : \action, count, data\
OutputCompleteEvent : \void\ Write Data Available to Transfer

to Smart Card from Application
7 : beginRemoval : \Timer\
Return if Timer expires 8 : \Card is Removed or no Longer

Detected...Note 2\
9 : beginRemoval : \Timer\
User Removes the Card from the
StatusUpdateEvent : \void\ Smart Card RW
10 : endRemoval : \void\
(1) If the smart card is not inserted into the SCR/W before the application
specified timeout elapses, an exception is fired. The application needs to call
beginInsertion again to confirm that a smart card has been inserted or call
endInsertion to cancel the card insertion. After a successful beginInsertion,
the application must call endInsertion to cause the SCR/W to exit insertion
mode and allow for further readData, writeData, or other methods to be
used with the SCR/W to obtain data from the smart card. When a card is
detected, a StatusUpdateEvent is fired.

(2) If the smart card is not removed from the SCR/W before the application
specified timeout elapses, an exception is fired. The application needs to call
beginRemoval again to confirm that the smart card has been removed, or call
endRemoval to cancel the card removal. After a successful beginRemoval,
the application must call endRemoval to cause the SCR/W to exit removal
mode. When a card is no longer detected, a StatusUpdateEvent is fired.
Device Sharing
The SCR/W is an exclusive-use device, as follows:

the SCR/W specific properties.

Data Transfer Modes
The SCR/W has the flexibility to be able to operate in one or more modes to
enable the transfer of data to and from the smart card. When the SCR/W is
initialized, the application must determine what communication and operation
mode will be used based upon a query of the capabilities of the SCR/W device.
The InterfaceMode property is used to store the current communication mode.
In the Command / Data mode, a simple read and write data functionality is
defined between the application and the SCR/W. The commands will cause the
data to be retrieved from, placed onto, or placed onto and executed on the smart
card currently available to the SCR/W device. Greater knowledge of the specific
SCR/W device is required in this mode. The application should query the
PhysicalDeviceName and/or PhysicalDeviceDescription properties and create
the write data and resultant read data based upon the type of SCR/W that is
connected to the system.
In the Block Transfer mode, blocks of commands/data are sent to and retrieved
from the SCR/W Service. It is up to the Service to parse the commands and data
from the block of information sent to it from the application and invoke the
necessary function and response in the smart card currently in the SCR/W.
Knowledge of the message content between the application and the SCR/W must
be established when the open method is called. The application should query the
PhysicalDeviceName and/or PhysicalDeviceDescription properties and base its
message content upon the type of SCR/W that is connected to the system.
In the APDU Transfer mode, blocks of data are sent to and retrieved from the
SCR/W Service similar to the Block Transfer mode described above. However, in
this mode the commands and data consist of string data elements that comply to
the ISO/IEC 7816 APDU (Application Protocol Data Units) standard for Smart
Cards communication. Provision has been made to support the messaging
requirements of ISO or EMV for operating in the APDU mode. The
CapIsoEmvMode property can be queried to determine what modes are
supported by the device. The application then sets the IsoEmvMode property to
the desired messaging scheme prior to sending data to and receiving data from the
SCR/W device.
In the XML Block Transfer mode, blocks of data are sent to and retrieved from the
SCR/W Service similar to the Block Transfer mode described above. However, in
this mode the commands and data are in the form of XML messages. The data
elements and schemas of these messages conform to the ARTS XML messaging
as they apply to the SCR/W device.

Smart Card Reader / Writer Sequence Diagram
ClientAP DataEventHandler SUE Handler OCE Handler cd SCRW DataEvent StatusUpdateEvent OCE SCRW Service User : Actor2
1 : \new\
2 : \new\
3 : \Create and Register a DataEvent

Handler with the Control\
4 : \claim(timeout)\
5 : \claim(timeout)\
6 : \setDeviceEnabled(true)\
7 : \setDeviceEnabled(true)\
8 : \beginInsertion(timeout)\
Smart Card Inserted

enqueue SUE
deliver StatusUpdateEvent
9 : \endInsertion()\
10 : \endInsertion()\
Parse and set SCR/W Properties
11 : \readData(action, count, data)\
12 : \readData(action, count, data)\ Read Operation to the SCR/W and
copy data to DataEvent on to the Smart Card Shown Next
deliver DataEvent
deliver DataEvent to each handler
13 : \writeData(action, count, data)\ Write Operation to the SCR/W and

14 : \writeData(action, count, data)\ on to the Smart Card Shown Next
15 : \new\ Output Data++

deliver OutputCompleteEvent to each deliver OutputCompleteEvent
handler
16 : \beginRemoval(timeout)\
17 : \beginRemoval(timeout)\
Smart Card Removed
18 : \endRemoval()\
19 : \endRemoval()\
20 : \setDeviceEnable(false)\
21 : \setDeviceEnable(false)\
22 : \release()\
23 : \release()\

Smart Card Reader / Writer State Diagram
Application Access to Smart Card
Closed
open() close()
close() Opened
claim() release()
Claimed
set DeviceEnabled(false)
release()
set DeviceEnabled(true) User Removes Smart Card
StatusUpdateEvent() Enabled
StatusUpdateEvent()
endRemoval()
endInsertion() ErrorEvent()
Smart Card Detected Smart Card no Longer Detected

beginInsertion(timeout) Normal Removal Condition
Error: Smart Card "Torn" (Removed)

From SCR/W Prematurely
User Inserts Smart Card
readData(action, count, data)

OutputCompleteEvent()
DataEvent()
writeData(action, count, data)
Smart Card R/W Read Requested

Smart Card R/W Write Requested
Data Read From Card Enqueued
Write Data Dequeued
ErrorEvent() ErrorEvent()
Error While Writing Data
Error While Reading Data
clearInput() clearOutput()
Clear Data Input

Clear Data Output


CapCardErrorDetection Property
Syntax CapCardErrorDetection: boolean { read-only, access after open }
Remarks If true, then the SCR/W has the ability to report that the smart card has been “torn”
(removed before all transfers have been completed) from the device, false if it does
not. The ErrorEvent is only fired with the ErrorCode set to the value
“ESC_TORN” if a “torn” error is detected and the value for this property is true.
See Also ErrorEvent event.
CapInterfaceMode Property
Syntax CapInterfaceMode: int32 { read-only, access after open }
Remarks This capability indicates the types of interface modes that the SCR/W device is
capable of supporting, a simple transaction command and data mode, a block data
mode, APDU format block data mode, or a block XML data mode that uses the
ARTS XML Standard for SCR/W functionality. The InterfaceMode property will
reflect the currently selected interface mode that the application is using to
communicate with the device.
CapInterfaceMode is a bitwise logical OR combination of any of the following

values:
Value Meaning
SC_CMODE_TRANS Simple Transaction Command and Data Mode
SC_CMODE_BLOCK Block Data Mode
SC_CMODE_APDU Same as Block Data Mode except APDU Standard
Commands are used.
SC_CMODE_XML XML Block Data Mode
See Also InterfaceMode Property, IsoEmvMode Property.

CapIsoEmvMode Property
Syntax CapIsoEmvMode: int32 { read-only, access after open }
Remarks This capability indicates the message modes the SCR/W supports in order to
interoperate with a smart card when the InterfaceMode is set to
SC_MODE_APDU. The APDU messaging format is dependent upon whether the
ISO or EMV standard is desired to be used. The IsoEmvMode property is used to
select the APDU mode that the SCR/W is currently using to interoperate with the
smart card.
CapIsoEmvMode is a bitwise logical OR combination of any of the following

values:
Value Meaning
SC_CMODE_ISO APDU messaging format conforms to the ISO standard.
SC_CMODE_EMV APDU messaging format conforms to the EMV
standard.
See Also IsoEmvMode Property, InterfaceMode Property.
CapSCPresentSensor Property
Syntax CapSCPresentSensor: int32 { read-only, access after open }
Remarks This capability indicates if the SCR/W device can sense if a smart card is present
in one of the available slots (entry points and/or proximity zones) where a user can
insert a smart card.
The SCR/W device will always have a minimum of one slot available (designated
as the default slot) indicated by the LSB.
CapSCPresentSensor is a bitwise logical OR combination of any of the int32 bits

with bit 0 (LSB) slot 0 (default); bit 1, slot 1; bit 2, slot 2; etc. If the bit value is
one, then the SCR/W has a sensor that can detect when a smart card is present; the
bit value is zero if it does not.
See Also SCPresentSensor Property.

CapSCSlots Property
Syntax CapSCSlots: int32 { read-only, access after open }
Remarks This capability indicates the bit mask of available slots (entry points and/or
proximity zones) where a user can insert a smart card for detection in the SCR/W
device. The application can select the slot to use by setting the SCSlot property to
one of the allowable CapSCSlots values. The device will always have a minimum
of one slot available (designated as the default slot) indicated by the LSB set to
one.
CapSCSlots is a bitwise logical OR combination of any of the int32 bits with bit
0 (LSB) slot 0 (default); bit 1, slot 1; bit 2, slot 2; etc.
See Also SCSlot Property.
CapTransmissionProtocol Property
Syntax CapTransmissionProtocol: int32 { read-only, access after open }
Remarks This capability indicates the types of ISO 7816-3 transmission protocols that the
SCR/W device is capable of supporting, T=0 (asynchronous half duplex character
transmission protocol), T=1 (asynchronous half duplex block transmission
protocol). The TransmissionProtocol property will reflect the currently selected
transmission protocol being used to communicate with the device.
CapTransmissionProtocol is a bitwise logical OR combination of any of the

following values:
Value Meaning
SC_CTRANS_PROTOCOL_T0 Asynchronous, Half Duplex, Character,
Transmission Protocol Mode
SC_CTRANS_PROTOCOL_T1 Asynchronous, Half Duplex, Block
See Also TransmissionProtocol Property.

InterfaceMode Property
Syntax InterfaceMode: int32 { read-write, access after open-claim-enable }
Remarks This property indicates the current communication interface mode that the SCR/
W device is using to communicate with the application program. The property
CapInterfaceMode contains the interface modes that are supported by the SCR/
W Service. If an InterfaceMode is selected that is not consistent with
CapInterfaceMode, a UposException will be thrown.
InterfaceMode may be one of the following values:
Value Meaning
SC_MODE_TRANS Simple Transaction Command and Data Mode
SC_MODE_BLOCK Block Data Mode
SC_MODE_APDU Same as Block Data Mode except APDU Standard
Defines the Commands and data.
SC_MODE_XML XML Block Data Mode
This property is initialized to SC_MODE_TRANS by the open method.
See Also CapInterfaceMode Property.
IsoEmvMode Property
Syntax IsoEmvMode: int32 { read-only, access after open-claim-enable }
Remarks This property indicates the message modes the SCR/W is currently using in order
to interoperate with a smart card when the InterfaceMode is set to
SC_MODE_APDU. The APDU messaging format is dependent upon whether the
ISO or EMV standard is desired to be used. The CapIsoEmvMode capability
defines the available modes the SCR/W supports and the IsoEmvMode property
will be set to reflect the mode that is currently in use by the SCR/W device.
IsoEmvMode may be one of the following values:
Value Meaning
SC_MODE_ISO APDU messaging format currently in use conforms to
the ISO standard.
SC_MODE_EMV APDU messaging format currently in use conforms to
the EMV standard.
See Also CapIsoEmvMode Property, InterfaceMode Property.

SCPresentSensor Property
Syntax SCPresentSensor: int32 { read-only, access after open-claim-enable }
Remarks This property indicates that a smart card has been detected in one of the supported
slots present in the SCR/W device and is in a position to exchange data with the
application. This property is only active if the CapSCPresentSensor confirms
that a smart card present sensor is supported by the slot. The SCR/W device will
always have a minimum of one slot available (designated as the default slot)
indicated by the LSB but may or may not support a smart card present sensor.
SCPresentSensor is a bitwise logical OR combination of any of the int32 bits with

bit 0 (LSB) slot 0 (default); bit 1, slot 1; bit 2, slot 2; etc. If the bit value is one,
then the sensor indicates that a smart card is present; the bit value is zero if it does
not.
See Also CapSCPresentSensor Property.
SCSlot Property
Syntax SCSlot: int32 { read-write, access after open-claim-enable }
Remarks This property indicates the current slot (entry point or proximity zone) where a
user can insert a smart card for detection in the SCR/W device. The application can
select the slot to use by setting the SCSlot property to one of the allowable
CapSCSlots values. The device will always have a minimum of one slot available
(designated as the default, slot 0) indicated by the LSB set to one.
SCSlot may be set by the application to one of the CapSCSlots values as follows:
bit 0 (LSB) slot 0 (default); bit 1, slot 1; bit 2, slot 2; etc.
This property is initialized by the open method to the default, slot 0 value.
See Also CapSCSlots Property.

TransactionInProgress Property
Syntax TransactionInProgress: boolean { read-only, access after open }
Remarks If true, then a smart card has been detected and active interchange of information
with the smart card is taking place.
See Also SCPresentSensor Property.
TransmissionProtocol Property
Syntax TransmissionProtocol: int32 { read-only, access after open }
Remarks This property indicates the type of ISO 7816-3 transmission protocols that the
SCR/W device is currently supporting, T=0 (asynchronous half duplex character
transmission protocol) or T=1 (asynchronous half duplex block transmission
protocol). The TransmissionProtocol property will reflect the currently selected
transmission protocol being used to communicate with the device.
TransmissionProtocol is a bitwise data element based upon the supported modes as
defined by the CapTransmissionProtocol property and may be one of the following
values:
Value Meaning
SC_TRANS_PROTOCOL_T0 Asynchronous, Half Duplex, Character,
SC_TRANS_PROTOCOL_T1 Asynchronous, Half Duplex, Block
See Also CapTransmissionProtocol Property.


timeout The number of milliseconds before failing the method.
If zero, the method initiates insertion mode and either returns immediately if
successful, or raises an exception. If FOREVER (-1), the method initiates the
begin insertion mode, then waits as long as needed until either the smart card is
Remarks Called to initiate smart card insertion processing in either a contact type or
contactless type SCR/W.
When called, SCR/W state is changed to allow the insertion of a smart card and
the smart card insertion mode is entered. This method is paired with the
endInsertion method for controlling smart card insertion.
If the SCR/W device cannot be placed into insertion mode an exception is raised.
Otherwise, the Control continues to monitor smart card insertion until either the
smart card is not inserted before timeout milliseconds have elapsed, or an error is
reported by the SCR/W device. In the latter case, the Control raises an exception
with the appropriate error code. The SCR/W device remains in smart card insertion
mode. This allows an application to perform some user interaction and reissue the
beginInsertion method without altering the smart card handling mechanism.
Value Meaning
E_ILLEGAL The SCR/W does not exist or an invalid timeout
E_TIMEOUT The specified time has elapsed without the smart

beginRemoval Method
If zero, the method initiates the begin removal mode and either returns
immediately or raises an exception. If FOREVER (-1), the method initiates the
begin removal mode, then waits as long as needed until either the smart card is
Remarks Called to initiate smart card removal processing.
When called, the SCR/W is made ready to be removed from either a contact type
or a contactless type SCR/W. This method is paired with the endRemoval method
for controlling smart card removal.
The contact type model that has the sensor in the entrance ends normally when a
card is removed from SCR/W. The contactless model (without a sensor) ends
normally when the smart card has been removed from the proximity of the
SCR/W device.
If the SCR/W cannot be placed into removal or ejection mode, an exception is
raised. Otherwise, the Control continues to monitor smart card removal until either
the smart card is not ejected before timeout milliseconds have elapsed, or an error
is reported by the SCR/W. In this case, the Control raises an exception with the
appropriate error code. The SCR/W remains in smart card ejection mode. This
beginRemoval method without altering the smart card handling mechanism.
Value Meaning
E_ILLEGAL The SCR/W does not exist or an invalid timeout
E_TIMEOUT The specified time has elapsed without the smart
card being properly removed.

endInsertion Method
Remarks Called to end smart card insertion processing.
When called, the SCR/W is taken out of smart card insertion mode. If no smart
card is present, an exception is raised.
This method is paired with the beginInsertion method for controlling smart card
insertion in either a contact type or contactless type SCR/W.
Value Meaning
E_ILLEGAL The SCR/W is not in smart card insertion mode.
E_FAILURE A card is not inserted in the SCR/W.
endRemoval Method
Remarks Called to end smart card removal processing.
When called, the SCR/W is taken out of smart card removal mode in either a
contact type or contactless type SCR/W. If a smart card is present, an exception is
raised. This method is paired with the beginRemoval method for controlling
smart card removal.
The application may choose to call this method immediately after a successful
beginRemoval if it wants to use the SCR/W sensors to determine when the smart
card has been removed. Alternatively, the application may prompt the user and
wait for a key being pressed before calling this method.
Value Meaning
E_ILLEGAL The SCR/W is not in smart card removal mode.
E_FAILURE There is a card in the SCR/W.

readData Method Updated in Release 1.10

Syntax readData ( action: int32, inout count: int32, inout data: string ):
action Indicates the type of processing of the data that is to be
done by the smart card.
count The total number of data bytes that are being returned by
the smart card.
data The data that is returned from the smart card.
Remarks Reads data from a smart card using the SCR/W. Note that a DataEvent is used to
indicate that the smart card is in a stable condition where read data is available and
that the readData method can be called to return the data.
The action parameter may have one of the following values:
Value Meaning
SC_READ_DATA The data being read from the smart card present in the
SCR/W is from the Data Area on the smart card.
SC_READ_PROGRAM The data being read from the smart card present in the
SCR/W is an executable program that was found in the
smart card memory associated with executable
programs.
SC_EXECUTE_AND_READ_DATA
The data being read from the smart card present in the
SCR/W is data that was processed by a program
currently resident on the smart card. When this action is
requested the smart card program will be started and
send back the data that it has processed.
SC_XML_READ_BLOCK_DATA
The data being read is XML data that the SCR/W is
sending to the application. It is up to the application to
parse the data being returned.
Value Meaning
E_CLAIMED Cannot read because the smart card present in the
SCR/W is claimed by another application.
E_ILLEGAL The action is not valid for the type of smart card present
in the SCR/W or the count value is not valid for the
smart card present in the SCR/W.
See Also writeData Method, Smart Card Model, Input Section.

writeData Method
Syntax writeData (action: int32, count: int32, data: string ):
action Indicates the type of processing of the data that is to be
done by the smart card.
count The total number of data bytes that are being sent to the
smart card with this method.
data The data that is to be sent to the smart card.
Remarks Writes data to a smart card using the SCR/W.

The action parameter may have one of the following values:
Value Meaning
SC_STORE_DATA The data being sent to the smart card present in the
SCR/W is to be stored in the Data Area on the smart
card.
SC_STORE_PROGRAM
The data being sent to the smart card present in the
SCR/W is an executable program and will be placed in
the smart card memory associated with executable
programs.
SC_EXECUTE_DATA The data being sent to the smart card present in the
SCR/W is data that will be processed by a program that
is currently resident and can execute on the smart card.
When this action is requested the smart card program
will be started and will use the data that has been sent.
SC_XML_BLOCK_DATA
The data being sent is XML data and is to be parsed by
the SCR/W to determine what actions are to take place.
SC_SECURITY_FUSE The smart card present in the SCR/W will have its
security fuse activated to prevent future data from being
stored in the smart card.
SC_RESET The smart card present in the SCR/W will be instructed
to be reset to its “power on” state and ready to execute
an application command.
Value Meaning
E_CLAIMED Cannot write because the smart card present in the
SCR/W is claimed by another application.
E_ILLEGAL The action is not valid for the type of smart card present
in the SCR/W or the count value is not valid for the
smart card present in the SCR/W.
See Also readData Method.


Description Fired to indicate that the smart card is in a stable condition in order to read data
from the card. The readData method can then be called to retrieve the data that
the smart card contains.
Remarks The smart card is now in a stable condition such that data can be read from the
smart card. The smart card has either been inserted into the SCR/W or is within the
read range for a successful data read. In either case, the readData method must be
called to retrieve the data from the smart card.
See Also Smart Card Model, Input Section.
DirectIOEvent
means for a vendor-specific SCR/W Service to provide events to the application
Service.
from being used with other vendor’s smart card devices which may not have any


Description Notifies the application that a SCR/W error has been detected and a suitable
Codes on page 52.
ErrorCodeExtended
values below.
following values:
Value Meaning
ESC_READ There was a read error.
ESC_WRITE There was a write error.
ESC_TORN The smart card was prematurely removed from the
SCR/W unexpectedly. Note: CapCardErrorDetection
capability must be true before this can be set.
ESC_NO_CARD There is no card detected in the SCR/W but a card was
expected.

Value Meaning
available.
available.

Value Meaning
ER_CONTINUEINPUT
EL_INPUT_DATA.
Remarks Input error events are generated when errors occur while reading the data from a
newly inserted smart card. These error events are not delivered until the
asynchronous writeData processing. The errors are placed into the applicable
properties before the event is delivered.
See Also CapCardErrorDetection Property, SCPresentSensor Property, readData
method, writeData method.

OutputCompleteEvent


is complete.
StatusUpdateEvent
Description Notifies the application that there is a change in the status of the SCR/W device.
Status int32 Indicates a change in the status of the SCR/W device.
Value Meaning
SC_SUE_NO_CARD No card detected in the SCR/W Device.
SC_SUE_CARD_PRESENT There is a card in the device.
process.
Remarks Fired when the status of a smart card in the SCR/W changes.


C H A P T E R 3 7
Tone Indicator
This Chapter defines the Tone Indicator device category.
Summary

1226 Tone Indicator
AsyncMode: boolean { read-write } 1.2 open & enable
CapPitch: boolean { read-only } 1.2 open
CapVolume: boolean { read-only } 1.2 open
InterToneWait: int32 { read-write } 1.2 open & enable
Tone1Duration: int32 { read-write } 1.2 open & enable
Tone1Pitch: int32 { read-write } 1.2 open & enable
Tone1Volume: int32 { read-write } 1.2 open & enable
Tone2Duration: int32 { read-write } 1.2 open & enable
Tone2Pitch: int32 { read-write } 1.2 open & enable
Tone2Volume: int32 { read-write } 1.2 open & enable

Common
Name Version
close ( ): 1.2
release ( ): 1.2
clearInput ( ): Not
void { } supported
void { } supported

Summary 1227
Specific
Name
sound ( numberOfCycles: int32, interSoundWait: int32 ): 1.2
soundImmediate (): 1.2
Note: Also requires that no other application has claimed the ToneIndicator.


1228 Tone Indicator
General Information
The Tone Indicator programmatic name is “ToneIndicator”.
Capabilities
The Tone Indicator has the following capabilities:

• Sound a tone device, which may be the PC or NC system speaker or another
hardware device. In many cases the PC or NC speaker will not be available or
will be in a position that is inaudible to the operator.
• Sound a two-tone indicator, providing simple pitch and volume control.
• Provide a synchronous one-shot indicator, similar to an Operating System’s
Beep function.
Tone Indicator Class Diagram
The following diagram shows the relationships between the Tone Indicator
classes.
<<uses >>
<<exception>> <<Interface>>
UposExcept ion BaseControl <<utility>>
<<event>> UposConst
DirectIOEvent
(from upos)
(from events) <<sends>>
<<sends>> <<utility>>
fires ToneIndicatorConst
(from upos)
<<Interface>>
<<event >> ToneIndicatorControl <<uses>>
ErrorEvent (from upos)
(from events)
<<capability>> CapVolume : boolean
<<prop>> ErrorCode : int32 <<capability>> CapPitc h : boolean
<<prop>> ErrorCodeExtended : int32 fires <<prop>> AsyncMode : boolean
<<prop>> ErrorLocus : int32 <<prop>> InterToneW ait : boolean
<<prop>> ErrorResponse : int32 <<prop>> Tone1Pitch : int32
<<prop>> Tone2Pitch : int32
<<prop>> Tone1Volume : int 32
f ires <<prop>> Tone2Volume : int 32
<<event>> <<prop>> Tone1Durat ion : int32
OutputCompleteEvent <<prop>> Tone2Durat ion : int32
(from event s)
<<prop>> OutputID : int32 sound(numOfCyles : int32, interSoundWait : int32) : void
soundImmediate() : void
f ires
<<event >>
StatusUpdateEvent
(from events)

Tone Indicator Sequence Diagram Added in Release 1.7

The following sequence diagram shows the typical usage of the Tone Indicator
device.
NOTE: we are assuming that the :ClientApp has already successfully opened and enabled the ToneIndicator device and
registered its event handlers with the control. This means that the DeviceEnabled property is == true
:ClientApp :ToneIndicator :OutputCompleteEvent :ToneIndicatorService
1: setInterToneWait(waitTime) 2: setInterToneWait(waitTime)
3: setTone1Pitch(t1Pitch)
7: sound(numOfCycles, iSWait)
8: sound(numOfCycles, iSWait)
9: setAsyncMode(true)
10: setAsyncMode(true)
11: sound(numOfCycles, iSWait) 12: sound(numOfCycles, iSWait)
13: getOutputID()
14: getOutputID()
The new OutputCompleteEvent is

created when tone finishes playing any
enqueued requests. 15: enqueue requests and sound tones
16: create new OCE event
17: deliver OCE to control


1230 Tone Indicator

The Tone Indicator device is for use when the POS hardware platform provides
such capabilities external to the PC or NC standard speaker. Many POS systems
have such devices, embedded, for example, in a keyboard, so that an indicator is
always present at the point of sale.
This device supports a two-tone sound so that “siren” tones can be produced. The
indicator is in general also started asynchronously so applications may perform
other functions while waiting for the user to acknowledge the tone. There are also
options to start the tone asynchronously with no count, so it runs forever, and be
stopped by the application at a later time.
When the tone is started asynchronously, an OutputCompleteEvent is enqueued
when all the tones have been played. This allows the application to know that the
tone has stopped. For example, when the cash drawer is opened the tone could be
started, quietly for a given number of cycles. If the cash drawer is closed then the
tone is stopped explicitly by the application, if not then the notification by the
OutputCompleteEvent allows the application to alter the prompt to the operator
and possibly restart the tone a little louder.
The Tone Indicator follows the general device behavior model for output devices.
Asynchronous output is handled as follows:
Physical Device as soon as the Physical Device can receive and process it, sets
OutputID to an identifier for this request, and returns as soon as possible.
When the request completes successfully, an OutputCompleteEvent is
enqueued. A parameter of this event contains the OutputID of the completed
request.
The sound method will not raise an exception due to a hardware problem.
These errors will only be reported by an ErrorEvent. An exception will only
be raised if the control is not claimed and enabled, a parameter is invalid, or
the request cannot be enqueued. The first two error cases are due to an
application error, while the last is a serious system resource exception.
• If an error occurs while performing an asynchronous request, an ErrorEvent

is enqueued.
• All buffered output data, including all asynchronous output, may be deleted
by calling clearOutput. OutputCompleteEvents will not be delivered for
cleared output. This method also stops any output that may be in progress
(when possible).

Device Sharing
The Tone Indicator is a sharable device. Its device sharing rules are:
properties, methods, and enqueued StatusUpdateEvents.
applications may access its properties and methods. StatusUpdateEvents will
be delivered to all applications that are using the device and have registered to
receive the event.
• If one application claims the tone indicator, then only that application may call
sound and soundImmediate. Use of this feature will effectively restrict the
tone indicator to the main application if that application claims the device at
startup.
• The application that initiates asynchronous sounds is the only one that
receives the corresponding OutputCompleteEvents and ErrorEvents.
• If a scenario exists such that an application is playing a sound and a separate
application legally claims the device and plays a sound, then the sound being
played from the first application will be interrupted. If the first application is
in the midst of a synchronous sound method, an exception will be raised with
the ErrorCode property set to E_CLAIMED from the method call. If the
application has issued an asynchronous sound method, then no consistent
reporting mechanism is possible and the first sound is simply terminated.

1232 Tone Indicator
AsyncMode Property Updated in Release 1.6

Remarks If true, the sound method will be performed asynchronously. If false, tones are
generated synchronously.
other devices.)
CapPitch Property
Syntax CapPitch: boolean { read-only, access after open }
Remarks If true, the hardware tone generator has the ability to vary the pitch of the tone.
CapVolume Property
Syntax CapVolume: boolean { read-only, access after open }
Remarks If true, the hardware tone generator has the ability to vary the volume of the tone.
InterToneWait Property Updated in Release 1.6
Syntax InterToneWait: int32 { read-write, access after open }
Remarks Holds the number of milliseconds of silence between tone-1 and tone-2. If a gap
is required after tone-2 but before a repeat of tone-1, then set the sound parameter
interSoundWait.
other devices.)
Value Meaning
E_ILLEGAL A negative value was specified.

Tone1Duration Property Updated in Release 1.6

Syntax Tone1Duration: int32 { read-write, access after open }
Remarks Holds the duration of the first tone in milliseconds. A value of zero or less will
cause this tone not to sound.
other devices.)
Tone1Pitch Property Updated in Release 1.6
Syntax Tone1Pitch: int32 { read-write, access after open }
Remarks Holds the pitch or frequency of the first tone in hertz. A value of zero or less will
If the device does not support user-defined pitch (CapPitch is false), then any
value greater than zero indicates that the tone indicator uses its default value.
other devices.)
Tone1Volume Property Updated in Release 1.6
Syntax Tone1Volume: int32 { read-write, access after open }
Remarks Holds the volume of the first tone in percent of the device's capability, where 0 (or
less) is silent and 100 (or more) is maximum.
If the device does not support user-defined volume (CapVolume is false), then
any value greater than zero indicates that the tone indicator uses its default value.
other devices.)

1234 Tone Indicator
Tone2Duration Property Updated in Release 1.6

Syntax Tone2Duration: int32 { read-write, access after open }
Remarks Holds the duration of the second tone in milliseconds. A value of zero or less will
other devices.)
Tone2Pitch Property Updated in Release 1.6

Syntax Tone2Pitch: int32 { read-write, access after open }
Remarks Holds the pitch or frequency of the second tone in hertz. A value of zero or less
will cause this tone not to sound.
If the device does not support user-defined pitch (CapPitch is false), then any
value greater than zero indicates that the tone indicator uses its default value.
other devices.)
Tone2Volume Property Updated in Release 1.6

Syntax Tone2Volume: int32 { read-write, access after open }
Remarks Holds the volume of the second tone in percent of the device's capability, where 0
(or less) is silent and 100 (or more) is maximum.
If the device does not support user-defined volume (CapVolume is false), then
any value greater than zero indicates that the tone indicator uses its default value.
other devices.)

sound Method Updated in Release 1.6

Syntax sound ( numberOfCycles: int32, interSoundWait: int32 ):
numberOfCycles The number of cycles to sound the indicator device. If

FOREVER, then start the indicator sounding and repeat
continuously, else perform the sound for the specified
number of cycles.
interSoundWait milliseconds before repeating the tone
cycle (before playing tone-1 again).
Remarks Sounds the indicator device, or start it sounding asynchronously.
The duration of an indicator cycle is:
Tone1Duration property +
InterToneWait property +
Tone2Duration property +
interSoundWait parameter (except on the last tone cycle)
After the tone indicator has started an asynchronous sound, then the sound may be
stopped by using one of the following methods. (When a numberOfCycles value
of FOREVER was used to start the sound, then the application must use one of
these to stop the continuous sounding of the tones.)
• clearOutput
• soundImmediate
Value Meaning
E_CLAIMED Indicates that another application has claimed the device
and has taken over the tone device causing the sound
from this method to be interrupted (can only be returned
if AsyncMode is false.)
• numberOfCycles is neither a positive, non-zero value
nor FOREVER.
• numberOfCycles is FOREVER when
AsyncMode is false.
• A negative interSoundWait was specified
• A negative InterToneWait was specified

1236 Tone Indicator
soundImmediate Method
Syntax soundImmediate ():
Remarks Sounds the hardware tone generator once, synchronously. Both tone-1 and tone-2
are sounded using InterToneWait.
If asynchronous output is outstanding, then it is terminated before playing the
immediate sound (as if clearOutput were called). This method is primarily
intended for use in exception conditions when asynchronous output is outstanding,
such as within an error event handler.

DirectIOEvent
means for a vendor-specific Tone Indicator Service to provide events to the
Service.
Remarks This event to be used only for those types of vendor specific functions that are not
otherwise described. Use of this event may restrict the application program from
being used with other vendor’s Tone Indicator devices which may not have any

1238 Tone Indicator

Description Notifies the application that an error has been detected at the device and a suitable
response is necessary to process the error condition.
Codes on page 52.
ErrorCodeExtended
int32 Extended Error code causing the error event. These
values below.
Value Meaning
The application’s error processing may change ErrorResponse to one of the

following values:
Value Meaning

This is the default value.
asynchronous output. The error state is exited.
into the error state.
page 62, “Error Codes” on page 52

OutputCompleteEvent

is complete.
See Also “Device Output Models” on page 57
StatusUpdateEvent
Description Notifies the application that there is a change in the power status of a Tone
Indicator device.
Status int32 Reports a change in the power state of a Tone Indicator

device.

process.
Remarks Enqueued when the Tone Indicator device detects a power state change.

1240 Tone Indicator

A P P E N D I X A
OLE for Retail POS — OPOS Implementation Reference
What Is “OLE for Retail POS?”

OLE for Retail POS provides an open device driver architecture that allows
Point-of-Sale (“POS”)1 hardware to be easily integrated into POS systems based
on Microsoft Windows family of Operating Systems2. It is an implementation of
the UnifiedPOS Standard based upon the Microsoft Operating System Software
and the OLE 2.x architecture.
The goals of OLE for Retail POS (or “OPOS”) include:
• Defining an architecture for Win32-based POS device access.
• Defining a set of POS device interfaces sufficient to support a range of POS
solutions.
Deliverables available for OPOS are:
• UnifiedPOS Programmer’s Guide – this document: For application
developers and hardware providers.
• Header files with OPOS constants.
• No complete software components: Hardware providers or third-party
providers develop and distribute these components.
• Reference Control Objects are available which incorporate the required
functionality. These Control Objects, along with other helpful information
may be found at the following web sites:
Reference implementation – Common Control Objects:

http://monroecs.com/opos.htm
NRF-ARTS Standards Body:

http://www.nrf-arts.org/
1.
POS may also refer to Point-of-Service – a somewhat broader category than Point-of-
Sale.
2. Excludes Windows 3.x. Other future operating systems that support OLE Controls may also
support OLE for Retail POS, depending upon software support by the hardware manufacturers
or third-party developers.
UnifiedPOS Retail Peripheral Architecture Appendix A
A-2 OPOS Implementation Reference
Who Should Read This Section

This Section is targeted at an application developer who requires access to POS-
specific peripheral devices and wishes to implement the UnifiedPOS Standard on
a Microsoft Windows operating system platform. It is also targeted for the system
developer who will write an OPOS Control, a vendor who wishes to write a
OPOS Service Object, or an application developer who desires a better
understanding of how to interface with OPOS under UnifiedPOS.
This guide assumes that the reader is familiar with the following:
• The UnifiedPOS Device chapters in this document.
• ActiveX and Automation terminology and architecture.
• Familiarity with an ActiveX Control Container development environment,
such as Microsoft Visual Basic or Microsoft Visual C++, will be useful.
General OLE for Retail POS Control Model

OLE for Retail POS Controls adhere to the ActiveX Control specifications. They
expose properties, methods, and events to a containing Application. The controls
are invisible at run time, and rely exclusively upon the containing application for
requests through methods and sometimes properties. Responses are given to the
application through method return values and parameters, properties, and events.
The OLE for Retail POS software is implemented using the
layers shown in the following diagram:

OPOS Definitions A-3
OPOS Definitions
Device Class
A device class is a category of POS devices that share a consistent set of
properties, methods, and events. Examples are Cash Drawer and POS Printer.
Some devices support more than one device class. For example, some POS
Printers include a Cash Drawer kickout. Also, some Bar Code Scanners include
an integrated Scale.
Control Object or CO
A Control Object exposes a set of properties, methods, and events to an
application for its device class. This guide describes these APIs.
A CO is a standard ActiveX (that is, OLE 32-bit) Control that is invisible at
runtime. The CO interfaces have been designed so that all implementations of a
class' Control Object will be compatible. This allows the CO to be developed
independently of the SO's for the same class – including development by different
companies.
Service Object or SO
A Service Object is called by a Control Object to implement the OPOS-
prescribed functionality for a specific device.
An SO is implemented as an Automation server. It exposes a set of methods that
are called by a CO. It can also call special methods exposed by the CO to cause
events to be delivered to the application.
A Service Object may include multiple sets of methods in order to support
devices with multiple device classes.
A Service Object is typically implemented as a local in-proc server (in a DLL). In
theory, it may also be implemented as a local out-proc server (in a separate
executable process). However, we have found that, in practice, out-proc servers
do not work well for OPOS Service Objects, and do not recommend their use.
OPOS Control or Control

An OPOS Control consists of a Control Object for a device class – which
provides the application interface, plus a Service Object – which implements the
APIs. The Service Object must support a device of the Control Object's class.
Usually, this guide will refer to “Control.” On occasion, we must distinguish
between the actions performed by the Control Object and Service Object. Then
the explicit layer is specified.

How an Application Uses an OPOS Control

The first action the application must take on the Control is to call its Open
method. The parameter of this method selects a device name to associate with the
Control. The Open method performs the following steps:
• Establishes a link to the device name.
• Initializes the properties OpenResult, Claimed, DeviceEnabled,
DataEventEnabled, FreezeEvents, AutoDisable, DataCount, and
BinaryConversion, as well as descriptions and version numbers of the OPOS
Control layers. Additional class-specific properties may also be initialized.
Several applications may have an OPOS Control open at the same time.
Therefore, after the device is opened, the application will often need to call the
ClaimDevice method to gain exclusive access to the device. Many devices must
be claimed before the Control allows access to its methods and properties.
Claiming the device ensures that other applications do not interfere with the use
of the device. The application may call the ReleaseDevice method when the
device can be shared by other applications – for instance, at the end of a
transaction.
Before using the device, the application must set the DeviceEnabled property to
TRUE. This value brings the device to an operational state, while FALSE disables
the device. For example, if a scanner Control is disabled, then the device will be
physically disabled (when possible). Whether physically disabled or not, any
input from the device will be discarded until the device is enabled.
After the application has finished using the device, the Close method should be
called to release the device and associated resources. If the DeviceEnabled
property is TRUE, then Close disables the device. If the Claimed property is
TRUE, then Close releases the lock. Before exiting, an application should close
all open OPOS Controls.
In summary, the application follows this general sequence:
• Open method: Call to link the Control Object to the Service Object.
• ClaimDevice method: Call to gain exclusive access to the device. Required
for exclusive-use devices; optional for some sharable devices. (See “Device
Sharing Model”, page A-10 for more information).
• DeviceEnabled property: Set to TRUE to make the device operational. (For
sharable devices, the device may be enabled without first claiming it.)
• Use the device.
• DeviceEnabled property: Set to FALSE to disable the device.
• ReleaseDevice method: Call to release exclusive access to the device.
• Close method: Call to release the Service Object from the Control Object.

When Methods and Properties May Be Accessed A-5
When Methods and Properties May Be Accessed

Methods
Before a successful Open, no other methods may be invoked. Doing so will do
nothing but return a status of OPOS_E_CLOSED.
Exclusive-use devices require the application to call the ClaimDevice method
and to set the DeviceEnabled property to TRUE before most other methods may
be called.
Sharable devices require the application to set the DeviceEnabled property to
TRUE before most other methods may be called.
The “Summary” section of each device class’ chapter should be consulted for the
specific prerequisites for each method.
Properties
Before a successful Open, the values of most properties are not initialized. An
attempt to set writable properties will be ignored.
The following properties are always initialized:
Property Value
State OPOS_S_CLOSED
ResultCode OPOS_E_CLOSED
ControlObjectDescription Control Object dependent string.
ControlObjectVersion Control Object dependent number.
Capability properties are initialized after the Open is successfully called.

Exclusive use devices require the application to call the ClaimDevice method
and to set the DeviceEnabled property to TRUE before some other properties are
initialized or may be written.
Sharable devices require the application to set the DeviceEnabled property to
TRUE before some other properties are initialized or may be written.
To determine when a property is initialized or writable, refer to the Summary
section of each device class plus the property’s Remarks section.
Setting writable properties before the prerequisites are met will cause the write to
be ignored, and will set the ResultCode property to either
OPOS_E_NOTCLAIMED or OPOS_E_DISABLED.

Reading an uninitialized property returns the following values, unless otherwise

specified in the device class documentation:
Property Type Value

Boolean FALSE
Long 0
String “[Error]” – include the brackets.
After properties have been initialized, subsequent claims and enables do not re-
initialize the properties. They remain initialized until the Close method is called.

Status, Result Code, and State Model A-7
Status, Result Code, and State Model Updated in Release 1.11

The status, result code, and state models are built around several common
properties, events, and methods, described in the following table, and are
supported by additional class-specific components.
Name Meaning
State A property containing the current state of the Control:

OPOS_S_CLOSED
OPOS_S_IDLE
OPOS_S_BUSY
OPOS_S_ERROR
ResultCode A property containing the status of the most recent
method or the most recently changed writable property:
OPOS_SUCCESS
OPOS_E_CLOSED
OPOS_E_CLAIMED
OPOS_E_NOTCLAIMED
OPOS_E_NOSERVICE
OPOS_E_DISABLED
OPOS_E_ILLEGAL
OPOS_E_NOHARDWARE
OPOS_E_OFFLINE
OPOS_E_NOEXIST
OPOS_E_EXISTS
OPOS_E_FAILURE
OPOS_E_TIMEOUT
OPOS_E_BUSY
OPOS_E_EXTENDED
OPOS_E_DEPRECATED
ResultCodeExtended A property containing the extended status of the most
recent method or the most recently changed writable
property. Value varies by ResultCode and by device
class.
StatusUpdateEvent An event fired when some class-specific state or status
variable has changed.
Release 1.3 and later: All devices may be able to
report device power state. See “Device Power
Reporting Model” on page A-17.
ErrorEvent An event fired when the State is changed to Error.

Status Model
The rules of the status model are as follows:
• The only aspect of the status model that is common to all device classes is the
means of alerting the application, which is through the firing of the
StatusUpdateEvent.
• Each device class specifies the status changes that cause it to fire the event.
Examples of device class-specific status changes are:
• A change in the cash drawer position (for example, a transition from open
to closed).
• A change in a POS printer sensor (for example, activation of a “form
present” sensor, indicating that a slip has been inserted).
Result Code Model

The rules of the result code model are as follows:
• Every method returns a result code. This code is also placed into ResultCode.
• Setting a writable property causes a result code to be placed into ResultCode.
• The ResultCode OPOS_SUCCESS is assigned the value of zero. Non-zero
values indicate an error or warning.
• The Control must select one of the result codes listed below. If the Control sets
ResultCode to OPOS_E_EXTENDED, then it must set
ResultCodeExtended to one of the values specified in the device class
documentation. (That is, when this ResultCode value is selected, then
ResultCodeExtended may only contain one of the values listed in this
document for the device class, in the appropriate method or property section.)
If the Control sets ResultCode to a value other than OPOS_E_EXTENDED,
then the Service Object may set the ResultCodeExtended property to any
SO-specific value. If an application uses these values, it will, of course, need
to add Service Object-specific code. (If the application needs to add such code,
then the ServiceObjectDescription, DeviceDescription, or DeviceName
property may be interrogated to determine the Service Object with which it is
dealing.)

State Model A-9
State Model Updated in Release 1.7

The rules of the state model are as follows:
• The Control’s State is initially OPOS_S_CLOSED.
• The State is changed to OPOS_S_IDLE when the Open method is called and
its result is OPOS_SUCCESS.
• The State is set to OPOS_S_BUSY when OPOS is processing output. The
State is restored to OPOS_S_IDLE when these complete successfully.
• The State is changed to OPOS_S_ERROR when:
• An asynchronous output encounters an error condition.
• An error is encountered during the gathering or processing of event-
driven input.
After OPOS changes the State property to OPOS_S_ERROR, it invokes
ErrorEvent. The parameters to this event are the result code and extended
result code, the locus of the error, and a pointer to the application’s response
to the error. The locus can indicate one of three error locations:
• Output – The error occurred while processing previously queued output.
• InputWithData – The error occurred while gathering or processing event-
driven input. Some previously gathered input data is available for the
application. When this error locus is given, then the application can
continue to process input until a second ErrorEvent is received with the
InputNoData locus, or it can clear the input.
• InputNoData – The error occurred while gathering or processing event-
driven input, and either all previously gathered input data has been
processed or there is no input data available.
When the application returns from the ErrorEvent, it may change the
response parameter. The response values are:
• Retry – If the locus is Output: Retry the asynchronous output and exit the
error state. If an error occurs while retrying, then another ErrorEvent
will be generated.
If the locus is Input: Some devices support retrying the input, if retry can
be controlled by the Service Object.
“Retry” is the default response when the locus is “Output.”
• Clear – Clear all buffered output data (including all asynchronous output)
or buffered input data and exit the error state.
“Clear” is the default response when the locus is “InputNoData.”
• Continue – Use only if the locus is InputWithData. This response
acknowledges the error and directs the Control to continue processing.
The Control remains in the error state, and will deliver additional data
events as directed by the DataEventEnabled property. When all input
has been delivered and the DataEventEnabled property is again set to
TRUE, then another ErrorEvent is delivered with locus “InputNoData.”
“Continue” is the default response when the locus is “InputNoData.”
The Control ensures that while the application is processing an ErrorEvent,
it will not deliver any other ErrorEvents.


The OLE for Retail POS device sharing model supports devices that are to be
used exclusively by one application3 at a time, as well as devices that may be
partially or fully shared by multiple applications. (See “When Methods and
Properties May Be Accessed”, page A-5, for other details.) All OPOS Controls
may be opened by more than one application at a given time. Some or many of
the activities that an application can perform with the Control, however, may be
restricted to an application that claims access to the device.
The most common device type is called an “exclusive-use device.” An example is
the POS printer. Due to physical or operational characteristics, this device can
only be used by one application at a time. The application must call the
ClaimDevice method to gain exclusive access to the device before most methods,
properties, or events are legal. Until the device is claimed, calling methods or
setting properties cause an OPOS_E_NOTCLAIMED error, and events are not
fired to the application.
Should two closely cooperating applications want to treat an exclusive-use device
in a shared manner, then one application may claim the device for a short
sequence of operations, then release it so that the other application may use it.
When the ClaimDevice method is called again, settable device characteristics are
restored to their condition at ReleaseDevice. Examples of restored characteristics
are the line display’s brightness, the MSR’s tracks to read, and the printer’s
characters per line. State characteristics are not restored, such as the printer’s
sensor properties. Instead, these are updated to their current values.
Sharable Devices
Some devices are “sharable devices.” An example is the keylock. A sharable
device allows multiple applications to call its methods and access its properties.
Also, it may fire its events to all applications that have opened it. A sharable
device may still limit access to some methods or properties to an application that
has claimed it, or may fire some events only to this application.
Note:
One might argue that all devices should be defined as sharable to allow maximum
flexibility to applications. In practical use, this flexibility is unlikely to be useful.
The downside is an implementation that may be significantly more complex and
less likely to be accurate.
In the interest of a specification that is both sufficiently robust for application
development, plus implementable by hardware manufacturers, this document
defines most devices as exclusive-use, and defines as sharable only those devices
that have a significant potential for simultaneous use by multiple applications.
3.
This document assumes that an application consists of only one process. Multi-process
applications are possible to create but uncommon. Technically, device sharing is performed on
a process basis. However, with single-process applications we can view sharing as application-
level.

Events A-11

OLE for Retail POS uses events to inform an application of various activities or
changes with the OPOS Control. The five event types follow. Subsequent sections
will clarify their definitions.
• DataEvent: Input data has been placed into device class-specific properties.
• ErrorEvent: An error has occurred during event-driven input or
• StatusUpdateEvent: Reports a change in the device’s status.
• OutputCompleteEvent: An asynchronous output has successfully
completed.
• DirectIOEvent: This event may be defined by a Service Object provider for
purposes not covered by the specification.
The Service Object enqueues events as they occur. Often these events will be
enqueued by worker threads, rather than the application’s thread. Enqueued
events are delivered to the application when conditions are correct. Conditions
which delay the delivery of events include:
• The application thread is busy processing other messages.
OPOS Controls are to follow the OLE Apartment Threading model.
According to OLE Apartment Threading rules, events are to be delivered on
the thread that created the COM object, which will usually be the application’s
main thread. If the application is processing another message, then event
delivery must wait until this processing has finished.
• The application has set the property FreezeEvents to TRUE.
• The event type is DataEvent or an input ErrorEvent, but the property
DataEventEnabled is FALSE. (See “Input Model” on page A-14.)
If the oldest enqueued event is blocked for one of these reasons, then all newer
events may also be blocked. That is, the delivery of enqueued events is typically
in a strict first in, first out order. Priority is not given to any event types on the
queue.

Note – Terminology
The following event terminology is used rather consistently in this document.
Some implementations may vary from the model described here, but the net
effect is similar:
• Enqueue: When the Service Object determines that an event needs to be fired
to the Application, it enqueues the event on an internal event queue. Event
queuing typically occurs from one or more internal Service Object worker
threads.
• Deliver: When the event queue is non-empty and all conditions are met for the
top event on the queue, this event is removed from the queue and delivered to
the Application. Event delivery is typically managed by a dedicated internal
Service Object worker thread. This thread ensures that events are delivered in
the context of the thread that created the Control, in order to adhere to the
Apartment Threading model.
• Fire: The combination of enqueuing and delivering an event. Sometimes, the
term is used more loosely and may only refer to one of these steps. The reader
should differentiate these cases by context.
Rules on the management of the queue of events are:

• The Control may only enqueue new events while the device is enabled.
• The Control may deliver enqueued events until the application calls the
ReleaseDevice method (for exclusive-use devices) or the Close method (for
any device), at which time any remaining events are deleted.
• For input devices, the ClearInput method clears data and error events.
While within an event handler, the application may access properties and call
methods. However, the application must not call the ReleaseDevice or Close
methods from an event handler, since ReleaseDevice may shut down event
handling (possibly including a thread that caused the event to be delivered) and
Close must shut down event handling before returning.

OPOS Event Registration Sequence Diagram A-13
OPOS Event Registration Sequence Diagram Added in Release 1.7

The following sequence diagram depicts the typical OPOS event registration
process.
NOTE: this diagram shows the typical event registration process for a Service Object in OPOS. Various details are omitted on
purpose to make the diagram clearer. Also, DevCat == POSPrinter, CashDrawer, ... and other UnifiedPOS device categories.
:ClientApp :<DevCat> :<OPOSEvent> :<DevCat>Service
create :<DevCat> Control

Depending on the We are assuming that
development environment, the OpenService() call
registering for events is is successful and that
done implicitly or the control is bound
register to receive events explicitly. with its service
Open(logicalName)
OpenService(DeviceClass, logicalName, pDispatch)
Some devices (exclusive-use) need to be

claimed before being enabled (this is not
shown here).
SetDeviceEnabled(TRUE) SetPropertyNumber(PIDX_DeviceEnabled, TRUE)
new
For DataEvent you also need the
DataEventEnabled property to be true
deliver :<OPOSEvent> to control [DeviceEnabled == TRUE &&

FreezeEvents == FALSE] through SOXxxx call
deliver :<OPOSEvent> to
:ClientApp
SetDeviceEnabled(FALSE)
SetPropertyNumber(PIDX_DeviceEnabled, FALSE)
Close() Close()
No more events will be delivered by the

Service Object. For sharable devices this
unregister for events is true after Disable, for exclusive-use
devices, this is true after Release. This
diagram depicts a sharable device.

Input Model Updated in Release 1.12

The OLE for Retail POS input model supports event-driven input. Event-driven
input allows input data to be received after DeviceEnabled is set to TRUE.
Received data is enqueued as a DataEvent, which is delivered to the application
when preconditions are correct. If the AutoDisable property is TRUE when data
is received, then the control will automatically disable itself, setting
DeviceEnabled to FALSE. This will inhibit the Control from enqueuing further
input and, when possible, physically disable the device.
When the application is ready to receive input from the device, it sets the
DataEventEnabled property to TRUE. Then, when input is received (usually as
a result of a hardware interrupt), the Control enqueues and delivers a DataEvent.
(If input has already been enqueued, the DataEvent will be delivered.) This event
may include input status information through a numeric parameter. The Control
places the input data plus other information as needed into device specific-
specific properties just before the event is fired.
Just before delivering this event, the Control disables further data events by
setting the DataEventEnabled property to FALSE. This causes subsequent input
data to be enqueued by the Control while the application processes the current
input and associated properties. When the application has finished the current
input and is ready for more data, it re-enables events by setting
DataEventEnabled to TRUE.
If the input device is an exclusive-use device, the application must both claim and
enable the device before the device begins reading input.
For sharable input devices, one or more applications must open and enable the
device before the device begins reading input. An application must call the
ClaimDevice method to request exclusive access to the device before the Control
will send data to it using the DataEvent. If event-driven input is received, but no
application has claimed the device, then the input is buffered until an application
claims the device (and the DataEventEnabled property is TRUE). This behavior
allows orderly sharing of the device between multiple applications, effectively
passing the input focus between them.
If the Control encounters an error while gathering or processing event-driven
input, then the Control changes its state to Error, and enqueues one or two
ErrorEvents to alert the application of the error condition. This event (or events)
is not delivered until the DataEventEnabled property is TRUE, so that orderly
Unlike a DataEvent, the Control does not disable further DataEvents or input
ErrorEvents; it leaves the DataEventEnabled property value at TRUE. Note that
the application may set DataEventEnabled to FALSE within its event handler if

Input Model A-15
Error events are delivered with the following loci:

• InputWithData (OPOS_EL_INPUT_DATA) – Only enqueued if the error
occurred while one or more DataEvents are enqueued. It is enqueued ahead
of all DataEvents. (A typical implementation would place it at the head of the
event queue.) This event gives the application the ability to immediately clear
the input, or to optionally alert the user to the error and process the buffered
input.
The latter case may be useful with a Scanner Control: The user can be
immediately alerted to the error so that no further items are scanned until the
error is resolved. Any previously scanned items can then be successfully
processed before error recovery is performed.
• InputNoData (OPOS_EL_INPUT) – Delivered when an error has occurred
and there is no data available. (A typical implementation would place it at the
tail of the event queue.) If some input data was already enqueued when the
error occurred, then an ErrorEvent with the locus “InputWithData” was
enqueued and delivered first, and then this error event is delivered after all
DataEvents have been fired. (If an “InputWithData” event was delivered and
the application event handler responded with a “Clear”, then this
“InputNoData” event is not delivered.)
The Control exits the Error state when one of the following occurs:
• The application returns from the InputNoData ErrorEvent.
• The application returns from the InputWithData ErrorEvent with
OPOS_ER_CLEAR.
• The application calls the ClearInput method.
For some Controls, the Application must call a method to begin event driven
input. After the input is received by the Control, then typically no additional input
The DataCount property may be read to obtain the number of DataEvents
enqueued by the Control.
All input enqueued by a Control may be deleted by calling the ClearInput
method. ClearInput may be called after Open for sharable devices and after
ClaimDevice for exclusive-use devices.
Calling the ClearInputProperties method sets all data properties, that were
of device classes containing methods or properties that return input data directly.
Some device classes will define such methods and properties in order to operate
in a more intuitive or flexible manner. An example is the Keylock device. This
type of input is sometimes called “synchronous input.”

Output Model
The OLE for Retail POS output model consists of two output types: synchronous
and asynchronous. A device class may support one or both types, or neither type.
Synchronous Output
This type of output is preferred when device output can be performed quickly. Its
merit is simplicity.
The application calls a class-specific method to perform output. The Control does
not return until the output is completed.

The application calls a class-specific method to start the output. The Control
buffers the request in program memory, for delivery to the Physical Device as
soon as the Physical Device can receive and process it, sets the OutputID
property to an identifier for this request, and returns as soon as possible. When
the device completes the request successfully, OPOS fires an
OutputCompleteEvent. A parameter of this event contains the OutputID of the
completed request.
If an error occurs while performing an asynchronous request, an ErrorEvent is
fired. The application’s event handler can either retry the outstanding output or
clear it. The Control is in the Error state while the ErrorEvent is in progress.
(Note that if the condition causing the error was not corrected, then the Control
may immediately reenter the Error state and fire another ErrorEvent.)
Asynchronous output is performed on a first-in first-out basis.
All buffered output data, including all asynchronous output, may be deleted by
calling ClearOutput. OutputCompleteEvents will not be fired for cleared
output. This method also stops any output that may be in progress (when
possible).
to the application. If the response is OPOS_ER_CLEAR, then outstanding
asynchronous output is cleared. If the response is OPOS_ER_RETRY, then
output is retried; note that if several outputs were simultaneously in progress at
the time that the error was detected, then the Service may need to retry all of these
outputs.

Device Power Reporting Model A-17
Device Power Reporting Model

Added in OPOS Release 1.3, Updated in Release 1.8
Earlier versions of OPOS had no consistent method for reporting this
information. Note: This model is not intended to report PC or POS Terminal
power conditions (such as “on battery” and “battery low”). Reporting of these
conditions is now managed by the POSPower device category, see page 927.
Model
OPOS segments device power into three states:
• ONLINE: The device is powered on and ready for use. This is the
• OFF: The device is powered off or detached from the terminal. This is a “non-
• OFFLINE: The device is powered on but is either not ready or not able to
• OFF_OFFLINE: The device is either off or offline, and the Service Object
cannot distinguish these states.
________________________________________________________________
Note – Enabled/Disabled vs. Power States
These states are different and usually independent. OPOS defines “disabled” /
“enabled” as a logical state, whereas the power state is a physical state. A device
may be logically “enabled” but physically “offline”. It may also be logically
“disabled” but physically “online”. Regardless of the physical power state, OPOS
only reports the state while the device is enabled. (This restriction is necessary
because a Service Object typically can only communicate with the device while
enabled.)
If a device is “offline”, then a Service Object may choose to fail an attempt to
“enable” the device. However, once enabled, the Service Object may not disable a
device based on its power state.
________________________________________________________________

Properties
The OPOS device power reporting model adds the following common elements
across all device classes:
• CapPowerReporting property: Identifies the reporting capabilities of the
device. This property may be one of:
• OPOS_PR_NONE: The Service Object cannot determine the state of the
device. Therefore, no power reporting is possible.
• OPOS_PR_STANDARD: The Service Object can determine and report
two of the power states – OFF_OFFLINE (that is, off or offline) and
ONLINE.
• OPOS_PR_ADVANCED: The Service Object can determine and report
all three power states – ONLINE, OFFLINE, and OFF.
• PowerState property: Maintained by the Service Object at the current power
condition, if it can be determined. This property may be one of:
• OPOS_PS_UNKNOWN
• OPOS_PS_ONLINE
• OPOS_PS_OFF
• OPOS_PS_OFFLINE
• OPOS_PS_OFF_OFFLINE
• PowerNotify property: The Application may set this property to enable power
property may only be set before the device is enabled (that is, before
DeviceEnabled is set to TRUE). This restriction allows simpler
implementation of power notification with no adverse effects on the
application. The application is either prepared to receive notifications or does
not want them, and has no need to switch between these cases. This property
may be one of:
• OPOS_PN_DISABLED
• OPOS_PN_ENABLED

Power Reporting Requirements for DeviceEnabled A-19

CapPowerReporting is not OPOS_PR_NONE, and
PowerNotify is OPOS_PN_ENABLED:
• When the Control changes from DeviceEnabled FALSE to TRUE, then begin
• If the device is ONLINE, then:
PowerState is set to OPOS_PS_ONLINE.
A StatusUpdateEvent is fired with Status parameter set to
OPOS_SUE_POWER_ONLINE.
• If the device power state is OFF, OFFLINE, or OFF_OFFLINE, then the
Control may choose to fail the enable, setting ResultCode to
OPOS_E_NOHARDWARE or OPOS_E_OFFLINE.
the Control chooses to return success for the enable, then:
PowerState is set to OPOS_PS_OFF, OPOS_PS_OFFLINE, or
OPOS_PS_OFF_OFFLINE.
A StatusUpdateEvent is fired with Status parameter set to
OPOS_SUE_POWER_OFF, OPOS_SUE_POWER_OFFLINE,
or OPOS_SUE_POWER_OFF_OFFLINE.
• When the Control changes from DeviceEnabled TRUE to FALSE, then
OPOS assumes that the Control is no longer monitoring the power state.
Therefore:
PowerState is set to OPOS_PS_UNKNOWN.

Device Information Reporting Model Added in Release 1.8.

Hours Running, etc. See page 63 for examples of XML definitions of the device
when required. This is done by using the ClaimDevice method and by setting
DeviceEnabled to TRUE when access to a device is required and then setting
DeviceEnabled to FALSE and using the ReleaseDevice method when access to
the device is no longer needed. Coordination of device access via this mechanism
is the responsibility of the applications themselves.
device. When CapStatisticsReporting is FALSE, then no statistical data
TRUE, then some statistical data for the device is available.
CapStatisticsReporting is TRUE. When CapUpdateStatistics is FALSE,
then none of the statistical data can be reset/updated by the application.
Otherwise, when CapUpdateStatistics is TRUE, then (some of) the statistical
data can be reset/updated by the application.
• ResetStatistics method. Can only be called if both CapStatisticsReporting
and CapUpdateStatistics are TRUE. This method resets one, some, or all of
the resettable device statistics to zero.
• RetrieveStatistics method. Can only be called if CapStatisticsReporting is
TRUE. This method retrieves one, some, or all of the accumulated statistics
for the device.
• UpdateStatistics method. Can only be called if both CapStatisticsReporting
and CapUpdateStatistics are TRUE. This method updates one, some, or all
of the resettable device statistics to the supplied values.

Update Firmware Device Model A-21

by an OPOS control.
firmware updating.
device.
• A method, UpdateFirmware, to perform an asynchronous update of the
• A method, CompareFirmwareVersion, to compare the firmware file’s
device categories defined in UnifiedPOS. The means by which a Service actually
updates the firmware in the device is not covered by this document, only the
means by which the update firmware process is started and progress is reported.

OPOS Component Descriptions
The following sections are arranged as follows and provide detailed information
on how an Application is expected to interface with a device covered under
OPOS.
Section 1:
Describes the specific characteristics of the data types that OPOS uses as they
relate to the Windows OPOS implementation.
Section 2:
Provides interface descriptions for the properties, methods, and events specific to
OPOS. For thorough description of these, one should consult the applicable
chapters located in this document.
Section 3:
Details the OPOS use of the system registry specific to Windows.
Section 4:
Contains the list of the C++ OPOS application header files.
Section 5:
Provides some miscellaneous additional technical information to help the
Application Developer understand some of the finer details of a Windows OPOS
implementation.
Section 6:
Provides additional information on ClaimDevice and ReleaseDevice methods
which became necessary as a result of Microsoft’s ActiveX changes that affected
the Claim and Release method naming convention that was used in OPOS 1.4
and earlier editions.
Section 7:
Provides the Change History previously contained in the OPOS Application
Programmer’s Guide (OPOS APG).
Section 8:
Provides information previously contained in the OPOS Control Programmer’s
Guide (OPOS CPG). Targeted at system developers who intend to write an OPOS
Control.

Section 1: OPOS Data Types A-23
Section 1: OPOS Data Types Updated in Release 1.12

The parameter and return types specified in the OPOS descriptions are as follows:
Type Meaning
BOOL An integer with the legal values TRUE (non-zero) and
FALSE (zero).
COM IDL type: VARIANT_BOOL (short). Values
VARIANT_TRUE (-1) and VARIANT_FALSE (0).
VARIANT type: VT_BOOL
BOOL* A pointer to a mutable integer with the legal values
TRUE (non-zero) and FALSE (zero).
COM IDL type: VARIANT_BOOL* (short*). Values
VARIANT_TRUE (-1) and VARIANT_FALSE (0).
VARIANT type: VT_BYREF | VT_BOOL
BSTR A character string. Consists of a length component
followed by the string and a terminating NUL (0)
character. See “System Strings (BSTR)” (page A-78)
for more information.
COM IDL type: BSTR (unsigned short*)
VARIANT type: VT_BSTR
BSTR* A pointer to a mutable character string.
COM IDL type: BSTR* (unsigned short**)
VARIANT type: VT_BYREF | VT_BSTR
LONG An integer with a size of 32 bits.
COM IDL type: long
VARIANT type: VT_I4
LONG* A pointer to a mutable 32-bit integer.
COM IDL type: long*
VARIANT type: VT_BYREF | VT_I4
Supported in Release 1.3 and later
CURRENCY A monetary value. An integer with a size of 64 bits. The
value assumes four decimal places. For example, if the
integer is “1234567”, then the value is “123.4567”.
COM IDL type: CURRENCY (union tagCY)
“union tagCY” is declared as
{
struct { long Hi; long Lo; };
__int64 int64;
};
VARIANT type: VT_CY

CURRENCY* A pointer to a mutable CURRENCY value.

COM IDL type: CURRENCY* (union tagCY*)
VARIANT type: VT_BYREF | VT_CY
Supported in Release 1.10 and later
SAFEARRAY of BSTR An array of binary data; may be used as an in
parameter.
COM IDL type: VARIANT
VARIANT type: VT_BSTR | VT_ARRAY or
VT_BYREF | VT_BSTR | VT_ARRAY
SAFEARRAY of LONG An array of 32-bit integers; may be used as an in
parameter.
VARIANT type: VT_I4 | VT_ARRAY or
VT_BYREF | VT_I4 | VT_ARRAY
SAFEARRAY* of LONG A pointer to a mutable array of 32-bit integers; may
be used as an out or in-out parameter.
VARIANT type: VT_EMPTY or
VT_I4 | VT_ARRAY or
VT_BYREF | VT_I4 | VT_ARRAY
Notice that the IDL type for all arrays is “VARIANT”, and that the VARIANT
type for all arrays includes “VT_ARRAY”. In addition, the following
requirements are imposed on the VARIANT type:
• Immutable (in) arrays must include the type of the data (VT_BSTR or VT_I4)
plus optional by-reference (VT_BYREF).
Before calling the Service Object, the Common Control Objects (a) ensure
that the VARIANT type is valid, and (b) convert by-reference arrays into by-
value arrays.
• Mutable (out or in-out) arrays must either have the type (a) VT_EMPTY or
(b) the type of the data (VT_BSTR or VT_I4) plus optional by-reference
(VT_BYREF).
Before calling the Service Object, the Common Control Objects (a) ensure
that the VARIANT type is valid, and (b) convert by-reference arrays into by-
value arrays.
After calling the Service Object, the Common Control Objects try to update
the VARIANT with the value set by the Service Object, converting by-
reference arrays into by-value arrays. (The current CCOs do not check the
type of the returned value. The Service Object must ensure that it is either
empty or an array of the proper type.)

Section 2: OPOS Interface Descriptions A-25
Section 2: OPOS Interface Descriptions
Information in this section further defines the requirements of the UnifiedPOS for
a Windows OS environment implementation. The common Properties, Methods,
and Events are included to help transition from the UML given in Chapter 1 to the
specifics for the Windows environment.
Next, tables are included that outline the specific programmatic examples for
each of the device classifications and reference back to the UML for the
respective devices.
The examples have been provided in Visual Basic and Visual C++ as the
Windows OS reference programming platforms. Other programming languages
written for the Windows OS environment may be supported as long as they
comply to the Microsoft OLE 2.x.

OPOS Common Properties, Methods, and Events
Common Properties Updated in Release 1.9

OPOS implementation specific definitions of the Common Properties.

Usage
Notes
AutoDisable Boolean { read-write } 1.2 1
BinaryConversion Long { read-write } 1.2
CapCompareFirmwareVersion Boolean { read-only } 1.9
CapPowerReporting Long { read-only } 1.3
CapStatisticsReporting Boolean { read-only } 1.8
CapUpdateFirmware Boolean { read-only } 1.9
CapUpdateStatistics Boolean { read-only } 1.8
CheckHealthText String { read-only } 1.0
Claimed Boolean { read-only } 1.0
DataCount Long { read-only } 1.2 1
DataEventEnabled Boolean { read-write } 1.0 1
DeviceEnabled: Boolean { read-write } 1.0
FreezeEvents Boolean { read-write } 1.0
OpenResult Long { read-only } 1.5
OutputID Long { read-only } 1.0 2
PowerNotify Long { read-write } 1.3
PowerState Long { read-only } 1.3
ResultCode Long { read-only } 1.0
ResultCodeExtended Long { read-only } 1.0
State Long { read-only } 1.0
ControlObjectDescription String { read-only } 1.0

ControlObjectVersion Long { read-only } 1.0
ServiceObjectDescription String { read-only } 1.0
ServiceObjectVersion Long { read-only } 1.0
DeviceDescription String { read-only } 1.0
DeviceName String { read-only } 1.0
Usage Notes:

Common Methods A-27
Common Methods Updated in Release 1.10
OPOS implementation specific definitions of the Common Methods.

Name Version
LONG Open ( BSTR DeviceName ); 1.0
LONG Close ( ); 1.0
LONG ClaimDevicea ( LONG Timeout ); 1.0
LONG ReleaseDevicea ( ); 1.0
LONG CheckHealth ( LONG Level ); 1.0
LONG ClearInput ( ); 1.0
LONG ClearInputProperties ( ); 1.10
LONG ClearOutput ( ); 1.0
LONG DirectIO ( LONG Command, LONG* pData, BSTR* pString ); 1.0
LONG CompareFirmwareVersion ( BSTR FirmwareFileName, LONG* pResult ); 1.9
LONG ResetStatistics ( BSTR StatisticsBuffer ); 1.8
LONG RetrieveStatistics ( BSTR* pStatisticsBuffer ); 1.8
LONG UpdateFirmware ( BSTR FirmwareFileName ); 1.9
LONG UpdateStatistics ( BSTR StatisticsBuffer ); 1.8
a. Note: In the OPOS environment starting with Release 1.5, the Claim and Release
methods are also defined as ClaimDevice and ReleaseDevice due to Release
being a reserved method name used by Microsoft’s Component Object Model
(COM).

OPOS Programmatic Names Updated in Release 1.12

OPOS implementation specific definitions of the POS Device Categories’
programmatic IDs.
UnifiedPOS Device
OPOS Programmatic IDs
Programmatic Names
Belt OPOS.Belt
BillAcceptor OPOS.BillAcceptor
BillDispenser OPOS.BillDispenser
Biometrics OPOS.Biometrics
BumpBar OPOS.BumpBar
CashChanger OPOS.CashChanger
CashDrawer OPOS.CashDrawer
CAT OPOS.CAT
CheckScanner OPOS.CheckScanner
CoinAcceptor OPOS.CoinAcceptor
CoinDispenser OPOS.CoinDispenser
ElectronicJournal OPOS.ElectronicJournal
ElectronicValueRW OPOS.ElectronicValueRW
FiscalPrinter OPOS.FiscalPrinter
Gate OPOS.Gate
HardTotals OPOS.HardTotals
ImageScanner OPOS.ImageScanner
ItemDispenser OPOS.ItemDispenser
Keylock OPOS.Keylock
Lights OPOS.Lights
LineDisplay OPOS.LineDisplay
MICR OPOS.MICR
MotionSensor OPOS.MotionSensor
MSR OPOS.MSR
PINPad OPOS.PINPad
PointCardRW OPOS.PointCardRW
POSKeyboard OPOS.POSKeyboard
POSPower OPOS.POSPower
POSPrinter OPOS.POSPrinter
RemoteOrderDisplay OPOS.RemoteOrderDisplay
RFIDScanner OPOS.RFIDScanner
Scale OPOS.Scale
Scanner OPOS.Scanner
SignatureCapture OPOS.SignatureCapture
SmartCardRW OPOS.SmartCardRW
ToneIndicator OPOS.ToneIndicator

Properties A-29
Properties
AutoDisable Property R/W Added in Release 1.2
Syntax BOOL AutoDisable;
Remarks This property applies to event-driven input devices. It provides the application
with an additional option for controlling the receipt of input data. If an application
wants to receive and process only one input, or only one input at a time, then this
property may be set to TRUE.
When TRUE, then as soon as the Service Object receives and enqueues data to be
fired as a DataEvent, then it sets DeviceEnabled = FALSE. Before any
additional input can be received, the application must set DeviceEnabled =
TRUE.
When FALSE, the Service Object does not automatically disable the device when
data is received. This is the behavior of OPOS controls prior to Release 1.2.
This property is initialized to FALSE by the Open method.
Return When this property is set, the following value is placed in the ResultCode
property:
Value Meaning
OPOS_SUCCESS The property was set successfully.
BinaryConversion Property R/W Updated in Release 1.12

Syntax LONG BinaryConversion;
Remarks OPOS passes multi-character input and output using BStrings. BStrings may be
safely used for text data. As the BStrings are passed between the application and
the OPOS Control, OLE may perform language-specific translations to or from
Unicode.
When BStrings are used to pass binary data, then these translations may alter the
data such that the data byte in a BString character at the application does not
match the corresponding byte at the Control. This mismatch is more likely when
BString pointers are used, since the Unicode characters are presented to the
application and/or Control, and a language difference between them may cause
misinterpretation. (This was first reported with Japanese, which uses the MBCS
Code Page 932, but can occur with other languages, also.)
Characters between 0x00 and 0x7F may be sent without fear of language-specific
translation. Only characters between 0x80 and 0xFF sometimes cause incorrect
translations.
This document specifies those properties and method parameters that are affected
by BinaryConversion in the individual property and method descriptions. The
following line is added to their description:
“In the OPOS environment, the format of this data depends upon the value of the
BinaryConversion property. See BinaryConversion property on page A-29.”
The following table defines the affected device categories and affected Properties
and Methods.

Device Category Property/Method/Event Name Reference Page

Common PME DirectIOEvent See page 105.
BIR See page 188.
RawSensorData See page 191.
BeginEnrollCapture (2 parameters) See page 195.
Identify (1 parameter) See page 196.
Biometrics
IdentifyMatch (2 parameters) See page 197.
ProcessPrematchData (3 parameters) See page 198.
Verify (3 parameters) See page 199.
VerifyMatch (4 parameters) See page 200.
CAT AdditionalSecurityInformation See page 292.
CheckScanner ImageData See page 344.
FiscalPrinter PrintNormal See page 552.
Read See page 642.
HardTotals
Write See page 646.
ImageScanner FrameData See page 663.
Keylock ElectronicKeyValue See page 693.
DefineGlyph See page 744.
LineDisplay DisplayText See page 748.
DisplayTextAt See page 750.
MSR WriteTracks See page 829.
PINPad ComputeMAC (2 parameters) See page 858.
PrintWrite See page 907.
PointCardRW
ValidateData See page 909.
PrintBarCode See page 1043.
PrintImmediate See page 1050.
PrintMemoryBitmap See page 1051.
POSPrinter PrintNormal See page 1054.
PrintTwoNormal (2 parameters) See page 1056.
SetLogo See page 1062.
ValidateData See page 1065.
RemoteOrderDisplay DisplayData See page 1103.
CurrentTagID See page 1131.
CurrentTagUserData See page 1131.
DisableTag (2 parameters) See page 1133.
LockTag (2 parameters) See page 1134.
RFIDScanner ReadTags (3 parameters) See page 1135.
StartReadTags (3 parameters) See page 1136.
StopReadTags See page 1137.
WriteTagData (3 parameters) See page 1138.
WriteTagID (3 parameters) See page 1139.
Scale DisplayText See page 1157.
ScanData See page 1170.
Scanner
ScanDataLabel See page 1171.
PointArray See page 1187.
SignatureCapture
RawData See page 1188.
The binary conversion values are:

Value Meaning
OPOS_BC_NONE Data is placed one byte per BString character, with no
conversion.
(This is the default, and is the behavior of OPOS
Service Objects prior to 1.2.)

Properties A-31
OPOS_BC_NIBBLE Each byte is converted into two characters.

(This option provides for the fastest conversion
between binary and ASCII characters.)
Each data byte is converted as follows:
First character = 0x30 + bits 7-4 of the data byte.
Second character = 0x30 + bits 3-0 of the data byte.
Example: Byte value 154 = 0x9A is converted into the
characters 0x39 0x3A (= the string “9:”). Note that this
conversion is not the more common hexadecimal
ASCII, which would have converted 154 to 0x39 0x41
(= the string “9A”).
OPOS_BC_DECIMAL Each byte is converted into three characters.
(This option provides for the easiest conversion
between binary and ASCII characters for Visual Basic
and similar languages.)
VAL( string ) may be used on each 3 characters to
convert from ASCII to binary.
RIGHT(“^^”+STR(byte), 3) may be used to produce 3
ASCII characters from each byte, where '^' represents
the space character.
Example 1: Byte value 154 = 0x9A becomes the
characters 0x31 0x35 0x34 ( = the string “154” ).
Example 2: Byte value 8 becomes the characters 0x30
0x30 0x38 ( = the string “008” ).
Requirements for a Service Object are:
(1) When the Service Object converts from ASCII to
binary, it must allow either leading spaces or ASCII
zeroes, since STR(byte) produces a leading space. (For
example, the application may pass “^^8^27”, where '^'
represents the space character, which will be interpreted
as the two bytes 8 (0x08) and 27 (0x1B).)
(2) When the Service Object converts from binary to
ASCII, is must always convert each byte into exactly
three ASCII decimal characters (range 0x30 to 0x39).
When BinaryConversion is on (that is, not OPOS_BC_NONE) and the property
or method parameter description specifies that BinaryConversion applies, then
the application has the following responsibilities:
• Before setting the property or passing the method parameter, convert the string
data into the format specified by the BinaryConversion value.
• After getting the property or receiving the method parameter, convert the
string data from the format specified by the BinaryConversion value.
To better understand the “direction” of the conversion, determine if the data flow
follows the Output Model or the Input Model. If the flow follows the Output
Model, then the application must adhere to the first responsibility listed above. If
the flow follows the Input Model, then the application must adhere to the second
responsibility listed above.
This property is initialized to OPOS_BC_NONE by the Open method.

Return When this property is set, one of the following values is placed in the ResultCode
property:
Value Meaning
OPOS_E_ILLEGAL An illegal value was specified.

Syntax BOOL CapCompareFirmwareVersion;
Remarks If TRUE, then the Service/device supports comparing the version of the firmware
in the physical device against that of a firmware file.
See Also CompareFirmwareVersion Method.
CapPowerReporting Property Added in Release 1.3

Syntax LONG CapPowerReporting;
Remarks Identifies the reporting capabilities of the device.
The power reporting values are:
Value Meaning
OPOS_PR_NONE The Service Object cannot determine the state of the
OPOS_PR_STANDARD
The Service Object can determine and report two of the
power states – OFF_OFFLINE (that is, off or offline)
and ONLINE.
OPOS_PR_ADVANCED
The Service Object can determine and report all three
power states – OFF, OFFLINE, and ONLINE.
This property is initialized by the Open method.
CapStatisticsReporting Property Added in Release 1.8
Syntax BOOL CapStatisticsReporting;

Remarks If TRUE, the device accumulates and can provide various statistics regarding
usage; otherwise no usage statistics are accumulated. The information
accumulated and reported is device specific, and is retrieved using the
RetrieveStatistics method.
See Also RetrieveStatistics Method.

Properties A-33

Syntax BOOL CapUpdateFirmware;
Remarks If TRUE, then the device’s firmware can be updated via the UpdateFirmware
method.
See Also UpdateFirmware Method.
CapUpdateStatistics Property Added in Release 1.8
Syntax BOOL CapUpdateStatistics;

Remarks If TRUE, the device statistics, or some of the statistics, can be reset to zero using
the ResetStatistics method, or updated using the UpdateStatistics method.
If CapStatisticsReporting is FALSE, then CapUpdateStatistics is also FALSE.
See Also CapStatisticsReporting Property, ResetStatistics Method, UpdateStatistics
Method.
Syntax BSTR CheckHealthText;
Remarks Holds the results of the most recent call to the CheckHealth method. The
Before the first CheckHealth method call, its value is uninitialized.
Claimed Property
Syntax BOOL Claimed;
Remarks If TRUE, the device is claimed for exclusive access.
If FALSE, the device is released for sharing with other applications.
methods and properties, and before it will fire events to the application.
The value of Claimed is initialized to FALSE by the Open method.

ControlObjectDescription Property
Syntax BSTR ControlObjectDescription;
Remarks String identifying the Control Object and the company that produced it.
The property identifies the Control Object. A sample returned string is:
“POS Printer OLE Control, (C) 1995 Epson”
ControlObjectVersion Property
Syntax LONG ControlObjectVersion;
Remarks Control Object version number.
This property holds the Control Object version number. Three version levels are
specified, as follows:
A change to the OPOS major version level for a device
class reflects significant interface enhancements, and
may remove support for obsolete interfaces from
A change to the OPOS minor version level for a device
class reflects minor interface enhancements, and must
provide a superset of previous interfaces at this major
version level.
Internal level provided by the Control Object developer.
Updated when corrections are made to the CO
implementation.
1002038
1, minor version 2, build 38 of the Control Object.

Properties A-35
Note:
A Control Object for a device class will operate with any Service Object for that
class, as long as its major version number matches the Service Object’s major
version number. If they match, but the Control Object’s minor version number is
greater than the Service Object’s minor version number, then the Control Object
may support some new methods or properties that are not supported by the
Service Object’s release.
The following rules apply to APIs supported by the Control Object’s release but
not supported by the Service Object’s older release:
• Reading an unsupported property: The Control Object returns the property’s
uninitialized value. (See “When Methods and Properties May Be Accessed”
on page A-5 for uninitialized property default values.)
• Writing an unsupported property: The Control Object returns, but must re-
member that an unsupported property write or method call occurred. Then, if
the application reads the ResultCode property, the Control Object must return
a value of OPOS_E_NOSERVICE (rather than reading the current Result-
Code from the Service Object). It must do this until the next property write or
method call, at which time ResultCode is set by that API.
• Calling an unsupported method: The Control Object returns a value of
OPOS_E_NOSERVICE, and must remember that an unsupported property
write or method call occurred. Then, if the application reads the ResultCode
property, the Control Object must return a value of OPOS_E_NOSERVICE
(rather than reading the current ResultCode from the Service Object). It must
do this until the next property write or method call, at which time ResultCode
is set by that API.
DataCount Property Added in Release 1.2

Syntax LONG DataCount;
Remarks Holds the number of enqueued DataEvents at the control.
The application may interrogate DataCount to determine whether additional
input is enqueued from a device, but has not yet been delivered because of other
This property is initialized to zero by the Open method.

DataEventEnabled Property R/W

Syntax BOOL DataEventEnabled;
Remarks When TRUE, a DataEvent will be delivered as soon as input data is enqueued. If
changed to TRUE and some input data is already queued, then a DataEvent is
delivered immediately. (Note that other, less likely, conditions may delay
“immediate” delivery: If FreezeEvents is TRUE or another event is already being
processed at the application, the DataEvent will remain enqueued at the Service
Object until the condition is corrected.)
When FALSE, input data is queued for later delivery to the application. Also, if
an input error occurs, the ErrorEvent is not delivered while DataEventEnabled
is FALSE.
property:
Value Meaning
DeviceDescription Property
Syntax BSTR DeviceDescription;
Remarks String identifying the device.
The property identifies the device and any pertinent information about it. A
sample returned string is:

Properties A-37
DeviceEnabled Property R/W

Syntax BOOL DeviceEnabled;
Remarks When TRUE, the device has been placed in an operational state. If changed to
TRUE, then the device is brought to an operational state.
When FALSE, the device has been disabled. If changed to FALSE, then the
device is physically disabled when possible, any subsequent input will be
discarded, and output operations are disallowed.
consistency, however, the application must set this property to TRUE before
using output devices.
Release 1.3 and later: The device’s power state may be reported while
DeviceEnabled is TRUE.
property:
Value Meaning
OPOS_E_NOTCLAIMED
An exclusive use device must be claimed before the
device may be enabled.
Other Values See ResultCode.
DeviceName Property
Syntax BSTR DeviceName;
Remarks Short string identifying the device.
The property identifies the device and any pertinent information about it. This is a
short version of DeviceDescription and should be limited to 30 characters.
DeviceName will typically be used to identify the device in an application
message box, where the full description is too verbose. A sample returned string
is:
“NCR 7192 Printer, Japanese”

FreezeEvents Property R/W Updated in Release 1.12

Syntax BOOL FreezeEvents;
Remarks When TRUE, the application has requested that the Control not deliver events.
Events will be held by the Control until events are unfrozen.
When FALSE, the application allows events to be delivered. If some events have
been held while events were frozen and all other conditions are correct for
delivering the events, then changing FreezeEvents to FALSE will cause these
events to be delivered.4
An application may choose to freeze events for a specific sequence of code where
interruption by an event is not desirable.
property:
Value Meaning
4. Firing of events can also be deferred by the containing application. A control container may
request controls to freeze event firing. For example, this feature is utilized by Visual Basic
when modal dialog boxes are active. Therefore, events are fired when both FreezeEvents is
FALSE and the container has not requested event freezing. Container-initiated event freezing
is not referenced elsewhere in this document, since an Application will seldom if ever notice it
and cannot directly control it.

Properties A-39
OpenResult Property Added in Release 1.5

Syntax LONG OpenResult;
Remarks Holds additional details about the most recent Open method.
The open result values are:
Value Meaning
OPOS_SUCCESS Successful open.
OPOS_OR_ALREADYOPEN
Control already open.
OPOS_OR_REGBADNAME
The registry does not contain a key for the specified
device name.
OPOS_OR_REGPROGID
Could not read the device name key's default value, or
could not convert the Programmatic ID it holds into a
valid Class ID.
OPOS_OR_CREATE Could not create a service object instance, or could not
get its IDispatch interface.
OPOS_OR_BADIF The service object does not support one or more of the
methods required by its release.
OPOS_OR_FAILEDOPEN
The service object returned a failure status from its
open call, but does not have a more specific failure
code.
OPOS_OR_BADVERSION
The service object major version number does not
match the control object major version number.
The following values can be returned by the Service
Object if it returns a failure status from its open call.
The Service Object can choose to return one of these, if
applicable, or define additional values. (See the Control
Programmer's Guide's GetOpenResult description for
details on how the Service Object returns these values.
If the Service Object does not implement
GetOpenResult, then OpenResult returns
OPOS_OR_FAILEDOPEN.)
OPOS_ORS_NOPORT The Service Object tried to access an I/O port (for
example, an RS232 port) during Open processing, but
the port that is configured for the DeviceName is
invalid or inaccessible.
As a general rule, an SO should refrain from accessing
the physical device until the DeviceEnabled property is
set to TRUE. But in some cases, it may require some
access at Open; for instance, to dynamically
determining the device type in order to set the
DeviceName and DeviceDescription properties.

OPOS_ORS_NOTSUPPORTED
The Service Object does not support the specified
device.
The SO has determined that it does not have the ability
to control the device it is opening. This determination
may be due to an inspection of the registry entries for
the device, or dynamic querying of the device during
open processing.
OPOS_ORS_CONFIG Configuration information error.
Usually this is due to incomplete configuration of the
registry, such that the SO does not have sufficient or
valid data to open the device.
OPOS_ORS_SPECIFIC Errors greater than this value are service object-
specific.
If the previous return values do not apply, then the SO
may define additional OpenResult values. These values
are Service Object-specific, but may be of value in
these cases:
1) The Application logs or reports this error during
debug and testing.
2) The Application adds SO-specific logic, to attempt to
report more error conditions or to recover from them.
OutputID Property
Syntax LONG OutputID;
When a method successfully initiates an asynchronous output, the Control assigns
an identifier to the request. When the output completes, the Control will fire an
OutputCompleteEvent passing this output ID as a parameter.
The output ID numbers are assigned by the Control and are guaranteed to be
unique among the set of outstanding asynchronous outputs. No other facts about
the ID should be assumed.

Properties A-41
PowerNotify Property R/W Added in Release 1.3

Syntax LONG PowerNotify;
Remarks Contains the type power notification selection made by the Application.
The power notification values are:
Value Meaning
OPOS_PN_DISABLED The Control will not provide any power notifications to
the application. No power notification
may not be set.
OPOS_PN_ENABLED The Control will fire power notification
beginning when DeviceEnabled is set to TRUE. The
level of functionality depends upon
CapPowerReporting.
DeviceEnabled is FALSE.
This property is initialized to OPOS_PN_DISABLED by the Open method. This
property:
Value Meaning
OPOS_E_ILLEGAL One of the following occurred:
• PowerNotify = OPOS_PN_ENABLED but
CapPowerReporting = OPOS_PR_NONE.
PowerState Property Added in Release 1.3

Syntax LONG PowerState;
Remarks Contains the current power condition, if it can be determined.
Value Meaning
OPOS_PS_UNKNOWN Cannot determine the device's power state, for one of
• CapPowerReporting = OPOS_PR_NONE.
Device does not support power reporting.
• PowerNotify = OPOS_PN_DISABLED. Power
notifications are disabled.
• DeviceEnabled = FALSE. Power state monitoring
does not occur until the device is enabled.

OPOS_PS_ONLINE The device is powered on and ready for use.

Can be returned if CapPowerReporting =
OPOS_PR_STANDARD or OPOS_PR_ADVANCED.
OPOS_PS_OFF The device is off or detached from the terminal.
Can only be returned if CapPowerReporting =
OPOS_PR_ADVANCED.
OPOS_PS_OFFLINE The device is powered on but is either not ready or not
able to respond to requests.
OPOS_PR_ADVANCED.
OPOS_PS_OFF_OFFLINE
The device is either off or offline.
OPOS_PR_STANDARD.
This property is initialized to OPOS_PS_UNKNOWN by the Open method.
When PowerNotify is set to enabled and DeviceEnabled is TRUE, then this
property is updated as the Service Object detects power condition changes.
ResultCode Property Updated in Release 1.11

Syntax LONG ResultCode;
Remarks This property is set by each method. It is also set when a writable property is set.
This property is always readable. Before the Open method is called, it returns the
value OPOS_E_CLOSED.
It is conceivable that more than one of the following result codes could be valid
for a particular failure. The order of error reporting precedence for such scenarios
is the following:
• OPOS_E_CLAIMED
• OPOS_E_NOTCLAIMED
• OPOS_E_DISABLED
The result code values are:
Value Meaning
OPOS_SUCCESS Successful operation.
OPOS_E_CLOSED Attempt was made to access a closed device.
OPOS_E_CLAIMED Attempt was made to access a device that is claimed by
another process. The other process must release the
device before this access may be made. For exclusive-
use devices, the application will also need to claim the
device before the access is legal.
OPOS_E_NOTCLAIMED
Attempt was made to access an exclusive-use device
action can be used.
If the device is already claimed by another process, then
the status OPOS_E_CLAIMED is returned instead.

Properties A-43
OPOS_E_NOSERVICE The Control cannot communicate with the Service

Object. Most likely, a setup or configuration error must
be corrected.
OPOS_E_DISABLED Cannot perform operation while device is disabled.
OPOS_E_ILLEGAL Attempt was made to perform an illegal or unsupported
operation with the device, or an invalid parameter value
was used.
OPOS_E_NOHARDWARE
The device is not connected to the system or is not
powered on.
OPOS_E_OFFLINE The device is off-line.
OPOS_E_NOEXIST The file name (or other specified value) does not exist.
OPOS_E_EXISTS The file name (or other specified value) already exists.
OPOS_E_FAILURE The device cannot perform the requested procedure,
even though the device is connected to the system,
powered on, and on-line.
OPOS_E_TIMEOUT The Service Object timed out waiting for a response
from the device, or the Control timed out waiting for a
response from the Service Object.
OPOS_E_BUSY The current Service Object state does not allow this
request. For example, if asynchronous output is in
progress, certain methods may not be allowed.
OPOS_E_EXTENDED A class-specific error condition occurred. The error
condition code is available in the
ResultCodeExtended property.
OPOS_E_DEPRECATED
The requested operation can not be performed since it
ResultCodeExtended Property
Syntax LONG ResultCodeExtended;
Remarks When the ResultCode is set to OPOS_E_EXTENDED, this property is set to a
class-specific value, and must match one of the values given in this document
under the appropriate device class section.
When the ResultCode is set to any other value, this property may be set by the
Service Object to any SO-specific value. These values are only meaningful if the
application adds Service Object-specific code to handle them.
ServiceObjectDescription Property
Syntax BSTR ServiceObjectDescription;
Remarks String identifying the Service Object supporting the device and the company that
produced it.
“TM-U950 Printer OPOS Service Driver, (C) 1995 Epson”

ServiceObjectVersion Property
Syntax LONG ServiceObjectVersion;
Remarks Service object version number.
This property holds the Service Object version number. Three version levels are
specified, as follows:
A change to the OPOS major version level for a device
class reflects significant interface enhancements, and
may remove support for obsolete interfaces from
A change to the OPOS minor version level for a device
class reflects minor interface enhancements, and must
provide a superset of previous interfaces at this major
version level.
Internal level provided by the Service Object developer.
Updated when corrections are made to the SO
implementation.
1002038
1, minor version 2, build 38 of the Service Object.
Note:
A Service Object for a device class will operate with any Control Object for that
class, as long as its major version number matches the Control Object’s major
version number. If they match, but the Service Object’s minor version number is
greater than the Control Object’s minor version number, then the Service Object
may support some methods or properties that cannot be accessed from the
Control Object’s release.
If the application requires such features, then it will need to be updated to use a
later version of the Control Object.

Properties A-45
State Property
Syntax LONG State;
Remarks Contains the current state of the Control.
Value Meaning
OPOS_S_CLOSED The Control is closed.
OPOS_S_IDLE The Control is in a good state and is not busy.
OPOS_S_BUSY The Control is in a good state and is busy performing
output.
OPOS_S_ERROR An error has been reported, and the application must
recover the Control to a good state before normal I/O
can resume.

Methods
CheckHealth Method
Syntax LONG CheckHealth (LONG Level);
The Level parameter indicates the type of health check to be performed on the
Value Meaning
OPOS_CH_INTERNAL
Perform a health check that does not physically change
extent possible.
OPOS_CH_EXTERNAL
Perform a more thorough test that may change the
printer.
OPOS_CH_INTERACTIVE
Perform an interactive test of the device. The
supporting Service Object will typically display a
modal dialog box to present test options and results.
Remarks Called to test the state of a device.
property.
The CheckHealth method is always synchronous.
Return One of the following values is returned by the method and also placed in the
ResultCode property.
Value Meaning
OPOS_SUCCESS Indicates that the health checking procedure was
initiated properly and, when possible to determine,
indicates that the device is healthy. However, the health
of many devices can only be determined by a visual
inspection of the test results.
OPOS_E_ILLEGAL The specified health check level is not supported by the
Service Object.
OPOS_E_BUSY Cannot perform while output is in progress.

Methods A-47
ClaimDevice Method Added in Release 1.5

Syntax LONG ClaimDevice (LONG Timeout);
The Timeout parameter gives the maximum number of milliseconds to wait for
exclusive access to be satisfied.
If zero, the method attempts to claim the device, then returns the appropriate
status immediately.
If OPOS_FOREVER (-1), the method waits as long as needed until exclusive
access is satisfied.
Remarks Call this method to request exclusive access to the device. Many devices require
an application to claim them before they can be used.
When successful, the Claimed property is changed to TRUE.
Release 1.0 – 1.4 In releases prior to 1.5, this method is named Claim.
Release 1.5 and later 5

ClaimDevice must be used by early-bound applications. For compatibility with
late-bound applications, the Control Object’s IDispatch interface supports both
ClaimDevice and Claim. It is recommended that applications written to the 1.5
specification use ClaimDevice, not Claim.
Early bound applications acquire Control Object calling details at development
time, including Class IDs, Interface IDs, and method, property, and event calling
details. They then can build in static sequences to call methods and properties and
receive events. Microsoft Visual C++ and Visual Basic plus most compiled
languages support early binding.
Late bound applications acquire calling details at run time. They then
dynamically build code sequences to call methods and properties plus receive
events. Scripting languages usually support late binding. Late binding can be
implemented with many compiled languages, too, but often require additional
programmer effort, especially to receive events.
ResultCode property:
Value Meaning
OPOS_SUCCESS Exclusive access has been granted. The Claimed
property is now TRUE.
Also returned if this application has already claimed the
device.
OPOS_E_ILLEGAL This device cannot be claimed for exclusive access, or
an invalid Timeout parameter was specified.
OPOS_E_TIMEOUT Another application has exclusive access to the device,
and did not relinquish control before Timeout
5.
For further details, see page A-81

ClearInput Method
Syntax LONG ClearInput ();
Remarks Called to clear all device input that has been buffered.
Any data events or input error events that were enqueued – usually waiting for
DataEventEnabled to be set to TRUE and FreezeEvents to be set to FALSE –
are also cleared.
Value Meaning
OPOS_SUCCESS Input has been cleared.
OPOS_E_CLAIMED The device is claimed by another process.
OPOS_E_NOTCLAIMED
The device must be claimed before this method can be
used.
ClearInputProperties Method Added in Release 1.10
Syntax LONG ClearInputProperties ();
Remarks Sets all data properties, that were populated as a result of firing a DataEvent or
ErrorEvent, back to their default values. This does not reset the DataCount or
State properties.
Value Meaning
OPOS_SUCCESS Properties have been rest.
OPOS_E_NOTCLAIMED
used.
ClearOutput Method Updated in Release 1.7
Syntax LONG ClearOutput ();
Remarks Called to clear all buffered output data, including all asynchronous output. Also,
when possible, halts outputs that are in progress.
Any output error events that were enqueued – usually waiting for FreezeEvents
to be set to FALSE – are also cleared.
Value Meaning
OPOS_SUCCESS Output has been cleared.
OPOS_E_NOTCLAIMED
used.

Methods A-49
Close Method
Syntax LONG Close ();
Remarks Called to release the device and its resources.
If the DeviceEnabled property is TRUE, then the device is first disabled.
If the Claimed property is TRUE, then exclusive access to the device is first
released.
Value Meaning
OPOS_SUCCESS Device has been disabled and closed.
CompareFirmwareVersion Method Added in Release 1.9

Syntax LONG CompareFirmwareVersion (BSTR FirmwareFileName, LONG*
pResult);
FirmwareFileName Specifies either the name of the file containing the
device.
pResult Location in which to return the result of the comparison.
operation.
The result of the comparison is returned in the pResult parameter and will be one
Value Meaning
OPOS_CFV_FIRMWARE_OLDER
OPOS_CFV_FIRMWARE_SAME
Indicates that the versions of all of the firmware
OPOS_CFV_FIRMWARE_NEWER

OPOS_CFV_FIRMWARE_DIFFERENT
determined, or
OPOS_CFV_FIRMWARE_UNKNOWN
possible reason for this result could be an
attempt to compare Japanese and US versions
of firmware.
If the FirmwareFileName parameter specifies a file list, all of the component
modification to the firmware list file
Value Meaning
OPOS_SUCCESS Compare firmware successful.
OPOS_E_ILLEGAL CapCompareFirmwareVersion is false.
OPOS_E_NOEXIST The file specified by FirmwareFileName does not exist
or, if FirmwareFileName specifies a file list, one or
more of the component firmware files are missing.
OPOS_E_EXTENDED ResultCodeExtended = OPOS_EFIRMWARE_BAD_FILE:

Methods A-51
DirectIO Method
Syntax LONG DirectIO (LONG Command, LONG* pData, BSTR* pString);
Command Command number. Specific values assigned by the
Service Object.
pData Pointer to additional numeric data. Specific values vary
by Command and Service Object.
pString Pointer to additional string data. Specific values vary by
Command and Service Object.
The format of this data depends upon the value of the
BinaryConversion property. See page A-29.
Remarks Call to communicate directly with the Service Object.
This method provides a means for a Service Object to provide functionality to the
application that is not otherwise supported by the standard Control Object for its
device class. Depending upon the Service Object’s definition of the command,
this method may be asynchronous or synchronous.
Use of DirectIO will make an application non-portable. The application may,
however, maintain portability by performing DirectIO calls within conditional
code. This code may be based upon the value of the ServiceObjectDescription,
DeviceDescription, or DeviceName property.
Value Meaning
OPOS_SUCCESS Direct I/O successful.
Open Method
Syntax LONG Open (BSTR DeviceName);
The DeviceName parameter specifies the device name to open.
Remarks Call to open a device for subsequent I/O.
The device name specifies which of one or more devices supported by this
Control Object should be used. The DeviceName must exist in the system registry
for this device class. The relationship between the device name and physical
devices is determined by entries within the operating system registry; these
entries are maintained by a setup or configuration utility.
When the Open method is successful, it sets the properties Claimed,
DeviceEnabled, DataEventEnabled, and FreezeEvents, as well as descriptions
and version numbers of the OPOS software layers. Additional class-specific
properties may also be initialized.
The value of the OpenResult property is set by the Open method.

Return One of the following values is returned by the method:

Value Meaning
OPOS_SUCCESS Open successful.
OPOS_E_ILLEGAL The Control is already open.
OPOS_E_NOEXIST The specified DeviceName was not found.
OPOS_E_NOSERVICE Could not establish a connection to the corresponding
Service Object.
Note:
The value of the ResultCode property after calling the Open method may not be
the same as the Open method return value for the following two cases:
• The Control was closed and the Open method failed: The ResultCode property
will continue to return OPOS_E_CLOSED.
• The Control was already opened: The Open method will return
OPOS_E_ILLEGAL, but the ResultCode property may continue to return the
value it held before the Open method.
ReleaseDevice Method Added in Release 1.5

Syntax LONG ReleaseDevice ();
Remarks Call this method to release exclusive access to the device.
If the DeviceEnabled property is TRUE, and the device is an exclusive-use
device, then the device is first disabled. (ReleaseDevice does not change the
device enabled state of sharable devices.)
Release 1.0 – 1.4
In releases prior to 1.5, this method is named Release.
Release 1.5 and later 6

ReleaseDevice must be used by early-bound applications. For compatibility with
late-bound applications, the Control Object’s IDispatch interface supports both
ReleaseDevice and Release. It is recommended that applications written to the
1.5 specification use ReleaseDevice, not Release.
Early bound applications acquire Control Object calling details at development
time, including Class IDs, Interface IDs, and method, property, and event calling
details. They then can build in static sequences to call methods and properties and
receive events. Microsoft Visual C++ and Visual Basic plus most compiled
languages support early binding.
Late bound applications acquire calling details at run time. They then
dynamically build code sequences to call methods and properties plus receive
events. Scripting languages usually support late binding. Late binding can be
implemented with many compiled languages, too, but often require additional
programmer effort, especially to receive events.
6.
For further details, see page A-81

Methods A-53
Value Meaning
OPOS_SUCCESS Exclusive access has been released. The Claimed
property is now FALSE.
OPOS_E_ILLEGAL The application does not have exclusive access to the
device.
ResetStatistics Method Added in Release 1.8
Syntax LONG ResetStatistics ( BSTR StatisticsBuffer );
StatisticsBuffer The data buffer defining the statistics that are to be reset.
Remarks Resets the defined resettable statistics in a device.
Both CapStatisticsReporting and CapUpdateStatistics must be TRUE in order
to successfully use this method.
Value Meaning
OPOS_SUCCESS The statistics have been reset.
OPOS_E_ILLEGAL CapStatisticsReporting or CapUpdateStatistics is
FALSE, or the named statistic is not defined/resettable.
RetrieveStatistics Method Added in Release 1.8

Syntax LONG RetrieveStatistics ( BSTR* pStatisticsBuffer );
pStatisticsBuffer The data buffer defining the statistics to be retrieved and
Remarks Retrieves the statistics from a device.
CapStatisticsReporting must be TRUE in order to successfully use this method.

All calls to RetrieveStatistics will return the following XML as a minimum:

<Event>
<Parameter>
<Value>1234</Value>
</Parameter>
</Event>
<Equipment>
</Equipment>
</UPOSStat>
<Parameter>
<Value></Value>
</Parameter>
tag. e.g.,
<Value>42</Value>
Value Meaning
OPOS_SUCCESS The statistics have been retrieved and placed into the
supplied buffer.
OPOS_E_ILLEGAL CapStatisticsReporting is FALSE or the named
statistic is not defined.

Methods A-55
UpdateFirmware Method Added in Release 1.9

Syntax LONG UpdateFirmware ( BSTR FirmwareFileName );
FirmwareFileName Specifies either the name of the file containing the
contained or defined in the file specified by the FirmwareFileName parameter
same as the version of the firmware already in the device. If the
FirmwareFileName parameter specifies a file list, all of the component firmware
files should reside in the same directory as the firmware list file. This will allow
for distribution of the updated firmware without requiring a modification to the
firmware list file.
continue asynchronously. The Service should notify the application of the status
of the update firmware process by firing StatusUpdateEvents with values of
OPOS_SUE_UF_PROGRESS + an integer between 1 and 100 indicating the
completion percentage of the update firmware process. For application
convenience, the StatusUpdateEvent value OPOS_SUE_UF_COMPLETE is
defined to be the same value as OPOS_SUE_UF_PROGRESS + 100.
OPOS_SUE_UF_COMPLETE, which has the same value. These Service
requirements allow applications using this method to be designed to always expect
some level of progress notification.
Value Meaning
OPOS_UF_FAILED_DEV_OK The update firmware process failed but the
OPOS_UF_FAILED_DEV_UNRECOVERABLE

OPOS_UF_FAILED_DEV_NEEDS_FIRMWARE
OPOS_UF_FAILED_DEV_UNKNOWN
Value Meaning
OPOS_SUCCESS The device firmware has been updated.
OPOS_E_ILLEGAL CapUpdateFirmware is false.
OPOS_E_NOEXIST The file specified by FirmwareFileName does not exist
or, if FirmwareFileName specifies a file list, one or
more of the component firmware files are missing.
OPOS_E_EXTENDED ResultCodeExtended = OPOS_EFIRMWARE_BAD_FILE:

Methods A-57
UpdateStatistics Method Added in Release 1.8
Syntax LONG UpdateStatistics ( BSTR StatisticsBuffer );

StatisticsBuffer The data buffer defining the statistics with values that
are to be updated.
Remarks Updates the defined resettable statistics in a device.
Both CapStatisticsReporting and CapUpdateStatistics must be TRUE in order
to successfully use this method.
Value Meaning
OPOS_SUCCESS The statistics have been reset.
OPOS_E_ILLEGAL CapStatisticsReporting or CapUpdateStatistics is
FALSE, or the named statistic is not defined/updatable.

Events
DataEvent Event
Syntax void DataEvent (LONG Status);
The Status parameter contains the input status. Its value is Control-dependent,
and may describe the type or qualities of the input.
Remarks Fired to present input data from the device to the application. The
DataEventEnabled property is changed to FALSE, so that no further data events
will be generated until the application sets this property back to TRUE. The actual
input data is placed in one or more device-specific properties.
If DataEventEnabled is FALSE at the time that data is received, then the data is
queued in an internal OPOS buffer, the device-specific input data properties are
not updated, and the event is not delivered. (When this property is subsequently
changed back to TRUE, the event will be delivered immediately if input data is
queued and FreezeEvents is FALSE.)
DirectIOEvent Event
Syntax void DirectIOEvent (LONG EventNumber, LONG* pData, BSTR* pString);
EventNumber Event number. Specific values are assigned by the

Service Object.
by EventNumber and the Service Object.
EventNumber and the Service Object.
The format of this data depends upon the value of the
BinaryConversion property. See page A-29.
Remarks Fired by a Service Object to communicate directly with the application.
This event provides a means for a Service Object to provide events to the
application that are not otherwise supported by the Control Object.

Events A-59
ErrorEvent Event Updated in Release 1.12

Syntax void ErrorEvent (LONG ResultCode, LONG ResultCodeExtended,
LONG ErrorLocus, LONG* pErrorResponse);
ResultCode Result code causing the error event. See ResultCode
for values.
ResultCodeExtended Extended result code causing the error event. See
ResultCodeExtended for values.
ErrorLocus Location of the error. See values below.
pErrorResponse Pointer to the error event response. See values below.
The ErrorLocus parameter may be one of the following:
Value Meaning
OPOS_EL_OUTPUT Error occurred while processing asynchronous output.
OPOS_EL_INPUT Error occurred while gathering or processing event-
available.
OPOS_EL_INPUT_DATA
Error occurred while gathering or processing event-
available.
The contents at the location pointed to by the pErrorResponse parameter are
preset to a default value, based on the ErrorLocus. The application may change
them to one of the following:
Value Meaning
OPOS_ER_RETRY Typically valid only when locus is
OPOS_EL_OUTPUT.
May be valid when locus is OPOS_EL_INPUT.
Default when locus is OPOS_EL_OUTPUT.
OPOS_ER_CLEAR Clear all buffered output data (including all
state is exited.
Default when locus is OPOS_EL_INPUT.
OPOS_ER_CONTINUEINPUT
Use only when locus is OPOS_EL_INPUT_DATA.
again set to TRUE, then another ErrorEvent is
delivered with locus OPOS_EL_INPUT.
Default when locus is OPOS_EL_INPUT_DATA.

Remarks Fired when an error is detected and the Control’s State transitions into the error
state.
Input error events are not delivered until the DataEventEnabled property is
TRUE, so that proper application sequencing occurs.
OutputCompleteEvent Event
Syntax void OutputCompleteEvent (LONG OutputID);
The OutputID parameter indicates the ID number of the asynchronous output
request that is complete.
Remarks Fired when a previously started asynchronous output request completes
successfully.
StatusUpdateEvent Event Updated in Release 1.9
Syntax void StatusUpdateEvent (LONG Status);
The Status parameter is for device class-specific data, describing the type of
status change.
Remarks Fired when a Control needs to alert the application of a device status change.
Examples are a change in the cash drawer position (open vs. closed) or a change
in a POS printer sensor (form present vs. absent).
When a device is enabled, then the Control may fire initial StatusUpdateEvents
to inform the application of the device state. This behavior, however, is not
required.
All device classes may fire StatusUpdateEvents with at least the following
Status parameter values, if PowerNotify = OPOS_PN_ENABLED:
Value Meaning
OPOS_SUE_POWER_ONLINE
The device is powered on and ready for use.
Can be returned if CapPowerReporting =
OPOS_PR_STANDARD or OPOS_PR_ADVANCED.
OPOS_SUE_POWER_OFF
The device is off or detached from the terminal.
OPOS_PR_ADVANCED.
OPOS_SUE_POWER_OFFLINE
able to respond to requests.
OPOS_PR_ADVANCED.

Events A-61
OPOS_SUE_POWER_OFF_OFFLINE
The device is either off or offline.
OPOS_PR_STANDARD.
The common property PowerState is also maintained at the current power state
of the device.
process:
Value Meaning
OPOS_SUE_UF_PROGRESS + 1 to 100
OPOS_SUE_UF_COMPLETEThe update firmware process has completed
OPOS_SUE_UF_PROGRESS + 100.
OPOS_SUE_UF_COMPLETE_DEV_NOT_RESTORED
the application needs to Close the Service, then Open,
Claim, and enable again, and also restore all custom
OPOS_SUE_UF_FAILED_DEV_OK
operational.
OPOS_SUE_UF_FAILED_DEV_UNRECOVERABLE
state.
OPOS_SUE_UF_FAILED_DEV_NEEDS_FIRMWARE
OPOS_SUE_UF_FAILED_DEV_UNKNOWN
See Also CapPowerReporting Property, CapUpdateFirmware Property, PowerNotify
Property.

Peripheral Interfaces
Note:
The following are two examples that attempt to show how a Visual Basic
program and a VC++ program would use the commands in a typical MFC
implementation. Where possible the tables are arranged to show the sequence
of the commands for proper operation of the peripheral device.
The Cash Drawer and the MICR devices were chosen because they represent a
simple output device and a more complex input device. The other peripheral
devices would follow similar command usage and flow.

OPOS: Cash Drawer A-63
OPOS: Cash Drawer

Visual Basic Command Examples.
OPERATION T VISUAL BASIC SAMPLE R W A R R R Ref

Y E R R T C C Page
P A I G N E
E D T S V
E
Initializing Properties, Methods, and Events
Open * M lResult = CashDrawer.Open(“Standard”) 1 LONG 96

• • • •
A-47
ClaimDevice * M lResult = CashDrawer.ClaimDevice(“1000”)
• • 1 LONG
• •
82
Claimed P bResult = CashDrawer.Claimed
• BOOL
DeviceEnabled * P CashDrawer.DeviceEnabled = True 1 - 84

•
84
DeviceEnabled P bResult = CashDrawer.DeviceEnabled
• BOOL
• •
94
DirectIO M lResult= CashDrawer.DirectIO(0,lval,”[[“)
• • 3 LONG
• •
91
CheckHealth M lResult = CashDrawer.CheckHealth(OPOS_CH_INTERNAL)
• • 1 LONG
• •
DirectIOEvent E Private Sub CashDrawer_DirectIOEvent(ByVal EventNumber 3 CMF 105
As Long, pData As Long, pString As String)
Capabilities, Assignments and Descriptions Properties, Methods, and Events
StatusUpdateEvent E Private Sub CashDrawer_StatusUpdateEvent(ByVal Status As 1 CMF 108

Long)
A-29
BinaryConversion P CashDrawer.BinaryConversion = OPOS_BC_DECIMAL
• 1 -
• •
BinaryConversion P lResult = CashDrawer.BinaryConversion LONG A-29

•
80
CapPowerReporting P lResult = CashDrawer.CapPowerReporting
• LONG
81
CheckHealthText P sResult = CashDrawer.CheckHealthText
• BSTR
FreezeEvents P CashDrawer.FreezeEvents = True 1 - 86

• • •
86
FreezeEvents P bResult = CashDrawer.FreezeEvents
• BOOL
87
PowerNotify P CashDrawer.PowerNotify = OPOS_PN_ENABLED
• 1 -
• •
87
PowerNotify P lResult = CashDrawer.PowerNotify
• LONG
88
PowerState P lResult = CashDrawer.PowerState
• LONG


Y E R R T C C Page
P A I G N E
E D T S V
E
A-42
ResultCode P lResult = CashDrawer.ResultCode
• LONG
ResultCodeExtended P lResult = CashDrawer.ResultCodeExtended LONG A-43

•
90
State P lResult = CashDrawer.State
• LONG
83
ControlObject P sResult = CashDrawer.ControlObjectDescription
• BSTR
Description
83
ControlObject P lResult = CashDrawer.ControlObjectVersion
• LONG
Version
84
ServiceObject P sResult = CashDrawer.ServiceObjectDescription
• BSTR
Description
85
ServiceObject P lResult = CashDrawer.ServiceObjectVersion
• LONG
Version
A-36
DeviceDescription P sResult = CashDrawer.DeviceDescription
• BSTR
A-37
DeviceName P sResult = CashDrawer.DeviceName
• BSTR
Cash Drawer Operations Properties and Methods
271
CapStatus P bResult = CashDrawer.CapStatus
• BOOL
271
CapStatusMultiDrawerDetect P bResult = CashDrawer.CapStatusMultiDrawerDetect
• BOOL
272
DrawerOpened P bResult = CashDrawer.DrawerOpened
• BOOL
273
OpenDrawer * M lResult = CashDrawer.OpenDrawer
• • LONG
• •
273
WaitForDrawerClose M lResult = CashDrawer.WaitForDrawerClose(2500, 1000, 10, 5)
• • 4 LONG
• •
Terminating Methods
A-52
ReleaseDevice M lResult = CashDrawer.ReleaseDevice
• • LONG
• •
93
Close * M lResult = CashDrawer.Close
• • LONG
• •
Notes:
* Required for basic Cash Drawer operations
Legends:
TYPE = (P)roperty, (M)ethod, or (E)vent
ARGS = Number of Arguments Expected
RTNV = Return Value
‘CMF’ = Class Member Function
RC = Result Code
RCE = Result Code Extended
Ref Page = Page Number of UnifiedPOS Reference Description

Visual C++ Command Examples. A-65
Visual C++ Command Examples.
OPERATION T VISUAL C++ SAMPLE R W A R R R Ref

Y E R R T C C Page
P A I G N E
E D T S V
E
96
Open * M lResult = m_CashDrawer.Open(“Standard”);
• • 1 LONG
• •
A-47
ClaimDevice * M lResult = m_CashDrawer.ClaimDevice(“1000”);
• • 1 LONG
• •
82
Claimed P bResult = m_CashDrawer.GetClaimed();
• BOOL
84
DeviceEnabled * P m_CashDrawer.SetDeviceEnabled(TRUE);
• 1 -
DeviceEnabled P bResult = m_CashDrawer.GetDeviceEnabled(); BOOL 84

• • •
94
DirectIO M lResult = m_CashDrawer.DirectIO(0,&lval,”[[“)
• • 3 LONG
• •
91
CheckHealth M lResult = m_CashDrawer.CheckHealth(OPOS_CH_INTERNAL);
• • 1 LONG
• •
DirectIOEvent E void COCashDrawerDlg::OnDirectIOEventCashDrawerctrl(long 3 CMF 105
EventNumber, long FAR* pData, BSTR FAR* pString)
StatusUpdateEvent E void COCashDrawerDlg::OnStatusUpdateEventCashDrawerctrl 1 CMF 108

(long Status)
A-29
BinaryConversion P m_CashDrawer.SetBinaryConversion(OPOS_BC_DECIMAL);
• 1 -
• •
A-29
BinaryConversion P lResult = m_CashDrawer.GetBinaryConversion();
• LONG
CapPowerReporting P lResult = m_CashDrawer.GetCapPowerReporting(); LONG 80

•
81
CheckHealthText P sResult = m_CashDrawer.GetCheckHealthText();
• BSTR
86
FreezeEvents P m_CashDrawer.SetFreezeEvents(TRUE);
• 1 -
• •
FreezeEvents P bResult = m_CashDrawer.GetFreezeEvents(); BOOL 86

•
87
PowerNotify P m_CashDrawer.SetPowerNotify(OPOS_PN_ENABLED);
• 1 -
• •
87
PowerNotify P lResult = m_CashDrawer.GetPowerNotify();
• LONG
88
PowerState P lResult = m_CashDrawer.GetPowerState();
• LONG
A-42
ResultCode P lResult = m_CashDrawer.GetResultCode();
• LONG
A-43
ResultCodeExtended P lResult = m_CashDrawer.GetResultCodeExtended();
• LONG


Y E R R T C C Page
P A I G N E
E D T S V
E
90
State P lResult = m_CashDrawer.GetState ();
• LONG
ControlObject P sResult = m_CashDrawer.GetControlObjectDescription(); BSTR 83

•
Description
83
ControlObject P lResult = m_CashDrawer.GetControlObjectVersion();
• LONG
Version
84
ServiceObject P sResult = m_CashDrawer.GetServiceObjectDescription();
• BSTR
Description
85
ServiceObject P lResult = m_CashDrawer.GetServiceObjectVersion();
• LONG
Version
89
DeviceDescription P sResult = m_CashDrawer.GetDeviceDescription();
• BSTR
89
DeviceName P sResult = m_CashDrawer.GetDeviceName();
• BSTR
Cash Drawer Operations Properties and Methods
271
CapStatus P bResult = m_CashDrawer.GetCapStatus();
• BOOL
271
CapStatusMultiDrawerDetect P bResult = m_CashDrawer.GetCapStatusMultiDrawerDetect();
• BOOL
272
DrawerOpened P bResult = m_CashDrawer.GetDrawerOpened();
• BOOL
273
OpenDrawer * M lResult = m_CashDrawer.OpenDrawer();
• • LONG
• •
273
WaitForDrawerClose M lResult = m_CashDrawer.WaitForDrawerClose(2500, 1000,
• • 4 LONG
• •
10, 5);
Terminating Methods
A-52
ReleaseDevice M lResult = m_CashDrawer.ReleaseDevice();
• • LONG
• •
93
Close * M lResult = m_CashDrawer.Close();
• • LONG
• •
Notes:
Legends:
RTNV = Return Value
RC = Result Code

OPOS: MICR A-67
OPOS: MICR
Visual Basic Command Examples.

Y E R R T C C Page
P A I G N E
E D T S V
E
96
Open * M lResult = Micr.Open(“M101”)
• • 1 LONG
• •
A-47
ClaimDevice * M lResult = Micr.ClaimDevice(“1000”)
• • 1 LONG
• •
82
Claimed P bResult = Micr.Claimed
• BOOL
84
DeviceEnabled * P Micr.DeviceEnabled = True
• 1 -
• •
DeviceEnabled P bResult = Micr.DeviceEnabled BOOL 84

•
80
AutoDisable P Micr.AutoDisable = True
• 1 -
• •
80
AutoDisable P bResult = Micr.AutoDisable
• 1 BOOL
94
DirectIO M lResult= Micr.DirectIO(0,lval,”0x1b“)
• • 3 LONG
• •
91
CheckHealth M lResult = Micr.CheckHealth(OPOS_CH_INTERNAL)
• • 1 LONG
• •
DirectIOEvent E Private Sub Micr_DirectIOEvent(ByVal EventNumber As Long, 3 CMF 105
pData As Long, pString As String)
ErrorEvent E Private Sub Micr_ErrorEvent(ByVal ResultCode As Long, ByVal 4 CMF 106

ResultCodeExtended As Long, ByVal ErrorLocus As Long,
pErrorResponse As Long)
StatusUpdateEvent E Private Sub Micr_StatusUpdateEvent(ByVal Status As Long) 1 CMF 108
A-29
BinaryConversion P Micr.BinaryConversion = OPOS_BC_DECIMAL
• 1 -
• •
A-29
BinaryConversion P lResult = Micr.BinaryConversion
• LONG
CapPowerReporting P lResult = Micr.CapPowerReporting LONG 80

•
81
CheckHealthText P sResult = Micr.CheckHealthText
• BSTR
82
DataCount P lResult = Micr.DataCount
• LONG
86
FreezeEvents P Micr.FreezeEvents = True
• 1 -
• •
86
FreezeEvents P bResult = Micr.FreezeEvents
• BOOL


Y E R R T C C Page
P A I G N E
E D T S V
E
87
PowerNotify P Micr.PowerNotify = OPOS_PN_ENABLED
• 1 -
• •
PowerNotify P lResult = Micr.PowerNotify LONG 87

•
88
PowerState P lResult = Micr.PowerState
• LONG
A-42
ResultCode P lResult = Micr.ResultCode
• LONG
ResultCodeExtended P lResult = Micr.ResultCodeExtended LONG A-43

•
90
State P lResult = Micr.State
• LONG
83
ControlObject P sResult = Micr.ControlObjectDescription
• BSTR
Description
83
ControlObject P lResult = Micr.ControlObjectVersion
• LONG
Version
ServiceObject P sResult = Micr.ServiceObjectDescription BSTR 84

•
Description
85
ServiceObject P lResult = Micr.ServiceObjectVersion
• LONG
Version
89
DeviceDescription P sResult = Micr.DeviceDescription
• BSTR
89
DeviceName P sResult = Micr.DeviceName
• BSTR
MICR Operations Properties, Methods, and Events
769
CapValidationDevice P bResult = Micr.CapValidationDevice
• BOOL
92
ClearInput M lResult = Micr.ClearInput
• • LONG
• •
DataEventEnabled * P Micr.DataEventEnabled = True 1 - 82

• • •
82
DataEventEnabled P bResult = Micr.DataEventEnabled
• BOOL
772
BeginInsertion * M lResult = Micr.BeginInsertion
• • LONG
• •
EndInsertion * M lResult = Micr.EndInsertion LONG 774

• • • •
DataEvent E Private Sub Micr_DataEvent(ByVal Status As Long) 1 CMF 104
773
BeginRemoval * M lResult = Micr.BeginRemoval
• • LONG
• •
775
EndRemoval * M lResult = Micr.EndRemoval
• • LONG
• •
771
RawData P sResult = Micr.RawData
• BSTR
768
AccountNumber P sResult = Micr.AccountNumber
• BSTR

Terminating Methods A-69

Y E R R T C C Page
P A I G N E
E D T S V
E
768
Amount P sResult = Micr.Amount
• BSTR
BankNumber P sResult = Micr.BankNumber BSTR 768

•
770
EPC P sResult = Micr.EPC
• BSTR
771
SerialNumber P sResult = Micr.SerialNumber
• BSTR
TransitNumber P sResult = Micr.TransitNumber BSTR 771

•
769
CheckType P lResult = Micr.CheckType
• LONG
770
CountryCode P lResult = Micr.CountryCode
• LONG
Terminating Methods
A-52
ReleaseDevice M lResult = Micr.ReleaseDevice
• • LONG
• •
93
Close * M lResult = Micr.Close
• • LONG
• •
Notes:
* Required for basic MICR operations
Legends:
RTNV = Return Value
RC = Result Code

Visual C++ Command Examples.

Y E R R T C C Page
P A I G N E
E D T S V
E
96
Open * M lResult = m_Micr.Open(“M101”);
• • 1 LONG
• •
A-47
ClaimDevice * M lResult = m_Micr.ClaimDevice(“1000”);
• • 1 LONG
• •
82
Claimed P bResult = m_Micr.GetClaimed();
• BOOL
DeviceEnabled * P m_Micr.SetDeviceEnabled(TRUE); 1 - 84
• • •
84
DeviceEnabled P bResult = m_Micr.GetDeviceEnabled();
• BOOL
80
AutoDisable P m_Micr.SetAutoDisable(TRUE);
• 1 -
• •
AutoDisable P bResult m_Micr.GetAutoDisable(); 1 BOOL 80

•
94
DirectIO M lResult = m_Micr.DirectIO(0,&lval,”0x1b“)
• • 3 LONG
• •
91
CheckHealth M lResult = m_Micr.CheckHealth(OPOS_CH_INTERNAL);
• • 1 LONG
• •
DirectIOEvent E void COMicrDlg::OnDirectIOEventMicrctrl(long EventNumber, 3 CMF 105
long FAR* pData, BSTR FAR* pString)
ErrorEvent E void COMicrDlg::OnErrorEventMicrctrl(long ResultCode, long 4 CMF 106

ResultCodeExtended, long ErrorLocus, long FAR*
pErrorResponse)
StatusUpdateEvent E void COMicrDlg::OnStatusUpdateEventMicrctrl 1 CMF 108

(long Status)
A-29
BinaryConversion P m_Micr.SetBinaryConversion(OPOS_BC_DECIMAL);
• 1 -
• •
A-29
BinaryConversion P lResult = m_Micr.GetBinaryConversion();
• LONG
80
CapPowerReporting P lResult = m_Micr.GetCapPowerReporting();
• LONG
CheckHealthText P sResult = m_Micr.GetCheckHealthText(); BSTR 81

•
82
DataCount P lResult = m_Micr.GetDataCount();
• LONG
86
FreezeEvents P m_Micr.SetFreezeEvents(TRUE);
• 1 -
• •
FreezeEvents P bResult = m_Micr.GetFreezeEvents(); BOOL 86

•

MICR Operations Properties, Methods, and Events A-71

Y E R R T C C Page
P A I G N E
E D T S V
E
87
PowerNotify P m_Micr.SetPowerNotify(OPOS_PN_ENABLED);
• 1 -
• •
PowerNotify P lResult = m_Micr.GetPowerNotify(); LONG 87

•
88
PowerState P lResult = m_Micr.GetPowerState();
• LONG
A-42
ResultCode P lResult = m_Micr.GetResultCode();
• LONG
ResultCodeExtended P lResult = m_Micr.GetResultCodeExtended(); LONG A-43

•
90
State P lResult = m_Micr.GetState();
• LONG
83
ControlObject P sResult = m_Micr.GetControlObjectDescription();
• BSTR
Description
83
ControlObject P lResult = m_Micr.GetControlObjectVersion();
• LONG
Version
ServiceObject P sResult = m_Micr.GetServiceObjectDescription(); BSTR 84

•
Description
85
ServiceObject P lResult = m_Micr.GetServiceObjectVersion();
• LONG
Version
89
DeviceDescription P sResult = m_Micr.GetDeviceDescription();
• BSTR
89
DeviceName P sResult = m_Micr.GetDeviceName();
• BSTR
769
CapValidationDevice P bResult = m_Micr.GetCapValidationDevice();
• BOOL
92
ClearInput M lResult = m_Micr.ClearInput();
• • LONG
• •
DataEventEnabled * P m_Micr.SetDataEventEnabled(TRUE); 1 - 82
• • •
82
DataEventEnabled P bResult = m_Micr.GetDataEventEnabled();
• BOOL
772
BeginInsertion * M lResult = m_Micr.BeginInsertion();
• • LONG
• •
EndInsertion * M lResult = m_Micr.EndInsertion(); LONG 774

• • • •
DataEvent E void COMicrDlg::OnDirectIOEventMicrctrl(long Status) 1 CMF 105
773
BeginRemoval * M lResult = m_Micr.BeginRemoval();
• • LONG
• •
775
EndRemoval * M lResult = m_Micr.EndRemoval();
• • LONG
• •
771
RawData P sResult = m_Micr.GetRawData();
• BSTR
768
AccountNumber P sResult = m_Micr.GetAccountNumber();
• BSTR


Y E R R T C C Page
P A I G N E
E D T S V
E
768
Amount P sResult = m_Micr.GetAmount();
• BSTR
BankNumber P sResult = m_Micr.GetBankNumber(); BSTR 768

•
770
EPC P sResult = m_Micr.GetEPC();
• BSTR
771
SerialNumber P sResult = m_Micr.GetSerialNumber();
• BSTR
TransitNumber P sResult = m_Micr.GetTransitNumber(); BSTR 771

•
769
CheckType P lResult = m_Micr.GetCheckType();
• LONG
770
CountryCode P lResult = m_Micr.GetCountryCode();
• LONG
Terminating Methods
A-52
ReleaseDevice M lResult = m_Micr.ReleaseDevice();
• • LONG
• •
93
Close * M lResult = m_Micr.Close();
• • LONG
• •
Notes:
Legends:
RTNV = Return Value
RC = Result Code

Section 3: OPOS Registry Usage A-73
Section 3: OPOS Registry Usage Updated in Release 1.12

OPOS Controls require some data in the system registry in order for the Control
Objects to locate the proper Service Object and initialize it for the device.
The registry is organized in a hierarchical structure, in which each level is named
a “key.” Each key may contain:
• Additional keys (sometimes called “subkeys”).
• Zero or more named “values.” A value is assigned “data” of type string,
binary, or double-word.
• One “default value” that may be assigned data of type string.
OPOS only defines string data.
Service Object Root Registry Key
All OPOS Service Object entries should be placed under the following main key:
HKEY_LOCAL_MACHINE\SOFTWARE\OLEforRetail\ServiceOPOS
The “HKEY_LOCAL_MACHINE\SOFTWARE” key is the recommended key
for software configuration local to the PC. The “OLEforRetail” key will group all
OLE for Retail related configuration information. The “ServiceOPOS” key
maintains configuration information for OPOS Service Objects.
Device Class Keys
Each class has an identifying Device Class subkey under the main OPOS key.
The following key names have been established:
Key Name Key Name

Belt Keylock
BillAcceptor Lights
BillDispenser LineDisplay
Biometrics MICR
BumpBar MotionSensor
CashChanger MSR
CashDrawer PINPad
CAT PointCardRW
CoinAcceptor POSKeyboard
CoinDispenser POSPower
CheckScanner POSPrinter
ElectronicJournal RemoteOrderDisplay
ElectronicValueRW RFIDScanner
FiscalPrinter Scale
Gate Scanner
HardTotals SignatureCapture
ImageScanner SmartCardRW
ItemDispenser ToneIndicator

Device Name Keys and Values

Each device within a class is assigned a Device Name subkey under the class’s
key. This should be performed by a Service Object installation procedure. This
Device Name key is passed to the Control Object’s Open method by the
application. The Device Name is not constrained, except that it must be unique
among the names under the device class.
The default value of the Device Name key is the programmatic ID7 of the Service
Object. This string is needed by the Control Object, so that the Service Object
may be loaded and the OLE Automation interfaces established between the CO
and the SO.
Value – Required Data

(Default) Service Object’s OLE Programmatic ID.
The device unit key’s values and their data describe the characteristics of the
actual device on the terminal or PC. The following values are strongly
recommended for use by installation and support personnel:
Value – Recommended Data

Service Filename of the Service Object.
Description String describing the Service Object.
String containing the Service Object version number.
Version General format is:
MajorVersion.MinorVersion.BuildVersion.
Other values may be defined as needed by the Service Object. Values might
contain information such as:
Communications Port
Baud Rate
Serial Line Characteristics
Interrupt Request (IRQ) Values
Input/Output (I/O) Ports
Logical Device Name Values

An application may open a Control by passing the Device Name key to the Open
method. In many cases, however, the application will want a level of isolation
where the application specifies a “Logical Device Name” that is translated into a
Device Name.
7.
A Programmatic ID, or “Prog ID”, is the name of a key that must appear in the “HKEY_CLASSES_ROOT” section of
the registry. This key must have a subkey named “CLSID”, which is the Class ID associated with the Prog ID. The
Class ID must be a key within the “HKEY_CLASSES_ROOT\CLSID” registry section. This key contains subkeys that
specify the OLE Automation Server type and that instruct OLE how to start the Server.

Section 3: OPOS Registry Usage A-75
A Logical Device Name is added to the registry as a value contained in the

Device Class key. The value name is set to the Logical Device Name, and its data
must match a Device Name key contained in the same Device Class.
The application integrator is responsible for adding Logical Device Names to the
registry. (They are not added by the Service Object install procedure.)
Service Provider Root Registry Key

The SO service providers may need to store some information in the registry that
is common to some or all of its Service Objects. This data could include
installation directories, installation date, and de-install information. Service
provider information should be placed under the following main key:
HKEY_LOCAL_MACHINE\SOFTWARE\OLEforRetail\ServiceInfo
The subkeys under this key should be the names of service provider companies.
Subkeys and values within each service provider company subkey are provider-
dependent.
Example
In this example, keys are listed in italics. Comments appear as comment.
Two device classes are given: POSPrinter and CashDrawer.
The POSPrinter class contains two Device Names. Also, two Logical Device
Names are present, which point to the Device Names.
The CashDrawer class contains one Device Name and one Logical Device Name.
The Service Object has a unique ProgID but uses the same executable as one of
the printers. This Service Object could use the example value “Uses” to point to
some registry values of the printer device that can be used for the cash drawer
parameters.

\HKEY_LOCAL_MACHINE
⏐
⏐→\SOFTWARE
⏐ ⏐
⏐ ⏐→\OLEforRetail
↓ ⏐ ⏐
⏐ ⏐→\ServiceOPOS
↓ ⏐ ⏐
⏐ ⏐→\POSPrinter Device Class Key
⏐ ⏐ ⏐
⏐ ⏐ ⏐→\NCR7156=NCR.Ptr7156.1 Device Name Key
⏐ ⏐ ⏐ Service=C:\OPOS\NCR\PTR7156.DLL
⏐ ⏐ ⏐ Description=NCR 7156 Serial Printer
⏐ ⏐ ⏐ Version=1.0.12
⏐ ⏐ ⏐ ...Service Object-specific values. Might include:
⏐ ⏐ ⏐ Port=COM3
⏐ ⏐ ⏐ BaudRate=9600
⏐ ⏐ ⏐
⏐ ⏐ ⏐→\Epson950=Epson.PtrTMU950.1 Device Name Key
⏐ ⏐ ⏐ Service=TMU950.EXE
⏐ ⏐ ⏐ Description=Epson TM-U950 Printer
⏐ ⏐ ⏐ Version=1.0.7
⏐ ⏐ ⏐ ...Service Object-specific values could go here.
⏐ ⏐ ⏐
⏐ ⏐ ⏐→PSI.Ptr.1=NCR7156 Logical Device Name
⏐ ⏐ ⏐
⏐ ⏐ ⏐→PSI.Ptr.2=Epson950 Logical Device Name
⏐ ⏐
⏐ ⏐→\CashDrawer Device Class Key
⏐ ⏐
⏐ ⏐→\EpsonCash=Epson.CD.1 Device Name Key
⏐ ⏐ Service=TMU950.EXE
⏐ ⏐ Description=Epson Cash Drawer Kickout on TM-U950
⏐ ⏐ Version=1.0.7
⏐ ⏐ ...Service Object-specific values. Might include:
⏐ ⏐ Uses=POSPrinter\Epson950
⏐ ⏐
⏐ ⏐→PSI.CD.1=EpsonCash Logical Device Name
⏐
⏐→\ServiceInfo
⏐
⏐→ \EPSON
⏐ InstallDir=C:\OPOS\EPSON
⏐ InstallDate=1995/11/13
↓

Section 4: OPOS Application Header Files A-77
Section 4: OPOS Application Header Files Updated in Release 1.12

The header files are listed in alphabetical order. The mapping of device class
name to header file name is as follows:
General Opos.h
Belt OposBelt.h
Bill Acceptor OposBacc.h
Bill Dispenser OposBdsp.h
Biometrics OposBio.h
Bump Bar OposBb.h
Cash Changer OposChan.h
Cash Drawer OposCash.h
CAT OposCat.h
Check Scanner OposChk.h
Coin Acceptor OposCacc.h
Coin Dispenser OposCoin.h
Electronic Journal OposEj.h
Electronic Value R / W OposEvrw.h
Fiscal Printer OposFptr.h
Gate OposGate.h
Hard Totals OposTot.h
Image Scanner OposImg.h
Item Dispenser OposItem.h
Keylock OposLock.h
Lights OposLgt.h
Line Display OposDisp.h
MICR OposMicr.h
Motion Sensor OposMotion.h
MSR OposMsr.h
PIN Pad OposPpad.h
Point Card Reader Writer OposPcrw.h
POS Keyboard OposKbd.h
POS Power OposPwr.h
POS Printer OposPtr.h
Remote Order Display OposRod.h
RFID Scanner OposRfid.h
Scale OposScal.h
Scanner OposScan.h
Signature Capture OposSig.h
Smart Card Reader Writer OposScrw.h
Tone Indicator OposTone.h
The most up-to-date header files can be downloaded from the following web site:
http://monroecs.com/oposccos_current.htm

Section 5: Technical Details

System Strings (BSTR)
System String Characteristics
OPOS uses OLE system strings to pass and return data of variable length. System
strings are often referred to as BStrings, and are assigned the type BSTR by
Microsoft Visual C++.
A system string consists of a sequence of Unicode characters, which are each 16-
bits wide. Thus, they are also referred to as “wide” characters. The string is
followed by a NUL, or zero, character. The string is preceded by an unsigned long
count of the bytes in the string, not including the NUL. Divide this count by two
to obtain the number of characters in the string.
Most of the time, OPOS uses system strings to pass character data back and forth
among the Application, Control Object, and System Object. A system string
(BSTR) is used to pass string parameters by methods and to return string
properties. A pointer to a system string (BSTR*) is used as a method parameter
when the method must return string data.
System String Usage

Visual Basic both receives and sends system strings without any complications.
The internal representation of VB strings is as wide characters with a length
component. A BSTR may be passed using a variable, a string expression, or a
literal. A BSTR* requires use of a variable, so that the data may be modified by
the method.
Similarly, Visual C++ using ATL is straightforward. BSTR and BSTR* data is
passed and received using these types. Any translation to or from Unicode is the
developer’s responsibility.
Visual C++ with MFC, however, requires more consideration.
BSTR is handled as follows:
• BSTR Method Parameters
• Calling Function: Calling an automation method with a BSTR parameter
is treated by MFC as a pointer to a character string, LPCTSTR. If the
VC++ ANSI option is used, MFC automatically converts from ANSI to
Unicode.
• Called Function: The function implementing an automation method
receives a BSTR parameter as a pointer to a character string, LPCTSTR.
If the VC++ ANSI option is used, then MFC performs an automatic
conversion from Unicode into ANSI before passing control to the
function. The string length immediately precedes the string pointer.
• BSTR Return Type (used for getting properties)
• Calling Function: An automation method returning a BSTR result is
automatically converted by MFC into a CString.

System Strings and Binary Data A-79
• Called Function: An automation method returns a BSTR result by

placing the data into an MFC CString object, and returning the result of
the CString's “AllocSysString” member function. If the VC++ ANSI
option is used, then this function automatically converts the string from
ANSI into Unicode.
BSTR* is passed and received by MFC as BSTR*, so the developer handling is
the same as with ATL. Some MFC macros and classes may be helpful:
• If the VC++ ANSI option is used, then conversion between Unicode and
MBCS is required. Some macros are available that make this conversion
easier, such as T2OLE and OLE2T. (These do not handle NUL characters
embedded in the string, however.)
• To set the string, place the data into an MFC CString object, and use CString's
“SetSysString” member function.
System Strings and Binary Data

Sometimes OPOS uses BSTR and BSTR* to pass binary data.
These cases may return byte data in the range 00-hex to FF-hex. Each 16-bit
character of the system string contains one byte of binary data in the lower 8 bits.
The upper 8 bits are zero. This can lead to two problematic areas:
• The NUL character, or zero. Although system strings have a length
component, some software still relies upon the NUL character to determine
the end of the string.
• Characters in the range 0x80 – 0xFF. The translation between ANSI and
Unicode formats may yield incorrect data, especially for eastern languages.
In order to avoid these translation and transmission problems, an Application
should employ the BinaryConversion feature if data outside the range of 0x01 –
0x7F may be sent or received by a method parameter or a property.
BinaryConversion, added in Release 1.2, supports two means of converting data
between binary and ASCII formats.

Mapping of CharacterSet Updated in Release 1.10

This section provides some details for proper use of the MapCharacterSet
property that is provided for some devices such as the LineDisplay, POSPrinter,
PointCardReaderWriter, and RemoteOrderDisplay. First, the application
must select an appropriate device character set in the CharacterSet property of
the Service Object. Next, the application must pass strings to the Service Object
using the Unicode character set. Then, the Service Object is responsible for
mapping these Unicode characters to the device-side code page when necessary.
A special case occurs for applications and/or service objects written in Microsoft
C++ using Microsoft Foundation Classes, when building in MBCS (and not
Unicode) mode. The effects of MFC are described in the earlier section on
System Strings (BSTR). When MFC perform conversions between “narrow”
strings and Unicode strings, it does so using the system ANSI Code Page, or
“ACP”. The ACP may be found in the Windows registry at the key
“HKLM\System\CurrentControlSet\Control\Nls\Codepage”, value “ACP”.
The following code snippet should assist Service Object providers in adding the
mapping mechanism into their Services. It assumes that the data transferred to the
Service for output to the device is already transformed from BSTR to LPCTSTR,
as with MFC. (If the data is still in Unicode, then adjust the snippet to only
perform the second conversion.)
BOOL AnsiToOEMCodePage(
UINT CodePage, // the desired destination code page like 858
LPCTSTR src, // source string assumed to be ACP (default
// system code page)
INT srcLength, // the length of the source string
LPTSTR dest, // destination String; when called ’dest’
// shows to a reserved area of ’destLength’-
INT *destLength) // bytes length of the destination string
{
LPWSTR lpWideCharStr = NULL;
INT WideCharStrLen = (srcLength+1)* sizeof(lpWideCharStr[0]);
lpWideCharStr = (LPWSTR) malloc (WideCharStrLen);
if (lpWideCharStr == NULL)
return FALSE;
// convert to Unicode
WideCharStrLen = MultiByteToWideChar (CP_ACP, 0, src, srcLength,
lpWideCharStr, WideCharStrLen);
if (WideCharStrLen<=0)
{
free (lpWideCharStr);
return FALSE;
}
// convert Unicode back to desired codepage;
// non mappable characters are mapped to space character
const char defaultChar = 0x20;
*destLength = WideCharToMultiByte (CodePage, 0, lpWideCharStr,
WideCharStrLen, dest, *destLength, &defaultChar, NULL);
free (lpWideCharStr);
if (*destLength == 0 && WideCharStrLen != 0)// cp does not exist
return FALSE;
return TRUE;
}
Note:
• The code page currently selected in the system can be found in the Registry
under: HKLM\System\CurrentControlSet\Control\Nls\Codepage\ACP.
• The destination code page must of course be installed when using the system
API calls for mapping.

Section 6: Release 1.5 API Change: ClaimDevice and ReleaseDevice A-81
Section 6: Release 1.5 API Change: ClaimDevice and ReleaseDevice

The common methods Claim and Release were defined in the very first OPOS
release. Since that time, an increased number of conflicts have occurred between
the OPOS Release method and the COM Release method, which is a required
method of every COM object. This conflict has required some development
restrictions:
• Control Objects and Service Objects must define their interfaces as pure
dispatch interfaces. This has precluded the use of the Microsoft Visual C++
Active Template Library, since ATL only supports IDispatch via a dual
interface implementation.
• Some development environments assume that ActiveX Controls will not
define a dispatch method that conflicts with COM. For example, users of
Delphi have had to work around the Release conflict. Future tools may be
even less tolerant of this conflict.
Therefore, these methods have been renamed to ClaimDevice and
ReleaseDevice in Release 1.5.
Several steps have been taken to provide a maximal migration of Applications
and Service Objects. These have been implemented in the reference set of Control
Objects known as the “Common Control Objects”:
• Application.
Both the ClaimDevice and Claim methods and the ReleaseDevice and
Release methods are supported by the Control Object’s IDispatch interface.
The IDispatch interface is used by an application to implement late binding.
By doing this, full backward compatibility is provided for current late bound
Applications.
If an application using a development environment that performs early
binding (including Microsoft Visual C++ and Visual Basic) changes from a
1.4 or earlier Control Object to a 1.5 or later Control Object, then it will also
have to update all Claim calls to ClaimDevice, and Release calls to
ReleaseDevice.
• Service Object.
A Service Object may expose either the Claim or ClaimDevice method and
either the Release or ReleaseDevice method through its IDispatch interface.
Note that if the Service Object is implemented using ATL, then it must use
ReleaseDevice, since Release is reserved for COM’s IUnknown reference
counting.
When the Application calls ClaimDevice or Claim, the Control Object calls
the Service Object method ClaimDevice if present; otherwise it calls Claim.
When the Application calls ReleaseDevice or Release, the Control Object
calls the Service Object method ReleaseDevice if present; otherwise it calls
Release. By doing this, full backward compatibility is provided for current
Service Objects while allowing new Service Objects to be implemented using
ATL.

Section 7: OPOS APG Change History

Release 1.01
Release 1.01 mostly adds clarifications and corrections, but the Line Display and
Signature Capture chapters received substantive changes to correct deficiencies in
their definition.
Release 1.01 replaces Release 1.0. The ControlObjectVersion for a compliant
Control Object is 1000xxx, where xxx is a vendor-specific build number. The
ServiceObjectVersion for a compliant Service Object is 1000xxx, where xxx is a
vendor-specific build number.
Section Change
Second Page Add name of Microsoft Web site for OPOS
information.
Introduction When … Properties May Be Accessed
Update to say that capabilities are initialized at Open,
others may not be initialized until DeviceEnabled =
TRUE, and properties remain initialized until the
Control is closed.
Introduction Device Sharing Model
If an exclusive device is Released, then reClaimed,
settable device characteristics are restored to their state
at Release.
Common Release method
If device is enabled, then disable before releasing.
Cash Drawer WaitForDrawerClose method
BeepFrequency is in hertz.
Hard Totals General Information
Recommend claiming necessary files before a
BeginTrans, to ensure that CommitTrans does not
fail.
Keylock General Information
Claim will return OPOS_E_ILLEGAL, not success.
Line Display General Information
Major clarification of line display usage modes;
including intercharacter wait and marquees.
Line Display MarqueeFormat property
Add this property.
Line Display MarqueeType property
Add DISP_MT_INIT value.
Line Display ClearText and RefreshWindow methods
Clarify their functionality.
POS Printer XxxLetterQuality properties
Add initialization information.

Release 1.1 A-83
POS Printer XxxLineWidth properties

Clarify these properties.
POS Printer CapConcurrentXxxXxx properties
Clarify that if a “concurrent” capability is false, then the
application should print to only one of the stations at a
time, and not alternate print lines between them.
POS Printer CapXxxNearendSensor properties
Rename to CapXxxNearEndSensor for consistency
with XxxNearEnd properties.
POS Printer CapXxxBarcode properties
Rename to CapXxxBarCode for consistency with
PrintBarCode method.
Scale Summary Change ClearInput method to Not Supported. Scale
input is not event-driven.
Scale WeightUnit property
Change to read-only property.
Signature Capture MaximumX and MaximumY properties
Clarify that maximum value is 65,535.
Signature Capture TotalVectors and VectorArray properties
Rename to TotalPoints and PointArray. Update the
General Information and the property remarks
sections for consistency.
Signature Capture PointArray property
Clarify that each point is represented by four
characters: x (low 8 bits), x (high 8 bits), y (low 8 bits),
y (high 8 bits).
Throughout Update the property initialization details.
OposDisp.h header file
Add DISP_MT_INIT constant and MarqueeFormat
constants.
Appendix C Technical Details
Add this appendix, with the sections:
- System strings and binary data.
- Event Handler Restrictions.
Release 1.1
Release 1.1 adds APIs based on requirements from OPOS-J, the Japanese OPOS
consortium.
Release 1.1 is a superset of Release 1.01.

Section Change
POS Keyboard New device: Add information in several locations, plus
POS Keyboard chapter and header file.
Second Page Remove CompuServe reference.
Line Display CapCharacterSet property
Add values for Kana and Kanji.
Line Display CharacterSet property
Add Windows code page information.
POS Printer Data Characters and Escape Sequences
Add new sequences for:
Feed and Paper cut
Feed, Paper cut, and Stamp
Feed lines
Feed units
Feed reverse
Font typeface selection
Reverse video
Shading
Scale horizontally
Scale vertically
Add width selection for underline sequence.
POS Printer: Add the following properties and methods:
CapCharacterSet property
CapTransaction property
ErrorLevel property
ErrorString property
FontTypefaceList property
RecBarCodeRotationList property
RotateSpecial property
SlpBarCodeRotationList property
TransactionPrint method
ValidateData method
POS Printer CharacterSet property
Add Windows code page information.
POS Printer PrintBarCode method
Add information on effects of the RotateSpecial
property.
POS Printer PrintImmediate and PrintNormal methods
Clarify the effects of Carriage Return and Line Feed.
Scanner ScanData property
Clarify the data that is present in this property.
OposDisp.h header file
Add CapCharacterSet values for Kana and Kanji.
OposPtr.h header file
Add CapCharacterSet values.
Add ErrorLevel values.
Add TransactionPrint Control values.

Release 1.2 A-85
Release 1.2
Release 1.2 adds additional device classes, plus additional APIs based on
requirements from various OPOS-US, OPOS-Japan, and OPOS-Europe
members.
Section Change
Cash Changer New device: Add information in several locations, plus
Cash Changer chapter and header file.
Tone Indicator New device: Add information in several locations, plus
Tone Indicator chapter and header file.
Several places When a method has a Timeout parameter, added the
constant OPOS_FOREVER as a value, and noted that
OPOS_E_ILLEGAL can be returned.
First Two Pages Update company names.
Update copyright notices.
Update web reference.
Introduction How an Application Uses an OPOS Control and
Explicitly state that a control may be simultaneously
opened by many applications, but may be restricted in
its functionality based on the Claim method.
Introduction Events Add this section.
Introduction Input Model
Clarify the handling of error conditions.
Add usage of AutoDisable and DataCount.
Clarify the Error state exit conditions.
Clarify when ClearInput is legal.
Introduction Output Model
Clarify the Error state conditions.
Introduction Result Code Model
Clarify the setting of ResultCodeExtended.
Common BinaryConversion, AutoDisable, and DataCount properties
Add these new properties.
Throughout document, add to Summary sections for
each device class.
Throughout document, specify the BString properties
and method parameters that are affected by
BinaryConversion.
Common ControlObjectVersion and ServiceObjectVersion properties
Add compliance information when versions don’t
match.
Common FreezeEvents property
Clarify FreezeEvents role in delaying event firing.

Common ResultCodeExtended property

Clarify the setting of ResultCodeExtended.
Common ClearInput and ClearOutput methods
Correct return value information: May return one of
three statuses.
Common Open method Correct return value information: ResultCode may not
match method return value.
Common Release method
Correct DeviceEnabled side effects: Only exclusive
use devices are disabled during the Release.
Common StatusUpdateEvent event
Clarify the initial firing of events at device enable.
MICR BankNumber Correct definition to digits 4-8 of the TransitNumber.
MSR ErrorReportingType
Add this new property.
MSR ParseDecodeData
Clarify inconsistency: Both ParseDecodeData and
ParseDecodedData were used for this property.
MSR ErrorEvent Update for track level error notification.
POS Keyboard General Information
Clarify the type of keyboards that may be a POS
Keyboard.
POS Keyboard POSKeyData property
Update definition of this property: A logical key value.
POS Keyboard CapKeyUp, EventTypes, and POSKeyEventType properties
POS Printer Escape Sequences
Clarify that escape sequences that are not OPOS
sequences are passed through to the printer.
POS Printer CapConcurrentXxxYyy
Clarify the interpretation of a FALSE value.
POS Printer XxxLineSpacing
Clarify that line spacing includes the printed line
height. Could have been interpreted as only the
whitespace between each pair of lines.
POS Printer PrintBarCode
Add list of symbologies.
POS Printer MapMode and XxxLetterQuality
Clarified legal handling of MapMode when the printer
supports half-dots.
Clarified potential impact on metrics when
XxxLetterQuality is changed and MapMode is dots.
POS Printer SetBitmap Extend the bitmap number usage to allow the same
bitmap to be used for both receipt and slip.

Release 1.3 A-87
POS Printer TransactionPrint

Clarify when Busy and Extended statuses may be
returned.
POS Printer ValidateData
Add “Underline” to the Illegal status section.
Scale Model Correct to state the weight unit is defined by the device,
and not settable by the application.
Scale CapDisplay Add this new property.
Scale WeightUnit Clarify inconsistency: Both WeightUnit and
WeightUnits were used for this property.
Scanner ScanDataLabel and ScanDataType
Signature Capture “Real Time” feature
Add the new properties CapRealTimeData and
RealTimeDataEnabled.
Update various sections for real time operation.
Change History Release 1.1
Remove the compliance requirements for 1.1 Control
Objects. This information was corrected and added to
the common ControlObjectVersion and
ServiceObjectVersion properties.
Opos.h header file Add OPOS_FOREVER constant.
Add BinaryConversion values.
OposMsr.h header file
Add ErrorReportingType values.
OposKbd.h header file
Add EventTypes values.
OposPtr.h header file
Remove PTR_RP_NORMAL_ASYNC.
Add symbologies to match scanner.
OposScan.h header file
Add symbologies for ScanDataType.
Technical Details “Event Handlers”
Delete section. Much of the information was
inaccurate, and the rest was merged into the new
“Events” section in the first chapter.
Throughout Correct various editing errors.
Release 1.3
Release 1.3 adds additional device classes, a few additional APIs, and some
corrections.

Section Change
First Two Pages Update copyright notices.
General Modify the use of the term event “firing.” Use
“enqueue” and “deliver” appropriately to describe event
firing.
Bump Bar New device: Add information in several locations, plus
Bump Bar chapter and header file.
Fiscal Printer New device: Add information in several locations, plus
Fiscal Printer chapter and header file.
PIN Pad New device: Add information in several locations, plus
PIN Pad chapter and header file.
Remote Order Display New device: Add information in several locations, plus
Remote Order Display chapter and header file.
Several places Relax ErrorEvent “retry” response to allow its use
with some input devices.
Introduction Events Clarify effect of the top event being blocked.
Add details concerning enqueuing and delivery of
ErrorEvents.
Add description of asynchronous input.
Introduction Device Power Reporting Model
Add this section.
Introduction OPOS Control Descriptions
Add CURRENCY data type.
Common CapPowerReporting, PowerNotify, PowerState properties
Add these properties here, plus…
Add to the Summary section of each device.
Common ResultCode property
Generalize the meaning of OPOS_E_BUSY.
Common StatusUpdateEvent
Add power state reporting information.
Change parameter name from Data to Status.
Every Device Add power reporting properties to Summary section.
Add StatusUpdateEvent support (if previously not
reported.
Add power reporting reference to existing
StatusUpdateEvent descriptions.
MSR DecodeData Add “raw format” description and column to track data
table.
MSR ExpirationDate Specify the format.

Release 1.4 A-89
MSR TrackxData Specify that data excludes the sentinels and LRC.
Add that decoding occurs when DecodeData is TRUE.
MSR ErrorEvent Clarify that DataCount and AutoDisable are not
relevant for MSR error events.
POSPrinter XxxLineChars
Add implementation recommendations.
POSPrinter PrintTwoNormal
Clarify the meaning of the Stations parameter,
including the addition of new constants.
Scale Add the following features:
• Asynchronous input. Property AsyncMode. Method
ClearInput, updates to ReadWeight. Events
DataEvent and ErrorEvent.
• Display of text. Properties CapDisplayText,
MaxDisplayTextChars. Method DisplayText.
• Price calculation. Properties CapPriceCalculating,
SalesPrice, UnitPrice.
• Tare weight. Properties CapTareWeight,
TareWeight.
• Scale zeroing. Property CapZeroScale. Method
ZeroScale.
Tone Indicator Summary and General Information’s Device Sharing
Consistently specify that Tone Indicator is a sharable
device.
Opos.h header file Add CapPowerReporting, PowerState, and
PowerNotify properties.
Add StatusUpdateEvent power reporting values.
OposPtr.h header file Add new PrintTwoNormal station constants.
Throughout Correct some editing errors.
Release 1.4
Release 1.4 adds one additional device class.
Section Change
CAT Added new device class, Credit Authorization Terminal

which includes CAT chapter and header file. This
device class was added at the request of OPOS-J and is
used primarily in Japan. No other revisions were made
to the version 1.3 of the OPOS specification.

Release 1.5
Release 1.5 adds 2 additional device classes.
Section Change

Update web references.
General Replace Claim with ClaimDevice and Release with
ReleaseDevice.
Introduction Update references to OLE to ActiveX where
appropriate.
Common OpenResult property
Add new property, plus add to the Summary section of
each device.
Common ClaimDevice and ReleaseDevice
Name change plus update remarks.
Cash Changer Added support for receipt of money functionality.
Cash Drawer Added multi-drawer handling.
CAT Added PaymentMedia property.
The TransactionNumber property summary was
changed to correctly show the type as String.
Fiscal Printer Properties CountryCode, ErrorOutID, PrinterState,
QuantityDecimalPlaces and QuantityLength have
been updated to reflect the fact that they should be
initialized after Open instead of Open, Claim and
Enable.
DuplicateReceipt: Corrected to show that is R/W.
Added return values.
Line Display Added DISP_CCS_UNICODE to CapCharacterSet
and DISP_CS_UNICODE to CharacterSet to allow
for devices that support the Unicode character set.
MSR Added Track4Data, CapTransmitSentinels and
TransmitSentinels properties. Clarified support for
JIS-II track data.
DataEvent status: Added meaning for the high byte.
ErrorEvent's ResultCodeExtended when
ResultCode=OPOS_E_EXTENDED: Added meaning
for the high byte.
PINPad Added Track4Data property.
Point Card Reader Writer
New device: Add information in several locations, plus
Point Card Reader Writer chapter and header file.

Release 1.5 A-91
POS Keyboard CapKeyUp: Corrected type from LONG to BOOL.

POS Power New device: Add information in several locations, plus
POS Power chapter and header file.
POS Printer Added support for color printing (ink jet technology),
printing both sides on the slip station and mark feed
paper.
Added PTR_CCS_UNICODE to CapCharacterSet
and PTR_CS_UNICODE to CharacterSet to allow for
devices that support the Unicode character set.
Remote Order Display Added ROD_CCS_UNICODE to CapCharacterSet
and ROD_CS_UNICODE to CharacterSet to allow
for devices that support the Unicode character set.
Scale Properties SalesPrice, TareWeight and UnitPrice have
been updated to reflect the fact that they should be
initialized after Open instead of Open, Claim and
Enable.
ErrorEvent: Added OPOS_ER_RETRY as a value
response.
Signature Capture Update Model to discuss AutoDisable implications.
RealTimeDataEnabled: Clarify when this takes effect.
DataEvent: Correct conditions when this event may be
fired to include real-time data.
Tone Indicator Properties AsyncMode, Tone1Pitch, Tone1Volume,
Tone1Duration, Tone2Pitch, Tone2Volume,
Tone2Duration and InterToneWait have been updated
to reflect the fact that they should be initialized after
Open instead of Open, Claim and Enable.
Clarified handling of the Sound method when another
application claims the device and calls the Sound
method.
Opos.h header file Add OpenResult property values.
Appendix C Added header files for Point Card Reader Writer and
POS Power. Updated other header files for devices
modified in this specification.
Appendix D Update System String information to include ATL
usages.
Appendix E Added this appendix for details on ClaimDevice and
ReleaseDevice.

Release 1.6

Section Change
Line Display Added the CapBlinkRate, CapCursorType,

CapCustomGlyph, CapReadBack, CapReverse,
BlinkRate, CursorType, CustomGlyphList,
GlyphHeight and GlyphWidth properties.
Added DefineGlyph and ReadCharacterAtCursor
methods.
Many updates in the General Information section.
Updated the DisplayText and DisplayTextAt methods
to include support for new attribute types for reverse
video, DISP_DT_REVERSE and
DISP_DT_BLINK_REVERSE.
Fiscal Printer Added the CapAdditionalHeader,
CapAdditionalTrailer, CapChangeDue,
CapEmptyReceiptIsVoidable,
CapFiscalReceiptStation, CapFiscalReceiptType,
CapMultiContractor, CapOnlyVoidLastItem,
CapPackageAdjustment, CapPostPreLine,
CapSetCurrency, CapTotalizerType,
ActualCurrency, AdditionHeader,
AdditionalTrailer, ChangeDue, ContractorId,
DateType, FiscalReceiptStation, FiscalReceiptType,
MessageType, PostLine, PreLine and TotalizerType
properties.
Added the SetCurrency, PrintRecCash,
PrintRecItemFuel, PrintRecItemFuelVoid,
PrintRecPackageAdjustment,
PrintRecPackageAdjustVoid, PrintRecRefundVoid,
PrintRecSubtotalAdjustVoid and PrintRecTaxID
methods.
Added country support for Bulgaria and Romania.
Clarified the description of the
CapPositiveAdjustment property.
Updated the CountryCode, DayOpened and
DescriptionLength properties to reflect additions to
the specification.

Release 1.7 A-93
Updated the EndFiscalReceipt, GetData, GetDate,

PrintRecItem, PrintRecMessage, PrintRecNotPaid,
PrintRecRefund, PrintRecSubtotal,
PrintRecSubtotalAdjustment, PrintRecTotal,
PrintRecVoid, PrintRecVoidItem, PrintZReport and
SetHeaderLine methods to reflect additions to the
specification.
Updated the ErrorEvent event to reflect additions to the
specification.
Properties CountryCode, ErrorOutID, PrinterState,
QuantityDecimalPlaces and QuantityLength have
been updated to tone down strong language in the 1.5
revision that changes the “Initialized After” text.
Scale Properties SalesPrice, TareWeight and UnitPrice have
been updated to tone down strong language in the 1.5
revision that changes the “Initialized After” text
Tone2Duration and InterToneWait have been updated
to tone down strong language in the 1.5 revision that
changes the “Initialized After” text.
Appendix C Added new constants for Fiscal Printer and Line
Display updates.
Release 1.7
The change history above has been maintained to this point for historical
reference.
No specific change history relative to the OPOS APG is maintained from this
release forward. Refer to Appendix D for the change history details (if any)
relative to this section.

Section 8: OPOS Control Programmer’s Guide

This Section of the OPOS Appendix is targeted for the system developer who will
write an OPOS Control.
This Section assumes that the reader understands the following:
• The POS peripheral device to be supported.
• ActiveX Control and Automation terminology and architecture.
• ActiveX Control Container development environments, such as Microsoft
Visual Basic or Microsoft Visual C++. These will be required for testing the
OPOS Control.
• A thorough knowledge of the OPOS models and APIs presented in the other
sections of Appendix A, The OPOS Implementation Reference.
See the following Web sites for additional OPOS information:

Microsoft Retail Industry Page:
http://www.microsoft.com/business/industry/ret/retoposoverview.asp
Reference implementation – Common Control Objects:

http://monroecs.com/opos.htm
NRF-ARTS Standards Body:

http://www.nrf-arts.org/

General OLE for Retail POS Control Model A-95
General OLE for Retail POS Control Model

OLE for Retail POS Controls adhere to the ActiveX Control specifications. They
expose properties, events, and methods to a containing application. They
specifically do not include a user interface, but rather rely exclusively upon the
containing application for requests through methods and sometimes properties.
Responses are given to the application through method return values and
parameters, events, and properties.
The OLE for Retail POS software is implemented using the layers shown in the
following diagram:

OPOS Definitions
Device Class
properties, methods, and events. Examples are Cash Drawer and POS Printer.
Control Object or CO
A Control Object exposes a set of properties, methods, and events to an
application for its device class. The OPOS Application Programmer’s Guide
describes these APIs.
A CO is a standard ActiveX (that is, OLE 32-bit) Control that is invisible at
runtime. The CO interfaces have been designed such that all implementations of a
class' Control Object will be compatible. This allows the CO to be developed
independently of the SO's for the same class – including development by different
companies.
A Service Object is called by a Control Object to implement the OPOS-
prescribed functionality for a specific device.
An SO is implemented as an Automation server. It exposes a set of methods that
are called by a CO. It can also call special methods exposed by the CO to cause
events to be fired to the application.
A Service Object may include multiple sets of methods in order to support
devices with multiple device classes.
A Service Object is typically implemented as a local in-proc server (in a DLL). In
theory, it may also be implemented as a local out-proc server (in a separate
executable process). However, we have found that, in practice, out-proc servers
do not work well for OPOS Service Objects, and do not recommend their use.
OPOS Control or Control

An OPOS Control consists of a Control Object for a device class – which
provides the application interface, plus a Service Object – which implements the
APIs. The Service Object must support a device of the Control Object's class.

OPOS Definitions A-97
Note - Service Object Implementation: Out-of-Process vs. In-Process Servers

In general, the primary difficulty in using out-proc automation servers arises when either of
the two possible scenarios may occur:
(A) The server is processing a COM function for the client application (such as when the
client has called a Control’s method) when another server calls a COM function in the
client (such as when a Control’s event is fired).
(B) The server has called a COM function in a client application (such as when a Control’s
event is fired) when another client application calls a COM function in the server (such
as when this client calls a Control’s method).
The likelihood of these scenarios, especially (A), is greater for OPOS Service Objects since:
• Some OPOS methods require an indeterminately long time to be processed, such as the
Cash Drawer WaitForDrawerClose.
• Some OPOS events may require an indeterminately long time to be processed, such as an
ErrorEvent whose application handler waits for a user response to a dialog box.
The case where an OPOS event occurs from one service object while another service object
is processing a method call or a property access then becomes probable.
These scenarios could be handled if both the client application and the out-proc server
installed message filters (using the function CoRegisterMessageFilter), and the code for
these filters dealt with these scenarios in an OPOS-prescribed manner. However, the default
message filters for client environments such as Visual Basic and Visual C++ do not
adequately handle the scenarios. Behavior varies from displaying a dialog and waiting for a
user response (which is unacceptable for many POS operations) to generating an exception
that terminates the client application (which is certainly unacceptable for POS applications).
In addition, some environments do not provide a mechanism that easily allows an
application to set up its custom message filter.
These issues simply do not exist when in-proc servers are used. Therefore, we recommend
that they be used to implement service objects. This does, however, somewhat complicate
sharing a Control between applications. Interprocess communication mechanisms, such as
shared memory and named mutexes and events, may be used for this sharing.
If out-proc servers are used, then both the service object developer and the application
developer will need to carefully implement message filters. The service object vendor
should properly document this requirement to its application writers.

Interface Overview
A major OPOS objective is to provide general peripheral device APIs that can be
applied to many vendors’ peripherals. This leads to a requirement that any
implementation of a Control Object be able to communicate with any vendor’s
Service Object. A straightforward example is with printers: Suppose a fast-food
restaurant requires a local printer by one vendor and a remote kitchen printer by
another vendor. Two instances of the printer CO will be required where each
instance communicates with a different SO. The single CO must work with both
vendors’ SOs.
In order to define Control Objects that work across many vendors’ Service
Objects, the Control Object interfaces should be as generic and simple as
possible. Therefore, the CO will maintain very little information and will, in
general, perform the following three duties:
• Service Object coupling: Supervises a dispatch interface with a Service Object
for the device.
• Methods and properties: Performs a pass-through of the application's method
and property requests to the Service Object.
• Events: When a Service Object calls one of the special event request methods
in the Control Object, the CO fires an appropriate event to the application.
The various paths of communication between the application, Control Object,
and Service Object are shown in the following sections.

Methods A-99
Methods
An application initiates method calls to the OPOS Control.
Open Method
The Open method is processed as follows:
Application
1. App calls CO's Open method.
Control Object
2. CO calls SO's OpenService method.
Service Object
Close Method
The Close method is processed as follows:
Application
1. App calls CO's Close method.
Control Object
2. CO calls SO's CloseService method, if
present; otherwise calls Close method.
Service Object
Other Methods
All other methods are processed as follows, where Method represents the name of
the method:
Application
1. App calls CO's Method method.
Control Object
2. CO calls SO's Method method.
Service Object

Properties
An application initiates property accesses to the OPOS Control.
String Properties
Gets and sets of string properties are processed as follows, where StringProp
represents the name of the property:
Application
1. App accesses CO's StringProp property.
Control Object
2. If get, CO calls SO's GetPropertyString
method, with an index that represents
StringProp.
If set, CO calls SO's SetPropertyString
StringProp.
The index values are specified in header files.
Service Object
LONG and BOOL Properties

Gets and sets of long and boolean properties are processed as follows, where
NumericProp represents the name of the property:
Application
1. App accesses CO's NumericProp property.
Control Object
2. If get, CO calls SO's GetPropertyNumber
NumericProp.
If set, CO calls SO's SetPropertyNumber
NumericProp.
The index values are specified in header files.
Service Object
Other Property Types

Gets and sets of properties of any other type are processed as follows, where
Property represents the name of the property:
Application
1. App accesses CO's Property property.
Control Object
2. If get, CO calls SO's GetProperty method.
If set, CO calls SO's SetProperty method.
Service Object

Events A-101
Events
See “Events” on page A-11 in this Appendix for an overview of event handling.
The Service Object enqueues events, which are delivered to an application
handler for the event.
The Service Object delivers events as follows:
Application
2. CO event request method delivers a Data,
DirectIO, Error, OutputComplete, or
StatusUpdate event to the App.
Control Object
1. SO calls a CO event request method. The
methods SOData, SODirectIO, SOError,
SOOutputComplete, and
SOStatusUpdate are exposed specifically
to cause events to be delivered to the App.
Service Object
Architecture: Firing an Event

A Service Object may need to fire an event for the following reasons:
• Method call or property set. A side effect of an application request to the
control may cause an event to be fired.
Example: Assume that some data has been read and enqueued by the SO.
When the application changes the DataEventEnabled property to TRUE,
then the SO needs to deliver a DataEvent.
• Asynchronous activity. The Service Object will usually create one or more
worker threads to monitor the device's input or output. The SO cannot rely
upon the application to call OPOS methods or access OPOS properties on a
regular basis to gain some processing time, so independently scheduled
worker threads are a good solution. These threads may determine that an event
needs to be fired.
Example: Assume that the DataEventEnabled property is TRUE, and that a
worker thread is managing device input through a serial port. When the thread
receives a data message, then the SO enqueues and needs to deliver a
DataEvent.
When the SO needs to deliver an event, it calls a special event request method
within the CO. The CO then delivers the event to the application.
Architectural Issue: Freezing Events by the Container

ActiveX control containers may freeze and unfreeze events by calling the
IOleControl::FreezeEvents function. This is presented to a control written with
MFC via the COleControl::OnFreezeEvents member function, or to an control

written with ATL via the IOleControlImpl::FreezeEvents member function.

(One use of this feature is by the Visual Basic Common Dialog functions, which
freeze events while the dialog is up.) When events have been frozen, a control
should not deliver events. The Visual C++ documentation notes that the control
may either discard events that occur during the freeze period, or it may buffer
them for later delivery.
For OPOS Controls, enqueued events must be retained but not delivered while the
container has frozen them. Then, when events are unfrozen by the container, the
events may be delivered.
Each Service Object must support the method COFreezeEvents. The Control
Object will call this method to freeze and unfreeze events.
Architectural Feature: Freezing Events by the Application

The application may wish to disable the arrival of events for a period of time.
They may do this by setting the common boolean property FreezeEvents to
TRUE.
The event freezing mechanism implemented for container-requested freezing is
utilized to remember requests while the application has frozen them. Then, when
the application sets the property to FALSE to unfreeze events, the events are
delivered.
Summary of Event Firing

When a Service Object needs to deliver an event, it calls the appropriate event
request method within the Control Object.
However, if events have been frozen due to a Control Object call to
COFreezeEvents or due to the application setting the FreezeEvents property to
TRUE, then the SO keep the event on its event queue. If the event is to be
delivered from a worker thread, then this typically will be implemented by
blocking the thread until events are unfrozen.

Control Object Responsibilities A-103
Control Object Responsibilities

The following sections describe the responsibilities of the Control Object. The
Common Control Object is a reference implementation, whose source is available
on the web.
Methods
The following sections describe the responsibilities of the Control Object
methods.
If a device class does not support a common method (as specified by the device
class Summary section in this document), then the Control Object should not
define that method.
Since a Control Object must perform properly with any version of Service Object,
as long as the major version numbers match, some bookkeeping must be
performed in the Control Object. Specifically, the Control Object must not call
methods that are not defined by a Service Object, or access properties that it does
not define. In addition, it must perform additional management with the return
values and ResultCode. (See the “OPOS Common Properties, Methods, and
Events” on page A-26, “ControlObjectVersion” section for additional
information.) The processing steps below assume that the Control Object defines
a ResultCode flag to help manage version mismatch conditions.
Open Method
• If the Control Object is already open, then set OpenResult to
OPOS_OR_ALREADYOPEN return OPOS_E_ILLEGAL.
• If an empty device name has been passed, then set OpenResult to
OPOS_OR_REGBADNAME and return OPOS_E_NOEXIST.
• Query the registry to find the Service Object that corresponds to this device
class and device name. If the device class or device name is not found in the
registry, then set OpenResult to OPOS_OR_REGBADNAME and return
OPOS_E_NOEXIST.
• Load the Service Object for the device name. This requires (a) reading the de-
vice’s Programmatic ID from the registry, (b) converting it to a Class ID, (c)
creating an instance of the Service Object, and (d) getting its IDispatch inter-
face. If any of these are unsuccessful, then return OPOS_E_NOSERVICE. Set
OpenResult to OPOS_OR_REGPROGID if (a) or (b) fails, or
OPOS_OR_CREATE if (c) or (d) fails.
MFC (a) Use RegQueryValueEx. (b) Use CLSIDFromProgID.
(c)-(d) Calling the CreateDispatch member function of an instance of the
Service Object class, passing the Class ID from (b).
The Service Object class is generated by using the Visual C++ Class Wizard:
• Within the “OLE Automation” tab, push the “Add Class from an OLE
TypeLib...” button. Then choose the .TLB file generated by a Service
Object project.

• The Class Wizard will generate a COleDispatchDriver derivative, with

member functions matching the OLE Automation methods exposed by
the Service Object.
The Class Wizard will also generate an implementation of the member functions,
which call InvokeHelper with fixed dispatch IDs. Since dispatch IDs depend
upon the definition order of the automation methods, this implementation must be
updated by the next step to allow for Service Objects that define the methods in a
different order.
ATL (a) Use RegQueryValueEx. (b) Use CLSIDFromProgID.
(c) Use CoCreateInstance. (d) Use QueryInterface on the interface pointer
returned by (c).
• Look up the dispatch IDs for all of the Service Object methods defined by the
device class.
If any of the dispatch IDs defined in the initial version of the device class are
not found in the Service Object, then close the dispatch interface, set
OpenResult to OPOS_OR_BADIF, and return OPOS_E_NOSERVICE.
(This ensures that the Service Object supports at least the minimum methods
of a valid Service Object for the device class, before calling any of its
methods.)
MFC Look up the dispatch IDs by calling the Service Object instance’s
m_lpDispatch → GetIDsOfNames function. Update the generated Service
Object methods to pass these dispatch IDs to the InvokeHelper member
function.
ATL Look up the dispatch IDs by calling the Service Object instance’s
GetIDsOfNames function. Save them for later use – they must be passed to
the Service Object dispatch’s Invoke function.
• Call the OpenService method of the Service Object, passing a device class
string, a device name string, and the IDispatch pointer to the Control Object.
If OpenService returns any result except OPOS_SUCCESS, then close the
dispatch interface and return the OpenService result to the application. If the
Service Object supports the method GetOpenResult, then call it and set
OpenResult to its returned value; otherwise set OpenResult to
OPOS_OR_FAILEDOPEN.
MFC The Control Object’s dispatch pointer is accessed through its
GetIDispatch(FALSE) member function.
ATL The Control Object’s dispatch pointer is accessed by calling its
QueryInterface function, requesting an IDispatch interface.
• Call the GetPropertyNumber(PIDX_ServiceObjectVersion) method of the
Service Object to retrieve its version number. If the major version number is
not one (1), then set OpenResult to OPOS_OR_BADVERSION and return
OPOS_E_NOSERVICE.
• If any of the dispatch IDs for the methods that should be defined by the Service
Object’s version are not found, then:
- call the Service Object’s CloseService method if present, otherwise call
its Close method,
- close the dispatch interface,

- set OpenResult to OPOS_OR_BADIF,

- and return OPOS_E_NOSERVICE.
(This ensures that the Service Object supports all of the methods of a valid
Service Object for the device class and version it claims to support. If the
Service Object’s version is newer than the Control Object, then the Control
Object ensures that all of the methods for the Control Object’s version are
supported.)
• If all of the steps above are successful, then set an internal variable that shows
that the Control Object is open, set OpenResult to OPOS_SUCCESS, and
return OPOS_SUCCESS. Otherwise, the Control Object remains closed.
Close Method
• If the Control Object is closed, then return OPOS_E_CLOSED.
• If the Service Object supports the CloseService method, then call it.
Otherwise, call its Close method.
• Set an internal variable that shows that the Control Object is closed.
• Release the Service Object.
• MFC Call the ReleaseDispatch member function of the Service Object
class.
• ATL Call the Service Object dispatch pointer’s Release member
function.
• Return the result of the Service Object’s Close method.
Other method calls

• If the Control Object is closed, then return OPOS_E_CLOSED.
• If the method was not defined in the Service Object’s version of the device
class, then:
• Set the special ResultCode flag to show “version violation state”.
• Return OPOS_E_NOSERVICE.
• If the method is defined in the Service Object, then:
• Pass the request down to the Service Object by calling the identically
named Service Object method, using an identical list of parameters.
• Set the special ResultCode flag to show “normal state”.
• Return the result of the Service Object method.

Properties
The Control Object processes property accesses as follows:
• The Control Object only maintains the properties
ControlObjectDescription, ControlObjectVersion, and OpenResult. The
Control Object will handle accesses to these properties directly, and return
their value.
• If the Control Object is closed, then:
• If setting a property, then return. (There is no means of informing the
application that the set failed.)
• If getting a property, then:
• If the property is State, return OPOS_S_CLOSED.
• If the property is ResultCode, return OPOS_E_CLOSED.
• Otherwise, return a default property value:
FALSE for boolean.
Zero for numeric.
“[Error]” for string.
• If getting the property ResultCode and the special ResultCode flag is “version
violation state”, then return OPOS_E_NOSERVICE.
• If the property is not supported by the version of the Service Object, then:
• If setting a property, then set the special ResultCode flag to show “version
violation state” and return.
• If getting a property, then return the default property value.
If not one of the cases above...

• Set the internal ResultCode flag to show “normal state”.
• Pass down the request to the Service Object as follows.
• If the property type is a 4-byte numeric value, including boolean and long,
then call the Service Object's GetPropertyNumber or
SetPropertyNumber. A parameter specifies the index of the property.
These indices are established in the OPOS internal header files.In order to
supply control objects for new devices, the writers of new device chapters
may be requested to prepare the approximately 2-page data file used to
define some of the key attributes of the device to the generator.In order to
supply control objects for new devices, the writers of new device chapters
may be requested to prepare the approximately 2-page data file used to
define some of the key attributes of the device to the generator.
• If the property type is string, then call the Service Object’s
GetPropertyString or SetPropertyString. A parameter specifies the
index of the property. These indices are established in the OPOS internal
header files.
• If the property is any other type, then call the Service Object’s get or set
method for that property.

Events
The Service Object initiates events. The SO calls an event request method
exposed by the Control Object.
The mapping of event request methods called by the Service Object into OPOS
events is:
Event Request Methods OPOS Event

SOData DataEvent
SODirectIO DirectIOEvent
SOError ErrorEvent
SOOutputComplete OutputCompleteEvent
SOStatusUpdate StatusUpdateEvent
Upon receiving one of these event request methods, the Control Object delivers
the appropriate event to the application. The Service Object thread will not regain
control until the application event handler has completed.
Warning: These methods are only for use by the Service Object. Though
accessible to the application, the application should not call them.
These five event request methods are defined on the following pages.
SOData
Syntax void SOData (LONG Status);
The Status parameter contains the input status. Its value is control-dependent and
may describe the type of or qualities of the input.
Remarks Requests the Control Object to deliver the event:
void DataEvent (LONG Status);
Called by the Service Object to deliver input data from the device to the
application. The SO must not call SOData unless the DataEventEnabled
property is TRUE. Just before calling SOData, the SO must change this property
to FALSE, so that no further data events will be generated until the application
sets this property back to TRUE. The actual input data is placed in one or more
device class-specific properties.

SODirectIO
Syntax void SODirectIO (LONG EventNumber, LONG* pData, BSTR* pString);
EventNumber Event number. Specific values assigned by the Service

Object.
by EventNumber and the Service Object.
EventNumber and the Service Object.
void DirectIOEvent (LONG EventNumber, LONG* pData,
BSTR* pString);
Called by the Service Object to communicate information directly to the
application.
This event provides a means for a Service Object to deliver events to the
application that are not otherwise supported by the Control Object.
The Service Object must ensure that pString points to a valid system string, and
then must free this string after SODirectIO returns.
SOError Updated in Release 1.10

Syntax void SOError (LONG ResultCode, LONG ResultCodeExtended,
ResultCode Result code causing the error event. See “ResultCode
Property” on page A-42 for values.
ResultCodeExtended Extended result code causing the error event. See
“ResultCodeExtended Property” on page A-43 for
values.
ErrorLocus Location of the error. See values below.
pErrorResponse Pointer to the error event response. See values below.
The ErrorLocus parameter may be one of the following:

Value Meaning
OPOS_EL_OUTPUT Error occurred while processing asynchronous output.
OPOS_EL_INPUT Error occurred while gathering or processing event-
available.

OPOS_EL_INPUT_DATA
available.
The contents at the location pointed to by the pErrorResponse parameter are

preset to a default value, based on the ErrorLocus. The application may change
the value to one of the following:
Value Meaning
OPOS_ER_RETRY Typically valid only when locus is

OPOS_EL_OUTPUT.
May be valid when locus is OPOS_EL_INPUT.
Default when locus is OPOS_EL_OUTPUT.
OPOS_ER_CLEAR Clear all buffered output data (including all
state is exited.
Default when locus is OPOS_EL_INPUT.
OPOS_ER_CONTINUEINPUT
Use only when locus is OPOS_EL_INPUT_DATA.
state and will fire additional DataEvents as directed by
the DataEventEnabled property. When all input has
been fired and the DataEventEnabled property is
again set to TRUE, then another ErrorEvent is fired
with locus OPOS_EL_INPUT.
Default when locus is OPOS_EL_INPUT_DATA.
void ErrorEvent (LONG ResultCode, LONG ResultCodeExtended,
Once SOError has been called, the Service Object must not request another error
event until the error has been cleared. However, if an error with locus
OPOS_EL_INPUT_DATA is fired and the event handler responds with
OPOS_ER_CONTINUEINPUT, then the SO may fire another error event with
OPOS_EL_INPUT after the enqueued input has been delivered.

SOOutputComplete
Syntax void SOOutputComplete (LONG OutputID);
The OutputID parameter indicates the number of the asynchronous output request
that has completed.
void OutputCompleteEvent (LONG OutputID);
Called by the Service Object when a previously started asynchronous output
request completes successfully.
SOStatusUpdate
Syntax void SOStatusUpdate (LONG Data);
The Data parameter is for device class-specific data describing the type of status
change.
void StatusUpdateEvent (LONG Data);
Called by the Service Object when the SO needs to alert the application of a
device status change.
Examples include a change in the cash drawer position (open vs. closed) and a
change in a POS printer sensor (form present vs. absent).
The following method is not related to event firing, but is a special purpose
support method.
SOProcessID
Syntax LONG SOProcessID();
Remarks Return the process ID of the application in which the Control Object exists.
The following method is provided to support local out-proc Service Objects. As
noted in the introduction chapter, out-proc servers are not recommended for
OPOS Service Objects. However, if a vendor successfully designs and
implements such a Service Object, this method may be useful.
For example, if a Service Object which supports Printer with MICR has allowed
an application to Claim the printer, then it will want to restrict Claim of the
MICR to the same application, since it is not reasonable for two applications to
share such a device with such closely interacting classes.

Service Object Responsibilities and Implementation A-111
Service Object Responsibilities and Implementation

Methods
The following common Service Object methods are defined for implementing
corresponding Control Object methods. If a device class does not support a
common method (as specified by the device class Summary section in the this
document), then the Service Object should not define that method.
For each device class, additional methods are defined for each device specific
method.
The general rules used to define the Service Object methods are:
• The Service Object method name is the same as the Control Object’s method
name.
• The parameters match those of the Control Object, both in order and type.
The only exceptions to these rules are the OpenService, CloseService (optional –
may use Close instead), GetOpenResult (optional), and COFreezeEvents
methods.
Note that these methods are always called through the Service Object’s IDispatch
interface.
For each of the methods below, syntax is shown for MFC as entered into the
control’s “Add Method” dialog, and for ATL as entered into the COM object’s
“Add Method to Interface” dialog.
CheckHealth
Syntax MFC long CheckHealth(long Level);
ATL HRESULT CheckHealth(long Level, [out, retval] long* pRC);
Remarks Called to test the state of a device.
ClaimDevice / Claim
Syntax MFC long ClaimDevice(long Timeout);
long Claim(long Timeout);
ATLHRESULT ClaimDevice(long Timeout, [out, retval] long* pRC);
HRESULT Claim(long Timeout, [out, retval] long* pRC);
Remarks Called to request exclusive access to the device.
Release 1.0 – 1.4
Control Objects for these releases will only look for the Claim method.
A Control Object for this release will first look for the ClaimDevice method. If
ClaimDevice is not present, then the Control Object looks for Claim.

ClearInput
Syntax MFC long ClearInput();
ATL HRESULT ClearInput([out, retval] long* pRC);
Remarks Called to clear all device input that has been enqueued.
ClearInputProperties
Syntax MFC long ClearInputProperties();
ATL HRESULT ClearInputProperties([out, retval] long* pRC);
Remarks Called to clear all input properties that have been populated by the last DataEvent
or ErrorEvent.
ClearOutput Updated in Release 1.7

Syntax MFC long ClearOutput();
ATL HRESULT ClearOutput([out, retval] long* pRC);
Remarks Called to clear all buffered output data, including all asynchronous output. Also,
when possible, halts outputs that are in progress.
Close
Syntax MFC long CloseService();
long Close();
ATL HRESULT CloseService([out, retval] long* pRC);
HRESULT Close([out, retval] long* pRC);
Remarks Called to release the device and its resources.
Release 1.0 – 1.4
Control Objects for these releases will only look for the Close method.
A Control Object for this release will first look for the CloseService method. If
CloseService is not present, then the Control Object looks for Close.

COFreezeEvents Internal Control/Service Object Method

Syntax MFC long COFreezeEvents(BOOL Freeze);
ATL HRESULT COFreezeEvents(VARIANT_BOOL Freeze,
[out, retval] long* pRC);
The Freeze parameter is TRUE / VARIANT_TRUE when event firing must be
frozen, and FALSE / VARIANT_FALSE when event firing is reenabled.
Remarks This method is for internal use by the Control Object.
The CO calls it in response to a container event freeze request to inform the SO of
a change in the state of event firing. See “Architectural Issue: Freezing Events by
the Container” on page A-101 for more information.
CompareFirmwareVersion Added in Release 1.9

Syntax MFC long CompareFirmwareVersion(BSTR FirmwareFileName, LONG*
pResult);
ATL HRESULT CompareFirmwareVersion(BSTR FirmwareFileName,
[out] long* pResult, [out, retval] long* pRC);
DirectIO
Syntax MFC long DirectIO(long Command, long* pData, BSTR* pString);
ATL HRESULT DirectIO(long Command, [in, out] long* pData,
[in, out] BSTR* pString, [out, retval] long* pRC);
Remarks Call to communicate directly with the Service Object.
GetOpenResult Internal Control/Service Object Method

Syntax MFC long GetOpenResult();
ATL HRESULT GetOpenResult([out, retval] long* pRC);
Remarks This method is for internal use by the Control Object. It is optional.
If a Service Object’s OpenService method returns a status other than
OPOS_SUCCESS, and it has implemented this method, then the Control Object
calls this method to set its OpenResult property.
The Service Object may select one of the values given in the OPOS.H header file,
or return a Service Object-specific value.
Return For MFC implementations, return one of the following values. For ATL
implementations, store one of the following values at pRC, and return S_OK.

Value Meaning
OPOS_ORS_NOPORT The Service Object tried to access an I/O port (for
example, an RS232 port) during Open processing, but
the port that is configured for the DeviceName is
invalid or inaccessible.
As a general rule, an SO should refrain from accessing
the physical device until the DeviceEnabled property is
set to TRUE. But in some cases, it may require some
access at Open; for instance, to dynamically
determining the device type in order to set the
DeviceName and DeviceDescription properties.
OPOS_ORS_NOTSUPPORTED
The Service Object does not support the specified
device.
The SO has determined that it does not have the ability
to control the device it is opening. This determination
may be due to an inspection of the registry entries for
the device, or dynamic querying of the device during
Open processing.
OPOS_ORS_CONFIG Configuration information error.
Usually this is due to incomplete configuration of the
registry, such that the SO does not have sufficient or
valid data to open the device.
OPOS_ORS_SPECIFIC Errors greater than this value are service object-
specific.
If the previous return values do not apply, then the SO
may define additional OpenResult values. These values
are Service Object-specific, but may be of value in
these cases:
1) The Application logs or reports this error during
debug and testing.
2) The Application adds SO-specific logic, to attempt
to report more error conditions or to recover from
them.

OpenService Internal Control/Service Object Method

Syntax MFC long OpenService(LPCTSTR DeviceClass, LPCTSTR DeviceName,
LPDISPATCH pDispatch);
ATL HRESULT OpenService(BSTR DeviceClass, BSTR DeviceName,
IDispatch* pDispatch, [out, retval] long* pRC);
DeviceClass Contains the requested device class, which are given in
the header file OPOS.HI. Examples are “CashDrawer”
and “POSPrinter.”
DeviceName Contains the Device Name to be managed by this
Service Object. The relationship between the device
name and physical devices is determined by entries
within the operating system registry; a setup or
configuration utility maintains these entries. (See the
“Application Programmer’s Guide” appendix “OPOS
Registry Usage.”)
pDispatch Points to the Control Object’s dispatch interface, which
contains the event request methods.
Remarks Call to open a device for subsequent I/O. The Control Object calls this method as
part of its Open method processing.
The Service Object will use the DeviceClass and DeviceName parameters in
inquiring the registry for additional device specific information.
The following steps assume that the Control Object is written using Visual C++
with MFC. Modify appropriately if another development environment is selected.
For MFC implementations, the pDispatch parameter may be used as follows:
• Attach to the Control Object’s IDispatch interface by passing the pDispatch
IDispatch pointer to the AttachDispatch member function of an instance of
a class that defines the Control Object’s event request methods.
This class is generated by using the Visual C++ Class Wizard:
• Within the “OLE Automation” tab, push the “Add Class from an OLE
TypeLib...” button. Then choose the .TLB file generated by a Control Ob-
ject project.
• The Class Wizard will generate a COleDispatchDriver derivative, with
member functions matching the OLE Automation methods exposed by
the Control Object.
• The Class Wizard will also generate an implementation of the member
functions, which call InvokeHelper with fixed dispatch IDs. Since dis-
patch IDs depend upon the definition order of the automation methods,
this implementation must be updated by the next step to allow for Control
Objects that define the methods in a different order.
• The class definition and implementation should be updated to remove all
of the non-event request methods.

• Look up the event request methods (such as SOData) by calling the Control
Object instance’s m_lpDispatch → GetIDsOfNames function. Update the
generated Control Object methods to pass these dispatch IDs to the
InvokeHelper member function.
For ATL implementations, the pDispatch parameter may be used directly to
call IDispatch’s GetIDsOfNames and Invoke functions. Alternatively, a
CComDispatchDriver class instance may be created; its Invoke1 and
InvokeN functions may be used to call the event functions.
Note
The Service Object attaches back to the Control Object’s dispatch pointer in order to
access the event request methods within the CO. This implies the following two
points:
• When the Control Object exposes the event request methods for access by the
Service Object, these methods also become accessible by the application. The
application, of course, should not call these methods.
• The Service Object can access other methods and properties within the
Control Object. This is not usually beneficial; however, the SO may wish to
access the ControlObjectDescription or ControlObjectVersion to validate
compatibility between itself and the CO.
Return For MFC implementations, return one of the following values. For ATL
implementations, store one of the following values at pRC, and return S_OK.
Value Meaning
OPOS_SUCCESS The Service Object is open.
This does not tell the Control Object or Application
that the device is online and functional. Rather, it states
that the Service Object software is initialized, and ready
to attempt device interaction when the DeviceEnabled
property is set to TRUE.
Other Values See “ResultCode Property” on page A-42.
Any return value except OPOS_SUCCESS is an Open
failure, and will result in the Control Object shutting
down the Service Object (by releasing its COM pointer)
and passing this status to the Application.
Since the APG defines meanings for
OPOS_E_ILLEGAL and OPOS_E_NOEXIST, a
Service Object should return one of these only if the
failure is similar to one of these meanings. Otherwise,
the Application may be misled.
On a failure, the Control Object will call the Service

Object’s GetOpenResult method, if present, to retrieve
an additional status value.

ReleaseDevice / Release
Syntax MFC long ReleaseDevice();
long Release();
ATL HRESULT ReleaseDevice([out, retval] long* pRC);
Remarks Called to release exclusive access to the device.
Release 1.0 – 1.4
Control Objects for these releases will only look for the Release method.
A Control Object for this release will first look for the ReleaseDevice method. If
ReleaseDevice is not present, then the Control Object looks for Release.
Note that ATL implementations cannot support the Release method (at least not
without updating/overriding ATL classes).
ResetStatistics Added in Release 1.8

Syntax MFC long ResetStatistics(BSTR StatisticsBuffer);
ATL HRESULT ResetStatistics(BSTR StatisticsBuffer, [out, retval] long*
pRC);
RetrieveStatistics Added in Release 1.8

Syntax MFC long RetrieveStatistics(BSTR* pStatisticsBuffer);
ATL HRESULT RetrieveStatistics([in, out] BSTR* pStatisticsBuffer, [out,
retval] long* pRC);
UpdateFirmware Added in Release 1.9

Syntax MFC long UpdateFirmware(BSTR FirmwareFileName);
ATL HRESULT UpdateFirmware(BSTR FirmwareFileName, [out, retval]
long* pRC);
Remarks Updates the firmware of a device with the version of the firmware contained or
defined in the file specified by the FirmwareFileName parameter.
UpdateStatistics Added in Release 1.8

Syntax MFC long UpdateStatistics(BSTR StatisticsBuffer);
ATL HRESULT UpdateStatistics(BSTR StatisticsBuffer, [out, retval] long*
pRC);

Properties
The following methods are defined for getting and setting properties of the
following types: 4-byte numeric and string.
For each method, the first parameter is:
LONG PropIndex
The values of PropIndex are specified in Opos.hi for the common properties. The
values of class-specific properties are specified in the class-specific header files.
For robustness, the Service Object should validate the PropIndex. If an invalid
value is found, then it could display a message box specifying the error, generate
a debug exception, or produce another alert to the developer. This type of error
should be found during development, testing, or staging prior to rollout to a
customer, so the method of informing the user may be rather terse.
Note that these methods are always called through the Service Object’s IDispatch
interface.
GetPropertyNumber
Syntax MFC long GetPropertyNumber(long PropIndex);
ATL HRESULT GetPropertyNumber(long PropIndex,
[out, retval] long* pNumber);
Return The current value of the LONG or BOOL / VARIANT_BOOL property.
For BOOL properties - VARIANT_BOOL COM IDL type - the Common Control
Objects return a zero value as VARIANT_FALSE and a non-zero value as
VARIANT_TRUE.
GetPropertyString
Syntax MFC BSTR GetPropertyString(long PropIndex);
ATL HRESULT GetPropertyString(long PropIndex,
[out, retval] BSTR* pString);
Return The current value of the string property.
SetPropertyNumber
Syntax MFC void SetPropertyNumber(long PropIndex, long Number);
ATL HRESULT SetPropertyNumber(long PropIndex, long Number);
Remarks Sets the LONG or BOOL property to Number.
For BOOL properties - VARIANT_BOOL COM IDL type - the Common Control
Objects pass a zero value as zero (0) and a non-zero value as one (1).

SetPropertyString
Syntax MFC void SetPropertyString(long PropIndex, LPCTSTR String);
ATL HRESULT SetPropertyString(long PropIndex, BSTR String);
Remarks Sets the string property to String.
Note – Rationale for property get and set methods

Instead of using the four methods above, the Service Object interface could have
defined distinct get methods for every property, plus set methods for writable
properties.
Due to the large number of properties present in several Control Objects,
however, the four methods above were chosen to reduce the amount of overhead
and Service Object code.
Other Types: Not BSTR, LONG, or BOOL

If the Control defines properties of types that are not BStrings, LONGs, or
BOOLeans, then the Service Object must define additional get and set methods
for these properties.
If using Visual C++ with MFC, this is most easily accomplished through the
Class Wizard by adding an Automation property.
Getting Other Property Types

Syntax MFC Type GetPropertyName();
ATL HRESULT GetPropertyName([out, retval] Type* pProp);
Where Type is replaced by the property’s type,
and PropertyName is replaced by the property’s name.
Return The current value of the property.
Example: If a property
CURRENCY SomeMoney;
is defined by the control, then the Service Object must define the method
MFC CURRENCY GetSomeMoney();
ATL HRESULT GetSomeMoney([out, retval] CURRENCY* pCY);

Setting Other Property Types

Syntax MFC void SetPropertyName(Type value);
ATL HRESULT SetPropertyName(Type value);
Where Type is replaced by the property’s type,
and PropertyName is replaced by the property’s name.
Remarks Sets the property to value.
This method is only defined if the property PropertyName is a writable property.
Example: If a read/write property
CURRENCY SomeMoney;
is defined by the control, then the Service Object must define the method
MFC void SetSomeMoney(CURRENCY NewMoneyValue);
ATL HRESULT SetSomeMoney(CURRENCY NewMoneyValue);
Events
A Service Object causes events to be fired by calling event methods in the
Control Object. These methods are named:
SOData
SODirectIO
SOError
SOOutputComplete
SOStatusUpdate
They are described in “Control Object Responsibilities” on page A-103.
See the OpenService description on page A-115 for information about how to get
the dispatch interface and dispatch IDs necessary for calling these functions.

OPOS CPG Change History A-121
OPOS CPG Change History

Release 1.01
Release 1.01 mostly adds clarifications and corrections, but the Line Display and
Signature Capture chapters received substantive changes to correct deficiencies in
their definition.
Section Change
Second Page
Add name of Microsoft Web site for OPOS
information.
Opos.hi header file
Remove HKEY_LOCAL_MACHINE from the root
keys.
OposPtr.hi header file
Change ...Nearend to ...NearEnd.
Change ...Barcode to ...BarCode.
OposScal.hi header file
Correct WeightUnits value from 1 to 2.
OposSig.hi header file
Change TotalVectors to TotalPoints.
Change VectorArray to PointArray.
Release 1.1
Release 1.1 adds APIs based on requirements from OPOS-J, the Japanese OPOS
consortium.
Section Change
Second Page Remove CompuServe reference.
Opos.hi header file Add POS Keyboard values.
OposKbd.hi header file New header file for POS Keyboard.
OposPtr.hi header file Add the following properties:
CapCharacterSet
CapTransaction
ErrorLevel
ErrorString
FontTypefaceList
RecBarCodeRotationList
RotateSpecial
SlpBarCodeRotationList

Release 1.2
Release 1.2 adds additional device classes, plus additional APIs based on
requirements from various OPOS-US, OPOS-Japan, and OPOS-Europe
members.
Section Change
First Two Pages Update company names.
Update copyright notices.
Introduction Add discussion of out-proc and in-proc service objects.
Control Object Chapter Update to include handling of version mismatch
between the Control Object and Service Object.
Add the method SOProcessID.
Opos.hi header file Add Cash Changer and Tone Indicator.
Add the following properties:
AutoDisable
BinaryConversion
DataCount
OposChan.hi header file
New header file for Cash Changer.
OposMsr.hi header file
Add the property ErrorReportingType.
Add the property ParseDecodedData, with value set
the same as ParseDecodeData.
OposKbd.hi header file
CapKeyUp
EventTypes
POSKeyEventType properties
CapDisplay
WeightUnit.
OposScan.hi header file
ScanDataLabel
ScanDataType
OposSig.hi header file
CapRealTimeData
RealTimeDataEnabled.
OposTone.hi header file
New header file for Tone Indicator.

Release 1.3
corrections.
Section Change
firing.
Control Object Chapter SOError: Allow OPOS_ER_RETRY to be returned on
input events if the Control supports it.
Service Object Chapter Add descriptions of property methods that don’t fall
into “4-byte number” or “string” types.
Opos.hi header file Add Bump Bar, Fiscal Printer, PIN Pad, and Remote
Order Display. Add the following properties:
CapPowerReporting
PowerNotify
PowerState
OposBb.hi header file New header file for Bump Bar
OposChan.hi header file Correct the string indices to use PIDX_STRING
instead of PIDX_NUMBER.
OposFptr.hi header file New header file for Fiscal Printer
OposPPad.hi header file New header file for PIN Pad
OposROD.hi header file New header file for Remote Order Display
CapDisplayText
CapPriceCalculating
CapTareWeight
CapZeroScale
AsyncMode
MaxDisplayTextChars
TareWeight
Several header files Add validation functions for the first release containing
the device.

Release 1.4
Release 1.4 adds 1 additional device class.
Section Change
Opos.hi header file Add CAT.

OposCat.hi header file New header file for CAT.
Release 1.5
Release 1.5 adds 2 additional device classes.
Section Change
Update web references.
General Update Claim and Release references to include
ClaimDevice and ReleaseDevice information.
Update references to OLE to ActiveX where
appropriate.
Generalize some references to MFC implementations,
and add some ATL implementation information.
Control Object Responsibilities
Remove implementation details, and refer to the
Common Control Objects.
Service Object GetOpenResult method
Add new method.
Opos.hi header file Added Point Card Reader Writer and POS Power
device categories.
OposCash.hi header file
Add CapMultiDrawerDetect property.
OposCat.hi header file
Add PaymentMedia property
OposCash.hi header file
Add DepositAmount, DepositStatus, DeviceStatus,
CapDeposit, CapDepositDataEvent,
CapPauseDeposit, CapRepayDeposit,
DepositCashList, DepositCodeList and
DepositCounts properties.
OposMSR.hi header file
Add CapTransmitSentinels, Track4Data and
TransmitSentinels properties.

OposPcrw.hi header file

New header file for Point Card Reader Writer.
OposPpad.hi header file Update to match the released 1.3 header file, then
Remove the Amount property index – it isn’t a string.
Add Track4Data property.
OposPtr.hi header file
Add CapJrnCartridgeSensor, CapJrnColor,
CapRecCartrdigeSensor, CapRecColor,
CapRecMarkFeed, CapSlpBothSidesPrint,
CapSlpCartridgeSensor, CapSlpColor,
CartridgeNotify, JrnCartridgeState,
JrnCurrentCartridge, RecCartridgeState,
RecCurrentCartridge, SlpPrintSide,
SlpCartridgeState, and SlpCurrentCartridge
properties.
OposPwr.hi header file New header file for POS Power.
Release 1.6
Section Change
OposDisp.hi header file

Added CapBlinkRate, CapCursorType,
GlyphHeight and GlyphWidth properties.
OposFptr.hi header file
Added CapAdditionalHeader,
MessageType, PostLine, PreLine and TotalizerType
properties.
Release 1.7
reference.
No specific change history relative to the OPOS CPG is maintained from this
release forward. Refer to Appendix D for the change history details (if any)
relative to this section.

Common Control Objects

As a combination of the personal effort of Curtiss Monroe plus as part of the
commitment of his employer, Research Computer Services, Inc. (based in
Dayton, Ohio) to the retail community, a complete set of OPOS control objects
have been developed for public use. These have been dubbed the “Common
Control Objects.”
These control objects are delivered as a reference implementation, believed to be
correct and suitable for direct use by applications, but not warranted to be correct
or to work with any vendor's Service Objects.
Features
• All OPOS controls are supported.
• ATL-based, using dual interfaces so that the app can access them via
IDispatch or COM interfaces (of the form IOPOSCashDrawer, etc.).
• Built using Microsoft Visual C++. (Currently at Version 6.0,
Service Pack 4.)
• Backward compatible with all releases of service objects. This means that they
check for older SOs, and return the proper errors to the application if it
accesses unsupported properties or methods.
• They have been tested with several major hardware vendors’ Service Objects.
• Event firing logic supports well-behaved service objects that fire events from
the thread that created the control, plus other service objects that fire them
from other threads.
• Self-contained, requiring only standard OS DLLs. Specifically, they do not
require MFC or ATL DLLs.
• Both MBCS and Unicode versions have been built and given limited testing.
At this time, only the MBCS versions are being posted.
• Source code for all control objects is available.
• For future additions, it is easy to add new control objects or update old ones.
A custom generator was developed that reads a data file for each control to be
built. To add properties or methods, the procedure is (a) update the data files,
(b) regenerate, and (c) build the resulting projects.
Availability and Future

Curtiss intends to maintain the control objects, and post corrections plus new
releases at the site http://www.monroecs.com as needed, for as long as he is
affiliated with OPOS. Should he not be able to perform this function, then the
OPOS Core Committee is authorized to do so.
In order to supply control objects for new devices, the writers of new device
chapters may be requested to prepare the approximately 2-page data file used to
define some of the key attributes of the device to the generator.

OPOS Internal Header Files A-127
OPOS Internal Header Files Updated in Release 1.12

The header files are listed in alphabetical order. The mapping of device class
name to header file name is as follows:
– General – Opos.hi
Belt OposBelt.hi
Bill Acceptor OposBacc.hi
Bill Dispenser OposBdsp.hi
Biometrics OposBio.hi
Bump Bar OposBb.hi
Cash Changer OposChan.hi
Cash Drawer OposCash.hi
CAT OposCat.hi
Check Scanner OposChk.hi
Coin Acceptor OposCacc.hi
Coin Dispenser OposCoin.hi
Electronic Journal OposEj.hi
Electronic Value R / W OposEvrw.hi
Fiscal Printer OposFptr.hi
Gate OposGate.hi
Hard Totals OposTot.hi
Image Scanner OposImg.hi
Item Dispenser OposItem.hi
Keylock OposLock.hi
Lights OposLgt.hi
Line Display OposDisp.hi
MICR OposMicr.hi
Motion Sensor OposMotion.hi
MSR OposMsr.hi
PIN Pad OposPpad.hi
Point Card Reader Writer OposPcrw.hi
POS Keyboard OposKbd.hi
POS Power OposPwr.hi
POS Printer OposPtr.hi
Remote Order Display OposRod.hi
RFID Scanner OposRfid.hi
Scale OposScal.hi
Scanner OposScan.hi
Signature Capture OposSig.hi
Smart Card Reader Writer OposScrw.hi
Tone Indicator OposTone.hi
The most up-to-date header files can be downloaded from the following web site:
http://monroecs.com/oposccos_current.htm


A P P E N D I X B
Java for Retail POS — JavaPOS Implementation Reference
What Is Java for Retail POS?
Java for Retail POS (JavaPOS) provides for open POS device solutions for
applications based on Java development technology. It is an implementation of
the UnifiedPOS architecture that defines:
• An architecture for Java-based POS (Point-Of-Service or Point-Of-Sale)
device access.
• A set of POS device interfaces (APIs) sufficient to support a range of POS
solutions.
The Java for Retail POS standards committee was formed by a collection of retail
vendors and end users, with a primary goal of providing device interfaces for the
retail applications written in Java. Prior to version 1.7 of the UnifiedPOS and
JavaPOS standards these documents were separate sets of documentation. This
Appendix has been added to this UnifiedPOS Standard to provide guidance on
how to implement services in a Java environment.
The JavaPOS committee will produce the following:
• UnifiedPOS Programmer’s Guide (this document).
• Java source files, including:
• Definition files. Various interface and class files described in the
standard.
• jpos.config/loader (JCL), configuration and service loader example.
• Example files. These will include a set of sample Device Control classes,
to illustrate the interface presented to an application.
The JavaPOS committee will not provide the following:
• Complete software components. Hardware providers or third-party providers
develop and distribute these components.
Benefits
The benefits of JavaPOS include:
• The opportunity for reduced POS terminal costs, through the use of thinner
clients.
• Platform-independent applications, where the application is separated from
both hardware and operating system specifics.
• Reduced administration costs, because an application and supporting software
may be maintained on a server and loaded on demand by Java.
UnifiedPOS Retail Peripheral Architecture Appendix B
B-2 JavaPOS Implementation Reference
Dependencies
Deployment of JavaPOS depends upon the following software components:
• Java Communications Port API (COM/API) or optionally some other Java
communications API that supports hardware device connectivity.
• jpos.config/loader (JCL)
• For more information concerning the availability and any other up-to-date
information about these components, see http://www.javapos.com/.
Relationship to OPOS
The OLE for Retail POS (OPOS) standards committee developed device
interfaces for Win32-based terminals using ActiveX technologies. The OPOS
standard was used as the starting point for JavaPOS, due to:
• Similar purposes. Both standards involve developing device interfaces for a
segment of the software community.
• Reuse of device models. The majority of the OPOS documentation specifies
the properties, methods, events, and constants used to model device behavior.
These behaviors are in large part independent of programming language.
• Reduced learning curve. Many application and hardware vendors are
already familiar with using and implementing the OPOS APIs.
• Early deployment. By sharing device models, JavaPOS “wrappers” or
“bridges” may be built to migrate existing OPOS device software to JavaPOS.
Therefore, most of the OPOS APIs were mapped into the Java language. The
general translation rules are given in Section 3 of this Appendix, page B-94.

This section is targeted to both the application developer who will use JavaPOS
Devices and the system developer who will write JavaPOS Devices.
This section assumes that the application developer is familiar with the following:
• Java terminology and architecture.
• A Java development environment, such as Javasoft's JDK, Sun's Java
Workshop, IBM's VisualAge for Java, or others.
A system developer must understand the above, plus the following:
• The POS peripheral device to be supported.
• The host operating system, if the JavaPOS Device will require a specific
operating system.
• A thorough knowledge of the JavaPOS models and the APIs of the device.

Architectural Overview Appendix Overview B-3
Appendix Overview
This appendix contains the following major sections:
Section Name Developer Audience

What Is “Java for Retail POS?” Application and System
Architectural Overview (page B-3) Application and System
Device Behavior Models (page B-6) Application and System
Classes and Interfaces (page B-31) Application and System
Device Controls (page B-46) System
Device Services (page B-55) System
Architectural Overview
JavaPOS defines a multi-layered architecture in which a POS Application

interacts with the Physical or Logical Device through the JavaPOS Device.
POS
Application
JavaPOS
Device JavaPOS API
Interface
JavaPOS
Device JavaPOS Device
Control
JavaPOS
Device
Service
Interface
JavaPOS Device
Service
Physical (or Logical)

Device

Architectural Components
The POS Application (or Application) is either a Java Application or applet that
uses one or more JavaPOS Devices. An application accesses the JavaPOS Device
through the JavaPOS Device Interface, which is specified by Java interfaces.
JavaPOS Devices are divided into categories called Device Categories, such as
Cash Drawer and POS Printer.
Each JavaPOS Device is a combination of these components:
• JavaPOS Device Control (or Device Control) for a device category. The
Device Control class provides the interface between the Application and the
device category. It contains no graphical component and is therefore invisible
at runtime, and conforms to the JavaBeans API.
The Device Control has been designed so that all implementations of a device
category’s control will be compatible. Therefore, the Device Control can be
developed independently of a Device Service for the same device category
(they can even be developed by different companies).
• JavaPOS Device Service (or Device Service), which is a Java class that is
called by the Device Control through the JavaPOS Device Service Interface
(or Service Interface). The Device Service is used by the Device Control to
implement JavaPOS-prescribed functionality for a Physical Device. It can
also call special event methods provided by the Device Control to deliver
events to the Application.
A set of Device Service classes can be implemented to support Physical
Devices with multiple Device Categories.
The Application manipulates the Physical Device (the hardware unit or
peripheral) by calling the JavaPOS Device APIs. Some Physical Devices support
more than one device category. For example, some POS Printers include a Cash
Drawer kickout, and some Bar Code Scanners include an integrated Scale.
However with JavaPOS, an application treats each of these device categories as if
it were an independent Physical Device. The JavaPOS Device writer is
responsible for presenting the peripheral in this way.
Note: Occasionally, a Device may be implemented in software with no user-
exposed hardware, in which case it is called a Logical Device.

Architectural Overview Architectural Components B-5
Additional Layers and APIs

The JavaPOS architecture contains additional layers and APIs in order to
integrate well with the Java development environment.
POS
Java
Application Device
JavaPOS JavaPOS API
Interface
Device JDK
Interface
JavaPOS
JCL (Java
Device JavaPOS Device
Control
- Service
Configuration
Loader
JavaPOS Loader)
Device
Service
Interface
JavaPOS Device JER (JavaPOS
System
-
Service Entry Registry)
Database
JDK 1.2 Comm Port API
Serial Parallel
USB Proprietary
Driver Driver
Physical (or Logical)

Device
Note: Comm Port API refers to the Java Communications Port API (COM/API)
or optionally some other Java communications API that supports hardware
device connectivity.
JavaPOS Development Environment

JavaPOS will use these packages:
• JavaPOS Configuration / Loader (JCL) Added in Release 1.5
The jpos.config/loader (JCL) is a simple binding (configuration and loading)
API which enables a JavaPOS control to bind to the correct JavaPOS service
in a manner independent of the actual configuration mechanism. For POS
applications, it represents a somewhat minimum (however, extensible)
functional equivalent of the “NT Registry”, JposEntryRegistry.
All JavaPOS Device Controls should use this API.
• Communications Port API (for example, JavaComm v2.0 API), so that
Applications can make standard access to devices that may use serial (RS-
232), parallel, USB, and other future communication methods.

Device Behavior Models

Introduction to Properties, Methods, and Events
An application accesses a JavaPOS Device via the JavaPOS APIs.
The three elements of JavaPOS APIs are:
• Properties. Properties are device characteristics or settings. A type is
associated with each property, such as boolean or String. An application may
retrieve a property’s value, and it may set a writable property’s value.
JavaPOS properties conform to the JavaBean property design pattern.
To read a property value, use the method:
Type getSampleProperty() throws JposException;
where Type is the data type of the property and SampleProperty is the property
name.
To write a property value (assuming that the property is writable), use the
method:
void setSampleProperty(Type value) throws JposException;
where Type is the data type of the property and SampleProperty is the property
name.
• Methods. An application calls a method to perform or initiate some activity

at a device. Some methods require parameters of specified types for sending
and/or returning additional information.
A JavaPOS method has the form:
void sampleMethod(parameters) throws JposException;
where sampleMethod is the method name and parameters is a list of zero or
more parameters.
Since JavaPOS uses Method names that are consistent with OPOS some
Methods may appear to be Property getters/setters (for example, setDate page
600 in Fiscal Printer). BeanInfo classes are used to properly describe the
Properties and Methods to provide clarification so that various vendors
builder tools will properly function.
• Events. A JavaPOS Device may call back into the application via events. The
application must specifically register for each event type that it needs to
receive. JavaPOS events conform to the JavaBean event design pattern.
See “Events” on page B-15 for further details.

Device Behavior Models Device Initialization and Finalization B-7
Device Initialization and Finalization

Initialization
The first actions that an application must take to use a JavaPOS Device are:
• Obtain a reference to a JavaPOS Device Control, either by creating a new
instance or by accessing an existing one.
• Call Control methods to register for the events that the application needs to
receive. (See “Events” on page B-15.)
To initiate activity with the Physical Device, an application calls the Control’s
open method:
void open(String logicalDeviceName) throws JposException;
The logicalDeviceName parameter specifies a logical device to associate with the

JavaPOS Device. The open method performs the following steps:
1. Creates and initializes an instance of the proper Device Service class for the
specified name.
2. Initializes many of the properties, including the descriptions and version
numbers of the JavaPOS Device.
More than one instance of a Device Control may have a Physical Device open at
the same time. Therefore, after the Device is opened, an application might need to
call the claim method to gain exclusive access to it. Claiming the Device ensures
that other Device instances do not interfere with the use of the Device. An
application can release the Device to share it with another Device Control
instance– for example, at the end of a transaction.
Before using the Device, an application must set the DeviceEnabled property to
true. This value brings the Physical Device to an operational state, while false
disables it. For example, if a Scanner JavaPOS Device is disabled, the Physical
Device will be put into its non-operational state (when possible). Whether
physically operational or not, any input is discarded until the JavaPOS Device is
enabled.
Finalization
After an application finishes using the Physical Device, it should call the close
method. If the DeviceEnabled property is true, close disables the Device. If the
Claimed property is true, close releases the claim.
Before exiting, an application should close all open JavaPOS Devices to free
device resources in a timely manner, rather than relying on the Java garbage
collection mechanism to free resources at some indeterminate time in the future.

Summary
In general, an application follows this general sequence to open, use, and close a
Device:
• Obtain a Device Control reference.
• Register for events (add listeners).
• Call the open method to instantiate a Device Service and link it to the Device
Control.
• Call the claim method to gain exclusive access to the Physical Device.
Required for exclusive-use Devices; optional for some sharable Devices. (See
“Device Sharing Model” on page B-9 for more information).
• Set the DeviceEnabled property to true to make the Physical Device
operational. (For sharable Devices, the Device may be enabled without first
claiming it.)
• Use the device.
• Set the DeviceEnabled property to false to disable the Physical Device.
• Call the release method to release exclusive access to the Physical Device.
• Call the close method to unlink the Device Service from the Device Control.
• Unregister from events (remove listeners).

Device Behavior Models Device Sharing Model B-9

JavaPOS Devices fall into two sharing categories:
• Devices that are to be used exclusively by one JavaPOS Device Control
instance.
• Devices that may be partially or fully shared by multiple Device Control
instances.
Any Physical Device may be open by more than one Device Control instance at a
time. However, activities that an application can perform with a Device Control
may be restricted to the Device Control instance that has claimed access to the
Physical Device.
Note: Currently, device exclusivity and sharing can only be guaranteed within an
application’s Java Virtual Machine. This is because the Java language and
environment does not directly support inter-virtual machine communication or
synchronization mechanisms. At some time in the future, this restriction may be
lifted. Until then, the sharing model will typically be of little benefit because a
single application will seldom find value in opening a Physical Device through
multiple Device Control instances.

The most common device type is called an exclusive-use device. An example is
the POS printer. Due to physical or operational characteristics, an exclusive-use
device can only be used by one Device Control at a time. An application must call
the Device’s claim method to gain exclusive access to the Physical Device before
most methods, properties, or events are legal. Until the Device is claimed and
enabled, calling methods or accessing properties may cause a JposException
with an error code of JPOS_E_NOTCLAIMED, JPOS_E_CLAIMED, or
JPOS_E_DISABLED. No events are delivered until the Device is claimed.
An application may in effect share an exclusive-use device by calling the Device
Control’s claim method before a sequence of operations, and then calling the
release method when the device is no longer needed. While the Physical Device
is released, another Device Control instance can claim it.
When an application calls the claim method again (assuming it did not perform
the sequence of close method followed by open method on the device), some
settable device characteristics are restored to their condition at the release.
Examples of restored characteristics are the line display’s brightness, the MSR’s
tracks to read, and the printer’s characters per line. However, state characteristics
are not restored, such as the printer’s sensor properties. Instead, these are updated
to their current values.
Sharable Devices
Some devices are “sharable devices.” An example is the keylock. A sharable
device allows multiple Device Control instances to call its methods and access its
properties. Also, it may deliver its events to all Device Controls that have
registered listeners. A sharable device may still limit access to some methods or
properties to the Device Control that has claimed it, or it may deliver some events
only to the Device Control that has claimed it.

Device Behavior Models Data Types B-11
JavaPOS uses the following data types:
Type Usage
boolean Boolean true or false.
boolean[1] Mutable boolean.
byte 8-bit integer.
byte[] Immutable array of bytes.
Immutable array of binary objects (themselves presented as arrays of
byte[][]
bytes).
Mutable array of bytes. The [0] element contains the array of bytes that
byte[1][]
can be modified, both in size and/or contents.
int 32-bit integer.
int[] 32-bit integer array.
int[1] Mutable 32-bit integer.
Mutable 32-bit integer array. The [0] element contains the array of 32-bit
int[1][]
integers that can be modified, both in size and/or contents.
64-bit integer. Sometimes used for currency values, where 4 decimal
long places are implied. For example, if the integer is “1234567”, then the
currency value is “123.4567”.
long[1] Mutable 64-bit integer.
String Text character string.
String[1] Mutable text character string.
Point[] Array of points. Used by Signature Capture.
An object. This will usually be subclassed to provide a Device Service-
Object
specific parameter.
The convention of type[1] (an array of size 1) is used to pass a mutable basic type.
This is required since Java’s primitive types, such as int and boolean, are passed
by value, and its primitive wrapper types, such as Integer and Boolean, do not
support modification.
For strings and arrays, do not use a null value to report no information. Instead
use an empty string (“”) or an empty array (zero length).
In some chapters, an integer may contain a “bit-wise mask”. That is, the integer
data may be interpreted one or more bits at a time. The individual bits are
numbered beginning with Bit 0 as the least significant bit.

Exceptions
Every JavaPOS method and property accessor may throw a JposException upon
failure, except for the properties DeviceControlVersion,
DeviceControlDescription, and State. No other types of exceptions will be
thrown.
JposException is in the package jpos, and extends java.lang.Exception. The
constructor variations are:
public JposException(int errorCode);
public JposException(int errorCode, int errorCodeExtended);
public JposException(int errorCode, String description);
public JposException(int errorCode, int errorCodeExtended,
String Description);
public JposException(int errorCode, String description,
Exception origException);
public JposException(int errorCode, int errorCodeExtended,
String description, Exception origException)
The parameters are:

errorCode The JavaPOS error code. Access is through the

getErrorCode method.
errorCodeExtended May contain an extended error code. If not provided by
the selected constructor, then is set to zero. Access is
through the getErrorCodeExtended method.
description A text description of the error. If not provided by the
selected constructor, then one is formed from the
errorCode and errorCodeExtended parameters. Access
is through the superclass’ methods getMessage or
toString.
origException Original exception. If the JavaPOS Device caught a
non-JavaPOS exception, then an appropriate errorCode
is selected and the original exception is referenced by
this parameter. Otherwise, it is set to null. Access is
through the getOrigException method.

Device Behavior Models Exceptions B-13
ErrorCode Updated in Release 1.11

This section lists the general meanings of the error code property of an
ErrorEvent or a JposException. In general, the property and method
descriptions in later chapters list error codes only when specific details or
information are added to these general meanings.
The error code is set to one of the following values:
Value Meaning
JPOS_E_CLOSED An attempt was made to access a closed JavaPOS

Device.
JPOS_E_CLAIMED An attempt was made to access a Physical Device that
is claimed by another Device Control instance. The
other Control must release the Physical Device before
this access may be made. For exclusive-use devices, the
application will also need to claim the Physical Device
before the access is legal.
JPOS_E_NOTCLAIMED
An attempt was made to access an exclusive-use device
action can be used.
If the Physical Device is already claimed by another
Device Control instance, then the status
JPOS_E_CLAIMED is returned instead.
JPOS_E_NOSERVICE The Control cannot communicate with the Service,
JPOS_E_DISABLED Cannot perform this operation while the Device is
disabled.
JPOS_E_ILLEGAL An attempt was made to perform an illegal or
unsupported operation with the Device, or an invalid
parameter value was used.
JPOS_E_NOHARDWARE
The Physical Device is not connected to the system or
is not powered on.
JPOS_E_OFFLINE The Physical Device is off-line.
JPOS_E_NOEXIST The file name (or other specified value) does not exist.
JPOS_E_EXISTS The file name (or other specified value) already exists.
JPOS_E_FAILURE The Device cannot perform the requested procedure,
even though the Physical Device is connected to the
system, powered on, and on-line.

JPOS_E_TIMEOUT The Service timed out waiting for a response from the
Physical Device, or the Control timed out waiting for a
JPOS_E_BUSY The current Device Service state does not allow this
request. For example, if asynchronous output is in
progress, certain methods may not be allowed.
JPOS_E_EXTENDED A device category-specific error condition occurred.
The error condition code is available by calling
getErrorCodeExtended.
JPOS_E_DEPRECATED
The requested operation can not be performed since it
ErrorCodeExtended
The extended error code is set as follows:
• When errorCode is JPOS_E_EXTENDED, errorCodeExtended is set to a
device category-specific value, and must match one of the values given in this
document under the appropriate device category chapter.
• When errorCode is any other value, errorCodeExtended may be set by the
Service to any Device Service-specific value. These values are only
meaningful if an application adds Service-specific code to handle them.

Device Behavior Models Events B-15

Java for Retail POS uses events to inform the application of various activities or
changes with the JavaPOS Device. The five event types follow.
Supported When A
Event Class Description Device Category
Supports...
Input data has been placed into device
DataEvent Event-driven input
class-category properties.
Event-driven input
An error has occurred during event- -or-
ErrorEvent
driven input or asynchronous output. Asynchronous
output
An asynchronous output has Asynchronous
OutputCompleteEvent
successfully completed. output
A change in the Physical Device’s
status has occurred.
Release 1.3 and later: All Status change
StatusUpdateEvent
devices may be able to report device notification
power state. See “Device Power
Reporting Model” on page B-24.
This event may be defined by a Device
Always, for Service-
DirectIOEvent Service provider for purposes not
specific use
covered by the specification.
Each of these events contains the following properties:

Property Type Description
Source Object Reference to the Device Control delivering the event. If

the application defines a class that listens for events
from more than one Device, then it uses this property to
determine the Device instance that delivered the event.
SequenceNumber long JavaPOS event sequence number. This number is a
sequence number that is global across all JavaPOS
Devices. Each JavaPOS event increments the global
sequence number, then places its value in this property.
When long An event timestamp; value is set to
System.currentTimeMillis().
Chapter 1, “Events (UML interfaces)” on page 102, provides details about each
of these events, including additional properties.

The Device Service must enqueue these events on an internally created and
managed queue. All JavaPOS events are delivered in a first-in, first-out manner.
(The only exception is that a special input error event is delivered early if some
data events are also enqueued. See “Device Input Model” on page B-19.) Events
are delivered by an internally created and managed Device Service thread. The
Device Service causes event delivery by calling an event firing callback method
in the Device Control, which then calls each registered listener's event method in
the order in which they were added.
corrected:
DataEventEnabled is false. (See “Device Input Model” on page B-19.)
Rules for event queue management are:
• The JavaPOS Device may only enqueue new events while the Device is
enabled.
• The Device delivers enqueued events until the application calls the release
• For output devices, the clearOutput method clears output error events.
• The application returns from the JPOS_EL_INPUT_DATA ErrorEvent with
ErrorResponse set to JPOS_ER_CLEAR.

Device Behavior Models Events B-17
Registering for Events

JavaPOS events use the event delegation model first outlined in JDK 1.1. With
this model, an application registers for events by calling a method supplied by the
event source, which is the Device Control. The method is supplied a reference to
an application class that implements a listener interface extended from
java.util.EventListener.
The following table specifies the event interfaces and methods for each event
class:
Listener Interface and
Methods Source Methods
Event Class
Implemented in an Implemented in the Device Control
application class
DataListener addDataListener (DataListener l)
DataEvent
dataOccurred (DataEvent e) removeDataListener (DataListener l)
ErrorListener addErrorListener (ErrorListener l)
ErrorEvent
errorOccurred (ErrorEvent e) removeErrorListener (ErrorListener l)
addStatusUpdateListener
StatusUpdateListener
(StatusUpdateListener l)
StatusUpdateEvent statusUpdateOccurred
removeStatusUpdateListener
(StatusUpdateEvent e)
(StatusUpdateListener l)
addOutputCompleteListener
OutputCompleteListener
(OutputCompleteListener l)
OutputCompleteEvent outputCompleteOccurred
removeOutputCompleteListener
(OutputCompleteEvent e)
(OutputCompleteListener l)
addDirectIOListener
DirectIOListener
(DirectIOListener l)
DirectIOEvent directIOOccurred
removeDirectIOListener
(DirectIOEvent e)
(DirectIOListener l)
Although more than one listener may be registered for an event type, the typical
case is for only one listener, or at least only one primary listener. This listener
takes actions such as processing data events and direct I/O events, and responding
to error events.
Event Delivery
A Device delivers an event by calling the listener method of each registered
listener. The listener processes the event, then returns to the Device Control.
An application must not assume that events are delivered in the context of any
particular thread. The JavaPOS Device delivers events on a privately created and
managed thread. It is an application’s responsibility to synchronize event
processing with its threads as needed.
While an application is processing an event within its listener method, no
additional events will be delivered by the Device.
While within a listener method, an application may access properties and call
methods of the Device. However, an application must not call the release or close
methods from an event method, because the release method may shut down event
handling (possibly including a thread on which the event was delivered) and close
must shut down event handling before returning.

JavaPOS Event Registration Sequence Diagram Added in Release 1.7

The following sequence diagram shows how applications register for events with
JavaPOS Controls, via classes implementing the JavaPOS event listener interface.
NOTE: this diagram shows the typical event registration process for a device service in JavaPOS. Various details are omitted on
purpose to make the diagram clearer. Also, DevCat == POSPrinter, CashDrawer, Keylock ... and other UnifiedPOS device categories.
:ClientApp :<JposEvent> :<DevCat> :<JposEvent> :<DevCat>Service

Listener
<JposEvent>Listener is a generic moniker for a class

implementing one of the jpos.events.<JposEvent>Listener
interfaces. This can be the application class or some
inner class or other class.
1: new
2: add<JposEvent>Listener(:<JposEventListener) We are assuming that

the open() call is
successful and that the
3: maintains a list of registered listeners
control is bound with its
service
Some devices (exclusive-use) need to be

claimed before being enabled (this is not
shown here)
For DataEvent you also need the 8: some hardware event occurred causing a JposEvent
DataEventEnabled property to be true. It will
be set to false once the event is delivered. 9: new
At this point some

application code executes 11: deliver events to all listeners 10: deliver :<JposEvent> to control [FreezeEvents == false]
in the listener class or by
having the listener object
call some other method 12: appropriate listener method is called
on some application
object [the details are
implied and not shown]
15: close() 16: close()

No more events will be delivered to the
listener object
17: remove<JposEvent>Listener(:<JposEventListener>)
18: update list
The delivery of events from a JavaPOS Service is almost always performed

asynchronously to calls by clients; that is, once the clients have registered their
<JposEvent>Listener objects with the Control, these listener objects will be
called back – appropriate <jposEvent>Occurred() method – in a separate thread
than the application thread. The event thread is usually a service thread that
operates on an event queue, delivering all posted events from the queue to the
Controls depending on whether the FreezeEvents property is true.

Device Behavior Models Device Input Model B-19
Device Input Model

The standard JavaPOS input model for exclusive-use devices is event-driven
input. Event-driven input allows input data to be received after DeviceEnabled is
set to true. Received data is enqueued as a DataEvent, which is delivered to an
application as detailed in the “Events” (page B-15). If the AutoDisable property
is true when data is received, then the JavaPOS Device will automatically disable
itself, setting DeviceEnabled to false. This will inhibit the Device from
enqueuing further input and, when possible, physically disable the device.
When the application is ready to receive input from the JavaPOS Device, it sets
the DataEventEnabled property to true. Then, when input is received (usually as
a result of a hardware interrupt), the Device delivers a DataEvent. (If input has
already been enqueued, the DataEvent will be delivered immediately after
DataEventEnabled is set to true.) The DataEvent may include input status
information through its Status property. The Device places the input data plus
other information as needed into device category-specific properties just before
Just before delivering this event, the JavaPOS Device disables further data events
by setting the DataEventEnabled property to false. This causes subsequent input
data to be enqueued by the Device while an application processes the current
input and associated properties. When an application has finished the current
input and is ready for more data, it enables data events by setting

Error Handling Updated in Release 1.12

If the JavaPOS Device encounters an error while gathering or processing event-
driven input, then the Device:
• Changes its state to JPOS_S_ERROR.
• Enqueues an ErrorEvent with locus JPOS_EL_INPUT to alert an application
of the error condition. This event is added to the end of the queue
• If one or more DataEvents are already enqueued for delivery, an additional
ErrorEvent with locus JPOS_EL_INPUT_DATA is enqueued before the
DataEvents, as a pre-alert.
This event (or events) is not delivered until the DataEventEnabled property is
true, so that orderly application sequencing occurs.
ErrorLocus Description
Only delivered if the error occurred when one or more
DataEvents are already enqueued.
This event gives the application the ability to immediately clear
the input, or to optionally alert the user to the error before
processing the buffered input. This error event is enqueued
before the oldest DataEvent, so that an application is alerted of
JPOS_EL_INPUT_DATA the error condition quickly.
This locus was created especially for the Scanner: When this
error event is received from a Scanner JavaPOS Device, the
operator can be immediately alerted to the error so that no
further items are scanned until the error is resolved. Then, the
application can process any backlog of previously scanned
items before error recovery is performed.
Delivered when an error has occurred and there is no data
available.
If some input data was buffered when the error occurred, then
an ErrorEvent with the locus JPOS_EL_INPUT_DATA was
JPOS_EL_INPUT delivered first, and then this error event is delivered after all
DataEvents have been delivered.
Note: This JPOS_EL_INPUT event is not delivered if: an
JPOS_EL_INPUT_DATA event was delivered and the
application event handler responded with a JPOS_ER_CLEAR.

Device Behavior Models Device Input Model B-21
The application’s event listener method can set the ErrorResponse property to
one of the following:
Clear the buffered DataEvents and ErrorEvents and exit
JPOS_ER_CLEAR the error state, changing State to JPOS_S_IDLE.
This is the default response for locus JPOS_EL_INPUT.
This response acknowledges the error and directs the
Device to continue processing. The Device remains in the
error state, and will deliver additional data events as
input has been delivered and the DataEventEnabled
JPOS_ER_CONTINUEINPUT property is again set to true, another ErrorEvent is
delivered with locus JPOS_EL_INPUT.
This is the default response when the locus is
JPOS_EL_INPUT_DATA, and is legal only with this
locus.
This response directs the Device to retry the input. The
error state is exited, and State is changed to
JPOS_S_IDLE.
JPOS_ER_RETRY
This response may only be selected when the device
chapter specifically allows it and when the locus is
JPOS_EL_INPUT. An example is the scale.
The Device exits the Error state when one of the following occurs:
• The application returns from the JPOS_EL_INPUT ErrorEvent.
• The application returns from the JPOS_EL_INPUT_DATA ErrorEvent.
• The application calls the clearInput method.
Miscellaneous
For some Devices, the Application must call a method to begin event driven
input. After the input is received by the Device, then typically no additional input
will be received until the method is called again to re-initiate input. Examples are
The DataCount property contains the number of DataEvents enqueued by the
JavaPOS Device.
Calling the clearInput method deletes all input enqueued by a JavaPOS Device.
clearInput may be called after open for sharable devices and after claim for
Calling the clearInputProperties method sets all data properties, that were
of device categories containing methods or properties that return input data
directly. Some device categories define such methods and properties in order to
operate in a more intuitive or flexible manner. An example is the Keylock Device.
This type of input is sometimes called “synchronous input.”

Device Output Models

The Java for Retail POS output model consists of two output types: synchronous
and asynchronous. A device category may support one or both types, or neither
type.
Synchronous Output
The application calls a category-specific method to perform output. The JavaPOS
Device does not return until the output is completed.
This type of output is preferred when device output can be performed relatively
quickly. Its merit is simplicity.

The application calls a category-specific method to start the output. The JavaPOS
Device validates the method parameters and throws an exception immediately if
necessary. If the validation is successful, the JavaPOS Device does the following:
1. Buffers the request in program memory, for delivery to the Physical Device as
soon as the Physical Device can receive and process it.
2. Sets the OutputID property to an identifier for this request.
3. Returns as soon as possible.
When the JavaPOS Device successfully completes a request, an
OutputCompleteEvent is enqueued for delivery to the application. A property of
this event contains the output ID of the completed request. If the request is
terminated before completion, due to reasons such as the application calling the
clearOutput method or responding to an ErrorEvent with a JPOS_ER_CLEAR
response, then no OutputCompleteEvent is delivered.
to the application. If the response is JPOS_ER_CLEAR, then outstanding
asynchronous output is cleared. If the response is JPOS_ER_RETRY, then output
is retried; note that if several outputs were simultaneously in progress at the time
that the error was detected, then the Service may need to retry all of these outputs.
Note: Asynchronous output is always performed on a first-in first-out basis.

Device Behavior Models Device Output Models B-23
Error Handling
If an error occurs while performing an asynchronous request, the error state
JPOS_S_ERROR is entered and an ErrorEvent is enqueued with the
ErrorLocus property set to JPOS_EL_OUTPUT. The application is guaranteed
that the request in error is the one following the request whose output ID was
most recently reported by an OutputCompleteEvent. An application’s event
listener method can set the ErrorResponse property to one of the following:
Clear the outstanding output and exit the error state (to
JPOS_ER_CLEAR
JPOS_S_IDLE).
Exit the error state (to JPOS_S_BUSY) and retry the
outstanding output. If the condition that caused the error was not
JPOS_ER_RETRY corrected, then the Device may immediately reenter the error
state and enqueue another ErrorEvent.
This is the default response.
Miscellaneous Updated in Release 1.7

Calling the clearOutput method deletes all buffered output data, including all
asynchronous output, buffered by the JavaPOS Device. This method also stops
any output that may be in progress (when possible).
Note: Currently, only the POS printer uses the complete Asynchronous Output
model described here. Other device categories use portions of the model.


Added in JavaPOS Release 1.3, Updated in Release 1.8.
Earlier Releases of JavaPOS had no consistent method for reporting this
information. Note: This model is not intended to report Workstation or POS
Terminal power conditions (such as “on battery” and “battery low”). Reporting of
these conditions is now managed by the POSPower device category, see page
927.
Model
JavaPOS segments device power into three states:
• ONLINE. The device is powered on and ready for use. This is the
• OFF. The device is powered off or detached from the terminal. This is a “non-
• OFFLINE. The device is powered on but is either not ready or not able to
• OFF_OFFLINE. The device is either off or offline, and the Device Service
cannot distinguish these states.
Note - Enabled/Disabled vs. Power States

These states are different and usually independent. JavaPOS defines “disabled” /
“enabled” as a logical state, whereas the power state is a physical state. A device may
be logically “enabled” but physically “offline”. It may also be logically “disabled” but
physically “online”. Regardless of the physical power state, JavaPOS only reports the
state while the device is enabled. (This restriction is necessary because a Device Service
typically can only communicate with the device while enabled.)
If a device is “offline”, then a Device Service may choose to fail an attempt to “enable”
the device. However, once enabled, the Device Service may not disable a device based
on its power state.

Device Behavior Models Device Power Reporting Model B-25
Properties
The JavaPOS device power reporting model adds the following common
elements across all device classes:
• CapPowerReporting property. Identifies the reporting capabilities of the
device. This property may be one of:
• JPOS_PR_NONE. The Device Service cannot determine the state of the
• JPOS_PR_STANDARD. The Device Service can determine and report
two of the power states - OFF_OFFLINE (that is, off or offline) and
ONLINE.
• JPOS_PR_ADVANCED. The Device Service can determine and report
all three power states - ONLINE, OFFLINE, and OFF.
• PowerState property. Maintained by the Device Service at the current power
condition, if it can be determined. This property may be one of:
• JPOS_PS_UNKNOWN
• JPOS_PS_ONLINE
• JPOS_PS_OFF
• JPOS_PS_OFFLINE
• JPOS_PS_OFF_OFFLINE
• PowerNotify property. The application may set this property to enable power
property may only be set before the device is enabled (that is, before
DeviceEnabled is set to true). This restriction allows simpler implementation
of power notification with no adverse effects on the application. The
application is either prepared to receive notifications or doesn't want them,
and has no need to switch between these cases. This property may be one of:
• JPOS_PN_DISABLED
• JPOS_PN_ENABLED


CapPowerReporting is not JPOS_PR_NONE, and
PowerNotify is JPOS_PN_ENABLED:
• When the Control changes from DeviceEnabled false to true, then begin
• If the Physical Device is ONLINE, then:
PowerState is set to JPOS_PS_ONLINE.
JPOS_SUE_POWER_ONLINE.
• If the Physical Device’s power state is OFF, OFFLINE, or
OFF_OFFLINE, then the Device Service may choose to fail the enable by
throwing a JposException with error code JPOS_E_NOHARDWARE or
JPOS_E_OFFLINE.
the Device Service chooses to return success for the enable, then:
PowerState is set to JPOS_PS_OFF, JPOS_PS_OFFLINE, or
JPOS_PS_OFF_OFFLINE.
JPOS_SUE_POWER_OFF, JPOS_SUE_POWER_OFFLINE,
or JPOS_SUE_POWER_OFF_OFFLINE.
• When the Device changes from DeviceEnabled true to false, JavaPOS
assumes that the Device is no longer monitoring the power state and sets the
value of PowerState to JPOS_PS_UNKNOWN.

Device Behavior Models Device Information Reporting Model B-27
Device Information Reporting Model Added in Release 1.8.

Hours Running, etc. See page 63 for examples of XML definitions of the device
when required. This is done by using the claim and setDeviceEnabled(true)
methods when access to a device is required and using the
setDeviceEnabled(false) and release methods when access to the device is no
longer needed. Coordination of device access via this mechanism is the
responsibility of the applications themselves.
device. When CapStatisticsReporting is false, then no statistical data
true, then statistical data for the device is available.
CapStatisticsReporting is true. When CapUpdateStatistics is false, then
none of the statistical data can be reset/updated by the application. Otherwise,
when CapUpdateStatistics is true, then (some of) the statistical data can be
reset/updated by the application.
• resetStatistics method. Can only be called if both CapStatisticsReporting
and CapUpdateStatistics are true. This method resets one, some, or all of the
resettable device statistics to zero.
• retrieveStatistics method. Can only be called if CapStatisticsReporting is
true. This method retrieves one, some, or all of the accumulated statistics for
the device.
• updateStatistics method. Can only be called if both CapStatisticsReporting
and CapUpdateStatistics are true. This method updates one, some, or all of
the resettable device statistics to the supplied values.


by a UnifiedPOS control.
firmware updating.
device.
• A method, updateFirmware, to perform an asynchronous update of the
• A method, compareFirmwareVersion, to compare the firmware file’s
device categories defined in UnifiedPOS.
The means by which a Service actually updates the firmware in the device is not
covered by this document, only the means by which the update firmware process
is started and progress is reported.

Device Behavior Models Device States B-29
Device States
JavaPOS defines a property State with the following values:
JPOS_S_CLOSED
JPOS_S_IDLE
JPOS_S_BUSY
JPOS_S_ERROR
The State property is set as follows:
• State is initially JPOS_S_CLOSED.
• State is changed to JPOS_S_IDLE when the open method is successfully
called.
• State is set to JPOS_S_BUSY when the Device Service is processing output.
The State is restored to JPOS_S_IDLE when the output has completed.
• The State is changed to JPOS_S_ERROR when an asynchronous output
encounters an error condition, or when an error is encountered during the
gathering or processing of event-driven input.
After the Device Service changes the State property to JPOS_S_ERROR, it
enqueues an ErrorEvent. The properties of this event are the error code and
extended error code, the locus of the error, and a mutable response to the error.
See Input Model, Error Handling on page B-20 and Output Model, Error
Handling on page B-23 for further details.

Threads
The Java language directly supports threads, and an application may create
additional threads to perform different jobs. The use of threads can add
complexity, however, often requiring synchronization to arbitrate sharing of
resources. For applications that share a control instance among multiple threads,
actions of one thread may have undesirable effects on the other thread(s). For
example, cancelled I/O (e.g., clearOutput) can result in any pending
synchronous requests of other threads being completed with a JPOS exception
with an error code of JPOS_E_FAILURE. These situations can be avoided by
insuring a control instance is managed by a single thread.
An application must be aware of multiple threads in the following cases:
• Properties and Methods. Calling some JavaPOS methods or setting some
properties can cause other property values to be changed. When an application
needs to access these properties, it must either access the properties and
methods from only one thread, or ensure that its threads synchronize these
sequences as required.
• Events. An application must not assume that events are delivered in the
context of any particular thread. The JavaPOS Device typically will deliver
events on a privately created and managed thread. It is an application’s
responsibility to synchronize event processing with its threads if necessary.
Version Handling
As JavaPOS evolves, additional releases will introduce enhanced versions of
some Devices. JavaPOS imposes the following requirements on Device Control
and Service versions:
• Device Control requirements. A Device Control for a device category must
operate with any Device Service for that category, as long as its major version
number matches the Service's major version number. If they match, but the
Control's minor version number is greater than the Service’s minor version
number, the Control may support some new methods or properties that are not
supported by the Service’s release. If an application calls one of these methods
or accesses one of these properties, a JposException with error code
JPOS_E_NOSERVICE will be thrown.
• Device Service requirements. A Device Service for a device category must
operate with any Device Control for that category, as long as its major version
number matches the Control's major version number. If they match, but the
Service's minor version number is greater than the Control's minor version
number, then the Service may support some methods or properties that cannot
be accessed from the Control.
When an application wishes to take advantage of the enhancements of a version,
it must first determine that the Device Control and Device Service are at the
proper major version and at or greater than the proper minor version. The
versions are reported by the properties DeviceControlVersion and
DeviceServiceVersion.

Classes and Interfaces Synopsis B-31
Classes and Interfaces

Synopsis
This section lists the JavaPOS classes and interfaces used by applications, Device Controls and
Device Services. Further details about their usage appear later in this document.
In the tables that follow, the following substitutions should be made for italic type:
Substitution
Description
Name
Replace with one of the five event types:
Event
Data, Error, OutputComplete, StatusUpdate, DirectIO
Replace with one of the five event types:
event
data, error, outputComplete, statusUpdate, directIO
Replace with one of the device categories:
BumpBar, CashChanger, CashDrawer, CAT, CoinDispenser, FiscalPrinter,
Devcat HardTotals, Keylock, LineDisplay, MICR, MSR, PINPad, PointCardRW,
POSKeyboard, POSPower, POSPrinter, RemoteOrderDisplay, Scale, Scanner,
SignatureCapture, ToneIndicator
Replace with the JavaPOS release number. For example, Release 1.2 is shown as 12.
Rr When an interface or class uses a release number, interfaces for later releases at the same
major version number extend the previous release's interface or class.
Replace with the JavaPOS release number prior to Rr. For example, if Rr is 13, then Pp
Pp
is 12.
The classes and interfaces defined or used by JavaPOS are summarized in the following tables,
organized by the software entity that implements them.
Application
Class or
Name Description Extends / Implements
Interface
Application defines and registers a class
that implements this interface. Events
jpos.EventListener are delivered by calling the Extends:
Interface java.util.EventListener
(Ex: DataListener) eventOccurred (ex: dataOccurred)
method of this interface with an
EventEvent (ex: DataEvent) instance.

Device Control
Class or
Interface
Implements:
jpos.DevcatControlRr
jpos.Devcat (ex: ScannerControl12,
Device Control Class. POSPrinterControl13)
Class (ex: Scanner, One fixed name per device category. Implements (as an Inner
POSPrinter)
Class): jpos.services.
EventCallbacks
Extends either:
jpos.DevcatControlRr Contains the methods and properties jpos.BaseControl
(for first release) or
Interface (ex: ScannerControl12, specific to Device Controls for this
jpos.DevcatControlPp
POSPrinterControl13) device category and release. (for later releases) (ex:
POSPrinterControl13)
Contains the methods and properties
Interface jpos.BaseControl --
common to all Device Controls.
Includes one callback method per
jpos.services. event type. The Device Service calls
Interface EventCallbacks --
these methods to cause events to be
delivered to the application.
Device Service
Class or
Interface
Implements:
jpos.services.
Class Vendor-defined name Device Service Class. DevcatServiceRr
(ex: ScannerService12,
POSPrinterService13)
Extends either:
jpos.services.
jpos.services. BaseService
DevcatServiceRr Contains the methods and properties
(for first release) or
Interface specific to Device Services for this
(ex: ScannerService12, jpos.services.
device category and release. DevcatServicePp
(for later releases) (ex:
jpos.services. Contains the methods and properties
Interface --
BaseService common to all Device Services.

Classes and Interfaces Synopsis B-33
Helper Classes
Class or
Interface
Interface containing the JavaPOS
Interface jpos.JposConst constants that are common to several --
device categories.
jpos.DevcatConst Interface containing the JavaPOS
Interface (ex: ScannerConst, constants specific to a device --
POSPrinterConst) category.
Abstract class from which all Extends:

Class jpos.JposEvent java.util.EventObject
JavaPOS event classes are extended.
The Device Service creates Event
jpos.EventEvent event instances of this class and
Extends:
Class delivers them through the Device jpos.JposEvent
(ex: DataEvent) Control’s event callbacks to the
application.
Exception class. The Device Control

and Device Service create and throw Extends:
Class jpos.JposException java.lang.Exception
exceptions on method and property
access failures.

Sample Class and Interface Hierarchies

The following example class hierarchies are given for the scanner Release 1.2
(the initial Release) and for the printer (Release 1.3). Assume that neither Device
Service generates any DirectIO events in which the application is interested.
Application Sample
“MyApplication” class hierarchy:
• DataListener. Implement to receive Scanner data events.
• ErrorListener. Implement to receive Scanner and POSPrinter error
events.
• OutputCompleteListener. Implement to receive POSPrinter output
complete events.
• StatusUpdateListener. Implement to receive POSPrinter status update
events.
(Frequently, an application will define additional classes that implement one
or more of the listener interfaces.)
The “MyApplication” Application class also uses the following:
• Scanner and POSPrinter. Instances of the Device Controls.
• JposConst, ScannerConst, and POSPrinterConst. Use constants, either
by fully qualified package names or by adding to the “implements” clause
of an application class.
• DataEvent. Instance of this class received by the DataListener's method
dataOccurred.
• ErrorEvent. Instance of this class received by the ErrorListener's
method errorOccurred.
• OutputCompleteEvent. Instance of this class received by the
OutputCompleteListener's method outputCompleteOccurred.
• StatusUpdateEvent. Instance of this class received by the
StatusUpdateListener's method statusUpdateOccurred.
• JposException. Instance of this class is caught when a Scanner or
POSPrinter method or property access fails.
Device Control Sample

Scanner
Scanner class hierarchy:
• ScannerControl12. Implement scanner’s methods and properties.
• EventCallbacks. Derive an inner class to pass to Service so that it may
generate events.

Classes and Interfaces Sample Class and Interface Hierarchies B-35
The Scanner Control class also uses the following:

• JposConst and ScannerConst. Use constants, either by fully qualified
package names or by adding to the “implements” clause of the Device
Control.
• JposException. Instance of this class is thrown when a method or
property access fails.
POSPrinter
POSPrinter class hierarchy:
• POSPrinterControl13. Implement printer’s methods and properties and
extends POSPrinterControl12.
• EventCallbacks. Derive an inner class to pass to Service so that it may
generate events.
The POSPrinter Control class also uses the following:
• JposConst and POSPrinterConst. Use constants, either by fully
qualified package names or by adding to the “implements” clause of the
Device Control.
Device Service Sample

“MyScannerService”
“MyScannerService” class hierarchy:
• ScannerService12. Implement scanner’s methods and properties.
The “MyScannerService” Service class also uses the following:
• JposConst and ScannerConst. Use constants, either by fully qualified
package names or by adding to the “implements” clause of the Device
Service.
• DataEvent. Instance of this class created as data is received. It is
delivered to an application when the event delivery preconditions are met
by calling the fireDataEvent method of the Control's derived
EventCallbacks class.
• ErrorEvent. Instance of this class created when an error is detected while
reading scanner data. It is delivered to an application when the event
delivery preconditions are met by calling the fireErrorEvent method of
the Control's derived EventCallbacks class.

“MyPrinterService”
“MyPrinterService” class hierarchy:
• POSPrinterService13. Implement printer’s methods and properties and
extends POSPrinterService12.
The “MyPrinterService” Service class also uses the following:
• JposConst and POSPrinterConst. Use constants, either by fully
qualified package names or by adding to the “implements” clause of the
Device Service.
• ErrorEvent. Instance of this class created when an error is detected while
printing asynchronous data. It is delivered to an application when the
event delivery preconditions are met by calling the fireErrorEvent
method of the Control's derived EventCallbacks class.
• OutputCompleteEvent. Instance of this class created when an
asynchronous output request completes. It is delivered to an application
when the event delivery preconditions are met by calling the
fireOutputCompleteEvent method of the Control's derived
EventCallbacks class.
• StatusUpdateEvent. Instance of this class created when a printer status
change is detected. It is delivered to an application when the event
delivery preconditions are met by calling the fireStatusUpdateEvent
method of the Control's derived EventCallbacks class.

Classes and Interfaces Sample Application Code B-37
Sample Application Code

The following code snippet shows how to use a scanner.
//import ...;
import jpos.*;
import jpos.events.*;
public class MyApplication implements DataListener

{
// Data listener’s method to process incoming scanner data.
public void dataOccurred(DataEvent e)
{
jpos.Scanner dc = (jpos.Scanner) e.getSource();
String Msg = “Scanner DataEvent (Status=” + e.getStatus() +
“) received.”;
System.out.println (Msg);
try {
dc.setDataEventEnabled(true);
} catch (JposException e){}
}
// Method to initialize the scanner.

public void initScanner(String openName) throws jpos.JposException
{
// Create scanner instance and register for data events.
jpos.Scanner myScanner1 = new jpos.Scanner();
myScanner1.addDataListener(this);
// Initialize the scanner. Exception thrown if a method fails.
myScanner1.open(openName);
myScanner1.claim(1000);
myScanner1.setDeviceEnabled(true);
myScanner1.setDataEventEnabled(true);
//...Success! Continue doing work...
}
//...Other methods, including main...

}

Package Structure Updated in Release 1.12

The JavaPOS packages and files are as follows:
Note: The only difference between Release 1.3 and Release 1.4 of JavaPOS is
the inclusion of the CAT device. No other technical changes were made.
Therefore the JavaPOS packages and files for devices covered under Release
1.3 may be used for Release 1.4.
Additional device classifications of Point Card Reader Writer and POSPower

were added in Release 1.5.
No new devices were added for Release 1.6, however additional functionality
was added to some devices.
Additional device classifications of Check Scanner and Motion Sensor were

added in Release 1.7.
Additional device classification of Smart Card Reader Writer was added in

Release 1.8 and additional functionality was added to all devices.
No new devices were added for Release 1.9, however additional functionality
was added to all devices.
Additional device classifications of Biometrics and Electronic Journal were

added in Release 1.10 and additional functionality was added to all devices.
Additional device classifications of Bill Acceptor, Bill Dispenser, Coin

Acceptor, and Image Scanner were added in Release 1.11, and additional
functionality was added to some devices.
Additional device classifications of Belt, Electronic Value Reader Writer, Gate,

ItemDispenser, Lights, and RFIDScanner were added in Release 1.12, and
additional functionality was added to some devices.

Classes and Interfaces Package Structure B-39
jpos
BaseControl.java
JposConst.java
JposException.java
CashChanger.java MSR.java
CashChangerBeanInfo.java MSRBeanInfo.java
CashChangerConst.java MSRConst.java
CashChangerControl12.java MSRControl12.java
CashDrawer.java POSKeyboard.java
CashDrawerBeanInfo.java POSKeyboardBeanInfo.java
CashDrawerConst.java POSKeyboardConst.java
CashDrawerControl12.java POSKeyboardControl12.java
CoinDispenser.java POSPrinter.java
CoinDispenserBeanInfo.java POSPrinterBeanInfo.java
CoinDispenserConst.java POSPrinterConst.java
CoinDispenserControl12.java POSPrinterControl12.java
HardTotals.java Scale.java
HardTotalsBeanInfo.java ScaleBeanInfo.java
HardTotalsConst.java ScaleConst.java
HardTotalsControl12.java ScaleControl12.java
Keylock.java Scanner.java
KeylockBeanInfo.java ScannerBeanInfo.java
KeylockConst.java ScannerConst.java
KeylockControl12.java ScannerControl12.java
LineDisplay.java SignatureCapture.java
LineDisplayBeanInfo.java SignatureCaptureBeanInfo.java
LineDisplayConst.java SignatureCaptureConst.java
LineDisplayControl12.java SignatureCaptureControl12.java
MICR.java ToneIndicator.java
MICRBeanInfo.java ToneIndicatorBeanInfo.java
MICRConst.java ToneIndicatorConst.java
MICRControl12.java ToneIndicatorControl12.java
New Peripheral Device Classes Added in Release 1.3
BumpBar.java PINPad.java
BumpBarBeanInfo.java PINPadBeanInfo.java
BumpBarConst.java PINPadConst.java
BumpBarControl13.java PINPadControl13.java
FiscalPrinter.java RemoteOrderDisplay.java
FiscalPrinterBeanInfo.java RemoteOrderDisplayBeanInfo.java
FiscalPrinterConst.java RemoteOrderDisplayConst.java
FiscalPrinterControl13.java RemoteOrderDisplayControl13.java
New Interfaces for existing Device Classes for Release 1.3
CashChangerControl13.java MSRControl13.java
New Peripheral Device Class Added in Release 1.4
CAT.java
CATBeanInfo.java
CATConst.java
CATControl14.java

BumpBarControl14.java MSRControl14.java
CashChangerControl14.java PINPadControl14.java
PointCardRW.java POSPower.java
PointCardRWBeanInfo.java POSPowerBeanInfo.java
PointCardRWConst.java POSPowerConst.java
PointCardRWControl15.java POSPowerControl15.java
CATControl15.java POSPrinterControl15.java
CoinDispenserControl15.java RemoteOrderDisplayControl15.java
FiscalPrinterControl15.java ScaleControl15.java
HardTotalsControl15.java ScannerControl15.java
KeylockControl15.java SignatureCaptureControl15.java
LineDisplayControl15.java ToneIndicatorControl15.java
MICRControl15.java
CashChangerControl16.java PointCardRWControl16.java
CATControl16.java POSPowerControl16.java
MSRControl16.java
CheckScanner.java MotionSensor.java
CheckScannerBeanInfo.java MotionSensorBeanInfo.java
CheckScannerConst.java MotionSensorConst.java
CheckScannerControl17.java MotionSensorControl17.java
CashChangerControl17.java PointCardRWControl17.java
CATControl17.java POSPowerControl17.java
MSRControl17.java

New Peripheral Device Class Added in Release 1.8
SmartCardRW.java
SmartCardRWBeanInfo.java
SmartCardRWConst.java
SmartCardRWControl18.java
CashDrawerControl18.java PointCardRWControl18.java
CATControl18.java POSKeyboardControl18.java
CheckScannerControl18.java POSPowerControl18.java
MotionSensorControl18.java
MICRControl19.java SmartCardRWControl19.java
MotionSensorControl19.java ToneIndicatorControl19.java
Biometrics.java ElectronicJournal.java
BiometricsBeanInfo.java ElectronicJournalBeanInfo.java
BiometricsConst.java ElectronicJournalConst.java
BiometricsControl110.java ElectronicJournalControl110.java
MICRControl110.java SmartCardRWControl110.java
MotionSensorControl110.java ToneIndicatorControl110.java

BillAcceptor.java CoinAcceptor.java
BillAcceptorBeanInfo.java CoinAcceptorBeanInfo.java
BillAcceptorConst.java CoinAcceptorConst.java
BillAcceptorControl111.java CoinAcceptorControl111.java
BillDispenser.java ImageScanner.java
BillDispenserBeanInfo.java ImageScannerBeanInfo.java
BillDispenserConst.java ImageScannerConst.java
BillDispenserControl111.java ImageScannerControl111.java
BiometricsControl111.java MotionSensorControl111.java
ElectronicJournalControl111.java RemoteOrderDisplayControl111.java
FiscalPrinterControl111.java ScaleControl111.java
HardTotalsControl111.java ScannerControl111.java
KeylockControl111.java SignatureCaptureControl111.java
LineDisplayControl111.java SmartCardRWControl111.java
Belt.java ItemDispenser.java
BeltBeanInfo.java ItemDispenserBeanInfo.java
BeltConst.java ItemDispenserConst.java
BeltControl112.java ItemDispenserControl112.java
ElectronicValueRW.java Lights.java
ElectronicValueRWBeanInfo.java LightsBeanInfo.java
ElectronicValueRWConst.java LightsConst.java
ElectronicValueRWControl112.java LightsControl112.java
Gate.java RFIDScanner.java
GateBeanInfo.java RFIDScannerBeanInfo.java
GateConst.java RFIDScannerConst.java
GateControl112.java RFIDScannerControl112.java
BillAcceptorControl112.java LineDisplayControl112.java
BillDispenserControl112.java MICRControl112.java
BiometricsControl112.java MotionSensorControl112.java
CoinAcceptorControl112.java POSPrinterControl112.java
CoinDispenserControl112.java RemoteOrderDisplayControl112.java
ElectronicJournalControl112.java ScaleControl112.java
FiscalPrinterControl112.java ScannerControl112.java
HardTotalsControl112.java SignatureCaptureControl112.java
ImageScannerControl112.java SmartCardRWControl112.java
KeylockControl112.java ToneIndicatorControl112.java

jpos.events
JposEvent.java
DataEvent.java
DataListener.java
DirectIOEvent.java
DirectIOListener.java
ErrorEvent.java
ErrorListener.java
OutputCompleteEvent.java
OutputCompleteListener.java
StatusUpdateEvent.java
StatusUpdateListener.java
jpos.services
BaseService.java EventCallbacks.java
CashChangerService12.java MSRService12.java
CashDrawerService12.java POSKeyboardService12.java
CoinDispenserService12.java POSPrinterService12.java
HardTotalsService12.java ScaleService12.java
KeylockService12.java ScannerService12.java
LineDisplayService12.java SignatureCaptureService12.java
MICRService12.java ToneIndicatorService12.java
BumpBarService13.java PINPadService13.java
FiscalPrinterService13.java RemoteOrderDisplayService13.java
New Interfaces for Existing Device Classes for Release 1.3
CashChangerService13.java MSRService13.java
CATService14.java
BumpBarService14.java MSRService14.java
CashChangerService14.java PINPadService14.java
PointCardRWService15.java POSPowerService15.java
CATService15.java POSPrinterService15.java
CoinDispenserService15.java RemoteOrderDisplayService15.java
FiscalPrinterService15.java ScaleService15.java
HardTotalsService15.java ScannerService15.java
KeylockService15.java SignatureCaptureService15.java
LineDisplayService15.java ToneIndicatorService15.java
MICRService15.java

CashChangerService16.java PointCardRWService16.java
CATService16.java POSPowerService16.java
MSRService16.java
CheckScannerService17.java MotionSensorService17.java
CashChangerService17.java PointCardRWService17.java
CATService17.java POSPowerService17.java
MSRService17.java
SmartCardRWService18.java
CashDrawerService18.java PointCardRWService18.java
CATService18.java POSKeyboardService18.java
CheckScannerService18.java POSPowerService18.java
MotionSensorService18.java
MICRService19.java SmartCardRWService19.java
MotionSensorService19.java ToneIndicatorService19.java

BiometricsService110.java ElectronicJournalService110.java
MICRService110.java SmartCardRWService110.java
MotionSensorService110.java ToneIndicatorService110.java
BillAcceptorService111.java CoinAcceptorService111.java
BillDispenserService111.java ImageScannerService111.java
BiometricsService111.java MotionSensorService111.java
ElectronicJournalService111.java RemoteOrderDisplayService111.java
FiscalPrinterService111.java ScaleService111.java
HardTotalsService111.java ScannerService111.java
KeylockService111.java SignatureCaptureService111.java
LineDisplayService111.java SmartCardRWService111.java
BeltService112.java ItemDispenserService112.java
ElectronicValueRWService112.java LightsService112.java
GateService112.java RFIDScannerService112.java
BillAcceptorService112.java LineDisplayService112.java
BillDispenserService112.java MICRService112.java
BiometricsService112.java MotionSensorService112.java
CoinAcceptorService112.java POSPrinterService112.java
CoinDispenserService112.java RemoteOrderDisplayService112.java
ElectronicJournalService112.java ScaleService112.java
FiscalPrinterService112.java ScannerService112.java
HardTotalsService112.java SignatureCaptureService112.java
ImageScannerService112.java SmartCardRWService112.java
KeylockService112.java ToneIndicatorService112.java

Device Controls
Note: This section is intended primarily for programmers who are creating
JavaPOS Device Controls and Services.
Device Control Responsibilities

• Supporting the JavaPOS Device Interface for its category. This includes a set
of properties, methods, and events.
• Managing the connection and interface to a Device Service.
• Forwarding most property accesses and method calls to the Device Service,
and throwing exceptions when a property access or method call fails.
• Supporting add and remove event listener methods.
• Generating events to registered listeners upon command from the Device
Service.
• Downgrading for older Device Service versions.
A Device Control is not responsible for:
• Managing multi-thread access to the Device Control and Service. An
application must either access a Control from only one thread, or ensure that
its threads synchronize sequences of requests as required to ensure that
affected state and properties are maintained until the sequences have
completed.
• Data buffering, including input and output data plus events. The Device
Service manages all buffering and enqueuing.
• The device behavior/semantics and nuances that are specific to the functional
control of the device.
• The loading functions that are to be contained in the jpos.config/loader (JCL).

Device Controls Device Service Management B-47
Device Service Management

The Device Control manages the connection to the Device Service. The Control
calls upon the jpos.config/loader (JCL) to accomplish the connection and
disconnection.
jpos.config/loader (JCL) and JavaPOS Entry Registry

(JER)
The jpos.config/loader (JCL) along with the JavaPOS Entry Registry (JER) is
used as the binding (configuration and loading) API that allows a JavaPOS
control to bind to the correct JavaPOS service in a manner independent of the
actual configuration mechanism. For POS applications, it represents a somewhat
minimum (but extensible) functional equivalent of the “NT Registry” called the
JposEntryRegistry.
All JavaPOS Device Controls that use this API and additional helpful reference
material can be obtained on the JavaPOS website, http://www.javapos.com. In
addition other standards information may be obtained from the http://www.NRF-
ARTS.org website.
A reference open source implementation of the JCL is available on this website
and maintained under the control of the JavaPOS technical committee. Included
on the website is a functioning JCL with complete JavaDoc documentation,
examples, sample code, a browser-based configuration editor and additional
explanatory material.
A brief description of the JCL process is given below. However, for additional
detailed information on the JCL one should consult the referenced web sites for
the most up to date information.
jpos.config/loader (JCL) Characteristics
The jpos.config/loader is the name for the minimal set of classes (1) and
interfaces (6) which are necessary to abstract into the JavaPOS specification.
They provide for an independent way of configuring, loading and creating
JavaPOS Device Services while maintaining the following important goals.
• Minimize the impact on existing controls
• Allow services to easily support multiple jpos.config/loader implementations
• Abstract as much as possible using Java interfaces to separate the JCL
specification from its implementation
• Keep to a minimum the number of necessary classes and interfaces
The jpos.config/loader class/interfaces are added in two packages named
jpos.config and jpos.loader. A jpos implementation is dependent upon the jpos
and jpos.loader packages included in the jpos.loader class/interfaces, the
jpos.JposConst interfaces and the jpos.JposException classes.
The jpos.config/loader specification contains 1 class and 6 interfaces. The single

class is the jpos.loader.ServiceLoader which bootstraps the implementation of the

jpos.config/loader to be used in the JVM by creating the manager object (an
instance of the jpos.loader.JposServiceManager interface). It also defaults to the
simple jpos.config/loader implementation if no bootstrap is defined. The
following table gives the name and a brief description of the class and interfaces
that are involved.
Class or
Name Description
Interface
This is the only class in the jpos.config and
jpos.loader packages. It maintains a
JposServiceManager instance (manager)
which it uses to create a
JposServiceConnection. The manager is
created by looking for a Java property
“jpos.loader.serviceManagerClass”. If this
property is defined, then the class that it defines
class jpos.loader.ServiceLoader
will be loaded and an instance of this class
created as the manager (NOTE: this also
assumes that the class implements
JposServiceManager interface and has a 0-
argument constructor). If the property is not
defined then the “simple” JCL reference
implementation manager is created
(jpos.loader.simple.SimpleServiceManager).
This interface defines a manager used to create
interface jpos.loader.JposServiceManager JposServiceConnection and allows access to
the JposEntryRegistry.
Defines a mediator between the service and the
user of the service. The JavaPOS controls use
this interface to connect to the service and then
interface jpos.loader.JposServiceConnection get the JposServiceInstance associated with the
connection. Once disconnected the
JposServiceinstance is no longer valid and a re-
connect is necessary.
Defines an interface for configuring a service.
Properties can be added, queried, modified and
removed. The JposServiceInstanceFactory
interface jpos.config.JposEntry
uses the information in the object implementing
this interface to create the current
JposServiceInstance and configure it.
This interface defines a way to statistically and
interface jpos.loader.JposEntryRegistry dynamically add known JposEntry objects to
the system.
Only interface required to be implemented by all
JavaPOS services. It defines one method that is
interface jpos.loader.JposServiceInstance
used to indicate to the service that the connection
has been disconnected.
Factory interface to create JposServiceInstance
objects (i.e., the JavaPOS services). It is passed
interface jpos.loader.JposServiceInstanceFactory
a JposEntry which it uses to create the correct
service.

Device Controls Device Service Management B-49
The configuration information is described as a set of properties in the

JposEntry. These are entered as <key, value> pairs. The key is a String and the
value is a Java Object of type: String, Integer, Long, Float, Boolean, Character or
Byte (which are the String and primitive wrapper classes provided in the
java.lang package). The following are two properties which must be defined by
all the entries in the JposEntry in order for it to be considered valid.
Property Name Property Type Description

This is the unique name that identifies this entry.
logicalName String The control uses this name to bind itself to the
service.
Defines the factory class which should be used to
create the service. This class must implement the
serviceInstanceFactoryClass String
jpos.loader.JposServiceInstanceFactory
interface and it must have a default constructor.
All other properties are optionally provided or needed for the correct creation and
initialization of the JavaPOS service. Note the service providers will most likely
want to define their own set of properties and require them to be in the JposEntry
in order to allow their JposServiceFactory to be used and their Device Service to
be configured and loaded.
Future releases of the reference jpos.config/loader (JCL) might be modified to
define a standard set of properties (in addition to the two mandated above) that all
JavaPOS services would need to define.

Property and Method Forwarding

The Device Control must use the Device Service to implement all properties and
methods defined by the JavaPOS Device Interface for a device category, with the
following exceptions:
• open method.
• close method.
• DeviceControlDescription property. The Control returns its description.
• DeviceControlVersion property. The Control returns its version.
• State property. The Control forwards the request to the Service as shown in
the following paragraphs. Any exception is changed to a return value of
JPOS_S_CLOSED; an exception is never thrown to an application.
For all other properties and methods, the Device Control forwards the request to
the identically named method or property of the Device Service. A template for
set property and method request forwarding follows:
public void name(Parameters) throws JposException
{
try
service.name(Parameters);
catch(JposException je)
throw je;
catch(Exception e)
throw new JposException(JPOS_E_CLOSED,
“Control not opened”, e);
}
Similarly, a template for get property request forwarding is:

public Type name() throws JposException
{
try
return service.name();
catch(JposException je)
throw je;
catch(Exception e)
throw new JposException(JPOS_E_CLOSED,
“Control not opened”, e);
}
The general forwarding sequence is to call the Service to process the request, and
return to the application if no exception occurs. If an exception occurs and the
exception is JposException, rethrow it to the application.
Otherwise wrap the exception in a JposException and throw it. This should only
occur if an open has not successfully linked the Service to the Control, that is, if
the service field contains a null reference. (Any exceptions that occur while in the
Service should be caught by it, and the Service should rethrow it as a
JposException.) This allows the Control to set the message text to “Control not
opened” with reasonable certainty.

Device Controls Event Handling B-51
Event Handling
Event Listeners and Event Delivery
An application must be able to register with the Device Control to receive events
of each type supported by the Device, as well as unregister for these events. To
conform to the JavaBean naming pattern for events, the registration methods have
the form:
void addXxxListener(XxxListener l);
void removeXxxListener(XxxListener l);
where Xxx is replaced by one of the event types: Data, Error, OutputComplete,
StatusUpdate, or DirectIO.
An example add listener method is:
protected Vector dataListeners;
public void addDataListener(DataListener l)
{
synchronized(dataListeners)
dataListeners.addElement(l);
}
When the Device Service requests that an event be delivered, the Control calls the
event method of each listener that has registered for that event. (Typically, only
one listener will register for each event type. However, diagnostic or other
software may choose to listen, also.) The event methods have the form:
void xxxOccurred(XxxEvent e)
where xxx is replaced by: data, error, outputComplete, statusUpdate, or

directIO.

Event Callbacks
The Device Service requests that an event be delivered by calling a method in a
callback instance. This instance is created by the Control and passed to the
Service in the open method.
The callback instance is typically created as an inner class of the Control. An
example callback inner class is:
protected class ScannerCallbacks implements EventCallbacks
{
public BaseControl getEventSource()
{
return (BaseControl)Scanner.this;
}
public void fireDataEvent(DataEvent e)

{
synchronized(Scanner.this.dataListeners)
// deliver the event to all registered listeners
for(int x = 0; x < dataListeners.size(); x++)
((DataListener)dataListeners.elementAt(x)).
dataOccurred(e);
}
public void fireDirectIOEvent(DirectIOEvent e)

{
//…Removed code similar to fireDataEvent…
}
public void fireErrorEvent(ErrorEvent e)

{
//…Removed code similar to fireDataEvent…
}
public void fireOutputCompleteEvent(OutputCompleteEvent e)

{
}
public void fireStatusUpdateEvent(StatusUpdateEvent e)

{
}
}

Device Controls Device Control Version Handling B-53
Device Control Version Handling

The Device Control responsibilities given in the preceding sections “Device
Service Management” and “Property and Method Forwarding” are somewhat
simplified: They do not take into account version handling.
Both the Device Control and the Device Service have version numbers. Each
version number is broken into three parts: Major, minor, and build. The major
and minor portions indicate compliance with a release of the JavaPOS
specifications. For example, release 1.4 compatibility is represented by a major
version of one and a minor version of four. The build portion is set by the
JavaPOS Device writer.
The JavaPOS version requirement is that a Device Control for a device category
must operate and return reasonable results with any Device Service for that class,
as long as its major version number matches the Service’s major version number.
In order to support this requirement, the following steps must be taken by the
Control:
• open method. The Control must validate and determine the version of the
Service, and save this version for later use (the “validated version”). The steps
are as follows:
1. After connecting to the Device Service and obtaining its reference,
determine the level of JavaPOS Service interface supported by the Service
(the “interface version”). This test ensures that the Service complies with
the property and method requirements of the interface.
For example, assume that the Scanner Control is at version 1.3. First
attempt to cast the Service reference to the original release version,
ScannerService12. If this succeeds, the “interface version” is at least 1.2;
otherwise fail the open. Next, attempt to cast to ScannerService13. If this
succeeds, the “interface version” is 1.3.
2. After calling the Service’s open method, get its DeviceServiceVersion
property. If the major version does not match the Control’s major version,
then fail the open.
3. At this point we know that some level of Service interface is supported,
and that the major Control and Service versions match. Now determine
the “validated version”:
if ( service_version <= interface_version )
{
// The Service version may match the interface
// version, or it may be less. The latter case may
// be true for a Service that wraps or bridges to
// OPOS software, because the Service may be able to
// support a higher interface version, but
// downgrades its reported Service version to that of
// the OPOS software.
// Remember the Services real version.
validated_version = service_version;
}
else if ( service_version > interface_version )

{
// The Service is newer than the Control.
// Look at two subcases.
if ( control_version == interface_version )
{
// The Service is newer than the Control, and it
// supports all the Controls methods and
// properties (and perhaps more that the Control
// will not call).
// Remember the maximum version that the Control
// supports.
validated_version = interface_version;
}
else if ( service_version > interface_version )
{
//... Fail the open!
// The Service is reporting a version for which it
// does not support all the required methods and
// properties.
}
}
• Properties and other methods. If an application accesses a property or calls a

method supported by the Control’s version but not by the “validated version”
of the Service, the Control must throw a JposException with error code
JPOS_E_NOSERVICE.

Device Services Device Service Responsibilities B-55
Device Services
Note: This section is intended primarily for programmers creating JavaPOS
Device Controls and Services.
Device Service Responsibilities

A Device Service for a device category is responsible for:
• Supporting the JavaPOS Device Service Interface for its category. This
includes a set of properties and methods, plus event generation and delivery.
• Implementing property accesses and method calls, and throwing exceptions
when a property access or method call fails.
• Enqueuing events and delivering them (through calls to Device Control event
callback methods) when the preconditions for delivering the event are
satisfied.
• Managing access to the Physical Device.
The Device Service requires the jpos.config/loader (JCL) JposEntry object which
contains all the configuration information.
Property and Method Processing

The Device Service performs the actual work for the property access and method
processing. If the Service is successful in carrying out the request, it returns to the
application. Otherwise, it must throw a JposException.
At the beginning of property and method processing, the Service will typically
need to validate that an application has properly initialized the device before it is
processed. If the device must first be claimed, the Service throws an exception
with the error code JPOS_E_CLAIMED (if the device is already claimed by
another JPOS Device) or JPOS_E_NOTCLAIMED (if the device is available to
be claimed). If the device must first be enabled, then the Service throws an
exception with the error code JPOS_E_DISABLED.
Some special cases are:
• open method. The Service must perform additional housekeeping and
initialization during this method. Initialization will often include accessing the
Java System Database (Release 1.4 and prior) or JposEntryRegistry (Release
1.5 and beyond) to obtain parameters specific to the Service and the Physical
Device.
• close method. The Service releases all resources that were acquired during or
after open.

Event Generation
The Device Service has the responsibility of enqueuing events and delivering
them in the proper sequence. The Service must enqueue and deliver them one at a
time, in a first-in, first-out manner. (The only exception is when a
JPOS_EL_INPUT_DATA event must be delivered early on an input error
because some data events are also enqueued.) Events are delivered by an
internally created and managed Service thread. They are delivered by calling an
event firing callback method in the Device Control, which then calls each
registered listener's event method. (See “Event Handling” on page B-51.)
corrected:
DataEventEnabled is false. (See “Device Input Model” on page B-19.)
• The JavaPOS Device may only enqueue new events while the Device is
enabled.
• The Device may deliver enqueued events until the application calls the release
• For output devices, the clearOutput method clears output error events.

Device Services Physical Device Access B-57
Physical Device Access

The Device Service is responsible for managing the Physical Device. Often, this
occurs by using a communications Port API (supplied or custom). At other times,
the Service may need to use other device drivers or techniques to control the
device.
The Java for Retail POS (JavaPOS) and OLE for Retail POS (OPOS) industry
standard initiatives are intentionally similar in many respects.
Support for Java requires several differences from OPOS in architecture, but the
JavaPOS committee agreed that the general model of OPOS device classes should
be reused as much as possible.
In order to reuse as much of the OPOS device models as possible, the following
sections detail the general mapping rules from OPOS to JavaPOS. A later section
lists the deviations of JavaPOS APIs from OPOS.
API Mapping Rules

In most cases, OPOS APIs may be translated in a mechanical fashion to equivalent
JavaPOS APIs. The exceptions to this mapping are largely due to differences in
some string parameters.
Areas of data mapping include data types, methods and properties, and events.

JavaPOS Component Descriptions
The following sections are arranged as follows and provide detailed information
on how an Application is expected to interface with a device covered under
JavaPOS.
Section 1:
Describes the specific characteristics of the data types that JavaPOS uses as they
relate to Java and a OS platform neutral implementation.
Section 2:
Provides interface descriptions for the properties, methods, and events specific to
JavaPOS. For thorough description of these, one should consult the applicable
chapters located in previous chapters in this document.
Section 3:
Compares the evolution of the JavaPOS from the OPOS standard and briefly
describes some of the differences between the two implementations.
Section 4:
Provides the Change History previously contained in the JavaPOS Programmer’s
Guide.

Section 1: JavaPOS Data Types API Mapping Rules B-59
Section 1: JavaPOS Data Types
Data types are mapped from OPOS to JavaPOS as follows, with exceptions noted
after the table:
Table 1:
OPOS JavaPOS
Usage
Type Type
BOOL boolean Boolean true or false.
BOOL * boolean[1] Mutable boolean.
LONG byte 8-bit integer.
LONG int 32-bit integer.
LONG * int[1] Mutable 32-bit integer.
SAFEARRAY
int[] 32-bit integer array.
of LONG
Mutable 32-bit integer array. The [0] element con-
SAFEARRAY *
int[1][] tains the array of 32-bit integers that can be modi-
of LONG
fied, both in size and/or contents.
64-bit integer. Used for currency values, with an
CURRENCY long
assumed 4 decimal places.
CURRENCY * long[1] Mutable 64-bit integer.
The string types are usually represented with the
following mapping:
BSTR String Text character string.
BSTR * String[1] Mutable text character string.
For some APIs, the string types are represented in
one of the following:
Immutable array of bytes. May be modified, but
BSTR byte[] size of array cannot be changed. Often used when
non-textual data is possible.
SAFEARRAY Immutable array of binary objects (themselves pre-
byte[][]
of BSTR sented as arrays of bytes).
Mutable array of bytes. The [0] element contains
BSTR * byte[1][] the array of bytes that can be modified, both in size
and/or contents.
BSTR Point[] Array of points. Used by Signature Capture.
An object. This will usually be subclassed to
BSTR * Object provide a Device Service-specific parameter for
directIO or DirectIOEvent.
nls (LONG) nls (String) Operating System National Language Data type.

Section 2: JavaPOS Interface Descriptions
Information in this section further defines the requirements of the UnifiedPOS for
Java implementation. The common Properties, Methods, and Events are included
to help transition from the UML given in Chapter 1 to the specifics for the Java
Implementation on an Operating System that supports Java.
Next, tables are included that outline the specific programmatic examples for
each of the device classifications and reference back to the UML for the
respective devices.
The examples have been provided in Java and make no requirement of a specific
OS in order to run.

JavaPOS Common Properties, Methods, and Events API Mapping Rules B-61
JavaPOS Common Properties, Methods, and Events
JavaPOS implementation specific definitions of the Common Properties.

Usage
Name Type Mutability Version Notes
AutoDisable boolean { read-write } 1.2 1
CapCompareFirmwareVersion boolean { read-only } 1.9
CapPowerReporting int { read-only } 1.3
CapStatisticsReporting boolean { read-only } 1.8
CapUpdateFirmware boolean { read-only } 1.9
CapUpdateStatistics boolean { read-only } 1.8
CheckHealthText String { read-only } 1.0
Claimed boolean { read-only } 1.0
DataCount int { read-only } 1.2 1
DataEventEnabled boolean { read-write } 1.0 1
DeviceEnabled boolean { read-write } 1.0
FreezeEvents boolean { read-write } 1.0
OutputID int { read-only } 1.0 2
PowerNotify int { read-write } 1.3
PowerState int { read-only } 1.3
State int { read-only } 1.0
DeviceControlDescription String { read-only } 1.0

DeviceControlVersion int { read-only } 1.0
DeviceServiceDescription String { read-only } 1.0
DeviceServiceVersion int { read-only } 1.0
PhysicalDeviceDescription String { read-only } 1.0
PhysicalDeviceName String { read-only } 1.0
Usage Notes:

JavaPOS implementation specific definitions of the Common Methods.

Name Version
void open ( String logicalDeviceName ) throws JposException; 1.4
void close ( ) throws JposException; 1.4
void claim ( int timeout ) throws JposException; 1.4
void release ( ) throws JposException; 1.4
void checkHealth ( int level ) throws JposException; 1.4
void clearInput ( ) throws JposException; 1.4
void clearInputProperties ( ) throws JposException; 1.10
void clearOutput ( ) throws JposException; 1.4
void directIO ( int command, int[1] data, Object object ) throws 1.4
JposException;
void compareFirmwareVersion ( String firmwareFileName, int[1] result ) 1.9
throws JposException;
void resetStatistics ( String statisticsBuffer ) throws JposException; 1.8
void retrieveStatistics ( String[1] statisticsBuffer ) throws JposException; 1.8
void updateFirmware ( String firmwareFileName ) throws JposException; 1.9
void updateStatistics ( String statisticsBuffer ) throws JposException; 1.8

JavaPOS Class Names API Mapping Rules B-63
JavaPOS Class Names Updated in Version 1.12

JavaPOS implementation specific definitions of the POS Device Categories’
Class names.
UnifiedPOS Device
JavaPOS Class Names
Programmatic Names
Belt jpos.Belt
BillAcceptor jpos.BillAcceptor
BillDispenser jpos.BillDispenser
Biometrics jpos.Biometrics
BumpBar jpos.BumpBar
CashChanger jpos.CashChanger
CashDrawer jpos.CashDrawer
CAT jpos.CAT
CheckScanner jpos.CheckScanner
CoinAcceptor jpos.CoinAcceptor
CoinDispenser jpos.CoinDispenser
ElectronicJournal jpos.ElectronicJournal
ElectronicValueRW jpos.ElectronicValueRW
FiscalPrinter jpos.FiscalPrinter
Gate jpos.Gate
HardTotals jpos.HardTotals
ImageScanner jpos.ImageScanner
ItemDispenser jpos.ItemDispenser
Keylock jpos.Keylock
Lights jpos.Lights
LineDisplay jpos.LineDisplay
MICR jpos.MICR
MotionSensor jpos.MotionSensor
MSR jpos.MSR
PINPad jpos.PINPad
PointCardRW jpos.PointCardRW
POSKeyboard jpos.POSKeyboard
POSPower jpos.POSPower
POSPrinter jpos.POSPrinter
RemoteOrderDisplay jpos.RemoteOrderDisplay
RFIDScanner jpos.RFIDScanner
Scale jpos.Scale
Scanner jpos.Scanner
SignatureCapture jpos.SignatureCapture
SmartCardRW jpos.SmartCardRW
ToneIndicator jpos.ToneIndicator

Properties
AutoDisable Property R/W
Type boolean
Remarks If true, the Device Service will set DeviceEnabled to false after it receives and
enqueues data as a DataEvent. Before any additional input can be received, the
application must set DeviceEnabled to true.
If false, the Device Service does not automatically disable the device when data is
received.
Errors A JposException may be thrown when this property is accessed. For further
information, see “Exceptions” on page B-12.
CapCompareFirmwareVersion Property R Added in Release 1.9
Type boolean
See Also compareFirmwareVersion Method.
CapPowerReporting Property R Added in Release 1.3

Type int
Remarks Identifies the reporting capabilities of the Device. It has one of the following
values:
Value Meaning
JPOS_PR_NONE The Device Service cannot determine the state of the
JPOS_PR_STANDARD The Device Service can determine and report two of the
power states - OFF_OFFLINE (that is, off or offline)
and ONLINE.
JPOS_PR_ADVANCED The Device Service can determine and report all three
power states - OFF, OFFLINE, and ONLINE.
Errors None.

Properties API Mapping Rules B-65
CapStatisticsReporting Property R Added in Release 1.8
Type boolean
Remarks If true, the device accumulates and can provide various statistics regarding usage;
otherwise no usage statistics are accumulated. The information accumulated and
reported is device specific, and is retrieved using the retrieveStatistics method.
See Also retrieveStatistics Method.
CapUpdateFirmware Property R Added in Release 1.9
Type boolean
Remarks If true, then the device’s firmware can be updated via the updateFirmware
method.
See Also updateFirmware Method.
CapUpdateStatistics Property R Added in Release 1.8

Type boolean
Remarks If true, the device statistics, or some of the statistics, can be reset to zero using the
resetStatistics method, or updated using the updateStatistics method.
If CapStatisticsReporting is false, then CapUpdateStatistics is also false.
See Also CapStatisticsReporting Property, resetStatistics Method, updateStatistics
Method.
CheckHealthText Property R
Type String
Remarks Holds the results of the most recent call to the checkHealth method. The
This property is empty (“”) before the first call to the checkHealth method.

Claimed Property R
Type boolean
Remarks If true, the device is claimed for exclusive access. If false, the device is released
for sharing with other applications.
methods and properties, and before it will deliver events to the application.
DataCount Property R
Type int
DataEventEnabled Property R/W
Type boolean
application, the DataEvent will remain queued at the Device Service until the
condition is corrected.)
DeviceControlDescription Property R
Type String
Remarks Holds an identifier for the Device Control and the company that produced it.
“POS Printer JavaPOS Control, (C) 1998 Epson”
Errors None.

DeviceControlVersion Property R
Type int
Remarks Holds the Device Control version number.

A change to the JavaPOS major version level for a
A change to the JavaPOS minor version level for a
Internal level provided by the Device Control developer.
Updated when corrections are made to the Device
Control implementation.
1002038
This value may be displayed as version “1.2.38”, and interpreted as major
version 1, minor version 2, build 38 of the Device Control.
Errors None.
DeviceEnabled Property R/W

Type boolean
Remarks If true, the device is in an operational state. If changed to true, then the device is
brought to an operational state.
If false, the device has been disabled. If changed to false, then the device is
physically disabled when possible, any subsequent input will be discarded, and
output operations are disallowed.
consistency, however, the application must set this property to true before using
output devices.
Release 1.3 and later: The Device’s power state may be reported while
DeviceEnabled is true; See “Device Power Reporting Model” on page B-58 for
details.
This property is initialized to false by the open method. Note that an exclusive use
device must be claimed before the device may be enabled.

DeviceServiceDescription Property R
Type String
Remarks Holds an identifier for the Device Service and the company that produced it.
“TM-U950 Printer JPOS Service Driver, (C) 1998 Epson”

DeviceServiceVersion Property R
Type int
Remarks Holds the Device Service version number.
A change to the JavaPOS major version level for a
A change to the JavaPOS minor version level for a
Internal level provided by the Device Service developer.
Updated when corrections are made to the Device
Service implementation.

1002038
1, minor version 2, build 38 of the Device Service.

FreezeEvents Property R/W Updated in Release 1.12

Type boolean
Remarks If true, events will not be delivered. Events will be enqueued until this property is
set to false.
If false, the application allows events to be delivered. If some events have been
held while events were frozen and all other conditions are correct for delivering
the events, then changing this property to false will allow these events to be
delivered. An application may choose to freeze events for a specific sequence of
code where interruption by an event is not desirable.
OutputID Property R
Type int
When a method successfully initiates an asynchronous output, the Device assigns
The output ID numbers are assigned by the Device and are guaranteed to be unique
among the set of outstanding asynchronous outputs. No other facts about the ID
should be assumed.

PowerNotify Property R/W Added in Release 1.3

Type int
Remarks Contains the type of power notification selection made by the Application. It has
Value Meaning
JPOS_PN_DISABLED The Device Service will not provide any power

notifications to the application. No power notification
may not be set.
JPOS_PN_ENABLED The Device Service will fire power notification
beginning when DeviceEnabled is set to true. The level
of functionality depends upon CapPowerReporting.
This property is initialized to JPOS_PN_DISABLED by the open method. This
Value Meaning
JPOS_E_ILLEGAL One of the following occurred:
The device is already enabled.
PowerNotify = JPOS_PN_ENABLED but

CapPowerReporting = JPOS_PR_NONE.

PowerState Property R Added in Release 1.3

Type int
Remarks Identifies the current power condition of the device, if it can be determined.
Value Meaning
JPOS_PS_UNKNOWN Cannot determine the device’s power state for one of the
following reasons:
CapPowerReporting = JPOS_PR_NONE; the device

does not support power reporting.
PowerNotify = JPOS_PN_DISABLED; power

notifications are disabled.
DeviceEnabled = false; Power state monitoring does

not occur until the device is enabled.
JPOS_PS_ONLINE The device is powered on and ready for use. Can be
JPOS_PR_STANDARD or JPOS_PR_ADVANCED.
JPOS_PS_OFF The device is powered off or detached from the POS
terminal. Can only be returned if CapPowerReporting
= JPOS_PR_ADVANCED.
JPOS_PS_OFFLINE The device is powered on but is either not ready or not
CapPowerReporting = JPOS_PR_ADVANCED.
JPOS_PS_OFF_OFFLINE
if CapPowerReporting = JPOS_PR_STANDARD.
This property is initialized to JPOS_PS_UNKNOWN by the open method. When
PowerNotify is set to enabled and DeviceEnabled is true, then this property is
updated as the Device Service detects power condition changes.
Errors None.

PhysicalDeviceDescription Property R
Type String
Remarks Holds an identifier for the physical device.

PhysicalDeviceName Property R
Type String
Remarks Holds a short name identifying the physical device. This is a short version of
PhysicalDeviceDescription and should be limited to 30 characters.
This property will typically be used to identify the device in an application
message box, where the full description is too verbose. A sample returned string is:
“IBM Model II Printer, Japanese”

State Property R
Type int
Remarks Holds the current state of the Device. It has one of the following values:
Value Meaning
JPOS_S_CLOSED The Device is closed.
JPOS_S_IDLE The Device is in a good state and is not busy.
JPOS_S_BUSY The Device is in a good state and is busy performing
output.
JPOS_S_ERROR An error has been reported, and the application must
recover the Device to a good state before normal I/O can
resume.
Errors None.

Methods API Mapping Rules B-73
Methods
checkHealth Method
Syntax void checkHealth (int level) throws JposException;
Value Meaning
JPOS_CH_INTERNAL
Perform a health check that does not physically change
extent possible.
JPOS_CH_EXTERNAL
Perform a more thorough test that may change the
printer.
JPOS_CH_INTERACTIVE
Perform an interactive test of the device. The supporting
Device Service will typically display a modal dialog box
to present test options and results.
Remarks Tests the state of a device.
A text description of the results of this method is placed in the
CheckHealthText property. The health of many devices can only be determined
by a visual inspection of these test results.
Errors A JposException may be thrown when this method is invoked. For further
Value Meaning
JPOS_E_ILLEGAL The specified health check level is not supported by the

Device Service.

claim Method
Syntax void claim (int timeout) throws JposException;
exclusive access to be satisfied. If zero, then immediately either returns (if
successful) or throws an appropriate exception. If JPOS_FOREVER (-1), the
method waits as long as needed until exclusive access is satisfied.
Remarks Requests exclusive access to the device. Many devices require an application to
claim them before they can be used.
Value Meaning
JPOS_E_ILLEGAL This device cannot be claimed for exclusive access, or
an invalid timeout parameter was specified.
JPOS_E_TIMEOUT Another application has exclusive access to the device,
and did not relinquish control before timeout
clearInput Method
Syntax void clearInput () throws JposException;
cleared.
clearInputProperties Method Added in Release 1.10
Syntax void clearInputProperties () throws JposException;

State properties.

clearOutput Method Updated in Release 1.7

Syntax void clearOutput () throws JposException;
close Method
Syntax void close () throws JposException;
Remarks Releases the device and its resources.
If the DeviceEnabled property is true, then the device is disabled.
If the Claimed property is true, then exclusive access to the device is released.
compareFirmwareVersion Method Added in Release 1.9
Syntax void compareFirmwareVersion ( String firmwareFileName, int[1] result )
throws JposException;
device.
result Location in which to return the result of the comparison.
operation.
The result of the comparison is returned in the result parameter and will be one of
Value Meaning
JPOS_CFV_FIRMWARE_OLDER
device and that none of the firmware files is newer
than the firmware in the device.
JPOS_CFV_FIRMWARE_SAME
Indicates that the versions of all of the firmware
filed are the same as the firmware in the device.

JPOS_CFV_FIRMWARE_NEWER
device and that none of the firmware files is older
than the firmware in the device.
JPOS_CFV_FIRMWARE_DIFFERENT
firmware files is different than the firmware in the
device, but either:
determined, or
• The relationship is inconsistent -- one or more
are older while one or more are newer.
JPOS_CFV_FIRMWARE_UNKNOWN
possible reason for this result could be an attempt to
compare Japanese and US versions of firmware.
modification to the firmware list file
Value Meaning
JPOS_E_ILLEGAL CapCompareFirmwareVersion is false.
JPOS_E_NOEXIST The file specified by firmwareFileName does not exist
JPOS_E_EXTENDED ErrorCodeExtended = JPOS_EFIRMWARE_BAD_FILE:

directIO Method
Syntax void directIO (int command, int[] data, Object object) throws JposException;
command Command number whose specific values are assigned
by the Device Service.
data An array of one mutable integer whose specific values
or usage vary by command and Device Service.
object Additional data whose usage varies by command and
Device Service.
Remarks Communicates directly with the Device Service.
This method provides a means for a Device Service to provide functionality to the
application that is not otherwise supported by the standard Device Control for its
device category. Depending upon the Device Service’s definition of the command,
this method may be asynchronous or synchronous.
Use of this method will make an application non-portable. The application may,
however, maintain portability by performing directIO calls within conditional
code. This code may be based upon the value of the DeviceServiceDescription,
PhysicalDeviceDescription, or PhysicalDeviceName property.

open Method
Syntax void open(String logicalDeviceName) throws JposException;
The logicalDeviceName parameter specifies the device name to open.
Remarks Opens a device for subsequent I/O.
The device name specifies which of one or more devices supported by this Device
Control should be used.
In Controls from version 1.4 and prior, The logicalDeviceName must exist in the
Java System Database (JSD) for this device category so that its relationship to the
physical device can be determined. Entries in the JSD are created by a setup or
configuration utility.
In Controls from version 1.5 and beyond, The logicalDeviceName must exist in
the JposEntryRegistry for this device category so that its relationship to the
physical device can be determined. JposEntry objects in the registry are created by
a populator or some configuration utility like the JCL GUI editor.
When this method is successful, it initializes the properties Claimed,
DeviceEnabled, DataEventEnabled and FreezeEvents, as well as descriptions
and version numbers of the JavaPOS software layers. Additional category-specific
properties may also be initialized.
Value Meaning
JPOS_E_ILLEGAL The Control is already open.
JPOS_E_NOEXIST The specified logicalDeviceName was not found.
JPOS_E_NOSERVICE Could not establish a connection to the corresponding
Device Service.
release Method
Syntax void release () throws JposException;
If the DeviceEnabled property is true, and the device is an exclusive-use device,
then the device is also disabled (this method does not change the device enabled
state of sharable devices).
Value Meaning
JPOS_E_ILLEGAL The application does not have exclusive access to the
device.

resetStatistics Method Added in Release 1.8
Syntax void resetStatistics ( String statisticsBuffer ) throws JposException;

statisticsBuffer The data buffer defining the statistics that are to be reset.
Value Meaning
JPOS_E_ILLEGAL CapStatisticsReporting or CapUpdateStatistics is
false, or the named statistic is not defined/resettable.
retrieveStatistics Method Added in Release 1.8

Syntax void retrieveStatistics ( String[1] statisticsBuffer ) throws JposException;
statisticsBuffer The data buffer defining the statistics to be retrieved and
CapStatisticsReporting must be true in order to successfully use this method.
All calls to retrieveStatistics will return the following XML as a minimum:


<Event>
<Parameter>
<Value>1234</Value>
</Parameter>
</Event>
<Equipment>
</Equipment>
</UPOSStat>
<Parameter>
<Value></Value>
</Parameter>
tag. e.g.,
<Value>42</Value>
Value Meaning
JPOS_E_ILLEGAL CapStatisticsReporting is false or the named statistic is
not defined.

updateFirmware Method Added in Release 1.9

Syntax void updateFirmware ( String firmwareFileName ) throws JposException;
continue asynchronously. The Service should notify the application of the status
of the update firmware process by firing StatusUpdateEvents with values of
JPOS_SUE_UF_PROGRESS + an integer between 1 and 100 indicating the
completion percentage of the update firmware process. For application
convenience, the StatusUpdateEvent value JPOS_SUE_UF_COMPLETE is
defined to be the same value as JPOS_SUE_UF_PROGRESS + 100.
JPOS_SUE_UF_COMPLETE, which has the same value. These Service
requirements allow applications using this method to be designed to always expect
some level of progress notification.
Value Meaning
JPOS_SUE_UF_FAILED_DEV_OK
The update firmware process failed but the
JPOS_SUE_UF_FAILED_DEV_UNRECOVERABLE

JPOS_SUE_UF_FAILED_DEV_NEEDS_FIRMWARE
JPOS_SUE_UF_FAILED_DEV_UNKNOWN
Value Meaning
JPOS_E_ILLEGAL CapUpdateFirmware is false.
JPOS_E_NOEXIST The file specified by firmwareFileName does not exist
JPOS_E_EXTENDED ErrorCodeExtended = JPOS_EFIRMWARE_BAD_FILE:
updateStatistics Method Added in Release 1.8
Syntax void updateStatistics ( String statisticsBuffer ) throws JposException;
statisticsBuffer The data buffer defining the statistics with values that
are to be updated.
Value Meaning
JPOS_E_ILLEGAL CapStatisticsReporting or CapUpdateStatistics is
false, or the named statistic is not defined/updatable.

Events API Mapping Rules B-83
Events
DataEvent
Interface jpos.events.DataListener
Method dataOccurred (DataEvent e)
Description Notifies the application that input data is available from the device.
Properties This event contains the following property:

Status int The input status with its value dependent upon the
device category; it may describe the type or qualities of
the input data.
Remarks When this event is delivered to the application, the DataEventEnabled property
is changed to false, so that no further data events will be delivered until the
application sets DataEventEnabled back to true. The actual byte array input data
is placed in one or more device-specific properties.
If DataEventEnabled is false at the time that data is received, then the data is
enqueued in an internal buffer, the device-specific input data properties are not
updated, and the event is not delivered. When DataEventEnabled is subsequently
changed back to true, the event will be delivered immediately if input data is
enqueued and FreezeEvents is false.

DirectIOEvent
Interface jpos.events.DirectIOListener
Method directIOOccurred (DirectIOEvent e);
Description Provides Device Service information directly to the application. This event
provides a means for a vendor-specific Device Service to provide events to the
application that are not otherwise supported by the Device Control.
Properties This event contains the following properties:
EventNumber int Event number whose specific values are assigned by the
Device Service.
Data int Additional numeric data. Specific values vary by the
EventNumber and the Device Service. This property is
settable.
Object Object Additional data whose usage varies by the EventNumber
and the Device Service. This property is settable.
not otherwise described as part of the JavaPOS standard. Use of this event may
restrict the application program from being used with other vendor’s devices
which may not have any knowledge of the Device Service’s need for this event.


Interface jpos.events.ErrorListener
Method errorOccurred (ErrorEvent e);
Description Notifies the application that an error has been detected and a suitable response is
necessary to process the error condition.
Properties This event contains the following properties:
ErrorCode int Error Code causing the error event. See the list of
ErrorCodeExtended
int Extended Error Code causing the error event. These
ErrorLocus int Location of the error. See values below.
ErrorResponse int Error response, whose default value may be overridden
values below.
The ErrorLocus parameter has one of the following values:
Value Meaning
JPOS_EL_OUTPUT Error occurred while processing asynchronous output.
JPOS_EL_INPUT Error occurred while gathering or processing event-
available.
JPOS_EL_INPUT_DATA
available.
The application’s error event listener can set the ErrorResponse property to one of
Value Meaning
JPOS_ER_RETRY Retry the asynchronous output. The error state is exited.
May be valid only when locus is JPOS_EL_INPUT.
Default when locus is JPOS_EL_OUTPUT.
JPOS_ER_CLEAR Clear all buffered output data (including all
state is exited. Default when locus is JPOS_EL_INPUT.
JPOS_ER_CONTINUEINPUT
continue input processing. The Device remains in the
error state and will deliver additional DataEvents as
input has been delivered and DataEventEnabled is
with locus JPOS_EL_INPUT.
Use only when locus is JPOS_EL_INPUT_DATA.
Default when locus is JPOS_EL_INPUT_DATA.

into the error state. Input error events are not delivered until DataEventEnabled
is true, so that proper application sequencing occurs.
OutputCompleteEvent
Interface jpos.events.OutputCompleteListener
Method outputCompleteOccurred (OutputCompleteEvent e);
OutputID int The ID number of the asynchronous output request that
is complete.
Remarks This event is enqueued after the request’s data has been both sent and the Device
Service has confirmation that is was processed by the device successfully.
StatusUpdateEvent
Interface jpos.events.StatusUpdateListener
Method statusUpdateOccurred (StatusUpdateEvent e);
Description Notifies the application when a device has detected an operation status change.
Status int Device category-specific status, describing the type of
status change.
Power State Reporting, added in Release 1.3, adds additional Status values of:
Value Meaning
JPOS_SUE_POWER_ONLINE
The device is powered on and ready for use. Can be
JPOS_PR_STANDARD or JPOS_PR_ADVANCED.
JPOS_SUE_POWER_OFF
The device is off or detached from the terminal. Can
only be returned if CapPowerReporting =
JPOS_PR_ADVANCED.
JPOS_SUE_POWER_OFFLINE
CapPowerReporting = JPOS_PR_ADVANCED.

JPOS_SUE_POWER_OFF_OFFLINE
if CapPowerReporting = JPOS_PR_STANDARD.
The common property PowerState is also maintained at the current power state of
the device.
process:
Value Meaning
JPOS_SUE_UF_PROGRESS + 1 to 100
JPOS_SUE_UF_COMPLETE
The update firmware process has completed
JPOS_SUE_UF_PROGRESS + 100.
JPOS_SUE_UF_COMPLETE_DEV_NOT_RESTORED
the application needs to close the Service, then open,
claim, and enable again, and also restore all custom
JPOS_SUE_UF_FAILED_DEV_OK
operational.
JPOS_SUE_UF_FAILED_DEV_UNRECOVERABLE
state.
JPOS_SUE_UF_FAILED_DEV_NEEDS_FIRMWARE
JPOS_SUE_UF_FAILED_DEV_UNKNOWN
Remarks This event is enqueued when a Device needs to alert the application of a device
status change. Examples are a change in the cash drawer position (open vs. closed)
or a change in a POS printer sensor (form present vs. absent).
When a device is enabled, this event may be delivered to inform the application of
the device state. This behavior, however, is not required.
See Also CapPowerReporting Property, CapUpdateFirmware Property, PowerNotify
Property.

Peripheral Interfaces
Note:
The following are two examples of how the proposed sections for each of the
peripheral devices would be constructed. Where possible the tables are
arranged to show the sequence of the commands for proper operation of the
peripheral device.
The Cash Drawer and the MICR devices were chosen because they represent a
simple output device and a more complex input device. The other peripheral
devices would follow similar command usage and flow.

JavaPOS: Cash Drawer Java Command Examples B-89
JavaPOS: Cash Drawer

Java Command Examples
OPERATION T JAVA SAMPLE R W A R E Ref

Y E R R T X Page
P A I G N C
E D T S V P
E
96
open * M myCashDrawer.open(LogicalDeviceName.CashDrawer);
• 1 void
•
claim * M myCashDrawer.claim(1000); 1 void 92

• •
82
Claimed P bResult = myCashDrawer.getClaimed();
• boolean
•
84
DeviceEnabled * P myCashDrawer.setDeviceEnabled(true);
• 1 -
•
84
DeviceEnabled P bResult = myCashDrawer.getDeviceEnabled();
• boolean
•
94
DirectIO M myCashDrawer.directIO(100,int[],byte[])
• 3 void
•
91
CheckHealth M myCashDrawer.checkHealth(JPOS_CH_INTERNAL);
• 1 void
•
DirectIOEvent E public void directIOOccurred(DirectIOEvent e) 1 CMF 105
StatusUpdateEvent E public void statusUpdateOccurred(StatusUpdateEvent e) 1 CMF 108
80
CapPowerReporting P iResult = myCashDrawer.getCapPowerReporting();
• int
81
CheckHealthText P sResult = myCashDrawer.getCheckHealthText();
• String
•
86
FreezeEvents P myCashDrawer.setFreezeEvents(true);
• 1 -
•
86
FreezeEvents P bResult = myCashDrawer.getFreezeEvents();
• boolean
•
87
PowerNotify P myCashDrawer.setPowerNotify(JPOS_PN_ENABLED);
• 1 -
•
87
PowerNotify P iResult = myCashDrawer.getPowerNotify();
• int
•
88
PowerState P iResult = myCashDrawer.getPowerState();
• int
•
89
PhysicalDevice P sResult = myCashDrawer.getPhysicalDeviceDescription();
• String
•
Description
89
PhysicalDevice P sResult = myCashDrawer.getPhysicalDeviceName();
• String
•
Name


Y E R R T X Page
P A I G N C
E D T S V P
E
90
State P iResult = myCashDrawer.getState();
• int
DeviceControl P sResult = myCashDrawer.getDeviceControlDescription(); String 83

•
Description
83
DeviceControl P iResult = myCashDrawer.getDeviceControlVersion();
• int
Version
84
DeviceService P sResult = myCashDrawer.getDeviceServiceDescription();
• String
•
Description
85
DeviceService P iResult = myCashDrawer.getDeviceServiceVersion();
• int
•
Version
Cash Drawer Operations Properties, Methods, and Events
271
CapStatus P bResult = myCashDrawer.getCapStatus();
• boolean
•
271
CapStatusMultiDrawerDetect P bResult = myCashDrawer.getCapStatusMultiDrawerDetect();
• boolean
•
272
DrawerOpened P myCashDrawer.drawerOpened();
• boolean
•
273
OpenDrawer * M myCashDrawer.openDrawer();
• void
•
273
WaitForDrawerClose M myCashDrawer.waitForDrawerClose(2500, 1000, 10, 5);
• 4 void
•
Cash Drawer Terminating Methods
97
Release M myCashDrawer.release();
• void
•
Close * M myCashDrawer.close(); void 93

• •
Notes:

JavaPOS: MICR Java Command Examples B-91
JavaPOS: MICR
Java Command Examples

Y E R R T X Page
P A I G N C
E D T S V P
E
96
open * M myMicr.open(LogicalDeviceName.MICR);
• 1 void
•
92
claim * M myMicr.claim(1000);
• 1 void
•
Claimed P bResult = myMicr.getClaimed(); boolean 82

• •
84
DeviceEnabled * P myMicr.setDeviceEnabled(true);
• 1 -
•
84
DeviceEnabled P bResult = myMicr.getDeviceEnabled();
• boolean
•
80
AutoDisable P myMicr.setAutoDisable(true);
• 1 -
•
80
AutoDisable P bResult = myMicr.getAutoDisable();
• boolean
•
94
DirectIO M myMicr.directIO(100,int[],byte[])
• 3 void
•
91
CheckHealth M myMicr.checkHealth(JPOS_CH_INTERNAL);
• 1 void
•
DirectIOEvent E public void directIOOccurred(DirectIOEvent e) 1 CMF 105
ErrorEvent E public void errorOccurred(ErrorEvent e) 1 CMF 106
StatusUpdateEvent E public void statusUpdateOccurred(StatusUpdateEvent e) 1 CMF 108
80
CapPowerReporting P iResult = myMicr.getCapPowerReporting();
• int
81
CheckHealthText P sResult = myMicr.getCheckHealthText();
• String
•
82
DataCount P iResult = myMicr.getDataCount();
• int
•
86
FreezeEvents P myMicr.setFreezeEvents(true);
• 1 -
•
86
FreezeEvents P bResult = myMicr.getFreezeEvents();
• boolean
•
87
PowerNotify P myMicr.setPowerNotify(JPOS_PN_ENABLED);
• 1 -
•
87
PowerNotify P iResult = myMicr.getPowerNotify();
• int
•


Y E R R T X Page
P A I G N C
E D T S V P
E
88
PowerState P iResult = myMicr.getPowerState();
• int
•
PhysicalDevice P sResult = myMicr.getPhysicalDeviceDescription(); String 89

• •
Description
89
PhysicalDevice P sResult = myMicr.getPhysicalDeviceName();
• String
•
Name
90
State P iResult = myMicr.getState();
• int
83
DeviceControl P sResult = myMicr.getDeviceControlDescription();
• String
Description
83
DeviceControl P iResult = myMicr.getDeviceControlVersion();
• int
Version
84
DeviceService P sResult = myMicr.getDeviceServiceDescription();
• String
•
Description
85
DeviceService P iResult = myMicr.getDeviceServiceVersion();
• int
•
Version

JavaPOS: MICR MICR Operations Properties, Methods, and Events B-93

Y E R R T X Page
P A I G N C
E D T S V P
E
769
CapValidationDevice P bResult = myMicr.getCapValidationDevice();
• boolean
•
92
ClearInput M myMicr.clearInput();
• void
•
82
DataEventEnabled * P myMicr.setDataEventEnabled(true);
• 1 -
•
DataEventEnabled P bResult = myMicr.getDataEventEnabled(); boolean 82

• •
772
BeginInsertion * M myMicr.beginInsertion(2000);
• 1 void
•
774
EndInsertion * M myMicr.endInsertion();
• void
•
DataEvent E public void dataOccurred(DataEvent e) 1 CMF 104
773
BeginRemoval * M myMicr.beginRemoval(1000);
• void
•
775
EndRemoval * M myMicr.endRemoval();
• void
•
771
RawData P sResult = myMicr.getRawData();
• String
•
768
AccountNumber P sResult = myMicr.getAccountNumber();
• String
•
768
Amount P sResult = myMicr.getAmount();
• String
•
768
BankNumber P sResult = myMicr.getBankNumber();
• String
•
770
EPC P sResult = myMicr.getEPC();
• String
•
771
SerialNumber P sResult = myMicr.getSerialNumber();
• String
•
771
TransitNumber P sResult = myMicr.getTransitNumber();
• String
•
769
CheckType P iResult = myMicr.getCheckType();
• int
•
770
CountryCode P iResult = myMicr.getCountryCode();
• int
•
MICR Terminating Methods
97
Release M myMicr.release();
• void
•
93
Close * M myMicr.close();
• void
•

Section 3: Technical Details - OPOS and JavaPOS

The Java for Retail POS (JavaPOS) and OLE for Retail POS (OPOS) industry
standard initiatives are intentionally similar in many respects since the
UnifiedPOS architecture is the basis from which JavaPOS and OPOS
implementations are derived. The most up to date information can be downloaded
from the web site, http://www.nrf-arts.org, under the JavaPOS Standard files
section.
Support for Java requires several differences from OPOS in architecture, but the
JavaPOS committee agreed that the general model of OPOS device classes should
be reused as much as possible.
In order to reuse as much of the OPOS device models as possible, the following
sections detail the general mapping rules from OPOS to JavaPOS. A later section
lists the deviations of JavaPOS APIs from OPOS.
OPOS to JavaPOS - API Mapping Rules

In most cases, OPOS APIs may be translated in a mechanical fashion to equivalent
JavaPOS APIs. The exceptions to this mapping are largely due to differences in
some string parameters.
Areas of data mapping include data types, methods and properties, and events.
Data types are mapped from OPOS to JavaPOS as shown in the table on page B-
59, with exceptions noted after the table.

Section 3: Technical Details OPOS to JavaPOS - API Mapping Rules B-95
Property and Method Names
Property and method names are mapped from OPOS to JavaPOS as follows:
Table 2:
Type OPOS Examples JavaPOS Examples Mapping Rule
Prepend “get” to the property

Claimed getClaimed() name to form the property
Property accessor method.
DeviceEnabled getDeviceEnabled()
Read
OutputID getOutputID() No parameters.
Return value is the property.
Prepend “set” to the property

name to form the property
Property AutoDisable setAutoDisable(...) mutator method.
Write DeviceEnabled setDeviceEnabled(...) One parameter, which is of the
property's type.
No return value.
Change first letter to

Open open
lowercase.
Method CheckHealth checkHealth
Other characters are
DirectIO directIO
unchanged.
Events
JavaPOS events use the Java Development Kit 1.1 event delegation model, where-
by the application registers for events, supplying a class instance that implements
an interface extended from EventListener.
For each Event type which the Application wishes to receive, the Application must
implement the corresponding jpos.events.EventListener interface and handle its
event method. Events are delivered by the JavaPOS Device by calling this event
method.
Constants
Constants are mapped from OPOS to JavaPOS as follows:

• If the constant begins with “OPOS”, then change “OPOS” to “JPOS.”
• Otherwise, make no changes to the constant name.
All constant interface files are available in the package “jpos.” All constants are of
type “static final int.”

API Deviations
The following OPOS APIs do not follow the above mapping rules:
• BinaryConversion property
Not needed by JavaPOS. This OPOS property was used to overcome a COM-
specific issue with passing binary data in strings. JavaPOS uses more appro-
priate types for these cases, such as byte arrays.
• OpenResult property
Not supported by JavaPOS.
• ResultCode and ResultCodeExtended properties
Not needed by JavaPOS. These OPOS properties are used for reporting
failures on method calls and property sets. In JavaPOS, these failures (plus
property get failures) cause a JposException. This exception includes the
properties ErrorCode and ErrorCodeExtended, with values that match the
OPOS properties.
• ClaimDevice method
In OPOS, this method was introduced in Release 1.5. Previous releases
defined the Claim method. This method is claim in all releases of JavaPOS.
• ReleaseDevice method
In OPOS, this method was introduced in Release 1.5. Previous releases
defined the Release method. This method is release in all releases of
JavaPOS.
• DirectIO method and DirectIOEvent
The BSTR* parameter is mapped to Object.
• Cash Drawer WaitForDrawerClosed method
The tone function of this method may not work on non-PCs, since it depends
on the availability of a speaker.
• Hard Totals Read method
The BSTR* parameter is mapped to byte[], with its size set to the requested
number of bytes.
• Hard Totals Write method
The BSTR parameter is mapped to byte[].
• MSR Track1Data, Track1DiscretionaryData, Track2Data,
Track2DiscretionaryData, Track3Data properties
These BSTR properties are mapped to byte[].
• PINPad PromptLanguage property
This LONG property is mapped to String.
• Scanner ScanData and ScanDataLabel properties
These BSTR properties are mapped to byte[].
• Signature Capture PointArray property
This BSTR property is mapped to Point[].
• Signature Capture RawData property
This BSTR property is mapped to byte[].
• Signature Capture TotalPoints property
Not needed by JavaPOS. This property is equivalent to “PointArray.length”,
so TotalPoints is redundant.

Section 3: Technical Details Mapping of CharacterSet B-97
Mapping of CharacterSet Updated in Release 1.10

This section provides some details for proper use of the MapCharacterSet
property that is provided for some devices such as the LineDisplay, POSPrinter,
PointCardReaderWriter, and RemoteOrderDisplay. First, the application
must select an appropriate device character set in the CharacterSet property of
the Service. Next, the application must pass strings to the Service using the
Unicode character set. Then, the Service is responsible for mapping these
Unicode characters to the device-side code page when necessary.
The following code snippet allows Device Service providers to easily add the
mapping mechanism into their Services. For mapping of the characters, the
encoding capabilities of the Java Runtime Environment (JRE) are used. (It is
assumed that the data transferred to the Service for output to the device is a
String, and that the lower software layers, such as comm.api, use byte arrays.)
/** converts a string with the appropriate code page to a byte array.
@param codePage the desired code page to which
the characters should be mapped - such as 1252 or 850...
@param src the source string to be mapped.
@return the mapped character as byte array.
Returns null if mapping to this codepage is not supported.
*/
static byte[] UnicodeToOEMCodePage (int codePage, String src)
{
try { return src.getBytes (“Cp” + codePage);}
catch (java.io.UnsupportedEncodingException e) {}
return null;
}
Note:
• The used (extended) encoding set of the Java Runtime Environment must be
installed. Usually, the i18n package is required.
• Refer to the Java SDK documentation for the term Internationalization.

Handling Binary Data inside Strings Added in Release 1.12

Sometimes there is a need to pass binary data as a Java string, e.g., the data
parameter of the readData and writeData methods of the SmartCard R/W when
used in the APDU programming mode. The main challenge in this case is to
avoid the use of the default charset conversion for the binary values stored in the
passed Java string when they are processed.
This paragraph describes a technique to avoid the default charset conversion
while processing binary data inside Java strings.
It is clear that code such as...
char binaryChar = '\u00fc'; // german ü
byte binaryData = (byte)binaryChar;
would be converted differently depending on the configured default charset in the
underlying Java environment.
However, the following code always handles binary data stored inside a Java
string object in the same way and the default charset conversion does not take
place. The only limitation is that strings containing binary data should not contain
Unicode characters > 0x00ff. Otherwise, only the lower byte of the two byte
Unicode value is used. But this should not be a problem due to the fact that only
binary data should be inside of these strings (see the note below).
// Define hex values 0x01 0x02 0xff as String
String binaryDataString = “\u0001\u0002\u00ff”;
byte[] binaryData = new byte[binaryDataString.length];
for (int i = 0; i < binaryData.length; i++) {
binaryData[i]=(byte)(binaryDataString.charAt(i) & 0xFF);
}
The idea behind the code is, that the '&' operator automatically converts the
Unicode character into its integer representation to match the requested operator
types. For the integer representation the Unicode value of the Unicode character
is used. The conversion to an integer value before casting it to a byte type ensures
that no default charset conversion takes place. To ensure that only the lower byte
of the Unicode two byte value is used, the Unicode value is ANDed with 0xff.
Note: All human readable characters in the binary data have to be converted to
their corresponding OEM codepage codes before the conversion algorithm shown
above can be applied.

Section 4: JavaPOS Change History Release 1.3 B-99
Section 4: JavaPOS Change History
Release 1.3
corrections. Release 1.3 is a superset of Release 1.2.
Section Change
firing.
Bump Bar New device: Add information in several locations, plus
Bump Bar chapter and interface files.
Fiscal Printer New device: Add information in several locations, plus
Fiscal Printer chapter and interface files.
PIN Pad New device: Add information in several locations, plus
PIN Pad chapter and interface files.
Remote Order Display New device: Add information in several locations, plus
Remote Order Display chapter and interface files.
Several places Relax ErrorEvent “retry” response to allow its use
with some input devices.
Introduction Events Clarify effect of the top event being blocked.
Add details concerning enqueuing and delivering
ErrorEvents.
Add description of asynchronous input.
Introduction Device Power Reporting Model
Add this section.
Common CapPowerReporting, PowerNotify, PowerState properties
Add these sections.
Common ErrorCode property
Generalize the meaning of JPOS_E_BUSY.
Common StatusUpdateEvent
Add power state reporting information.
Change parameter name from Data to Status.
Every Device Add power reporting properties to Summary section.
Add StatusUpdateEvent support (if previously not
reported).
Add power reporting reference to existing
StatusUpdateEvent descriptions.
MSR DecodeData Add “raw format” description and column to track data
table.
MSR ExpirationDate Specify the format.

MSR TrackxData Specify that data excludes the sentinels and LRC.
Add that decoding occurs when DecodeData is true.
MSR ErrorEvent Clarify that DataCount and AutoDisable are not
relevant for MSR error events.
POSPrinter XxxLineChars
Add implementation recommendations.
POSPrinter printTwoNormal
Clarify the meaning of the stations parameter, including
the addition of new constants.
Scale Add the following features:
• Asynchronous input. Property AsyncMode. Method
clearInput, updates to readWeight. Events
DataEvent and ErrorEvent.
• Display of text. Properties CapDisplayText,
MaxDisplayTextChars. Method displayText.
• Price calculation. Properties CapPriceCalculating,
SalesPrice, UnitPrice.
• Tare weight. Properties CapTareWeight,
TareWeight.
• Scale zeroing. Property CapZeroScale. Method
zeroScale.
Tone Indicator Summary and General Information’s Device Sharing
Consistently specify that Tone Indicator is a sharable
device.
JposConst.java interface files
Add CapPowerReporting, PowerState, and
PowerNotify properties.
Add StatusUpdateEvent power reporting values.
POSPrinterConst.java interface files
Add new printTwoNormal station constants.
Throughout Correct some editing errors.
Release 1.4
Release 1.4 added the additional peripheral device, Credit Authorization Terminal
(CAT). This device, as specified, is currently only used in the Japanese POS
markets.
Addition of this device required re-ordering the chapters and modifications to the
Table of Contents. Other minor changes to the standard are as noted below.
Section Change
General Update the Package Structure on page B-38 to include
CAT device; update the files to correct some erroneous
references to OPOS.

Fiscal Printer Add clarification to when the ErrorStation property is

valid.
POS Printer Add clarification to when the ErrorStation property is
valid.
Appendix B Add clarification to the “Events” section description.
Throughout Correct interface name to
jpos.events.OutputCompleteListener.
Correct minor spelling errors.
Release 1.5
Release 1.5 adds two additional peripheral devices: Pointcard Reader Writer and
POSPower, incorporates additional clarifications to the standard, adds a few new
additional APIs for some of the existing devices, and makes some corrections to
insure consistency in the device descriptions. Release 1.5 is a superset of Release
1.4.
Section Change
Throughout Correct notation for Java Unicode to “\uxxxx”
General Add clarification to when the Device exits the Error
state.
Remove the JPS documentation from the standard. The
JPS implementation has been replaced with the JCL
mechanism for locating and maintaining the Java
Device Services. Revised the tables and diagrams as
necessary to reflect these changes.
Update the Standard and the Package Structure to
reflect the additional new devices added to this version.
Common Properties, Methods, and Events
Modified General section to reflect JDK version
dependencies.
Bump Bar Add clarification that this Device can be both an input
and an output device.
Cash Changer Add the necessary properties (DataCount,
DataEventEnabled, CapDeposit,
CapDepositDataEvent, CapPauseDeposit,
CapRepayDeposit, DepositAmount,
DepositCashList, DepositCodeList, DepositCounts,
DepositStatus), methods (beginDeposit, endDeposit,
fixDeposit, pauseDeposit) and events (DataEvent) for
this device to optionally be able to handle cash
acceptance.
Cash Drawer Added new property, CapStatusMultiDrawerDetect
to improve status reporting in multiple cash drawer
environments.
CAT Correct the properties section to reflect the correct data

type for TransactionType (an integer) and

TransactionNumber (a String); other minor
corrections to fix typographical errors.
Coin Dispenser No Changes
Fiscal Printer Added Russia to list of countries in the CountryCode
property.
Added note to clarify that Currency value is specified to
be four decimal places.
Changed the properties CountryCode, ErrorOutID,
PrinterState, QuantityDecimalPlaces, and
QuantityLength to clarify when the parameters are
Initialized.
Corrected DuplicateReceipt to show that it is
a R/W Property.
Hard Totals No Changes
Keylock No Changes
Line Display Clarify properties CharacterSet and CharacterSetList
to indicate when they are initialized and to what values
they may be set.
MICR Added clarification to description of Model concerning
the availability of parsed data.
Clarify number of digits for BankNumber as specified
by ABA Standard, Thomson Financial Publishing Inc.
MSR Added properties CapTransmitSentinels,
Track4Data, and TransmitSentinels to enhance the
features that may be available in a global MSR device.
Updated the status byte definitions for the DataEvent
event.
Pin Pad Added the Track4Data property.
Clarify that Track1Data, Track2Data, Track3Data,
and Track4Data are assumed to be decoded data if a
successful read takes place.
Pointcard Reader Writer
New device classification added to the standard. This
device is used primarily in Asian markets.
POS Keyboard CapKeyUp property type corrected from Long to
boolean
POS Power New device classification added to the standard to
allow for systems that have the capability to report and
manage alternative mains power (UPS type devices).
POS Printer Revise this device classification to include properties,
methods, and events to add multi-color printing, both
side printing for documents such as checks, and marked

paper and sensing capability for special POS printer

forms handling. This section had significant changes to
the General Information section as well to help clarify
standard to reduce the possibility of creating a Device
Service that does not meet the intent of the standard.
ROD Clarify model remarks to indicate that this device can
be both an output device and an input device.
Clarify General Model description explaining how
Applications can manage and control the Remote Order
Displays.
Clarify to indicate that ErrorUnits and ErrorString
are updated instead by synchronous broadcast method.
Clarify what value the CurrentUnitID property is
initialized.
Scale Clarify the properties SalesPrice, TareWeight, and
UnitPrice to indicate when the values are initialized
and can be expected to remain stable and valid.
Scanner (Bar Code Reader)
No Changes
Signature Capture Update Model to discuss AutoDisable implications;
clarify when RealTimeDataEnabled takes effect;
correct DataEvent to indicate when this event may be
fired to include real-time data.
Tone Indicator Clarify all the specific properties to indicate when the
values are initialized and can be expected to remain
stable and valid. Also clarify handling of the Sound
method when another application claims the device and
calls the Sound method.
Release 1.6
Release 1.6 does not add any new devices to the standard but does make
significant changes to the Fiscal Printer and Line Display devices. Additional
minor clarification and correction changes are added as noted below. Release 1.6
is a superset of Release 1.5.
Section Change
Fiscal Printer Added the CapAdditionalHeader,


MessageType, PostLine, PreLine, and TotalizerType
properties.
Added the setCurrency, printRecCash,
printRecItemFuel, printRecItemFuelVoid,
printRecPackageAdjustment,
printRecPackageAdjustVoid, printRecRefundVoid,
printRecSubtotalAdjustVoid, and printRecTaxID
methods.
Clarified the description of the
CapPositiveAdjustment property.
Added country support for Bulgaria and Romania.
Updated the CountryCode, DayOpened, and
DescriptionLength properties to reflect additions to
the specification.
Updated the endFiscalReceipt, getData, getDate,
printRecItem, printRecMessage, printRecNotPaid,
printRecRefund, printRecSubtotal,
printRecSubtotalAdjustment, printRecTotal,
printRecVoid, printRecVoidItem, printZReport, and
setHeaderLine methods to reflect additions to the
specification.
Updated ErrorEvent to reflect additions to the
specification.
Properties CountryCode, ErrorOutputID,
PrinterState, QuantityDecimalPlaces, and
QuantityLength have been updated to reflect the fact
that they should be initialized after open instead of
open, claim, and enable.
Line Display Added CapBlinkRate, CapCursorType,
GlyphHeight, and GlyphWidth properties.
Added defineGlyph and readCharacterAtCursor
methods.
Updated the displayText and displayTextAt methods
to support new attributes for reverse video,
DISP_DT_REVERSE and
DISP_DT_BLINK_REVERSE.
Scale Properties SalesPrice, TareWeight, and UnitPrice
have been updated when the parameters are initialized
following an open method.


Tone2Duration, and InterToneWait have been
updated to reflect the fact that they should be initialized
after open instead of open, claim, and enable.
Clarified handling of the sound method when another
application claims the device and calls the sound
method.
Release 1.7
reference.
No specific change history relative to the JavaPOS Programming Guide is
maintained from this release forward. Refer to Appendix D for the change history
details (if any) relative to this section.


A P P E N D I X C
POS for .NET Implementation Reference
What is “POS for .NET?” Updated in Release 1.11

POS for .NET is a class library that provides an open device driver architecture
that allows Point-of-Service (“POS”) hardware to be easily integrated into POS
systems based on Windows Embedded for Point of Service (WEPOS) and other
POS for .NET supported Microsoft Windows Operating Systems. It is an
implementation of the UnifiedPOS Standard based upon the Microsoft Operating
System Software utilizing the .NET Framework Architecture.
Note: POS for .NET 1.0 conforms to UnifiedPOS Version 1.8. POS for .NET 1.1 maps
to UnifiedPOS Version 1.9. Starting with release 1.10 of POS for .NET, the POS for
.NET version number is in sync with the version of the UnifiedPOS Specification it
conforms to.
Microsoft will not break backwards compatibility with any documented API.
Undocumented functionality, including undocumented APIs, file locations, and
schemas are subject to change at any time.
The goals of POS for .NET include:
• Defining an architecture for Win32-based POS device access for the .NET
Framework, while maintaining a close relationship to certain aspects of the
existing OPOS implementation of the UnifiedPOS specification.
• Defining a set of POS device interfaces sufficient to support a range of POS
applications that incorporate the UnifiedPOS device abstraction. The benefits of
the .NET Framework extensions aid in the management of these devices.
• Provide for a migration path for legacy (existing) OPOS device services to
function under the .NET Framework, albeit without all of the feature rich
functionality that the .NET Framework potentially offers.
Deliverables available for POS for .NET are:
• UnifiedPOS Programmer’s Guide – this document: For application developers
and hardware providers.
• POS for .NET Runtime and SDK (which include the Complete Class Libraries)
available at: www.microsoft.com/downloads/details.aspx?FamilyID=ADAA1129-
5CB1-415E-B339-E508FCA55CA0&displaylang=en.
The SDK also includes code samples.
Additional resources for creating POS for .NET service objects from legacy
OPOS services: Updated in Release 1.11
• A set of software middleware documentation and code, known as “Shim”
software, is available that allows for developers to port their legacy OPOS
service objects to run under the .NET framework, using existing OPOS
naming conventions. The “Shim” is not a Microsoft supported product, does
not allow for all the .NET framework benefits, but does allow for an
alternative way to migrate to the POS for .NET platform with minimal code
changes. A brief description is included in this appendix.
UnifiedPOS Retail Peripheral Architecture Appendix C
C-2 POS for .NET Implementation Reference
Who Should Read This Section Updated in Release 1.11

This section is intended for application developers who require access to POS-
specific peripheral devices and want to implement the UnifiedPOS Standard on a
POS for .NET supported Microsoft Windows Operating System like Microsoft
Windows Embedded for Point of Service (WEPOS). This section is also intended
for a programmer who wants to write a POS for .NET Service Object (usually the
device manufacturer), or an application developer who desires a better
understanding of how to interface with POS for .NET.
This guide assumes that the reader is familiar with the following:
• The UnifiedPOS Device chapters in this document.
• The general characteristics of POS peripheral devices.
• Microsoft’s .NET Framework terminology and architecture.
• A working knowledge of the OPOS Implementation Reference found in
Appendix A in this document. This is helpful to give the reader special insight
into the Windows based nuances of peripheral devices implemented under
UnifiedPOS.
• Familiarity with Microsoft Developer Integration tools including the latest
version of Visual Studio and at least one of the .NET Application
Development languages. Note that as there is no Control Programmer’s Guide
(CPG) for POS for .NET, code samples can be found in the POS for .NET
SDK located at: www.microsoft.com/downloads/details.aspx?FamilyID
=ADAA1129-5CB1-415E-B339-E508FCA55CA0&displaylang=en.
Note: Examples in this Appendix use the Visual C# .NET syntax if method
signatures are provided.
Overview of POS for .NET

The following diagram shows the high level architecture of POS for .NET. An
application calls into the PosExplorer API to enumerate available POS
peripherals and to instantiate service objects for them. Once a service object is
instantiated by the PosExplorer API, the application then directly communicates
to it. Device-dependent service objects represent state and behavior of the
physical peripheral via properties, methods, and events.
Unlike the behavior of an OPOS implementation, in POS for .NET there is no
notion of control objects. Instead, the PosExplorer API acts, in some sense, as a
sole control object for all device classes. There is a global configuration store
where the configuration of POS for .NET is persisted. PosExplorer API reads
what logical devices are defined in the system and other related information from
the store. Also, configuration of the service objects and physical devices is
persisted in the configuration store. Service objects can read and write their
properties from and to the store.

Overview of POS for .NET C-3
PosExplorer API Application
Enumerates devices
and instantiates
Service Objects
Service Object Service Object
Configuration Operating System & Drivers

Store
Hardware
It is important to note that provision is made for both legacy OPOS CO/SO’s
software code and new .NET base class dependent software code to be used.
However, the full rich features of a .NET based service cannot be expected using
an OPOS legacy service object scenario. It is fully expected that over time, full-
featured .NET enabled devices with full featured .NET designed services will
become the preferred implementation for .NET POS applications.
Similar to OPOS Controls, .NET SO base classes expose properties, methods,
and events to a containing Application. The Service Object is a class that
implements a device class interface defined by POS for .NET. The Microsoft
supplied interfaces provide the class interfaces that serve as the basis for the
Applications to interact with a POS peripheral device through the use of
properties, methods, and events as defined by the UnifiedPOS standard.
Responses are given to the application through method return values and
parameters, properties, and events.

POS for .NET Definitions

Device Class
properties, methods, and events. Examples are CashDrawer and POSPrinter.
A Service Object is a class that implements a device class interface defined by
POS for .NET. It exposes properties and methods that are called by an
application.
Key POS for .NET Features

.NET Interfaces for POS Peripherals
POS for .NET defines interfaces for the devices defined in version 1.8 of
UnifiedPOS. Devices added in version 1.9 and 1.10 (this version) will be defined
in a future UnifiedPOS version release.
Base Classes for Service Objects

The Base classes implement routine functionality of Service Objects by device
type. This helps to simplify development of SOs, improve overall quality and
consistency, and reduce development time.
Basic Classes for Service Objects

The Basic classes implement the common behavior of Service Objects. Some
examples of common behavior include:
Open();
Claim();
DeviceEnabled();

Device Category Support Level C-5
Device Category Support Level Updated in Release 1.12

The following table shows the various classes and the POS for .NET version in
which they were initially supported.
COM Interface
Basic Class Base Class
Inter-op Class
Provides Definition of Provides built- Provides a
Device Categories Inter-op UnifiedPOS in management standard .NET-
support for standard and built-in based Service
legacy OPOS behavior per device Object for the
Services device class statistics device class
Belt 1.12 1.12
BillAcceptor 1.11 1.11
BillDispenser 1.11 1.11
Biometrics 1.11 1.11
BumpBar 1.0 1.0
CashChanger 1.0 1.0
CashDrawer 1.0 1.0 1.0 1.0
CAT (Credit Authorization Terminal) 1.12 1.0 1.0
CheckScanner 1.0 1.0 1.0 1.0
CoinAcceptor 1.11 1.11
CoinDispenser 1.1 1.0 1.0
ElectronicJournal 1.11 1.11
ElectronicValueRW 1.12 1.12
FiscalPrinter 1.0 1.0
Gate 1.12 1.12
HardTotals 1.0 1.0
ImageScanner 1.11 1.11
ItemDispenser 1.12 1.12
Keylock 1.1 1.0 1.0
Lights 1.12 1.12
LineDisplay 1.0 1.0 1.0 1.0
MICR (Magnetic Ink Character Recognition) 1.1 1.0 1.0
MotionSensor 1.0 1.0
MSR (Magnetic Stripe Reader) 1.0 1.0 1.0 1.0
PINPad 1.0 1.0 1.0 1.0
PointCardRW 1.0 1.0
POSKeyboard 1.0 1.0 1.0 1.0
POSPower 1.1 1.0 1.0
POSPrinter 1.0 1.0 1.0 1.0
RemoteOrderDisplay 1.0 1.0
RFIDScanner 1.12 1.12 1.12
Scale 1.1 1.0 1.0
Scanner (Bar Code Reader) 1.0 1.0 1.0 1.0
SignatureCapture 1.1 1.0 1.0
SmartCardRW 1.0 1.0
ToneIndicator 1.1 1.0 1.0

Plug and Play

POS for .NET helps to bring retail peripherals to the same parity as standard PC
desktop peripherals which can use the Plug and Play (PnP) Windows architecture.
PnP is a feature of Windows that, with little or no user intervention, automatically
installs drivers when their corresponding hardware peripherals are plugged into a
PC. Currently PnP is not a feature of a UnifiedPOS implementation but usage of
PnP devices is supported along with UnifiedPOS devices. For more information
about supporting PnP, see http://msdn.microsoft.com/library/default.asp?url=/
library/en-us/dnwue/html/ch11j.asp.
Standardized Setup
A standard installation and uninstall procedure support of POS for .NET Service
Objects is provided, which negates the requirement for a special service loader
install program (as is required in OPOS).
Device Enumeration
The ability to enumerate all the POS Peripheral devices installed on the system is
provided in the POS for .NET services.
Software-Based Device Statistics

Additional native support for hardware-specific device statistics is available in
addition to device statistics that are provided for under UnifiedPOS.
Support for OPOS (COM-Based) Service Objects

POS for .NET provides for full .NET to COM interoperability as part of the
library to avoid depreciating the investment in COM-based Service Objects.
However, for POS for .NET V1.1, only the following device classes provide this
interoperability layer in the Version 1.10 release:
• CashDrawer
• CheckScanner
• CoinDispenser
• Keylock
• LineDisplay
• MICR (Magnetic Ink Character Recognition)
• MSR (Magnetic Stripe Reader)
• PINPad
• POSKeyboard
• POSPower
• POSPrinter
• Scale
• Scanner (Bar Code Reader)
• SignatureCapture
• ToneIndicator

Service Object Verification Program C-7
Service Object Verification Program

An advancement of POS for .NET compared to OPOS is the availability of a third
party verification program. This program provides for a specific testing level of
functionality for POS for .NET Service Objects. Currently this interoperability
program is being administered by Microsoft.
Key Programming Construct Differences from OPOS
Naming Conventions
The library uses Pascal naming conventions for .NET classes and parameters of
methods are camel-case. These conventions are consistent with .NET Guidelines
for Class Library Developers. For more information on .NET Guidelines for
Class Library Developers, see:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/
cpconnetframeworkdesignguidelines.asp
Enumerations Updated in Release 1.12

POS for .NET makes extensive use of enumerations, which serves several
purposes. Enumerations force both the application and its Device Service Object
to use in-bounds parameters. This method of type checking helps avoid bugs that
result from out-of-bounds parameters or from passing return values.
In addition, the use of enumerations eliminates the need for a large list of
constants in the name space. Best practices for a library development requires
range validation for constant data types, something that is automatically provided
by using enumerations.
Note that there are cases where the range of acceptable enumeration values is
bound; however, the individual number of choices can be quite large. An example
is the timeout parameter. The possible values are -1 through the size of an Int32.
The value of -1 is interpreted as “wait forever”, all values from 0 through the size
of an Int32 represent the number of milliseconds before a timeout error occurs.
Best practices in this case would be to use a constant (such as -1) to define “wait
forever” and to use an Int32 value for the non-wait condition.
The following pages contain a table showing the current OPOS reference
implementation constant definitions and the corresponding POS for .NET
enumerations. This table was updated in version 1.12 of the specification to
reflect the naming replacement of “RSS” barcodes with “GS1 DataBar” for the
POSPrinter and Scanner device categories.

POS for .NET

UnifiedPOS Name Parameter
ClassName
Type Name
S_CLOSED ControlState enum Constant Closed
S_IDLE ControlState enum Constant Idle
S_BUSY ControlState enum Constant Busy
S_ERROR ControlState enum Constant Error
SUCCESS ErrorCode enum Constant Success

ErrorCode enum Constant Unspecified
E_CLOSED ErrorCode enum Constant Closed
E_CLAIMED ErrorCode enum Constant Claimed
E_NOTCLAIMED ErrorCode enum Constant NotClaimed
E_NOSERVICE ErrorCode enum Constant NoService
E_DISABLED ErrorCode enum Constant Disabled
E_ILLEGAL ErrorCode enum Constant Illegal
E_NOHARDWARE ErrorCode enum Constant NoHardware
E_OFFLINE ErrorCode enum Constant Offline
E_NOEXIST ErrorCode enum Constant NoExist
E_EXISTS ErrorCode enum Constant Exists
E_FAILURE ErrorCode enum Constant Failure
E_TIMEOUT ErrorCode enum Constant Timeout
E_BUSY ErrorCode enum Constant Busy
E_EXTENDED ErrorCode enum Constant Extended
ESTATS_ERROR PosCommon System.Int32 ExtendedErrorStatistics
CH_INTERNAL HealthCheckLevel enum Constant Internal

CH_EXTERNAL HealthCheckLevel enum Constant External
CH_INTERACTIVE HealthCheckLevel enum Constant Interactive
PR_NONE PowerReporting enum Constant None

PR_STANDARD PowerReporting enum Constant Standard
PR_ADVANCED PowerReporting enum Constant Advanced
PN_DISABLED PowerNotification enum Constant Disabled

PN_ENABLED PowerNotification enum Constant Enabled
PS_UNKNOWN PowerState enum Constant Unknown

PS_ONLINE PowerState enum Constant Online
PS_OFF PowerState enum Constant Off
PS_OFFLINE PowerState enum Constant Offline
PS_OFF_OFFLINE PowerState enum Constant OffOffline
EL_OUTPUT ErrorLocus enum Constant Output

EL_INPUT ErrorLocus enum Constant Input
EL_INPUT_DATA ErrorLocus enum Constant InputData
ER_RETRY ErrorResponse enum Constant Retry

ER_CLEAR ErrorResponse enum Constant Clear
ER_CONTINUEINPUT ErrorResponse enum Constant ContinueInput
SUE_POWER_ONLINE PosCommon System.Int32 StatusPowerOnline

SUE_POWER_OFF PosCommon System.Int32 StatusPowerOff
SUE_POWER_OFFLINE PosCommon System.Int32 StatusPowerOffline
SUE_POWER_OFF_OFFLINE PosCommon System.Int32 StatusPowerOffOffline
CFV_FIRMWARE_DIFFERENT CompareFirmwareResult enum Constant Different

CFV_FIRMWARE_NEWER CompareFirmwareResult enum Constant Newer
CFV_FIRMWARE_OLDER CompareFirmwareResult enum Constant Older
CFV_FIRMWARE_SAME CompareFirmwareResult enum Constant Same
CFV_FIRMWARE_UNKNOWN CompareFirmwareResult enum Constant Unknown
SUE_UF_FAILED_DEV_OK PosCommon System.Int32 StatusUpdateFirmwareFailedDeviceOk

SUE_UF_FAILED_DEV_UNRECOVERABLE PosCommon System.Int32 StatusUpdateFirmwareFailedDeviceUnrecoverable
SUE_UF_FAILED_DEV_NEEDS_FIRMWARE PosCommon System.Int32 StatusUpdateFirmwareFailedDeviceNeedsFirmware
SUE_UF_FAILED_DEV_UNKNOWN PosCommon System.Int32 StatusUpdateFirmwareFailedDeviceUnknown
SUE_UF_COMPLETE PosCommon System.Int32 StatusUpdateFirmwareComplete
SUE_UF_COMPLETE_DEV_NOT_RESTORED PosCommon System.Int32 StatusUpdateFirmwareCompleteDeviceNotRestored
SUE_UF_PROGRESS + 1 to 100 PosCommon System.Int32 StatusUpdateFirmwareProgress
FOREVER PosCommon System.Int32 WaitForever
BB_UID_1 DeviceUnits enum Constant Unit1


Enumerations C-9
POS for .NET

ClassName
Type Name
BB_DE_KEY BumpBar System.Int32 DataEventKey
CASH_SUE_DRAWERCLOSED CashDrawerStatus enum Constant Closed

CASH_SUE_DRAWEROPEN CashDrawerStatus enum Constant Open
CAT_PAYMENT_LUMP PaymentCondition enum Constant Lump

CAT_PAYMENT_BONUS_1 PaymentCondition enum Constant Bonus1
CAT_PAYMENT_INSTALLMENT_1 PaymentCondition enum Constant Installment1
CAT_PAYMENT_BONUS_COMBINATION_1 PaymentCondition enum Constant BonusCombination1
CAT_PAYMENT_REVOLVING PaymentCondition enum Constant Revolving
CAT_PAYMENT_DEBIT PaymentCondition enum Constant Debit
CAT_TRANSACTION_SALES CreditTransactionType enum Constant Sales

CAT_TRANSACTION_VOID CreditTransactionType enum Constant Void
CAT_TRANSACTION_REFUND CreditTransactionType enum Constant Refund
CAT_TRANSACTION_VOIDPRESALES CreditTransactionType enum Constant VoidPreSales
CAT_TRANSACTION_COMPLETION CreditTransactionType enum Constant Completion
CAT_TRANSACTION_PRESALES CreditTransactionType enum Constant PreSales
CAT_TRANSACTION_CHECKCARD CreditTransactionType enum Constant CheckCard
CAT_MEDIA_UNSPECIFIED PaymentMedia enum Constant Unspecified

CAT_MEDIA_NONDEFINE
CAT_MEDIA_CREDIT PaymentMedia enum Constant Credit
CAT_MEDIA_DEBIT PaymentMedia enum Constant Debit
ECAT_CENTERERROR Cat System.Int32 ExtendedErrorCenterError

ECAT_COMMANDERROR Cat System.Int32 ExtendedErrorCommandError
ECAT_RESET Cat System.Int32 ExtendedErrorReset
ECAT_COMMUNICATIONERROR Cat System.Int32 ExtendedErrorCommunicationError
ECAT_DAILYLOGOVERFLOW Cat System.Int32 ExtendedErrorDailyLogOverflow

POS for .NET

ClassName
Type Name
CAT_DL_NONE CatLogs enum Constant None
CAT_DL_REPORTING CatLogs enum Constant Reporting
CAT_DL_SETTLEMENT CatLogs enum Constant Settlement
CAT_DL_REPORTING_SETTLEMENT CatLogs enum Constant ReportingAndSettlement
CHAN_STATUS_OK CashChangerStatus enum Constant OK

CHAN_STATUS_EMPTY CashChangerStatus enum Constant Empty
CHAN_STATUS_NEAREMPTY CashChangerStatus enum Constant NearEmpty
CHAN_STATUS_EMPTYOK
CashChangerFullStatus enum Constant OK

CHAN_STATUS_FULL CashChangerFullStatus enum Constant Full
CHAN_STATUS_NEARFULL CashChangerFullStatus enum Constant NearFull
CHAN_STATUS_FULLOK
CHAN_STATUS_JAM CashChangerStatus enum Constant Jam

CHAN_STATUS_JAMOK
CHAN_STATUS_ASYNC CashChanger System.Int32 StatusAsync
CHAN_STATUS_DEPOSIT_START CashDepositStatus enum Constant Start

CHAN_STATUS_DEPOSIT_END CashDepositStatus enum Constant End
CHAN_STATUS_DEPOSIT_NONE CashDepositStatus enum Constant None
CHAN_STATUS_DEPOSIT_COUNT CashDepositStatus enum Constant Count
CHAN_STATUS_DEPOSIT_JAM CashDepositStatus enum Constant Jam
CHAN_DEPOSIT_CHANGE CashDepositAction enum Constant Change

CHAN_DEPOSIT_NOCHANGE CashDepositAction enum Constant NoChange
CHAN_DEPOSIT_REPAY CashDepositAction enum Constant Repay
CHAN_DEPOSIT_PAUSE CashDepositPause enum Constant Pause

CHAN_DEPOSIT_RESTART CashDepositPause enum Constant Restart
ECHAN_OVERDISPENSE CashChanger System.Int32 ExtendedErrorOverDispense
CHK_CCL_MONO CheckColors enum Constant Mono

CHK_CCL_GRAYSCALE CheckColors enum Constant GrayScale
CHK_CCL_16 CheckColors enum Constant Color16
CHK_CCL_256 CheckColors enum Constant Color256
CHK_CCL_FULL CheckColors enum Constant Full
CHK_CIF_NATIVE CheckImageFormats enum Constant Native

CHK_CIF_TIFF CheckImageFormats enum Constant Tiff
CHK_CIF_BMP CheckImageFormats enum Constant Bmp
CHK_CIF_JPEG CheckImageFormats enum Constant Jpeg
CHK_CIF_GIF CheckImageFormats enum Constant Gif
CHK_CL_MONO CheckColors enum Constant Mono

CHK_CL_GRAYSCALE CheckColors enum Constant GrayScale
CHK_CL_16 CheckColors enum Constant Color16
CHK_CL_256 CheckColors enum Constant Color256
CHK_CL_FULL CheckColors enum Constant Full
CHK_IF_NATIVE CheckImageFormats enum Constant Native

CHK_IF_TIFF CheckImageFormats enum Constant Tiff
CHK_IF_BMP CheckImageFormats enum Constant Bmp
CHK_IF_JPEG CheckImageFormats enum Constant Jpeg
CHK_IF_GIF CheckImageFormats enum Constant Gif
CHK_IMS_EMPTY ImageMemoryStatus enum Constant Empty

CHK_IMS_OK ImageMemoryStatus enum Constant OK
CHK_IMS_FULL ImageMemoryStatus enum Constant Full
CHK_MM_DOTS MapMode enum Constant Dots

CHK_MM_TWIPS MapMode enum Constant Twips
CHK_MM_ENGLISH MapMode enum Constant English
CHK_MM_METRIC MapMode enum Constant Metric
CHK_CLR_ALL CheckImageClear enum Constant All

CHK_CLR_BY_FILEID CheckImageClear enum Constant FileId
CHK_CLR_BY_FILEINDEX CheckImageClear enum Constant FileIndex
CHK_CLR_BY_IMAGETAGDATA CheckImageClear enum Constant ImageTagData

Enumerations C-11
POS for .NET

ClassName
Type Name
CHK_CROP_AREA_ENTIRE_IMAGE CheckScanner System.Int32 CropEntireImage

CHK_CROP_AREA_RESET_ALL CheckScanner System.Int32 CropResetAll
CHK_CROP_AREA_RIGHT CheckScanner System.Int32 CropRight

CHK_CROP_AREA_BOTTOM CheckScanner System.Int32 CropBottom
CHK_LOCATE_BY_FILEID CheckImageLocate enum Constant FileId

CHK_LOCATE_BY_FILEINDEX CheckImageLocate enum Constant FileIndex
CHK_LOCATE_BY_IMAGETAGDATA CheckImageLocate enum Constant ImageTagData
CHK_SUE_SCANCOMPLETE CheckScannerStatus enum Constant ScanComplete
ECHK_NOCHECK CheckScanner System.Int32 ExtendedErrorNoCheck

ECHK_CHECK CheckScanner System.Int32 ExtendedErrorCheck
ECHK_NOROOM CheckScanner System.Int32 ExtendedErrorNoRoom
COIN_STATUS_OK CoinDispenserStatus enum Constant OK

COIN_STATUS_EMPTY CoinDispenserStatus enum Constant Empty
COIN_STATUS_NEAREMPTY CoinDispenserStatus enum Constant NearEmpty
COIN_STATUS_JAM CoinDispenserStatus enum Constant Jam
DISP_CB_NOBLINK DisplayBlink enum Constant None

DISP_CB_BLINKALL DisplayBlink enum Constant All
DISP_CB_BLINKEACH DisplayBlink enum Constant Each
DISP_CCS_NUMERIC CharacterSetCapability enum Constant Numeric

DISP_CCS_ALPHA CharacterSetCapability enum Constant Alpha
DISP_CCS_ASCII CharacterSetCapability enum Constant Ascii
DISP_CCS_KANA CharacterSetCapability enum Constant Kana
DISP_CCS_KANJI CharacterSetCapability enum Constant Kanji
DISP_CCS_UNICODE CharacterSetCapability enum Constant Unicode
DISP_CCT_NONE DisplayCursors enum Constant None

DISP_CCT_FIXED DisplayCursors enum Constant Fixed
DISP_CCT_BLOCK DisplayCursors enum Constant Block
DISP_CCT_HALFBLOCK DisplayCursors enum Constant HalfBlock
DISP_CCT_UNDERLINE DisplayCursors enum Constant Underline
DISP_CCT_REVERSE DisplayCursors enum Constant Reverse
DISP_CCT_OTHER DisplayCursors enum Constant Other
DISP_CCT_BLINK DisplayCursors enum Constant Blink
DISP_CRB_NONE DisplayReadBack enum Constant None

DISP_CRB_SINGLE DisplayReadBack enum Constant Single
DISP_CR_NONE DisplayReverse enum Constant None

DISP_CR_REVERSEALL DisplayReverse enum Constant All
DISP_CR_REVERSEEACH DisplayReverse enum Constant Each
DISP_CS_UNICODE PosCommon System.Int32 CharacterSetUnicode

DISP_CS_ASCII PosCommon System.Int32 CharacterSetAscii
DISP_CS_WINDOWS
DISP_CS_ANSI PosCommon System.Int32 CharacterSetAnsi
DISP_CT_NONE DisplayCursors enum Constant None

DISP_CT_FIXED DisplayCursors enum Constant Fixed
DISP_CT_BLOCK DisplayCursors enum Constant Block
DISP_CT_HALFBLOCK DisplayCursors enum Constant HalfBlock
DISP_CT_UNDERLINE DisplayCursors enum Constant Underline
DISP_CT_REVERSE DisplayCursors enum Constant Reverse
DISP_CT_OTHER DisplayCursors enum Constant Other
DISP_CT_BLINK DisplayCursors enum Constant Blink
DISP_MT_NONE DisplayMarqueeType enum Constant None

DISP_MT_UP DisplayMarqueeType enum Constant Up
DISP_MT_DOWN DisplayMarqueeType enum Constant Down
DISP_MT_LEFT DisplayMarqueeType enum Constant Left
DISP_MT_RIGHT DisplayMarqueeType enum Constant Right
DISP_MT_INIT DisplayMarqueeType enum Constant Init
DISP_MF_WALK DisplayMarqueeFormat enum Constant Walk

DISP_MF_PLACE DisplayMarqueeFormat enum Constant Place

POS for .NET

ClassName
Type Name
DISP_DT_NORMAL DisplayTextMode enum Constant Normal

DISP_DT_BLINK DisplayTextMode enum Constant Blink
DISP_DT_REVERSE DisplayTextMode enum Constant Reverse
DISP_DT_BLINK_REVERSE DisplayTextMode enum Constant BlinkReverse
DISP_ST_UP DisplayScrollText enum Constant Up

DISP_ST_DOWN DisplayScrollText enum Constant Down
DISP_ST_LEFT DisplayScrollText enum Constant Left
DISP_ST_RIGHT DisplayScrollText enum Constant Right
DISP_SD_OFF DisplaySetDescriptor enum Constant Off

DISP_SD_ON DisplaySetDescriptor enum Constant On
DISP_SD_BLINK DisplaySetDescriptor enum Constant Blink
DISP_BM_ASIS LineDisplay System.Int32 DisplayBitmapAsIs
DISP_BM_LEFT LineDisplay System.Int32 DisplayBitmapLeft

DISP_BM_CENTER LineDisplay System.Int32 DisplayBitmapCenter
DISP_BM_RIGHT LineDisplay System.Int32 DisplayBitmapRight
DISP_BM_TOP LineDisplay System.Int32 DisplayBitmapTop

DISP_BM_BOTTOM LineDisplay System.Int32 DisplayBitmapBottom
EDISP_TOOBIG LineDisplay System.Int32 ExtendedErrorTooBig

EDISP_BADFORMAT LineDisplay System.Int32 ExtendedErrorBadFormat
FPTR_S_JOURNAL FiscalPrinterStations enum Constant Journal

FPTR_S_RECEIPT FiscalPrinterStations enum Constant Receipt
FPTR_S_SLIP FiscalPrinterStations enum Constant Slip
FPTR_S_JOURNAL_RECEIPT FiscalPrinterStations enum Constant JournalReceipt

FiscalPrinterStations enum Constant JournalSlip
FiscalPrinterStations enum Constant ReceiptSlip
FPTR_AC_BRC FiscalCurrency enum Constant BrazilianCruceiro

FPTR_AC_BGL FiscalCurrency enum Constant BulgarianLev
FPTR_AC_EUR FiscalCurrency enum Constant Euro
FPTR_AC_GRD FiscalCurrency enum Constant GreekDrachma
FPTR_AC_HUF FiscalCurrency enum Constant HungarianForint
FPTR_AC_ITL FiscalCurrency enum Constant ItalianLira
FPTR_AC_PLZ FiscalCurrency enum Constant PolishZloty
FPTR_AC_ROL FiscalCurrency enum Constant RomanianLeu
FPTR_AC_RUR FiscalCurrency enum Constant RussianRouble
FPTR_AC_TRL FiscalCurrency enum Constant TurkishLira
FPTR_CID_FIRST FiscalContractorId enum Constant First

FPTR_CID_SECOND FiscalContractorId enum Constant Second
FPTR_CID_SINGLE FiscalContractorId enum Constant Single
FPTR_CC_BRAZIL FiscalCountryCodes enum Constant Brazil

FPTR_CC_GREECE FiscalCountryCodes enum Constant Greece
FPTR_CC_HUNGARY FiscalCountryCodes enum Constant Hungary
FPTR_CC_ITALY FiscalCountryCodes enum Constant Italy
FPTR_CC_POLAND FiscalCountryCodes enum Constant Poland
FPTR_CC_TURKEY FiscalCountryCodes enum Constant Turkey
FPTR_CC_RUSSIA FiscalCountryCodes enum Constant Russia
FPTR_CC_BULGARIA FiscalCountryCodes enum Constant Bulgaria
FPTR_CC_ROMANIA FiscalCountryCodes enum Constant Romania
FPTR_DT_CONF FiscalDateType enum Constant Configuration

FPTR_DT_EOD FiscalDateType enum Constant EndOfDay
FPTR_DT_RESET FiscalDateType enum Constant Reset
FPTR_DT_RTC FiscalDateType enum Constant RealTimeClock
FPTR_DT_VAT FiscalDateType enum Constant VatChange
FPTR_EL_NONE FiscalErrorLevel enum Constant None

FPTR_EL_RECOVERABLE FiscalErrorLevel enum Constant Recoverable
FPTR_EL_FATAL FiscalErrorLevel enum Constant Fatal
FPTR_EL_BLOCKED FiscalErrorLevel enum Constant Blocked
FPTR_PS_MONITOR FiscalPrinterState enum Constant Monitor

Enumerations C-13
POS for .NET

ClassName
Type Name
FPTR_PS_FISCAL_RECEIPT FiscalPrinterState enum Constant FiscalReceipt
FPTR_PS_FISCAL_RECEIPT_TOTAL FiscalPrinterState enum Constant FiscalReceiptTotal
FPTR_PS_FISCAL_RECEIPT_ENDING FiscalPrinterState enum Constant FiscalReceiptEnding
FPTR_PS_FISCAL_DOCUMENT FiscalPrinterState enum Constant FiscalDocument
FPTR_PS_FIXED_OUTPUT FiscalPrinterState enum Constant FixedOutput
FPTR_PS_ITEM_LIST FiscalPrinterState enum Constant ItemList
FPTR_PS_LOCKED FiscalPrinterState enum Constant Locked
FPTR_PS_NONFISCAL FiscalPrinterState enum Constant NonFiscal
FPTR_PS_REPORT FiscalPrinterState enum Constant Report
FPTR_RS_RECEIPT FiscalReceiptStation enum Constant Receipt

FPTR_RS_SLIP FiscalReceiptStation enum Constant Slip
FPTR_RT_CASH_IN FiscalReceiptType enum Constant CashIn

FPTR_RT_CASH_OUT FiscalReceiptType enum Constant CashOut
FPTR_RT_GENERIC FiscalReceiptType enum Constant Generic
FPTR_RT_SALES FiscalReceiptType enum Constant Sales
FPTR_RT_SERVICE FiscalReceiptType enum Constant Service
FPTR_RT_SIMPLE_INVOICE FiscalReceiptType enum Constant SimpleInvoice
FPTR_MT_ADVANCE FiscalMessageType enum Constant Advance

FPTR_MT_ADVANCE_PAID FiscalMessageType enum Constant AdvancePaid
FPTR_MT_AMOUNT_TO_BE_PAID FiscalMessageType enum Constant AmountToBePaid
FPTR_MT_AMOUNT_TO_BE_PAID_BACK FiscalMessageType enum Constant AmountToBePaidBack
FPTR_MT_CARD FiscalMessageType enum Constant Card
FPTR_MT_CARD_NUMBER FiscalMessageType enum Constant CardNumber
FPTR_MT_CARD_TYPE FiscalMessageType enum Constant CardType
FPTR_MT_CASH FiscalMessageType enum Constant Cash
FPTR_MT_CASHIER FiscalMessageType enum Constant Cashier
FPTR_MT_CASH_REGISTER_NUMBER FiscalMessageType enum Constant CashRegisterNumber
FPTR_MT_CHANGE FiscalMessageType enum Constant Change
FPTR_MT_CHEQUE FiscalMessageType enum Constant Cheque
FPTR_MT_CLIENT_NUMBER FiscalMessageType enum Constant ClientNumber
FPTR_MT_CLIENT_SIGNATURE FiscalMessageType enum Constant ClientSignature
FPTR_MT_COUNTER_STATE FiscalMessageType enum Constant CounterState
FPTR_MT_CREDIT_CARD FiscalMessageType enum Constant CreditCard
FPTR_MT_CURRENCY FiscalMessageType enum Constant Currency
FPTR_MT_CURRENCY_VALUE FiscalMessageType enum Constant CurrencyValue
FPTR_MT_DEPOSIT FiscalMessageType enum Constant Deposit
FPTR_MT_DEPOSIT_RETURNED FiscalMessageType enum Constant DepositReturned
FPTR_MT_DOT_LINE FiscalMessageType enum Constant DotLine
FPTR_MT_DRIVER_NUMB FiscalMessageType enum Constant DriverNumber
FPTR_MT_EMPTY_LINE FiscalMessageType enum Constant EmptyLine
FPTR_MT_FREE_TEXT FiscalMessageType enum Constant FreeText
FPTR_MT_FREE_TEXT_WITH_DAY_LIMIT FiscalMessageType enum Constant FreeTextWithDayLimit
FPTR_MT_GIVEN_DISCOUNT FiscalMessageType enum Constant GivenDiscount
FPTR_MT_LOCAL_CREDIT FiscalMessageType enum Constant LocalCredit
FPTR_MT_MILEAGE_KM FiscalMessageType enum Constant MileageKilometers
FPTR_MT_NOTE FiscalMessageType enum Constant Note
FPTR_MT_PAID FiscalMessageType enum Constant Paid
FPTR_MT_PAY_IN FiscalMessageType enum Constant PayIn
FPTR_MT_POINT_GRANTED FiscalMessageType enum Constant PointGranted
FPTR_MT_POINTS_BONUS FiscalMessageType enum Constant PointsBonus
FPTR_MT_POINTS_RECEIPT FiscalMessageType enum Constant PointsReceipt
FPTR_MT_POINTS_TOTAL FiscalMessageType enum Constant PointsTotal
FPTR_MT_PROFITED FiscalMessageType enum Constant Profited
FPTR_MT_RATE FiscalMessageType enum Constant Rate
FPTR_MT_REGISTER_NUMB FiscalMessageType enum Constant RegisterNumber
FPTR_MT_SHIFT_NUMBER FiscalMessageType enum Constant ShiftNumber
FPTR_MT_STATE_OF_AN_ACCOUNT FiscalMessageType enum Constant StateOfAnAccount
FPTR_MT_SUBSCRIPTION FiscalMessageType enum Constant Subscription
FPTR_MT_TABLE FiscalMessageType enum Constant Table
FPTR_MT_THANK_YOU_FOR_LOYALTY FiscalMessageType enum Constant ThankYouForLoyalty
FPTR_MT_TRANSACTION_NUMB FiscalMessageType enum Constant TransactionNumber
FPTR_MT_VALID_TO FiscalMessageType enum Constant ValidTo
FPTR_MT_VOUCHER FiscalMessageType enum Constant Voucher
FPTR_MT_VOUCHER_PAID FiscalMessageType enum Constant VoucherPaid
FPTR_MT_VOUCHER_VALUE FiscalMessageType enum Constant VoucherValue
FPTR_MT_WITH_DISCOUNT FiscalMessageType enum Constant WithDiscount
FPTR_MT_WITHOUT_UPLIFT FiscalMessageType enum Constant WithoutUplift
FPTR_SS_FULL_LENGTH FiscalSlipSelection enum Constant FullLength

POS for .NET

ClassName
Type Name
FPTR_SS_VALIDATION FiscalSlipSelection enum Constant Validation
FPTR_TT_DOCUMENT FiscalTotalizerType enum Constant Document

FPTR_TT_DAY FiscalTotalizerType enum Constant Day
FPTR_TT_RECEIPT FiscalTotalizerType enum Constant Receipt
FPTR_TT_GRAND FiscalTotalizerType enum Constant Grand
FPTR_GD_CURRENT_TOTAL FiscalData enum Constant CurrentTotal

FPTR_GD_DAILY_TOTAL FiscalData enum Constant DailyTotal
FPTR_GD_RECEIPT_NUMBER FiscalData enum Constant ReceiptNumber
FPTR_GD_REFUND FiscalData enum Constant Refund
FPTR_GD_NOT_PAID FiscalData enum Constant NotPaid
FPTR_GD_MID_VOID FiscalData enum Constant NumberOfVoidedReceipts
FPTR_GD_Z_REPORT FiscalData enum Constant ZReport
FPTR_GD_GRAND_TOTAL FiscalData enum Constant GrandTotal
FPTR_GD_PRINTER_ID FiscalData enum Constant PrinterId
FPTR_GD_FIRMWARE FiscalData enum Constant Firmware
FPTR_GD_RESTART FiscalData enum Constant Restart
FPTR_GD_REFUND_VOID FiscalData enum Constant RefundVoid
FPTR_GD_NUMB_CONFIG_BLOCK FiscalData enum Constant NumberOfConfigurationBlocks
FPTR_GD_NUMB_CURRENCY_BLOCK FiscalData enum Constant NumberOfCurrencyBlocks
FPTR_GD_NUMB_HDR_BLOCK FiscalData enum Constant NumberOfHeaderBlocks
FPTR_GD_NUMB_RESET_BLOCK FiscalData enum Constant NumberOfResetBlocks
FPTR_GD_NUMB_VAT_BLOCK FiscalData enum Constant NumberOfVatBlocks
FPTR_GD_FISCAL_DOC FiscalData enum Constant FiscalDocument
FPTR_GD_FISCAL_DOC_VOID FiscalData enum Constant FiscalDocumentVoid
FPTR_GD_FISCAL_REC FiscalData enum Constant FiscalReceipt
FPTR_GD_FISCAL_REC_VOID FiscalData enum Constant FiscalReceiptVoid
FPTR_GD_NONFISCAL_DOC FiscalData enum Constant NonFiscalDocument
FPTR_GD_NONFISCAL_DOC_VOID FiscalData enum Constant NonFiscalDocumentVoid
FPTR_GD_NONFISCAL_REC FiscalData enum Constant NonFiscalReceipt
FPTR_GD_SIMP_INVOICE FiscalData enum Constant SimplifiedInvoice
FPTR_GD_TENDER FiscalData enum Constant Tender
FPTR_GD_LINECOUNT FiscalData enum Constant LineCount
FPTR_GD_DESCRIPTION_LENGTH FiscalData enum Constant DescriptionLength
FPTR_PDL_CASH FiscalPrinter System.Int32 PaymentDescriptionCash

FPTR_PDL_CHEQUE FiscalPrinter System.Int32 PaymentDescriptionCheque
FPTR_PDL_CHITTY FiscalPrinter System.Int32 PaymentDescriptionChitty
FPTR_PDL_COUPON FiscalPrinter System.Int32 PaymentDescriptionCoupon
FPTR_PDL_CURRENCY FiscalPrinter System.Int32 PaymentDescriptionCurrency
FPTR_PDL_DRIVEN_OFF FiscalPrinter System.Int32 PaymentDescriptionDrivenOff
FPTR_PDL_EFT_IMPRINTER FiscalPrinter System.Int32 PaymentDescriptionEftImprinter
FPTR_PDL_EFT_TERMINAL FiscalPrinter System.Int32 PaymentDescriptionEftTerminal
FPTR_PDL_TERMINAL_IMPRINTER FiscalPrinter System.Int32 PaymentDescriptionTerminalImprinter
FPTR_PDL_FREE_GIFT FiscalPrinter System.Int32 PaymentDescriptionFreeGift
FPTR_PDL_GIRO FiscalPrinter System.Int32 PaymentDescriptionGiro
FPTR_PDL_HOME FiscalPrinter System.Int32 PaymentDescriptionHome
FPTR_PDL_IMPRINTER_WITH_ISSUER FiscalPrinter System.Int32 PaymentDescriptionImprinterWithIssuer
FPTR_PDL_LOCAL_ACCOUNT FiscalPrinter System.Int32 PaymentDescriptionLocalAccount
FPTR_PDL_LOCAL_ACCOUNT_CARD FiscalPrinter System.Int32 PaymentDescriptionLocalAccountCard
FPTR_PDL_PAY_CARD FiscalPrinter System.Int32 PaymentDescriptionPayCard
FPTR_PDL_PAY_CARD_MANUAL FiscalPrinter System.Int32 PaymentDescriptionPayCardManual
FPTR_PDL_PREPAY FiscalPrinter System.Int32 PaymentDescriptionPrepay
FPTR_PDL_PUMP_TEST FiscalPrinter System.Int32 PaymentDescriptionPumpTest
FPTR_PDL_SHORT_CREDIT FiscalPrinter System.Int32 PaymentDescriptionShortCredit
FPTR_PDL_STAFF FiscalPrinter System.Int32 PaymentDescriptionStaff
FPTR_PDL_VOUCHER FiscalPrinter System.Int32 PaymentDescriptionVoucher
FPTR_LC_ITEM FiscalPrinter System.Int32 LineCountItem

FPTR_LC_ITEM_VOID FiscalPrinter System.Int32 LineCountItemVoid
FPTR_LC_DISCOUNT FiscalPrinter System.Int32 LineCountDiscount
FPTR_LC_DISCOUNT_VOID FiscalPrinter System.Int32 LineCountDiscountVoid
FPTR_LC_SURCHARGE FiscalPrinter System.Int32 LineCountSurcharge
FPTR_LC_SURCHARGE_VOID FiscalPrinter System.Int32 LineCountSurchargeVoid
FPTR_LC_REFUND FiscalPrinter System.Int32 LineCountRefund
FPTR_LC_REFUND_VOID FiscalPrinter System.Int32 LineCountRefundVoid
FPTR_LC_SUBTOTAL_DISCOUNT FiscalPrinter System.Int32 LineCountSubtotalDiscount
FPTR_LC_SUBTOTAL_DISCOUNT_VOID FiscalPrinter System.Int32 LineCountSubtotalDiscountVoid
FPTR_LC_SUBTOTAL_SURCHARGE FiscalPrinter System.Int32 LineCountSubtotalSurcharge
FPTR_LC_SUBTOTAL_SURCHARGE_VOID FiscalPrinter System.Int32 LineCountSubtotalSurchargeVoid
FPTR_LC_COMMENT FiscalPrinter System.Int32 LineCountComment

Enumerations C-15
POS for .NET

ClassName
Type Name
FPTR_LC_SUBTOTAL FiscalPrinter System.Int32 LineCountSubtotal
FPTR_LC_TOTAL FiscalPrinter System.Int32 LineCountTotal
FPTR_DL_ITEM FiscalPrinter System.Int32 DescriptionLengthItem

FPTR_DL_ITEM_ADJUSTMENT FiscalPrinter System.Int32 DescriptionLengthItemAdjustment
FPTR_DL_ITEM_FUEL FiscalPrinter System.Int32 DescriptionLengthItemFuel
FPTR_DL_ITEM_FUEL_VOID FiscalPrinter System.Int32 DescriptionLengthItemFuelVoid
FPTR_DL_NOT_PAID FiscalPrinter System.Int32 DescriptionLengthNotPaid
FPTR_DL_PACKAGE_ADJUSTMENT FiscalPrinter System.Int32 DescriptionLengthPackageAdjustment
FPTR_DL_REFUND FiscalPrinter System.Int32 DescriptionLengthRefund
FPTR_DL_REFUND_VOID FiscalPrinter System.Int32 DescriptionLengthRefundVoid
FPTR_DL_SUBTOTAL_ADJUSTMENT FiscalPrinter System.Int32 DescriptionLengthSubtotalAdjustment
FPTR_DL_TOTAL FiscalPrinter System.Int32 DescriptionLengthTotal
FPTR_DL_VOID FiscalPrinter System.Int32 DescriptionLengthVoid
FPTR_DL_VOID_ITEM FiscalPrinter System.Int32 DescriptionLengthVoidItem
FPTR_GT_GROSS FiscalTotalizer enum Constant Gross

FPTR_GT_NET FiscalTotalizer enum Constant Net
FPTR_GT_DISCOUNT FiscalTotalizer enum Constant Discount
FPTR_GT_DISCOUNT_VOID FiscalTotalizer enum Constant DiscountVoid
FPTR_GT_ITEM FiscalTotalizer enum Constant Item
FPTR_GT_ITEM_VOID FiscalTotalizer enum Constant ItemVoid
FPTR_GT_NOT_PAID FiscalTotalizer enum Constant NotPaid
FPTR_GT_REFUND FiscalTotalizer enum Constant Refund
FPTR_GT_REFUND_VOID FiscalTotalizer enum Constant RefundVoid
FPTR_GT_SUBTOTAL_DISCOUNT FiscalTotalizer enum Constant SubtotalDiscount
FPTR_GT_SUBTOTAL_DISCOUNT_VOID FiscalTotalizer enum Constant SubtotalDiscountVoid
FPTR_GT_SUBTOTAL_SURCHARGES FiscalTotalizer enum Constant SubtotalSurcharges
FPTR_GT_SUBTOTAL_SURCHARGES_VOID FiscalTotalizer enum Constant SubtotalSurchargesVoid
FPTR_GT_SURCHARGE FiscalTotalizer enum Constant Surcharge
FPTR_GT_SURCHARGE_VOID FiscalTotalizer enum Constant SurchargeVoid
FPTR_GT_VAT FiscalTotalizer enum Constant Vat
FPTR_GT_VAT_CATEGORY FiscalTotalizer enum Constant VatCategory
FPTR_AT_AMOUNT_DISCOUNT FiscalAdjustment enum Constant AmountDiscount

FPTR_AT_AMOUNT_SURCHARGE FiscalAdjustment enum Constant AmountSurcharge
FPTR_AT_PERCENTAGE_DISCOUNT FiscalAdjustment enum Constant PercentageDiscount
FPTR_AT_PERCENTAGE_SURCHARGE FiscalAdjustment enum Constant PercentageSurcharge
FPTR_RT_ORDINAL FiscalReport enum Constant Ordinal

FPTR_RT_DATE FiscalReport enum Constant Date
FPTR_SC_EURO FiscalCurrency enum Constant Euro
FPTR_SUE_COVER_OPEN PrinterStatus enum Constant CoverOpen

FPTR_SUE_COVER_OK PrinterStatus enum Constant CoverOK
FPTR_SUE_JRN_COVER_OPEN PrinterStatus enum Constant JournalCoverOpen
FPTR_SUE_JRN_COVER_OK PrinterStatus enum Constant JournalCoverOK
FPTR_SUE_REC_COVER_OPEN PrinterStatus enum Constant ReceiptCoverOpen
FPTR_SUE_REC_COVER_OK PrinterStatus enum Constant ReceiptCoverOK
FPTR_SUE_SLP_COVER_OPEN PrinterStatus enum Constant SlipCoverOpen
FPTR_SUE_SLP_COVER_OK PrinterStatus enum Constant SlipCoverOK
FPTR_SUE_JRN_EMPTY PrinterStatus enum Constant JournalEmpty

FPTR_SUE_JRN_NEAREMPTY PrinterStatus enum Constant JournalNearEmpty
FPTR_SUE_JRN_PAPEROK PrinterStatus enum Constant JournalPaperOK
FPTR_SUE_REC_EMPTY PrinterStatus enum Constant ReceiptEmpty

FPTR_SUE_REC_NEAREMPTY PrinterStatus enum Constant ReceiptNearEmpty
FPTR_SUE_REC_PAPEROK PrinterStatus enum Constant ReceiptPaperOK
FPTR_SUE_SLP_EMPTY PrinterStatus enum Constant SlipEmpty

FPTR_SUE_SLP_NEAREMPTY PrinterStatus enum Constant SlipNearEmpty
FPTR_SUE_SLP_PAPEROK PrinterStatus enum Constant SlipPaperOK
FPTR_SUE_IDLE PrinterStatus enum Constant Idle
EFPTR_COVER_OPEN FiscalPrinter System.Int32 ExtendedErrorCoverOpen

EFPTR_JRN_EMPTY FiscalPrinter System.Int32 ExtendedErrorJournalEmpty
EFPTR_REC_EMPTY FiscalPrinter System.Int32 ExtendedErrorReceiptEmpty
EFPTR_SLP_EMPTY FiscalPrinter System.Int32 ExtendedErrorSlipEmpty
EFPTR_SLP_FORM FiscalPrinter System.Int32 ExtendedErrorSlipForm

POS for .NET

ClassName
Type Name
EFPTR_MISSING_DEVICES FiscalPrinter System.Int32 ExtendedErrorMissingDevices
EFPTR_WRONG_STATE FiscalPrinter System.Int32 ExtendedErrorWrongState
EFPTR_TECHNICAL_ASSISTANCE FiscalPrinter System.Int32 ExtendedErrorTechnicalAssistance
EFPTR_CLOCK_ERROR FiscalPrinter System.Int32 ExtendedErrorClockError
EFPTR_FISCAL_MEMORY_DISCONNECTED FiscalPrinter System.Int32 ExtendedErrorMemoryDisconnected
EFPTR_FISCAL_MEMORY_FULL FiscalPrinter System.Int32 ExtendedErrorMemoryFull
EFPTR_FISCAL_TOTALS_ERROR FiscalPrinter System.Int32 ExtendedErrorTotalsError
EFPTR_BAD_ITEM_QUANTITY FiscalPrinter System.Int32 ExtendedErrorBadItemQuantity
EFPTR_BAD_ITEM_AMOUNT FiscalPrinter System.Int32 ExtendedErrorBadItemAmount
EFPTR_BAD_ITEM_DESCRIPTION FiscalPrinter System.Int32 ExtendedErrorBadItemDescription
EFPTR_RECEIPT_TOTAL_OVERFLOW FiscalPrinter System.Int32 ExtendedErrorReceiptTotalOverflow
EFPTR_BAD_VAT FiscalPrinter System.Int32 ExtendedErrorBadVat
EFPTR_BAD_PRICE FiscalPrinter System.Int32 ExtendedErrorBadPrice
EFPTR_BAD_DATE FiscalPrinter System.Int32 ExtendedErrorBadDate
EFPTR_NEGATIVE_TOTAL FiscalPrinter System.Int32 ExtendedErrorNegativeTotal
EFPTR_WORD_NOT_ALLOWED FiscalPrinter System.Int32 ExtendedErrorWordNotAllowed
EFPTR_BAD_LENGTH FiscalPrinter System.Int32 ExtendedErrorBadLength
EFPTR_MISSING_SET_CURRENCY FiscalPrinter System.Int32 ExtendedErrorMissingSetCurrency
KBD_ET_DOWN KeyboardEventType enum Constant Down

KBD_ET_DOWN_UP KeyboardEventType enum Constant DownUp
KBD_KET_KEYDOWN KeyEvent enum Constant Down

KBD_KET_KEYUP KeyEvent enum Constant Up
LOCK_KP_ANY Keylock System.Int32 PositionAny

LOCK_KP_LOCK Keylock System.Int32 PositionLocked
LOCK_KP_NORM Keylock System.Int32 PositionNormal
LOCK_KP_SUPR Keylock System.Int32 PositionSupervisor
MICR_CT_PERSONAL CheckType enum Constant Personal

MICR_CT_BUSINESS CheckType enum Constant Business
MICR_CT_UNKNOWN CheckType enum Constant Unknown
MICR_CC_USA CheckCountryCode enum Constant Usa

MICR_CC_CANADA CheckCountryCode enum Constant Canada
MICR_CC_MEXICO CheckCountryCode enum Constant Mexico
MICR_CC_UNKNOWN CheckCountryCode enum Constant Unknown
EMICR_NOCHECK Micr System.Int32 ExtendedErrorNoCheck

EMICR_CHECK Micr System.Int32 ExtendedErrorCheck
EMICR_BADDATA Micr System.Int32 ExtendedErrorBadData
EMICR_NODATA Micr System.Int32 ExtendedErrorNoData
EMICR_BADSIZE Micr System.Int32 ExtendedErrorBadSize
EMICR_JAM Micr System.Int32 ExtendedErrorJam
EMICR_CHECKDIGIT Micr System.Int32 ExtendedErrorCheckDigit
EMICR_COVEROPEN Micr System.Int32 ExtendedErrorCoverOpen
MOTION_M_PRESENT MotionSensor System.Int32 StatusMotionPresent

MOTION_M_ABSENT MotionSensor System.Int32 StatusMotionAbsent
MSR_TR_1 MsrTracks enum Constant Track1

MSR_TR_1_2 MsrTracks enum Constant Tracks12
MSR_TR_1_2_3 MsrTracks enum Constant Tracks123
MSR_TR_1_2_3_4 MsrTracks enum Constant Tracks1234
MSR_ERT_CARD MsrErrorReporting enum Constant Card

MSR_ERT_TRACK MsrErrorReporting enum Constant Track
Msr System.Int32 ExtendedErrorSuccess

Msr System.Int32 ExtendedErrorFailure

Enumerations C-17
POS for .NET

ClassName
Type Name
EMSR_START Msr System.Int32 ExtendedErrorStart
EMSR_END Msr System.Int32 ExtendedErrorEnd
EMSR_PARITY Msr System.Int32 ExtendedErrorParity
EMSR_LRC Msr System.Int32 ExtendedErrorLrc
CharacterSetCapability enum Constant Numeric

PCRW_CCS_ALPHA CharacterSetCapability enum Constant Alpha
PCRW_CCS_ASCII CharacterSetCapability enum Constant Ascii
PCRW_CCS_KANA CharacterSetCapability enum Constant Kana
PCRW_CCS_KANJI CharacterSetCapability enum Constant Kanji
PCRW_CCS_UNICODE CharacterSetCapability enum Constant Unicode
PCRW_STATE_NOCARD PointCardState enum Constant NoCard

PCRW_STATE_REMAINING PointCardState enum Constant Remaining
PCRW_STATE_INRW PointCardState enum Constant Inserted
PCRW_TRACK1 PointCardRWTracks enum Constant Track1

PCRW_CS_UNICODE PosCommon System.Int32 CharacterSetUnicode

PCRW_CS_ASCII PosCommon System.Int32 CharacterSetAscii
PCRW_CS_WINDOWS
PCRW_CS_ANSI PosCommon System.Int32 CharacterSetAnsi
PCRW_MM_DOTS MapMode enum Constant Dots

PCRW_MM_TWIPS MapMode enum Constant Twips
PCRW_MM_ENGLISH MapMode enum Constant English
PCRW_MM_METRIC MapMode enum Constant Metric
EPCRW_READ PointCardRW System.Int32 ExtendedErrorRead

EPCRW_WRITE PointCardRW System.Int32 ExtendedErrorWrite
EPCRW_JAM PointCardRW System.Int32 ExtendedErrorJam
EPCRW_MOTOR PointCardRW System.Int32 ExtendedErrorMotor
EPCRW_COVER PointCardRW System.Int32 ExtendedErrorCover
EPCRW_PRINTER PointCardRW System.Int32 ExtendedErrorPrinter
EPCRW_RELEASE PointCardRW System.Int32 ExtendedErrorRelease
EPCRW_DISPLAY PointCardRW System.Int32 ExtendedErrorDisplay
EPCRW_NOCARD PointCardRW System.Int32 ExtendedErrorNoCard
PointCardReadWriteState enum Constant Success

EPCRW_START PointCardReadWriteState enum Constant Start
EPCRW_END PointCardReadWriteState enum Constant End
EPCRW_PARITY PointCardReadWriteState enum Constant Parity
EPCRW_ENCODE PointCardReadWriteState enum Constant Encode
EPCRW_LRC PointCardReadWriteState enum Constant LrcError
EPCRW_VERIFY PointCardReadWriteState enum Constant Verify
PointCardReadWriteState enum Constant Failure
PCRW_RP_NORMAL PrintRotation enum Constant Normal

PCRW_RP_RIGHT90 PrintRotation enum Constant Right90
PCRW_RP_LEFT90 PrintRotation enum Constant Left90
PCRW_RP_ROTATE180 PrintRotation enum Constant Rotate180
PCRW_SUE_NOCARD PointCardRW System.Int32 StatusNoCard

PCRW_SUE_REMAINING PointCardRW System.Int32 StatusRemaining
PCRW_SUE_INRW PointCardRW System.Int32 StatusInserted
PointCardKinds enum Constant PrintingArea

PointCardKinds enum Constant MagneticTracks
PointCardKinds enum Constant PrintingAreaAndMagneticTracks
PPAD_DISP_UNRESTRICTED PinPadDisplay enum Constant Unrestricted

PPAD_DISP_PINRESTRICTED PinPadDisplay enum Constant PinRestricted
PPAD_DISP_RESTRICTED_LIST PinPadDisplay enum Constant RestrictedList
PPAD_DISP_RESTRICTED_ORDER PinPadDisplay enum Constant RestrictedOrder
PPAD_DISP_NONE PinPadDisplay enum Constant None
PPAD_MSG_ENTERPIN PinPadMessage enum Constant EnterPin

POS for .NET

ClassName
Type Name
PPAD_MSG_PLEASEWAIT PinPadMessage enum Constant PleaseWait
PPAD_MSG_ENTERVALIDPIN PinPadMessage enum Constant EnterValidPin
PPAD_MSG_RETRIESEXCEEDED PinPadMessage enum Constant RetriesExceeded
PPAD_MSG_APPROVED PinPadMessage enum Constant Approved
PPAD_MSG_DECLINED PinPadMessage enum Constant Declined
PPAD_MSG_CANCELED PinPadMessage enum Constant Canceled
PPAD_MSG_AMOUNTOK PinPadMessage enum Constant AmountOK
PPAD_MSG_NOTREADY PinPadMessage enum Constant NotReady
PPAD_MSG_IDLE PinPadMessage enum Constant Idle
PPAD_MSG_SLIDE_CARD PinPadMessage enum Constant SlideCard
PPAD_MSG_INSERTCARD PinPadMessage enum Constant InsertCard
PPAD_MSG_SELECTCARDTYPE PinPadMessage enum Constant SelectCardType
PPAD_LANG_NONE PinPadLanguage enum Constant None

PPAD_LANG_ONE PinPadLanguage enum Constant One
PPAD_LANG_PINRESTRICTED PinPadLanguage enum Constant PinRestricted
PPAD_LANG_UNRESTRICTED PinPadLanguage enum Constant Unrestricted
PPAD_TRANS_DEBIT EftTransactionType enum Constant Debit

PPAD_TRANS_CREDIT EftTransactionType enum Constant Credit
PPAD_TRANS_INQ EftTransactionType enum Constant Inquiry
PPAD_TRANS_RECONCILE EftTransactionType enum Constant Reconcile
PPAD_TRANS_ADMIN EftTransactionType enum Constant Admin
PPAD_EFT_NORMAL EftTransactionControl enum Constant Normal

PPAD_EFT_ABNORMAL EftTransactionControl enum Constant Abnormal
PPAD_SUCCESS PinEntryStatus enum Constant Success

PPAD_CANCEL PinEntryStatus enum Constant Cancel
PinEntryStatus enum Constant Timeout
PinEntryStatus enum Constant BadKey
PinPadSystem enum Constant MasterSession

enum Constant Dukpt
enum Constant Apacs40
enum Constant AS2805
enum Constant Hgepos
enum Constant Jdebit2
EPPAD_BAD_KEY PinPad System.Int32 ExtendedErrorBadKey
PrinterStation enum Constant None

PTR_S_JOURNAL PrinterStation enum Constant Journal
PTR_S_RECEIPT PrinterStation enum Constant Receipt
PTR_S_SLIP PrinterStation enum Constant Slip
PTR_S_JOURNAL_RECEIPT FiscalPrinterStations enum Constant JournalReceipt

PTR_S_JOURNAL_SLIP FiscalPrinterStations enum Constant JournalSlip
PTR_S_RECEIPT_SLIP FiscalPrinterStations enum Constant ReceiptSlip
PTR_TWO_RECEIPT_JOURNAL PrinterStation enum Constant TwoReceiptJournal

PTR_TWO_SLIP_JOURNAL PrinterStation enum Constant TwoSlipJournal
PTR_TWO_SLIP_RECEIPT PrinterStation enum Constant TwoSlipReceipt
CharacterSetCapability enum Constant Numeric

PTR_CCS_ALPHA CharacterSetCapability enum Constant Alpha
PTR_CCS_ASCII CharacterSetCapability enum Constant Ascii
PTR_CCS_KANA CharacterSetCapability enum Constant Kana
PTR_CCS_KANJI CharacterSetCapability enum Constant Kanji
PTR_CCS_UNICODE CharacterSetCapability enum Constant Unicode
PTR_CS_UNICODE PosCommon System.Int32 CharacterSetUnicode

PTR_CS_ASCII PosCommon System.Int32 CharacterSetAscii
PTR_CS_WINDOWS
PTR_CS_ANSI PosCommon System.Int32 CharacterSetAnsi
PTR_EL_NONE PrinterErrorLevel enum Constant None

PTR_EL_RECOVERABLE PrinterErrorLevel enum Constant Recoverable
PTR_EL_FATAL PrinterErrorLevel enum Constant Fatal
PTR_MM_DOTS MapMode enum Constant Dots

Enumerations C-19
POS for .NET

ClassName
Type Name
PTR_MM_TWIPS MapMode enum Constant Twips
PTR_MM_ENGLISH MapMode enum Constant English
PTR_MM_METRIC MapMode enum Constant Metric
PrinterColors enum Constant None

PTR_COLOR_PRIMARY PrinterColors enum Constant Primary
PTR_COLOR_CUSTOM1 PrinterColors enum Constant Custom1
PTR_COLOR_CYAN PrinterColors enum Constant Cyan
PTR_COLOR_MAGENTA PrinterColors enum Constant Magenta
PTR_COLOR_YELLOW PrinterColors enum Constant Yellow
PTR_COLOR_FULL PrinterColors enum Constant Full
PTR_CART_UNKNOWN PrinterCartridgeStates enum Constant Unknown

PTR_CART_OK PrinterCartridgeStates enum Constant OK
PTR_CART_REMOVED PrinterCartridgeStates enum Constant Removed
PTR_CART_EMPTY PrinterCartridgeStates enum Constant Empty
PTR_CART_NEAREND PrinterCartridgeStates enum Constant NearEnd
PTR_CART_CLEANING PrinterCartridgeStates enum Constant Cleaning
PTR_CN_DISABLED PrinterCartridgeNotify enum Constant Disabled

PTR_CN_ENABLED PrinterCartridgeNotify enum Constant Enabled
PTR_CP_FULLCUT PosPrinter System.Int32 PrinterCutPaperFullCut
PTR_BC_LEFT PosPrinter System.Int32 PrinterBarCodeLeft

PTR_BC_CENTER PosPrinter System.Int32 PrinterBarCodeCenter
PTR_BC_RIGHT PosPrinter System.Int32 PrinterBarCodeRight
PTR_BC_TEXT_NONE BarCodeTextPosition enum Constant None

PTR_BC_TEXT_ABOVE BarCodeTextPosition enum Constant Above
PTR_BC_TEXT_BELOW BarCodeTextPosition enum Constant Below
BarCodeSymbology enum Constant Unknown

PTR_BCS_UPCA BarCodeSymbology enum Constant Upca
PTR_BCS_UPCE BarCodeSymbology enum Constant Upce
PTR_BCS_JAN8 BarCodeSymbology enum Constant EanJan8
PTR_BCS_EAN8
PTR_BCS_JAN13 BarCodeSymbology enum Constant EanJan13
PTR_BCS_EAN13
PTR_BCS_TF BarCodeSymbology enum Constant TF
PTR_BCS_ITF BarCodeSymbology enum Constant Itf
PTR_BCS_Codabar BarCodeSymbology enum Constant Codabar
PTR_BCS_Code39 BarCodeSymbology enum Constant Code39
PTR_BCS_UPCA_S BarCodeSymbology enum Constant Upcas
PTR_BCS_UPCE_S BarCodeSymbology enum Constant Upces
PTR_BCS_UPCD1 BarCodeSymbology enum Constant Upcd1
PTR_BCS_EAN8_S BarCodeSymbology enum Constant Ean8S
PTR_BCS_EAN13_S BarCodeSymbology enum Constant Ean13S
PTR_BCS_EAN128 BarCodeSymbology enum Constant Ean128
PTR_BCS_OCRA BarCodeSymbology enum Constant Ocra
PTR_BCS_OCRB BarCodeSymbology enum Constant Ocrb
PTR_BCS_Code128_Parsed BarCodeSymbology enum Constant Code128 Parsed
PTR_BCS_RSS14 BarCodeSymbology enum Constant Rss14 - Deprecated v1.12
PTR_BCS_RSS_EXPANDED BarCodeSymbology enum Constant RssExpanded - Deprecated v1.12
PTR_BCS_GS1DATABAR BarCodeSymbology enum Constant GS1 DataBar Omnidirectional
PTR_BCS_GS1DATABAR_S BarCodeSymbology enum Constant GS1 DataBar Stacked Omnidirectional
PTR_BCS_GS1DATABAR_E BarCodeSymbology enum Constant GS1 DataBar Expanded
PTR_BCS_GS1DATABAR_E_S BarCodeSymbology enum Constant GS1 DataBar Expanded Stacked
BarCodeSymbology enum Constant Cca
BarCodeSymbology enum Constant Ccb
BarCodeSymbology enum Constant Ccc

POS for .NET

ClassName
Type Name
PTR_BCS_PDF417 BarCodeSymbology enum Constant Pdf417
PTR_BCS_MAXICODE BarCodeSymbology enum Constant Maxicode
PTR_BCS_OTHER BarCodeSymbology enum Constant Other
PTR_BM_ASIS PosPrinter System.Int32 PrinterBitmapAsIs
PTR_BM_LEFT PosPrinter System.Int32 PrinterBitmapLeft

PTR_BM_CENTER PosPrinter System.Int32 PrinterBitmapCenter
PTR_BM_RIGHT PosPrinter System.Int32 PrinterBitmapRight
PTR_RP_NORMAL PrintRotation enum Constant Normal

PTR_RP_RIGHT90 PrintRotation enum Constant Right90
PTR_RP_LEFT90 PrintRotation enum Constant Left90
PTR_RP_ROTATE180 PrintRotation enum Constant Rotate180
PTR_RP_BARCODE PrintRotation enum Constant Barcode
PTR_RP_BITMAP PrintRotation enum Constant Bitmap
PTR_L_TOP PrinterLogoLocation enum Constant Top

PTR_L_BOTTOM PrinterLogoLocation enum Constant Bottom
PTR_TP_TRANSACTION PrinterTransactionControl enum Constant Transaction

PTR_TP_NORMAL PrinterTransactionControl enum Constant Normal
PrinterMarkFeeds enum Constant None

PTR_MF_TO_TAKEUP PrinterMarkFeeds enum Constant Takeup
PTR_MF_TO_CUTTER PrinterMarkFeeds enum Constant Cutter
PTR_MF_TO_CURRENT_TOF PrinterMarkFeeds enum Constant CurrentTopOfForm
PTR_MF_TO_NEXT_TOF PrinterMarkFeeds enum Constant NextTopOfForm
PTR_PS_UNKNOWN PrinterSide enum Constant Unknown

PTR_PS_SIDE1 PrinterSide enum Constant Side1
PTR_PS_SIDE2 PrinterSide enum Constant Side2
PTR_PS_OPPOSITE PrinterSide enum Constant Opposite
PTR_SUE_COVER_OPEN PrinterStatus enum Constant CoverOpen

PTR_SUE_COVER_OK PrinterStatus enum Constant CoverOK
PTR_SUE_JRN_EMPTY PrinterStatus enum Constant JournalEmpty
PTR_SUE_JRN_NEAREMPTY PrinterStatus enum Constant JournalNearEmpty
PTR_SUE_JRN_PAPEROK PrinterStatus enum Constant JournalPaperOK
PTR_SUE_REC_EMPTY PrinterStatus enum Constant ReceiptEmpty
PTR_SUE_REC_NEAREMPTY PrinterStatus enum Constant ReceiptNearEmpty
PTR_SUE_REC_PAPEROK PrinterStatus enum Constant ReceiptPaperOK
PTR_SUE_SLP_EMPTY PrinterStatus enum Constant SlipEmpty
PTR_SUE_SLP_NEAREMPTY PrinterStatus enum Constant SlipNearEmpty
PTR_SUE_SLP_PAPEROK PrinterStatus enum Constant SlipPaperOK
PTR_SUE_JRN_CARTRIDGE_EMPTY PrinterStatus enum Constant JournalCartridgeEmpty
PTR_SUE_JRN_CARTRIDGE_NEAREMPTY PrinterStatus enum Constant JournalCartridgeNearEmpty
PTR_SUE_JRN_HEAD_CLEANING PrinterStatus enum Constant JournalHeadCleaning
PTR_SUE_JRN_CARTRIDGE_OK PrinterStatus enum Constant JournalCartridgeOK
PTR_SUE_REC_CARTRIDGE_EMPTY PrinterStatus enum Constant ReceiptCartridgeEmpty
PTR_SUE_REC_CARTRIDGE_NEAREMPTY PrinterStatus enum Constant ReceiptCartridgeNearEmpty
PTR_SUE_REC_HEAD_CLEANING PrinterStatus enum Constant ReceiptHeadCleaning
PTR_SUE_REC_CARTRIDGE_OK PrinterStatus enum Constant ReceiptCartridgeOK
PTR_SUE_SLP_CARTRIDGE_EMPTY PrinterStatus enum Constant SlipCartridgeEmpty
PTR_SUE_SLP_CARTRIDGE_NEAREMPTY PrinterStatus enum Constant SlipCartridgeNearEmpty
PTR_SUE_SLP_HEAD_CLEANING PrinterStatus enum Constant SlipHeadCleaning
PTR_SUE_SLP_CARTRIDGE_OK PrinterStatus enum Constant SlipCartridgeOK
PTR_SUE_JRN_COVER_OPEN PrinterStatus enum Constant JournalCoverOpen
PTR_SUE_JRN_COVER_OK PrinterStatus enum Constant JournalCoverOK
PTR_SUE_REC_COVER_OPEN PrinterStatus enum Constant ReceiptCoverOpen
PTR_SUE_REC_COVER_OK PrinterStatus enum Constant ReceiptCoverOK
PTR_SUE_SLP_COVER_OPEN PrinterStatus enum Constant SlipCoverOpen
PTR_SUE_SLP_COVER_OK PrinterStatus enum Constant SlipCoverOK
PTR_SUE_IDLE PrinterStatus enum Constant Idle
EPTR_COVER_OPEN PosPrinter System.Int32 ExtendedErrorCoverOpen

EPTR_JRN_EMPTY PosPrinter System.Int32 ExtendedErrorJrnEmpty
EPTR_REC_EMPTY PosPrinter System.Int32 ExtendedErrorRecEmpty
EPTR_SLP_EMPTY PosPrinter System.Int32 ExtendedErrorSlpEmpty
EPTR_SLP_FORM PosPrinter System.Int32 ExtendedErrorSlpForm
EPTR_TOOBIG PosPrinter System.Int32 ExtendedErrorTooBig
EPTR_BADFORMAT PosPrinter System.Int32 ExtendedErrorBadFormat

Enumerations C-21
POS for .NET

ClassName
Type Name
EPTR_JRN_CARTRIDGE_REMOVED PosPrinter System.Int32 ExtendedErrorJrnCartridgeRemoved
EPTR_JRN_CARTRIDGE_EMPTY PosPrinter System.Int32 ExtendedErrorJrnCartridgeEmpty
EPTR_JRN_HEAD_CLEANING PosPrinter System.Int32 ExtendedErrorJrnHeadCleaning
EPTR_REC_CARTRIDGE_REMOVED PosPrinter System.Int32 ExtendedErrorRecCartridgeRemoved
EPTR_REC_CARTRIDGE_EMPTY PosPrinter System.Int32 ExtendedErrorRecCartridgeEmpty
EPTR_REC_HEAD_CLEANING PosPrinter System.Int32 ExtendedErrorRecHeadCleaning
EPTR_SLP_CARTRIDGE_REMOVED PosPrinter System.Int32 ExtendedErrorSlpCartridgeRemoved
EPTR_SLP_CARTRIDGE_EMPTY PosPrinter System.Int32 ExtendedErrorSlpCartridgeEmpty
EPTR_SLP_HEAD_CLEANING PosPrinter System.Int32 ExtendedErrorSlpHeadCleaning
PWR_UPS_FULL UpsChargeStates enum Constant Full

PWR_UPS_WARNING UpsChargeStates enum Constant Warning
PWR_UPS_LOW UpsChargeStates enum Constant Low
PWR_UPS_CRITICAL UpsChargeStates enum Constant Critical
PWR_SUE_UPS_FULL PosPower System.Int32 StatusUpsFull

PWR_SUE_UPS_WARNING PosPower System.Int32 StatusUpsWarning
PWR_SUE_UPS_LOW PosPower System.Int32 StatusUpsLow
PWR_SUE_UPS_CRITICAL PosPower System.Int32 StatusUpsCritical
PWR_SUE_FAN_STOPPED PosPower System.Int32 StatusFanStopped
PWR_SUE_FAN_RUNNING PosPower System.Int32 StatusFanRunning
PWR_SUE_TEMPERATURE_HIGH PosPower System.Int32 StatusTemperatureHigh
PWR_SUE_TEMPERATURE_OK PosPower System.Int32 StatusTemperatureOK
PWR_SUE_SHUTDOWN PosPower System.Int32 StatusShutDown
ROD_UID_1 DeviceUnits enum Constant nit1

ROD_UID_2 DeviceUnits enum Constant Unit2
ROD_ATTR_BLINK VideoAttributes enum Constant Blink
ROD_ATTR_BG_BLACK VideoAttributes enum Constant BackgroundBlack

ROD_ATTR_BG_BLUE VideoAttributes enum Constant BackgroundBlue
ROD_ATTR_BG_GREEN VideoAttributes enum Constant BackgroundGreen
ROD_ATTR_BG_CYAN VideoAttributes enum Constant BackgroundCyan
ROD_ATTR_BG_RED VideoAttributes enum Constant BackgroundRed
ROD_ATTR_BG_MAGENTA VideoAttributes enum Constant BackgroundMagenta
ROD_ATTR_BG_BROWN VideoAttributes enum Constant BackgroundBrown
ROD_ATTR_BG_GRAY VideoAttributes enum Constant BackgroundGray
ROD_ATTR_INTENSITY VideoAttributes enum Constant ntensity
ROD_ATTR_FG_BLACK VideoAttributes enum Constant ForegroundBlack

POS for .NET

ClassName
Type Name
ROD_ATTR_FG_BLUE VideoAttributes enum Constant ForegroundBlue
ROD_ATTR_FG_GREEN VideoAttributes enum Constant ForegroundGreen
ROD_ATTR_FG_CYAN VideoAttributes enum Constant ForegroundCyan
ROD_ATTR_FG_RED VideoAttributes enum Constant ForegroundRed
ROD_ATTR_FG_MAGENTA VideoAttributes enum Constant ForegroundMagenta
ROD_ATTR_FG_BROWN VideoAttributes enum Constant ForegroundBrown
ROD_ATTR_FG_GRAY VideoAttributes enum Constant ForegroundGray
ROD_BDR_SINGLE BorderType enum Constant Single

ROD_BDR_DOUBLE BorderType enum Constant Double
ROD_BDR_SOLID BorderType enum Constant Solid
ROD_CLK_START ClockFunction enum Constant Start

ROD_CLK_PAUSE ClockFunction enum Constant Pause
ROD_CLK_RESUME ClockFunction enum Constant Resume
ROD_CLK_MOVE ClockFunction enum Constant Move
ROD_CLK_STOP ClockFunction enum Constant Stop
ROD_CRS_LINE VideoCursorType enum Constant Line

ROD_CRS_LINE_BLINK VideoCursorType enum Constant LineBlink
ROD_CRS_BLOCK VideoCursorType enum Constant Block
ROD_CRS_BLOCK_BLINK VideoCursorType enum Constant BlockBlink
ROD_CRS_OFF VideoCursorType enum Constant Off
ROD_CS_UNICODE PosCommon System.Int32 CharacterSetUnicode

ROD_CS_ASCII PosCommon System.Int32 CharacterSetAscii
ROD_CS_WINDOWS
ROD_CS_ANSI PosCommon System.Int32 CharacterSetAnsi
ROD_TD_TRANSACTION RemoteOderDisplayTransaction enum Constant Transaction

ROD_TD_NORMAL RemoteOderDisplayTransaction enum Constant Normal
ROD_UA_SET VideoAttributeCommand enum Constant Set

ROD_UA_INTENSITY_ON VideoAttributeCommand enum Constant IntensityOn
ROD_UA_INTENSITY_OFF VideoAttributeCommand enum Constant IntensityOff
ROD_UA_REVERSE_ON VideoAttributeCommand enum Constant ReverseOn
ROD_UA_REVERSE_OFF VideoAttributeCommand enum Constant ReverseOff
ROD_UA_BLINK_ON VideoAttributeCommand enum Constant BlinkOn
ROD_UA_BLINK_OFF VideoAttributeCommand enum Constant BlinkOff
ROD_DE_TOUCH_DOWN RemoteOrderDisplayEventTypes enum Constant TouchDown

ROD_DE_TOUCH_MOVE RemoteOrderDisplayEventTypes enum Constant TouchMove
ROD_DE_TOUCH_UP RemoteOrderDisplayEventTypes enum Constant TouchUp
EROD_BADCLK RemoteOrderDisplay System.Int32 ExtendedErrorBadClock

EROD_NOCLOCKS RemoteOrderDisplay System.Int32 ExtendedErrorNoClocks
EROD_NOREGION RemoteOrderDisplay System.Int32 ExtendedErrorNoRegion
EROD_NOROOM RemoteOrderDisplay System.Int32 ExtendedErrorNoRoom
EROD_NOBUFFERS RemoteOrderDisplay System.Int32 ExtendedErrorNoBuffers
SCAL_WU_GRAM WaitUnit enum Constant Gram

SCAL_WU_KILOGRAM WaitUnit enum Constant Kilogram
SCAL_WU_OUNCE WaitUnit enum Constant Ounce
SCAL_WU_POUND WaitUnit enum Constant Pound
ESCAL_OVERWEIGHT Scale System.Int32 ExtendedErrorOverWeight
SCAN_SDT_UNKNOWN BarCodeSymbology enum Constant Unknown

SCAN_SDT_UPCA BarCodeSymbology enum Constant Upca
SCAN_SDT_UPCE BarCodeSymbology enum Constant Upce
SCAN_SDT_JAN8 BarCodeSymbology enum Constant EanJan8
SCAN_SDT_EAN8
SCAN_SDT_JAN13 BarCodeSymbology enum Constant EanJan13
SCAN_SDT_EAN13
SCAN_SDT_TF BarCodeSymbology enum Constant TF
SCAN_SDT_ITF BarCodeSymbology enum Constant Itf
SCAN_SDT_Codabar BarCodeSymbology enum Constant Codabar
SCAN_SDT_Code39 BarCodeSymbology enum Constant Code39
SCAN_SDT_UPCA_S BarCodeSymbology enum Constant Upcas
SCAN_SDT_UPCE_S BarCodeSymbology enum Constant Upces

Enumerations C-23
POS for .NET

ClassName
Type Name
SCAN_SDT_UPCD1 BarCodeSymbology enum Constant Upcd1
SCAN_SDT_EAN8_S BarCodeSymbology enum Constant Ean8S
SCAN_SDT_EAN13_S BarCodeSymbology enum Constant Ean13S
SCAN_SDT_EAN128 BarCodeSymbology enum Constant Ean128
SCAN_SDT_OCRA BarCodeSymbology enum Constant Ocra
SCAN_SDT_OCRB BarCodeSymbology enum Constant Ocrb
SCAN_SDT_RSS14 BarCodeSymbology enum Constant Rss14 - Deprecated v1.12
SCAN_SDT_RSS_EXPANDED BarCodeSymbology enum Constant RssExpanded - Deprecated v1.12
SCAN_SDT_GS1DATABAR BarCodeSymbology enum Constant GS1 DataBar Omnidirectional
SCAN_SDT_GS1DATABAR_E BarCodeSymbology enum Constant GS1 DataBar Expanded
SCAN_SDT_CCA BarCodeSymbology enum Constant Cca
SCAN_SDT_CCB BarCodeSymbology enum Constant Ccb
SCAN_SDT_CCC BarCodeSymbology enum Constant Ccc
SCAN_SDT_PDF417 BarCodeSymbology enum Constant Pdf417
SCAN_SDT_MAXICODE BarCodeSymbology enum Constant Maxicode
SCAN_SDT_OTHER BarCodeSymbology enum Constant Other
SC_CMODE_TRANS
SC_CMODE_BLOCK
SC_CMODE_APDU SmartCardInterfaceModes enum Constant Transaction
SC_CMODE_XML SmartCardInterfaceModes enum Constant Block
SmartCardInterfaceModes enum Constant Apdu
SC_CMODE_ISO SmartCardInterfaceModes enum Constant Xml
SC_CMODE_EMV
SmartCardIsoEmvModes enum Constant Iso
SC_CTRANS_PROTOCOL_T0 SmartCardIsoEmvModes enum Constant Emv
SC_CTRANS_PROTOCOL_T1
SmartCardTransactionProtocols enum Constant T0
SC_MODE_TRANS SmartCardTransactionProtocols enum Constant T1
SC_MODE_BLOCK
SC_MODE_APDU SmartCardInterfaceModes enum Constant Transaction
SC_MODE_XML SmartCardInterfaceModes enum Constant Block
SmartCardInterfaceModes enum Constant Apdu
SC_MODE_ISO SmartCardInterfaceModes enum Constant Xml
SC_MODE_EMV
SmartCardIsoEmvModes enum Constant Iso
SC_TRANS_PROTOCOL_T0 SmartCardIsoEmvModes enum Constant Emv
SC_TRANS_PROTOCOL_T1
SmartCardTransactionProtocols enum Constant T0
SC_READ_DATA SmartCardTransactionProtocols enum Constant T1
SC_READ_PROGRAM
SC_EXECUTE_AND_READ_DATA SmartCardReadAction enum Constant ReadData
SC_XML_READ_BLOCK_DATA SmartCardReadAction enum Constant ReadProgram
SmartCardReadAction enum Constant ExecuteAndReadData
SC_STORE_DATA SmartCardReadAction enum Constant XmlReadBlockData
SC_STORE_PROGRAM
SC_EXECUTE_DATA SmartCardWriteAction enum Constant StoreData
SC_XML_BLOCK_DATA SmartCardWriteAction enum Constant StoreProgram
SC_SECURITY_FUSE SmartCardWriteAction enum Constant ExecuteData
SC_RESET SmartCardWriteAction enum Constant XmlBlockData
SmartCardWriteAction SecurityFuse
SC_SUE_NO_CARD SmartCardWriteAction enum Constant Rest
SC_SUE_CARD_PRESENT
ESC_READ SmartCardRW System.Int32 ExtendedErrorRead

ESC_WRITE SmartCardRW System.Int32 ExtendedErrorWrite
ESC_TORN SmartCardRW System.Int32 ExtendedErrorTorn
ESC_NO_CARD SmartCardRW System.Int32 ExtendedErrorNoCard
ETOT_NOROOM HardTotals System.Int32 ExtendedErrorNoRoom

ETOT_VALIDATION HardTotals System.Int32 ExtendedErrorValidation
STAT_BarcodePrintedCount
STAT_BumpCount
STAT_CommunicationErrorCount PosPrinter System.String StatisticBarcodePrintedCount
BumpBar System.String StatisticBumpCount
STAT_DrawerFailedOpenCount PosCommon System.String StatisticCommunicationErrorCount

POS for .NET

ClassName
Type Name
STAT_DrawerGoodOpenCount PosCommon System.String StatisticDeviceCategory
STAT_FailedDataParseCount CashDrawer System.String StatisticDrawerFailedOpenCount
STAT_FailedPaperCutCount CashDrawer System.String StatisticDrawerGoodOpenCount
STAT_FailedPrintSideChangeCount Micr System.String StatisticFailedDataParseCount
STAT_FailedReadCount PosPrinter System.String StatisticFailedPaperCutCount
PosPrinter System.String StatisticFailedPrintSideChangeCount
STAT_FailedSignatureReadCount Micr System.String StatisticFailedReadCount
Msr System.String StatisticFailedReadCount
STAT_FormInsertionCount SignatureCapture System.String StatisticFailedSignatureReadCount
STAT_GoodReadCount PosCommon System.String StatisticFirmwareRevision
PosPrinter System.String StatisticFormInsertionCount
STAT_GoodScanCount Micr System.String StatisticGoodReadCount
STAT_GoodSignatureReadCount Msr System.String StatisticGoodReadCount
STAT_GoodWeightReadCount Scanner System.String StatisticGoodScanCount
STAT_HomeErrorCount SignatureCapture System.String StatisticGoodSignatureReadCount
STAT_HoursPoweredCount Scale System.String StatisticGoodWeightReadCount
PosPrinter System.String StatisticHomeErrorCount
PosCommon System.String StatisticHoursPoweredCount
STAT_InvalidPINEntryCount PosCommon System.String StatisticInstallationDate
STAT_JournalCharacterPrintedCount PosCommon System.String StatisticInterface
PinPad System.String StatisticInvalidPINEntryCount
STAT_JournalLinePrintedCount PosPrinter System.String StatisticJournalCharacterPrintedCount
STAT_KeyPressedCount PosPrinter System.String StatisticJournalCoverOpenCount
STAT_LockPositionChangeCount PosPrinter System.String StatisticJournalLinePrintedCount
PosKeyBoard System.String StatisticKeyPressedCount
Keylock System.String StatisticLockPositionChangeCount
STAT_MaximumTempReachedCount PosCommon System.String StatisticManufactureDate
PosCommon System.String StatisticManufacturerName
PosPrinter System.String StatisticMaximumTempReachedCount
STAT_MotionEventCount PosCommon System.String StatisticMechanicalRevision
STAT_NVRAMWriteCount PosCommon System.String StatisticModelName
STAT_OnlineTransitionCount MotionSensor System.String StatisticMotionEventCount
STAT_PaperCutCount PosPrinter System.String StatisticNVRAMWriteCount
STAT_PrinterFaultCount LineDisplay System.String StatisticOnlineTransitionCount
STAT_PrintSideChangeCount PosPrinter System.String StatisticPaperCutCount
STAT_ReceiptCharacterPrintedCount PosPrinter System.String StatisticPrinterFaultCount
STAT_ReceiptCoverOpenCount PosPrinter System.String StatisticPrintSideChangeCount
STAT_ReceiptLineFeedCount PosPrinter System.String StatisticReceiptCharacterPrintedCount
STAT_ReceiptLinePrintedCount PosPrinter System.String StatisticReceiptCoverOpenCount
PosPrinter System.String StatisticReceiptLineFeedCount
STAT_SlipCharacterPrintedCount PosPrinter System.String StatisticReceiptLinePrintedCount
STAT_SlipCoverOpenCount PosCommon System.String StatisticSerialNumber
STAT_SlipLineFeedCount PosPrinter System.String StatisticSlipCharacterPrintedCount
STAT_SlipLinePrintedCount PosPrinter System.String StatisticSlipCoverOpenCount
STAT_StampFiredCount PosPrinter System.String StatisticSlipLineFeedCount
STAT_ToneSoundedCount PosPrinter System.String StatisticSlipLinePrintedCount
PosPrinter System.String StatisticStampFiredCount
STAT_UnreadableCardCount ToneIndicator System.String StatisticToneSoundedCount
STAT_ValidPINEntryCount PosCommon System.String StatisticUnifiedPOSVersion
Msr System.String StatisticUnreadableCardCount
PinPad System.String StatisticValidPINEntryCount

Structures C-25
Structures
POS for .NET defines structure types to aggregate data values that are returned by
method calls. This is required since parameters in POS for .NET are In only. On
the other hand, structure types are used in POS for .NET to provide a more type-
safe handling for aggregated data. Structural strings containing several data
values that are returned by a UnifiedPOS property or method are broken into
members of a new defined structure type.
Structures are similar to classes. However, structures have value semantics and
they do not require heap allocation. The language concept of structures is
described under http://msdn.microsoft.com/library/en-us/csspec/html/
vclrfcsharpspec_11.asp.
The following structures are defined in POS for .NET.
CashCount Structure
The structure CashCount contains the dispensing cash units and counts.
Structure Properties
Name Description
Count Holds the number bills or coins.
NominalValue Holds the face value.
Type Defines whether the currency is bills or coins.
Used by
• CashChanger.DepositCounts Property as item type of the returned array, the
POS for .NET method has the following signature:
public abstract CashCount[] DepositCounts
• CashChanger.DispenseCash Method parameter array item type for the
parameter CashCounts, the POS for .NET method has the following signature:
public abstract void DispenseCash( CashCount[] cashCounts )
CashCounts Structure
The structure CashCounts aggregates an array of items of type CashCount
whether a cash discrepancy is given or not.
Name Description
Counts Holds the CashCount data.
If TRUE, there is some cash that could not be included in a
Discrepancy
CashCount; otherwise FALSE.
Used by
• CashChanger.ReadCashCounts Method as return value type, the POS for
.NET method has the following signature:
public abstract CashCounts ReadCashCounts()

CashUnits Structure
Holds the cash units supported in the CashChanger. The cash units are stored in
two separate String arrays for bills and coins.
Name Description
Bills Holds the number of each type of bill.
Coins Holds the number of each type of coin.
Used by
• CashChanger.DepositCashList Property as return value type, the POS for
public abstract CashUnits DepositCashList
• CashChanger.CurrenyCashList Property as return value type, the POS for
public abstract CashUnits CurrencyCashList
• CashChanger.ExitCashList Property as return value type, the POS for .NET
method has the following signature:
public abstract CashUnits ExitCashList
DirectIOData Structure
The structure DirectIOData aggregates values that are returned by the DirectIO
method.
Name Description
Data Specific values vary by Command and Service Object.
Object Specific object vary by Command and Service Object.
Used by
• PosCommon.DirectIO Method as return value type, the POS for .NET
public abstract DirectIOData DirectIO( int command, int data, object
obj )
FiscalDataItem Structure
The structure FiscalDataItem aggregates values that are returned by the GetData
method of the FiscalPrinter category.
Name Description
Data Character string describing data.
Optional additional parameter. Consult the Service Object
ItemOption vendor's documentation for more information about how to
use this argument.

Structures C-27
Used by
• FiscalPrinter.GetData Method as return value type, the POS for .NET
public abstract FiscalDataItem GetData(FiscalData dataItem, int
itemOption)
TotalsFileInfo Structure
The structure TotalsFileInfo aggregates file information for the HardTotals
device category.
Name Description
Handle Handle to the totals file.
Size Totals file size.
Used by
• Totals.Find Method as return value type, the POS for .NET method has the
following signature:
public abstract TotalsFileInfo Find( string fileName )
VatInfo Structure
The structure VatInfo aggregates VAT information used in the FiscalPrinter
category.
Name Description
Amount Indicates the VAT amount.
Id VAT identifier.
Used by
• FiscalPrinter.PrintRecPackageAdjustVoid Method as array item type of
the parameter vatAdjustments, the POS for .NET method has the following
signature:
public abstract void PrintRecPackageAdjustVoid(
FiscalAdjustmentType adjustmentType, VatInfo[] vatAdjustments )
• FiscalPrinter.PrintRecPackageAdjustment Method array item type of the
parameter vatAdjustments, the POS for .NET method has the following
signature:
public abstract void PrintRecPackageAdjustment(
FiscalAdjustmentType adjustmentType, string description, VatInfo[]
vatAdjustments )

VideoMode Structure
The structure VideoMode holds the video modes supported for the video unit
used by the RemoteOrderDisplay device category.
Name Description
Colors The number of colors.
Columns The number of columns.
IsColor TRUE if video is color; otherwise, FALSE
Rows The number of rows.
Used by
• RemoteOrderDisplay.VideoModesList Property as item type of the
returned array, the POS for .NET method has the following signature:
public abstract VideoMode[] VideoModesList
Complete Class Libraries Provided

• Interface Classes
• Interface libraries provide no code functionality. They represent the
interface to the device class only. There are Interface classes for each of
the device classes defined within UnifiedPOS.
• The interfaces meet or provide extensions to the UnifiedPOS
specification standards.
• The interface classes define all the constants needed for management of
device statistics, status reporting via events, and standard error
conditions.
• The interface classes define all the enumerations needed for all device
classes.
• Basic Classes
• Basic classes inherit from the Interface classes and implement the
common functionality across device classes. For example, the Basic
classes implement the Open(), Claim(), and Release() methods. There
are Basic classes for each of the device classes defined within
UnifiedPOS.
• The Basic classes not only manage all common properties and methods,
they manage event delivery to the application, retrieval and storage of
device statistics, manage error handling for all classes of errors, and
provide functionality for notifying the Service Object of hardware state
change conditions.
• Base Classes
• Base classes inherit from Basic classes and implement device class
specific functionality across device classes. With POS for .NET V 1.0,
there are eight Base Classes. The Device Service Object provider is left to
implement only the hardware-specific functionality.

Return Values C-29
• Base classes build on the basic class functionality by providing

implementations for all event types (as well as managing event delivery),
increment and manage all device statistics, manage validation of property
and parameter values (and deliver errors, as needed, to the application),
update all device-specific properties according to specification guidelines
as part of delivering data events to the application, plus provide a flexible
structure of protected methods and helper classes that the application can
use if it chooses to provide its own hardware-specific functionality.
Return Values
Many POS for .NET API calls return a value. For example, the common method
string CheckHealth (HealthCheckLevel level);
returns a string describing the health level. Parameters in POS for .NET are
In only.
Returning Properties
Often, an application method call will result in the change of a property value or
the method will return some status value as defined within the UnifiedPOS
specification.
For example, assume the following case:
An ISV calls a method that may change the value of a specific property. Further
processing is dependent upon the new value of the property. In the OPOS
implementation of UnifiedPOS, the ISV would first make a method call and then
call another method that would return the value of the property.
MethodThatChangesAProperty()
Dim MyProperty as Property
GetPropertyValue(MyProperty)
//GetPropertyValue has a
// byref parameter
Select MyProperty
case ….
In POS for .NET, the ISV would call the method and test the returned value as
follows (Visual Basic .NET):
Select MethodThatChangesAProperty()
Case ….
Returning Lists
Often, a method will return a list of values. In OPOS, methods that return lists do
so by returning strings that are comma-delimited (regardless of the data type of
the list item). The application must construct the string and do any necessary
conversion of the data items to a string, adding commas as delimiters.
The application will have to parse the string and cast the data items into the type
associated by the list. Example:

CHAR nChar = “,”;

int x;
int y = 0;
CHAR* pMyElements[];
CHAR* psCurrent;
for(x=0;x<len(sReturn);x++)
{
if(sReturn[x] == nChar)
{
pMyElements[y] = psCurrent;
y++;
}
psCurrent += sReturn[x];
}
//assumes all return types should be strings if not,
//cast to appropriate data type is required
In POS for .NET, arrays are native data types. There is no need to cast the data
elements to a coerced type. Further, arrays provide their own iterate functions to
allow easy access to any and all items in the list.
//use each item as needed
SomeMethod(ReturnedArray[0]);
SomeOtherMethod(ReturnedArray[1]);
NOTE:
From the SO, the following code demonstrates returning a clone – necessary to
preserve data safety.
return SomeArrary.Clone();
The reasons to return arrays instead of compound strings are as follows:
• Arrays are native data types in .NET and they can be enumerated with a FOR
EACH statement.
• Building and parsing delimited strings introduces more code that must be
maintained and increases the chance of introducing bugs.
• Clarity of intent of the code is clearer when arrays are used.
EXAMPLE:
To further illustrate the differences between UnifiedPOS, OPOS, and POS for
.NET, refer to the property PosPrinter.CharacterSetList. This property has the
following signature in UnifiedPOS:
CharacterSetList: string { read-only, access after open }
The property in UnifiedPOS returns a string with a comma separated list of code
page numbers. The application program has to parse the string to extract the code
page numbers and has to convert them to integer values if needed. In POS for
.NET, the property PosPrinter.CharacterSetList has the following method
signature:
public abstract int[] CharacterSetList
This returns the list of code page numbers as an integer array. There is no need for
parsing a string and converting code page numbers to integer values. This
approach is more type safe and easier to handle for application programmers.

Key Parameter Differences C-31
Key Parameter Differences

POS for .NET makes use of enumerations versus OPOS use of constants. POS for
.NET makes use of array data typing versus OPOS use of compound strings. POS
for .NET makes use of native integer types. POS for .NET makes use of “right-
sizing” variables (using variables that match the type of data they represent)
rather than OPOS use of data types for values that require more bytes than would
ever be necessary to contain the proper meaning and expected range.
POS for .NET divides a UnifiedPOS method into multiple POS for .NET
methods if it contains a parameter that can contain only 2 or 3 values. E.g., the
FiscalPrinter method printReport has the following signature under
UnifiedPOS:
printReport(reportType: int32, startNum: string, endNum: string): void
The parameter reportType can have only one of the following values -
FPTR_RT_ORDINAL or FPTR_RT_DATE. For FPTR_RT_DATE the two
following parameters have to be interpreted as date strings otherwise both values
have to be used as integer values.
In POS for .NET the reportType parameter is omitted. Instead two new methods
have been introduced defining printReport() with different signatures. These are
more type safe.
void PrintReport(DateTime startDate, DateTime endDate)
void PrintReport(int startNumber, int endNumber)
The following table lists the method/parameter differences in POS for .NET
compared to the corresponding UnifiedPOS method/parameters. Methods
differing only by the usage of an Enumeration type are not listed.
UnifiedPOS Method POS for .NET Signature
CashChanger
dispenseCash(cashCounts: string): void void DispenseCash(CashCount[] cashCounts)
FiscalPrinter
getData(dataItem: int32, inout optArgs: int32,
FiscalDataItem GetData(FiscalData dataItem,
inout data: string): void int itemOption)
printPeriodicTotalsReport(date1: string, void PrintPeriodicTotalsReport(DateTime
date2: string): void startingDate, DateTime endingDate)
printRecItem(description: string, price: void PrintRecItem(string description, decimal
currency, quantity: int32, vatInfo: int32, price, decimal quantity, int vatId, decimal
unitPrice: currency, unitName: string): void unitPrice, string unitName)
printRecPackageAdjustment(adjustmentType void PrintRecPackageAdjustment(
: int32, description: string, vatAdjustment: FiscalAdjustmentType adjustmentType,
string): void string description, VatInfo[] vatAdjustments)
void PrintRecPackageAdjustVoid(
printRecPackageAdjustVoid(adjustmentType:
FiscalAdjustmentType adjustmentType,
int32, vatAdjustment: string): void
VatInfo[] vatAdjustments)
printReport(reportType: int32, startNum: void PrintReport(DateTime startDate,
string, endNum: string): void DateTime endDate)
printReport(reportType: int32, startNum: void PrintReport(int startNumber, int
string, endNum: string): void endNumber)
printReport(reportType: int32, startNum:
void PrintReport(int startNumber)
string, endNum: string): void
setDate(date: string): void void SetDate(DateTime newDate)
setVatValue(vatID: int32, vatValue: string):
void SetVatValue(int vatId, decimal vatRate)
void

Key Property Signature Differences

There are several properties which have different POS for .NET signatures
compared to UnifiedPOS. They use arrays or structures instead of comma
separated lists inside strings. The following table shows these properties.
UnifiedPOS Property POS for .NET Signature

CashChanger
CurrencyCodeList public abstract string[] CurrencyCodeList
CurrencyCashList public abstract CashUnits CurrencyCashList
DepositCodeList public abstract string[] DepositCodeList
DepositCounts public abstract CashCount[] DepositCounts
ExitCashList public abstract CashUnits ExitCashList
CheckScanner
QualityList public abstract int[] QualityList
FiscalPrinter
PredefinedPaymentLines public abstract string[] PredefinedPaymentLines
POSPrinter
CharacterSetList public abstract int[] CharacterSetList
FontTypefaceList public abstract string[] FontTypefaceList
RecBarCodeRotationList public abstract Rotation[] RecBarCodeRotationList
RecBitmapRotationList public abstract Rotation[] RecBitmapRotationList
SlpBarCodeRotationList public abstract Rotation[] SlpBarCodeRotationList
SlpBitmapRotationList public abstract Rotation[] SlpBitmapRotationList
RemoteOrderDisplay
VideoModesList public abstract VideoMode[] VideoModesList
More Information
Samples are available in the POS for .NET Software Development Kit (SDK)
which is available for download at www.microsoft.com/downloads/
results.aspx?pocid=&freetext=POS%20for%20.NET%20SDK&displaylang=en.

PosExplorer API C-33
PosExplorer API
PosExplorer is used by applications to acquire a list of installed POS devices,
open—or create instances of—service objects for those devices, and receive
Plug-n-Play events when the devices are connected or disconnected from the
system.
PosExplorer Properties
PosRegistryKey Property
Syntax public static string PosRegistryKey {read-only}
Remarks Holds the POS for .NET configuration root registry key relative to
HKEY_LOCAL_MACHINE.
StatisticsFile Property
Syntax public static string StatisticsFile {read-only}
Remarks Holds the path to the file in which device statistics is persisted.
SynchronizingObject Property
Syntax public ISynchronizeInvoke SynchronizingObject {read-write}
Remarks Sets or holds the ISynchronizeInvoke object.

PosExplorer Methods
CreateInstance Method
Syntax public PosDevice CreateInstance(DeviceInfo device)
Remarks Instantiates the device based on the information supplied by the property values of
the DeviceInfo object.
device An object that describes the device you want to create
an instance of, and which is an instance of the
DeviceInfo class. DeviceInfo contains properties such
as Compatibility, Description, HardwareID, and so on,
for the device.
GetDevice Method (string)

Syntax public DeviceInfo GetDevice(string type)
Remarks Retrieves a device of the specified type.
type A string that contains one of the UnifiedPOS device
types, as defined by the DeviceType helper class.
There must be only one device of that type currently in the system, or if there is
more than one, one must have been configured as the default device. If there is
more than one device of the specified type and no device has been configured as
the default device, a PosLibraryException will be thrown.
This signature of GetDevice represents the simplest case for retrieving and
instantiating a device in the POS for .NET system. To retrieve one device and
instantiate its service object, the application must only:
• Create an instance of PosExplorer;
• Call GetDevice using the above method signature; and
• Call CreateInstance.
POS for .NET initializes the device of the type specified or, if there is more than
one device of that type, the pre-configured default device for that type.
GetDevice Method (string, string)

Syntax public DeviceInfo GetDevice(string type, string logicalName)
Remarks Retrieves a device of the specified type and name (or alias).
logicalName The logical name or alias of the device.

PosExplorer Methods C-35
GetDevices Method
Syntax public DeviceCollection GetDevices()
Remarks Retrieves all POS devices currently installed in the system.
GetDevices Method (DeviceCompatibilities)

Syntax public DeviceCollection GetDevices(DeviceCompatibilities compatibility)
Remarks Retrieves all POS devices currently installed in the system, based on a
compatibility level.
compatibility DeviceCompatibilities enumeration that indicates
GetDevices Method (string)

Syntax public DeviceCollection GetDevices(string type)
Remarks Retrieves all POS devices of the specified type.
GetDevices Method (string, DeviceCompatibilities)

Syntax public DeviceCollection GetDevices(string type, DeviceCompatibilities
compatibility)
Remarks Retrieves all POS devices of the specified type, based on a compatibility level.
compatibility DeviceCompatibilities enumeration that indicates
Refresh Method
Syntax public void Refresh()
Remarks Re-enumerates the list of attached POS devices and rebuilds the internal data
structures.

PosExplorer Events
DeviceAddedEvent Event
Syntax public event DeviceChangedEventHandler DeviceAddedEvent;
Remarks Notifies the application when a POS device has been added to the system.
DeviceAddedEvent only notifies for POS devices for which there is a service
object installed.
The event handler receives an argument of type DeviceChangedEventArgs
which contains a DeviceInfo object for the added device.
DeviceRemovedEvent Event
Syntax public event DeviceChangedEventHandler DeviceRemovedEvent;
Remarks Notifies the application when a POS device has been removed from the system.
DeviceRemovedEvent only notifies for POS devices for which there is a service
object installed.
The event handler receives an argument of type DeviceChangedEventArgs
which contains a DeviceInfo object for the removed device.

Global Configuration C-37
Global Configuration
PosExplorer reads the global configuration file (config.xml), which enables
application developers to specify aliases for Plug-n-Play and non Plug-n-Play
devices, and to define physical devices for non Plug-n-Play Service Objects.
The global configuration file also enables application developers to define more
than one physical device associated with a non Plug-n-Play Service Object and to
assign aliases and device paths (such as COM ports) to them. This enables
Application Developers to target non Plug-n-Play Service Objects to specific
physical devices.
Service Object Registry

In OPOS, configuration information for Service Objects is stored in the registry.
In POS for .NET, configuration information is stored in Config.xml. POS for
.NET enables seamless access to registry information for COM Service Objects
through PosExplorer; the Common Control Library does the work of gathering
registry configuration information.
Consuming Service Objects

OPOS
Control Objects represent the application interface to its matching Service Object.
The UnifiedPOS standard does not provide any code for Control Objects.
However, it does suggest that the OPOS Control objects located at http://
www.monroecs.com/oposccos.htm be used or at the very least tested against. In
addition, the site holds an ActiveX® Control that is an aggregation of all device
classes. This is commonly referred to as the Common Controls Objects.
Under OPOS it is common practice for IHVs, ISVs, and OEMs to create their
own versions of Control Objects and to not use or test the referenced Common
Control Objects. This has lead to compatibility issues between hardware,
services, and application code.
The OPOS implementation consists of the following steps:
• Instantiate an instance of the Control Object
• Call the Control Objects:
• Open to load the Service Object by name
• Claim
• Enable
Note that on a device-by-device basis, there may be properties that must be read
or set before interacting with the device for device-specific functionality.

POS for .NET

To instantiate a Service Object in POS for .NET, do the following:
• Instantiate the PosExplorer object.
• Use the PosExplorer.GetDevice or GetDevices method to obtain a list of one
or more DeviceInfo objects that represent devices attached to the machine.
• Call PosExplorer.CreateInstance, passing in the DeviceInfo for the device you
want to load.
• Call methods/properties on the Service Object returned by the previous step.
The supplied PosExplorer tool is a helper class that acts as a Service Object
Factory. The developer will instantiate: Sample POSExplorer.GetDevice(…);
This approach provides the following benefits:
• Achieves infrastructure required to support feature set (see POS for .NET
features).
• Simplifies an application: One section of code can be used to dynamically
instantiate a Service Object.
• For most cases it eliminates the need for detailed knowledge of the specific
brand of hardware peripheral.
• An application can easily get a list of available POS peripherals actually
attached to the device (Available for Plug-n-Play).
• For an application there is no difference between .NET SOs and OPOS SOs.
Writing Service Objects

POS for .NET
There are three different approaches available:
• Derive the Service Object from the Interface class
• Derive the Service Object from the Basic class
• Derive the Service Object from the Base class
There are different levels of work required for the Service Object writer for each
approach. For example, deriving from the Interface class requires the most
amount of code to be implemented by the service application yet gives it the most
control over the operation of the Service Object. By deriving from the Basic
class, the service application only has to implement the core functionality of the
device. The Basic class already provides the common functionality. Deriving
from the Base class leaves the service application with only having to implement
the specific hardware functionality; the basic functionality of the device class has
already been provided.

Status, State Model, and Exceptions C-39
Status, State Model, and Exceptions

The status, error code, and state models are built around several common
enumerations, events, and a property, described below:
StatusUpdateEvent
An event fired when some class-specific state or status variable has changed.
ControlState
An enumeration containing the current state. Possible values are:
• Closed
• Idle
• Busy
• Error
Exceptions
Every POS for .NET method invocation and property access may throw a
PosControlException upon failure, except for accesses to the properties
DeviceControlVersion, DeviceControlDescription, and State. No other types
of exceptions will be thrown.
PosControlException is defined in the namespace Microsoft.PointOfService,
and extends System.Exception.
Public Properties
Name Description
ErrorCode causing the error exception. See the list of Error
ErrorCode
Codes on page 52.
Extended Error Code causing the error exception. This may
ErrorCodeExtended
The constructor variations are defined as follows:

PosControlException (string message, ErrorCode errorCode)
PosControlException (string message, ErrorCode errorCode, Exception
innerException)
PosControlException (string message, ErrorCode errorCode, int
errorCodeExtended)
PosControlException (string message, ErrorCode errorCode, int
errorCodeExtended, Exception innerException)
The parameters are defined as follows:
errorCode The POS for .NET error code. Access is through the
ErrorCode getter method.
errorCodeExtended May contain an extended error code. If not provided by
the selected constructor, then is set to zero. Access is
through the ErrorCodeExtended getter method.

message A text description of the error. If not provided by the

selected constructor, then one is formed from the
errorCode and errorCodeExtended parameters. Access
is through the superclass’ getter method Message or
method ToString.
innerException Original exception. If the POS for .NET Service caught
a non-POS for .NET exception, then an appropriate
errorCode is selected and the original exception is
referenced by this parameter. Otherwise, it is set to null.
Access is through the inherited getter method
InnerException.

Device Sharing Model C-41

The POS for .NET device sharing model supports devices that are to be used
exclusively by one application at a time, as well as devices that may be partially
or fully shared by multiple applications. All POS for .NET service objects may be
opened by more than one application at a given time. Some or many of the
activities that an application can perform with the service object, however, may
be restricted to an application that claims access to the device.
The most common device type is called an “exclusive-use device”. An example is
the POSPrinter. Due to physical or operational characteristics, this device can
only be used by one application at a time. The application must call the Claim
method to gain exclusive access to the device before most methods, properties, or
events are legal. Until the device is claimed, calling methods or setting properties
cause an Illegal error, and events are not fired to the application.
Should two closely cooperating applications want to treat an exclusive-use device
in a shared manner, then one application may claim the device for a short
sequence of operations, then release it so that the other application may use it.
When the Claim method is called again, settable device characteristics are
restored to their condition at Release. Examples of restored characteristics are the
LineDisplay's brightness, the MSR's tracks to read, and the POSPrinter's
characters per line. State characteristics are not restored, such as the POSPrinter's
sensor properties. Instead, these are updated to their current values.
Sharable Devices
Some devices are “sharable devices”. An example is the Keylock. A sharable
device allows multiple applications to call its methods and access its properties.
Also, it may fire its events to all applications that have opened it. A sharable
device may still limit access to some methods or properties to an application that
has claimed it, or may fire some events only to this application.

POS for .NET implements UnifiedPOS events as standard .NET events with
multicast delegates.
The events inform an application of various activities or changes with a device, or
when a device is added or removed. The event types are as follows:
Event Description
Input data has been placed into device class-
DataEvent
specific properties
An error has occurred during event-driven
ErrorEvent
input or asynchronous output.
StatusUpdateEvent Reports a change in the device’s status.
An asynchronous output has successfully
OutputCompleteEvent
completed.
This event may be defined by a Service
DirectIOEvent Object provider for purposes not covered by
the specification.
The Service Object queues events as they occur. Queued events are delivered to
the application when conditions are correct. Conditions that delay the delivery of
events include:
• The application has set the property FreezeEvents to TRUE.
• The event type is DataEvent or an input ErrorEvent, but the property
DataEventEnabled is FALSE.
Note: The following event terminology is used in this document.
Queue When the Service Object determines that an event needs to
be fired to the application, it queues the event on an internal
event queue.
Deliver When the event queue is non-empty and all conditions are
met for the top event on the queue, this event is removed
from the queue and delivered to the application.
Fire The combination of queuing and delivering an event.
Sometimes, the term is used more loosely and may only
refer to one of these steps. The reader should differentiate
these cases by context.
• The Service Object can only queue new events while the device is enabled.
• The Service Object can deliver queued events until the application calls the
Release method (for exclusive-use devices) or the Close method (for any
device), at which time any remaining events are deleted.

Input Model C-43
• For input devices, the ClearInput method clears data and input error events.
While within an event handler, the application may access properties and call
methods. However, the application must not call the Release or Close
methods from an event handler, because Release may shut down event
handling (possibly including a thread that caused the event to be delivered)
and Close must shut down event handling before returning.
Input Model Updated in Release 1.12
The POS for .NET input model supports event-driven input. Event-driven input
allows input data to be received after DeviceEnabled is set to TRUE. Received
data is queued as a DataEvent, which is delivered to the application when
preconditions are correct. If the AutoDisable property is TRUE when data is
received, then the control will automatically disable itself, setting
DeviceEnabled to FALSE. This will inhibit the Service Object from queuing
further input and, when possible, physically disable the device.
When the application is ready to receive input from the device, it sets the
DataEventEnabled property to TRUE. Then, when input is received (usually as
a result of a hardware interrupt), the Control enqueues and delivers a DataEvent.
(If input has already been enqueued, the DataEvent will be delivered.) This event
may include input status information through a numeric parameter. The Control
places the input data plus other information as needed into device-specific
properties just before the event is fired.
Just before delivering this event, the Control disables further data events by
setting the DataEventEnabled property to FALSE. This causes subsequent input
data to be enqueued by the Control while the application processes the current
input and associated properties. When the application has finished the current
input and is ready for more data, it re-enables events by setting
DataEventEnabled to TRUE.
If the input device is an exclusive-use device, the application must both claim and
enable the device before the device begins reading input.
For sharable input devices, one or more applications must open and enable the
device before the device begins reading input. An application must call the Claim
method to request exclusive access to the device before the Control will send data
to it using the DataEvent. If event-driven input is received, but no application
has claimed the device, then the input is buffered until an application claims the
device (and the DataEventEnabled property is TRUE). This behavior allows
orderly sharing of the device between multiple applications, effectively passing
the input focus between them.
If the Control encounters an error while gathering or processing event-driven
input, then the Control changes its state to Error, and enqueues one or two
ErrorEvents to alert the application of the error condition. This event (or events)
is not delivered until the DataEventEnabled property is TRUE, so that orderly

Error events are delivered with the following loci:
InputData – Only queued if the error occurred while one or more DataEvent
events are queued. It is enqueued ahead of all DataEvents. This event gives the
application the ability to immediately clear the input, or to optionally alert the
user to the error and process the buffered input.
The latter case may be useful with a Scanner Control. The user can be
immediately alerted to the error so that no further items are scanned until the error
is resolved. Any previously scanned items can then be successfully processed
before error recovery is performed.
Input – Delivered when an error has occurred and there is no data available. (A
typical implementation would place it at the tail of the event queue.) If some input
data was already enqueued when the error occurred, then an ErrorEvent with the
locus InputData was queued and delivered first, and then this error event is
delivered after all DataEvents have been fired. (If an “InputData” event was
delivered and the application event handler responded with a “Clear”, then this
“Input” event is not delivered.)
The Control exits the Error state when one of the following occurs:
• The application returns from the Input ErrorEvent.
• The application returns from the InputData ErrorEvent with a Clear
ErrorResponse.
• The application calls the ClearInput method.
For some Controls, the Application must call a method to begin event-driven
input. After the input is received by the Control, then typically no additional input
The DataCount property can be read to obtain the number of DataEvents
queued by the Control.
All input queued by a Control can be deleted by calling the ClearInput method.
ClearInput can be called after Open for sharable devices and after Claim for
of device classes containing methods or properties that return input data directly.
Some device classes will define such methods and properties in order to operate
in a more intuitive or flexible manner. An example is the Keylock device. This
type of input is sometimes called “synchronous input.”

Output Model C-45
Output Model
The POS for .NET output model consists of two output types: synchronous and
asynchronous. A device class can support one or both types, or neither type.
Synchronous Output
This type of output is preferred when device output can be performed quickly. Its
merit is simplicity.
The application calls a class-specific method to perform output. The service
object does not return until the output is completed.
interactions. Its merit is perceived responsiveness, because the application can
The application calls a class-specific method to start the output. The Service
Object buffers the request in program memory, for delivery to the Physical
Device as soon as the Physical Device can receive and process it, sets the
OutputId property to an identifier for this request, and returns as soon as
possible. When the device completes the request successfully, POS for .NET fires
an OutputCompleteEvent. A parameter of this event contains the OutputId of
the completed request.
If an error occurs while performing an asynchronous request, an ErrorEvent is
fired. The application’s event handler can either retry the outstanding output or
clear it. The Service Object is in the Error state while the ErrorEvent is in
progress. (Note that if the condition causing the error was not corrected, then the
Service Object can immediately reenter the Error state and fire another
ErrorEvent.) Asynchronous output is performed on a first-in, first-out basis. All
buffered output data, including all asynchronous output, can be deleted by calling
ClearOutput. OutputCompleteEvents are not fired for cleared output. This
to the application. If the ErrorResponse is Clear, then outstanding asynchronous
output is cleared. If the ErrorResponse is Retry, then output is retried; note that
if several outputs were simultaneously in progress at the time that the error was
detected, then the Service may need to retry all of these outputs.


This state is managed by the PowerState enumeration.
Note: This model is not intended to report PC or POS Terminal power conditions
(such as “on battery” and “battery low”). Reporting of these conditions is now
managed by the PosPower enumeration.
Model
POS for .NET segments device power into four states:
Online The device is powered on and ready for use. This is the
Off The device is powered off or detached from the
terminal. This is a “non-operational” state.
Offline The device is powered on but is either not ready or not
able to respond to requests. It may need to be placed
online by pressing a button, or it may not be responding
to terminal requests. This is a “non-operational” state.
OffOffline The device is either off or offline, and the Service
Object cannot distinguish these states.
_____________________________________________________
Note – Enabled/Disabled vs. Power States
These states are different and usually independent. POS for .NET defines “disabled” /
“enabled” as a logical state, whereas the power state is a physical state. A device may be
logically “enabled” but physically “offline”. It may also be logically “disabled” but
physically “online”. Regardless of the physical power state, POS for .NET only reports the
state while the device is enabled. (This restriction is necessary because a Service Object
typically can only communicate with the device while enabled.) If a device is “offline”, then
a Service Object may choose to fail an attempt to “enable” the device. However, once
enabled, the Service Object may not disable a device based on its power state.
_____________________________________________________

Power Reporting Properties C-47
Power Reporting Properties

The POS for .NET device power reporting model adds the following common
elements across all device classes:
CapPowerReporting property: Identifies the reporting capabilities of the device.
This property is a PowerReporting enumeration value:
None The Service Object cannot determine the state of the
Standard The Service Object can determine and report two of the
power states – OffOffline (that is, off or offline) and
Online.
Advanced The Service Object can determine and report all three
power states – Online, Offline, and Off.
PowerState enumeration: Maintained by the Service Object at the current power

condition, if it can be determined. This value can be one of:
• Unknown
• Online
• Off
• Offline
• OffOffline
PowerNotify property: The Application can set this property to enable power
reporting via StatusUpdateEvents and the PowerState enumeration. This
property can only be set before the device is enabled (that is, before
DeviceEnabled is set to TRUE). This restriction allows simpler implementation
of power notification with no adverse effects on the application. The application
is either prepared to receive notifications or does not want them, and has no need
to switch between these cases. This property returns a PowerNotification
enumeration, the value of which is either Disabled or Enabled.


CapPowerReporting is not None, and PowerNotify is Enabled:
When the Control changes from DeviceEnabled FALSE to TRUE, then begin
If the device is Online, then:
• PowerState is set to Online.
• A StatusUpdateEvent is fired with StatusUpdateEventArgs.Status
property set to Online.
If the device power state is Off, Offline, or OffOffline, then the Control can
choose to fail the enable, throwing a PosControlException and setting
ErrorCode to NoHardware or OffLine.
However, if there are no other conditions that cause the enable to fail, and the
Control chooses to return success for the enable, then:
• PowerState is set to Off, Offline, or OffOffline.
• A StatusUpdateEvent is fired with the StatusUpdateEventArgs.Status
property set to PowerOff, Offline, or OffOffline.
Device Information Reporting Model

Examples of configuration data are the device’s serial number, firmware version,
and connection type. Examples of usage data for the POSPrinter device are the
Number of Lines Printed, Number of Hours Running, Number of paper cuts, and
so on. Examples of usage data for the Scanner device are the Number of scans,
the Number of successful swipes, Number of swipes resulting in errors, Number
of Hours Running, etc.
when required. This is done by using the Claim method and by setting
DeviceEnabled to TRUE when access to a device is required and then setting
DeviceEnabled to FALSE and using the Release method when access to the
device is no longer needed. Coordination of device access via this mechanism is
the responsibility of the applications themselves.

Statistics Reporting Properties and Methods C-49

• CapStatisticsReporting property. Identifies the reporting capabilities of
the device. When CapStatisticsReporting is FALSE, then no statistical
data regarding the device is available. This is equivalent to Services
compatible with prior versions of the specification. When
CapStatisticsReporting is TRUE, then some statistical data for the
device is available.
• CapUpdateStatistics property. Defines whether gathered statistics (or
some of them) can be reset/updated by the application. This property is
only valid if CapStatisticsReporting is TRUE. When
CapUpdateStatistics is FALSE, then none of the statistical data can be
reset/updated by the application. Otherwise, when CapUpdateStatistics
is TRUE, then (some of) the statistical data can be reset/updated by the
application.
• ResetStatistics method. Can only be called if both
CapStatisticsReporting and CapUpdateStatistics are TRUE. This
method resets one, some, or all of the resettable device statistics to zero.
• RetrieveStatistics method. Can only be called if
CapStatisticsReporting is TRUE. This method retrieves one, some, or
all of the accumulated statistics for the device.
• UpdateStatistics method. Can only be called if both
CapStatisticsReporting and CapUpdateStatistics are TRUE. This
method updates one, some, or all of the resettable device statistics to the
supplied values.

POS for .NET Component Descriptions
POS for .NET Data Types Updated in Release 1.11

The parameter and return types specified in the POS for .NET descriptions are as
follows:
VB.NET .NET Framework UnifiedPOS
C# Type Description
Type Type Type
A Boolean value (TRUE or
bool Boolean System.Boolean boolean
FALSE).
byte Byte System.Byte Arbitrary binary data. byte
System.Array with
byte[] Byte() array element type Arbitrary binary data array. binary
System.Byte
decimal Decimal System.Decimal A currency value. currency
int Integer System.Int32 Signed 32-bit integer. int32
System.Array with
int[] Integer() array element type Signed 32-bit integer array. int32 array
System.Int32
Provides information about a
specific culture, such as the
System.
names of the culture, the
CultureInfo CultureInfo Globalization. nls
writing system, the calendar
CultureInfo
used, and how to format
dates and sort strings.
An object reference. This will
usually be a subclass to the
root of the class hierarchy to
object Object System.Object object
provide a Device Service-
specific parameter for
directIO or DirectIOEvent.
System.Array with An array of ordered pairs of
array element type integer x- and y-coordinates
Point[] Point() array of points
System.Drawing. that define a point in a two-
Point dimensional plane.
An immutable, fixed-length
string String System.String string
string of Unicode characters.

POS for .NET Common Properties, Methods, Events, Statistics, and Constants C-51
POS for .NET Common Properties, Methods, Events,

Statistics, and Constants
Name Type
AutoDisable bool
CapCompareFirmwareVersion bool
CapPowerReporting PowerReporting
CapStatisticsReporting bool
CapUpdateFirmware bool
CapUpdateStatistics bool
CheckHealthText string
Claimed bool
Compatibility DeviceCompatibilities
DataCount int
DataEventEnabled bool
DeviceDescription string
DeviceEnabled bool
DeviceName string
DevicePath string
FreezeEvents bool
OutputId int
PowerNotify PowerNotification
PowerState PowerState
ServiceObjectDescription string
ServiceObjectVersion System.version
State ControlState
SynchronizingObject System.ComponentModel.ISynchronizeInvoke
The common properties are explained in detail further below.

The following are POS for .NET implementation-specific definitions of Common

Methods:
CheckHealth ( HealthCheckLevel level );

Claim ( int timeout );
ClearInput ();
ClearInputProperties ();
ClearOutput ();
Close ();
CompareFirmwareVersion ( string filename );
DeleteConfigurationProperty ( string propertyName );
DirectIO ( int command, int data, object obj );
GetConfigurationProperty ( string propertyName );
Invoke ( Delegate method, object[] args );
Open ();
Release ();
ResetStatistics ();
ResetStatistics ( StatisticCategories statistics );
ResetStatistics ( string[] statistics );
RetrieveStatistics ( StatisticCategories statistics );
RetrieveStatistics ( string[] statistics );
RetrieveStatistic ( string statistic );
UpdateFirmware ( string filename );
UpdateStatistic ( string name, object value );
UpdateStatistics ( Statistic[] statistics );
UpdateStatistics ( StatisticCategories statistics, object value );
The common methods are explained in detail further below.
Common Events
Events in the .NET Framework are based on the delegate model. For more
information about the delegate model, on how to consume events in applications,
and how to raise events from a class, see http://msdn.microsoft.com/library/
default.asp?url=/library/en-us/cpguide/html/cpconevents.asp.
The following are POS for .NET implementation-specific definitions of Common

Events:
DataEventHandler DataEvent;
DirectIOEventHandler DirectIOEvent;
DeviceErrorEventHandler ErrorEvent;
OutputCompleteEventHandler OutputCompleteEvent;
StatusUpdateEventHandler StatusUpdateEvent;
The common events are explained in detail further below.

POS for .NET Common Properties, Methods, Events, Statistics, and Constants C-53
Common Statistics
StatisticUnifiedPOSVersion= “UnifiedPOSVersion”;
StatisticDeviceCategory= “DeviceCategory”;
StatisticManufacturerName= “ManufacturerName”;
StatisticModelName = “ModelName”;
StatisticSerialNumber= “SerialNumber”;
StatisticManufactureDate= “ManufactureDate”;
StatisticMechanicalRevision= “MechanicalRevision”;
StatisticFirmwareRevision= “FirmwareRevision”;
StatisticInterface = “Interface”;
StatisticInstallationDate= “InstallationDate”;
StatisticHoursPoweredCount= “HoursPoweredCount”;
StatisticCommunicationErrorCount = “CommunicationErrorCount”;
Common Constants
int WaitForever= -1;

int StatusPowerOnline= 2001;
int StatusPowerOff= 2002;
int StatusPowerOffline= 2003;
int StatusPowerOffOffline= 2004;
int ExtendedErrorStatistics= 280;

Common Properties
AutoDisable Property
Type bool
Remarks If true, the Service will set DeviceEnabled to false after it receives and enqueues
data as a DataEvent. Before any additional input can be received, the application
must set DeviceEnabled to true.
If false, the Service does not automatically disable the device when data is
received.
Errors A PosControlException may be thrown when this property is accessed. For
further information, see “Exceptions” on page C-39.
Type bool
CapPowerReporting Property
Type PowerReporting
Remarks Identifies the reporting capabilities of the device. Possible values are defined by
the PowerReporting enumeration.
The service object should then set PowerReporting based on the capabilities of
the device.
Value Meaning
None The Service Object cannot determine the state of the
Standard The Service Object can determine and report two of the
power states – OffOffLine (that is, off or offline) and
Online.
Advanced The Service Object can determine and report all three
power states – Off, OffLine, and OnLine.
Errors None.

Common Properties C-55
CapStatisticsReporting Property
Type bool
Remarks If set to TRUE, the device accumulates and can provide various statistics
regarding usage. The information accumulated is device-specific, and can be
retrieved using the RetrieveStatistic(s) method.
Type bool
Remarks If true, then the device’s firmware can be updated via the UpdateFirmware
method.
CapUpdateStatistics Property
Type bool
Remarks If set to TRUE, some or all of the device statistics can be reset to 0 (zero) using the
ResetStatistic(s) methods, or updated using the UpdateStatistic(s) methods.
If the CapStatisticsReporting property is set to FALSE, CapUpdateStatistics
will always be FALSE.
Type string
Remarks Contains text indicating the health of the device. Updated by the service object
when the application calls the CheckHealth method.
Claimed Property
Type bool
Remarks If TRUE, the device is claimed for exclusive access. If FALSE, the device is
released for sharing with other applications.
Exclusive use devices must be claimed using the Claim method before the
service object will allow access to many of its methods and properties, and before
the service object will fire events to the application.

Compatibility Property
Type DeviceCompatibilities
Remarks Indicates the compatibility level of a device.
Member Name Description
CompatibilityLevel1 Indicates compatibility with any .NET service object.
Opos Indicates compatibility with any COM service object.
OposAndCompatibilityLevel1
Indicates compatibility with any .NET or COM service
object.
DataCount Property
Type int
DataEventEnabled Property
Type bool
application, the DataEvent will remain queued at the Service until the condition
is corrected.)

DeviceDescription Property
Type string
Remarks Contains text identifying the device and any pertinent information about it. A
sample of the text might be:
This property is initialized when the application calls the Open method.
Errors None.
DeviceEnabled Property
Type bool
Remarks When TRUE, the device has been placed in an operational state. If changed to
TRUE, then the device is brought to an operational state.
When FALSE, the device has been disabled. If changed to FALSE, then the
device is physically disabled when possible. Any subsequent input will be
discarded, and output operations are disallowed.
Changing DeviceEnabled usually does not physically affect output devices. For
consistency, however, the application must set DeviceEnabled to TRUE before
using output devices.
DeviceName Property
Type string
Remarks Contains a short string identifying the device and any pertinent information about
it.
This is a short version of DeviceDescription and should be limited to 30
characters.
DeviceName will typically be used to identify the device in an application
message box, where the full description is too verbose. A sample DeviceName
string is:
“NCR 7192 Printer, Japanese”
Errors None.

DevicePath Property
Type string
Remarks Contains the hardware path of a device.
The PosExplorer class attempts to initialize DevicePath to the hardware path of
the physical device using the following algorithm:
• If the physical hardware supports Plug and Play and the service object is
mapped to a specific hardware ID via the HardwareId custom attribute or a
configuration XML file, PosExplorer class will set DevicePath to the
HardwarePath of the physical device. Service objects can typically use this
DevicePath to directly access the device.
• If the device does not support Plug and Play, but has been configured via
Posdm.exe or WMI, DevicePath will be set to the path specified when the
device was configured.
• If the device does not support Plug and Play and has not been configured via
Posdm.exe or WMI, DevicePath will be set to empty string (“”) and must be
set by the service object before the Open method in the base/basic class can
be called.
FreezeEvents Property Updated in Release 1.12

Type bool
Remarks When set to TRUE, the application has requested that the service object not deliver
events. Events will be queued by the service object but not delivered until the
application changes FreezeEvents to FALSE.
When set to FALSE, the application allows events to be delivered. If some events
have been held while events were frozen and all other conditions are correct for
delivering the events, changing FreezeEvents to FALSE will allow these events
to be delivered.
An application can choose to freeze events for a specific sequence of code where
interruption by an event is not desirable.

OutputId Property
Type int
When a method successfully initiates an asynchronous output, the Service assigns
The output ID numbers are assigned by the Service and are guaranteed to be
unique among the set of outstanding asynchronous outputs. No other facts about
the ID should be assumed.
PowerNotify Property
Type PowerNotification
Remarks Contains the type of power notification selection made by the application. Possible
values are defined by the PowerNotification enumeration.
PowerNotify can only be set while the device is disabled, that is, while the
DeviceEnabled property is set to FALSE.
PowerState Property
Type PowerState
Remarks Contains the current power condition. Possible values are defined by the
PowerState enumeration.
When PowerNotify is set to enabled and DeviceEnabled is TRUE, PowerState
is updated as the service object detects power condition changes. When the power
state changes, the service object updates PowerState and queues a
StatusUpdateEvent event, notifying the application.
Errors None.
ServiceObjectDescription Property
Type string
Remarks Contains a string identifying the service object supporting the device and the
company that produced it.
A sample ServiceObjectDescription string is:
“TM-T88IV Printer POS for .Net Service Driver, (C) 2005 Epson”

ServiceObjectVersion Property
Type System.version
Remarks ServiceObjectVersion holds the service object version number. Version numbers
consist of two to four integers, Major, Minor, Build, and Revision. Build and
Revision are optional, but Revision is optional only if Build is not specified.
The Major and Minor version numbers correspond to the UnifiedPOS version
implemented by the service object. A service object that implements the
UnifiedPOS 1.8 specification would set Major=1 and Minor=8. The Build and
Revision version numbers are optional and can be used by the service object to
track its internal version.
State Property
Type ControlState
Remarks Contains the current state of the device. Possible values are defined by the
ControlState enumeration.
State is set to ControlState.Idle by the Open method and is always readable,
regardless of the state of the device.
Errors None.
SynchronizingObject Property
Type System.ComponentModel.ISynchronizeInvoke
Remarks Contains an instance of the ISynchronizeInvoke class. Applications can use this
property to specify the thread events that are to be delivered on. If
SynchronizingObject is set to null, events are delivered on an internal thread
owned by the service object. Applications using Windows Forms should set
SynchronizationObject to the this pointer of the main Form class so that events
are delivered on the main application thread ... as required by the Form class.

Common Methods C-61
Common Methods
CheckHealth Method
Syntax string CheckHealth ( HealthCheckLevel level );
Remarks The application calls CheckHealth to test the state of a device. CheckHealth is
always performed synchronously. The service object returns a string indicating the
health level and updates the CheckHealthText property.
device. Possible values are defined by the HealthCheckLevel enumeration.
Value Meaning
Internal Perform a health check that does not physically change
extent possible.
External Perform a more thorough test that may change the
printer.
Interactive Perform an interactive test of the device. The supporting
Service Object will typically display a modal dialog box
to present test options and results.
Errors A PosControlException may be thrown when this method is invoked. For further
information, see “Exceptions” on page C-39.
CheckHealth may throw the following PosControlException:
ErrorCode Value Description
The specified health check level is not supported by the
Illegal
service object.

Claim Method
Syntax void Claim ( int timeout );
Remarks The application calls Claim to request exclusive access to the device. Many
devices require an application to claim them before they can be used.
If the timeout parameter is set to 0 (zero), the method attempts to claim the
device, then returns the appropriate status immediately. If timeout is set to
WaitForever (-1), Claim waits until exclusive access is satisfied.
An application can claim a device more than once without generating an error.
When Claim is successful, the Claimed property is set to TRUE.
The timeout parameter contains the maximum number of milliseconds to wait for
exclusive access to be satisfied.
Claim may throw the following PosControlExceptions:

One of the following conditions has occurred:
The device cannot currently be claimed for exclusive
Illegal
access; or a value of less than -1 has been specified for the
timeout parameter.
Another application has exclusive access to the device and
Timeout did not relinquish control before timeout milliseconds
expired.
ClearInput Method
Syntax void ClearInput ();
cleared.
ClearInputProperties Method Added in Release 1.11
Syntax void ClearInputProperties ();

State properties.

Common Methods C-63
ClearOutput Method
Syntax void ClearOutput ();
Close Method
Syntax void Close ( );
Remarks The application calls Close to release the device and its resources.
If the DeviceEnabled property is set to TRUE, the device will be disabled. If the
Claimed property is set to TRUE, the device will be released.
Close may throw the following PosControlExceptions:
The State property is set to ControlState.Busy, indicating
Busy
that the device is currently in use and cannot be shut down.
Closed The device is already closed.
CompareFirmwareVersion Method Added in Release 1.11

Syntax CompareFirmwareResult CompareFirmwareVersion (
string firmwareFileName );
Specifies either the name of the file containing the firmware
firmwareFileName or a file containing a set of firmware files whose versions are
to be compared against those of the device.
operation.
The result of the comparison is returned in the enumeration
CompareFirmwareResult and will be one of the following values:

Value Meaning
Older Indicates that the version of one or more of the
Same Indicates that the versions of all of the firmware
Newer Indicates that the version of one or more of the
Different Indicates that the version of one or more of the
determined, or
Unknown Indicates that a relationship between the two
possible reason for this enumeration could be
an attempt to compare Japanese and US
versions of firmware.
modification to the firmware list file.
CompareFirmwareVersion may throw the following PosControlExceptions:

Illegal CapCompareFirmwareVersion is false.
The file specified by firmwareFileName does not exist or, if
NoExist firmwareFileName specifies a file list, one or more of the
component firmware files are missing.
ErrorCodeExtended = EFIRMWARE_BAD_FILE:
Extended The specified firmware file or files exist, but one or more are
either not in the correct format or are corrupt.

Common Methods C-65
DirectIO Method
Syntax DirectIOData DirectIO ( int command, int data, object obj );
Remarks The application calls DirectIO to communicate directly with the service object.
Using DirectIO allows a service object to provide functionality to the application
that is not otherwise supported by the standard service interface for its device
class. Depending on the service object’s definition of the command, DirectIO
may be asynchronous or synchronous.
DirectIO returns an instance of the DirectIOData structure.
The command number. Specific values are assigned by the
command
service object.
Additional numeric data. Specific values vary by command
data
and the service object.
Additional data supplied by the service object. Specific
obj values vary by command and by what the service object
chooses to transmit.
Open Method
Syntax void Open ( );
Remarks The application calls Open to open a device for subsequent input/output
processing. Open initializes the values of numerous properties, including
DataEventEnabled, FreezeEvents, AutoDisable, Claimed, and so on.
Open may throw the following PosControlException:

Illegal The device is already opened

Release Method
Syntax void Release ( );
Remarks The application calls Release to release exclusive access to the device.
If the DeviceEnabled property is set to TRUE, and the device is an exclusive-use
device, the device is first disabled. (Release does not change the device-enabled
state of sharable devices.) If Release is successful, it sets the Claimed property to
FALSE.
Release may throw the following PosControlExceptions:

Busy The device is in use.
Illegal The application does not have exclusive access to the
device; or the device is not claimed.
ResetStatistic Method (string)

Syntax void ResetStatistic ( string statistic );
Remarks statistic specifies the statistic that is to be reset.
The application calls ResetStatistic to reset the specified statistic to 0 (zero). For
ResetStatistic to be successful, both the CapStatisticsReporting and
CapUpdateStatistics properties must be set to TRUE.
ResetStatistic is always executed synchronously.
ResetStatistic may throw the following PosControlExceptions:

Either the CapStatisticsReporting or
Illegal CapUpdateStatistics property is set to FALSE;
The statistic parameter is null; or
The specified statistic does not exist.
ExtendedErrorStatistics. The specified statistic can not be
Extended
reset.

Common Methods C-67
ResetStatistics Method ()
Syntax void ResetStatistics ( );
Remarks Resets all statistics associated with a device to 0 (zero).
For ResetStatistics to be successful, both the CapStatisticsReporting and
ResetStatistics is always executed synchronously.
ResetStatistics may throw the following PosControlExceptions:

The CapStatisticsReporting or
Illegal
CapUpdateStatistics property is set to FALSE.
ExtendedErrorStatistics. At least one of the specified
Extended
statistics could not be reset.
ResetStatistics Method (StatisticsCategories)

Syntax void ResetStatistics ( StatisticCategories statistics );
Remarks Resets all statistics for a specified category to 0 (zero).
The statistics parameter contains the category of statistics the application wants
to reset for the device. Possible categories are defined by the StatisticsCategories
enumeration.

The CapStatisticsReporting or CapUpdateStatistics
Illegal
property is set to FALSE; or the specified statistics category
is not valid.
ExtendedErrorStatistics. At least one of the specified sta-
Extended
tistics could not be reset.

ResetStatistics Method (String[])

Syntax void ResetStatistics ( string [] statistics );
Remarks Resets the specified statistics to 0 (zero).
The statistics parameter contains a comma-separated string of statistics.

Illegal
property is set to FALSE; or
One of the specified statistics is not defined.
ExtendedErrorStatistics. At least one of the specified sta-
Extended
tistics could not be reset.
RetrieveStatistic Method (string)

Syntax string RetrieveStatistic ( string statistic );
Remarks The application calls RetrieveStatistic to retrieve the specified device statistic.
RetrieveStatistic is always executed synchronously.
The statistic parameter specifies the statistic that is to be retrieved.
RetrieveStatistic returns and XML string of statistics if successful.
RetrieveStatistic may throw the following PosControlException:

The CapStatisticsReporting property is set to FALSE, in-
Illegal dicating that the device does not support statistics reporting;
The statistic parameter is null or has a length of 0 (zero); or
the specified statistic does not exist.

Common Methods C-69
RetrieveStatistics Method ()
Syntax string RetrieveStatistics ( );
Remarks The application calls RetrieveStatistics to retrieve all device statistics.
RetrieveStatistics is always executed synchronously.
RetrieveStatistics returns an XML string of statistics if successful.
RetrieveStatistics may throw the following PosControlException:

The CapStatisticsReporting property is set to FALSE,
Illegal indicating that the device does not support statistics
reporting.
RetrieveStatistics Method (StatisticCategories)

Syntax string RetrieveStatistics ( StatisticCategories statistics );
Remarks Retrieves the statistics for the specified category.
The statistics parameter contains the category of statistics the application wants
to retrieve. Possible values are defined by the StatisticCategories enumeration.
RetrieveStatistics returns an XML string of statistics if successful.

indicating that the device does not support statistics
Illegal
reporting;
The statistics parameter is null or has a length of 0 (zero);
or the specified statistics category is invalid.

RetrieveStatistics Method (String[])

Syntax string RetrieveStatistics ( string [] statistics );
Remarks Retrieves the statistics for the specified category.
The statistics parameter contains a comma-separated string of statistics. Retrieves
the specified string of statistics.
RetrieveStatistics returns an XML string of statistics if successful
indicating that the device does not support statistics
Illegal
reporting;
The statistics parameter is null or has a length of 0 (zero); or,
one or more of the specified statistics do not exist.
UpdateFirmware Method Added in Release 1.11

Syntax UpdateFirmware ( string firmwareFileName );
Specifies either the name of the file containing the firmware
firmwareFileName or a file containing a set of firmware files that are to be
downloaded into the device.
continue asynchronously.
The Service should notify the application of the status of the update firmware
process by firing StatusUpdateEvents with values of SUE_UF_PROGRESS + an
integer between 1 and 100 indicating the completion percentage of the update
firmware process. For application convenience, the StatusUpdateEvent value
SUE_UF_COMPLETE is defined to be the same value as SUE_UF_PROGRESS
+ 100.

Common Methods C-71
SUE_UF_COMPLETE, which has the same value. These Service requirements
allow applications using this method to be designed to always expect some level
of progress notification.
Value Meaning
SUE_UF_FAILED_DEV_OK The update firmware process failed but the
UpdateFirmware may throw the following PosControlExceptions:
Illegal CapUpdateFirmware is false.
The file specified by firmwareFileName does not exist or, if
NoExist firmwareFileName specifies a file list, one or more of the
component firmware files are missing.
ErrorCodeExtended = EFIRMWARE_BAD_FILE:
Extended The specified firmware file or files exist, but one or more are
either not in the correct format or are corrupt.

UpdateStatistic Method
Syntax void UpdateStatistic ( string name, object value );
Remarks The application calls UpdateStatistic to update the value of a specified device
statistic.
For UpdateStatistic to be successful, both the CapStatisticsReporting and
UpdateStatistic is always executed synchronously.
name Name of the statistic to be updated.
value Value to which the statistic should be set.
UpdateStatistic may throw the following PosControlExceptions:

Illegal
property is set to FALSE; or
The specified statistic does not exist.
ExtendedErrorStatistics. The specified statistic could not
Extended
be updated.
UpdateStatistics Method (Statistic[])
Syntax void UpdateStatistics ( Statistic [] statistics );
Remarks Updates a list of statistics with the corresponding specified values.
For UpdateStatistics to be successful, both the CapStatisticsReporting and
UpdateStatistics is always executed synchronously.
The statistics parameter contains an array of Statistic class instances (name-value
pairs).
UpdateStatistics may throw the following PosControlExceptions:
Illegal property is set to FALSE; or
The statistics parameter is null; or
One or more of the specified statistics does not exist.
Extended
statistics could not be updated.

Common Methods C-73
UpdateStatistics Method (StatisticCategories, Object)

Syntax void UpdateStatistics ( StatisticCategories statistics, object value );
Remarks Updates the specified category of statistics with the specified value.
For UpdateStatistics to be successful, both the CapStatisticsReporting and
UpdateStatistics is always executed synchronously.
Contains the category of statistics the application wants to
statistics update. Possible categories are defined by the
StatisticCategories enumeration.
Contains the value to be used to update the statistics in the
value
specified category.
UpdateStatistics may throw the following PosControlExceptions:

One of the following conditions has occurred: The
CapStatisticsReporting or CapUpdateStatistics property
Illegal
is set to FALSE; or The specified statistics category is
invalid.
Extended
statistics could not be updated.

Common Events
DataEvent Event
Remarks Fired to present input data from the device to the application. The
DataEventEnabled property is changed to FALSE, so that no further data events
will be generated until the application sets this property back to TRUE. The actual
input data is placed in one or more device-specific properties.
If DataEventEnabled is FALSE at the time that data is received, then the data is
queued in an internal buffer, the device-specific input data properties are not
updated, and the event is not delivered. (When this property is subsequently
changed back to TRUE, the event will be delivered immediately if input data is
queued and FreezeEvents is FALSE.)
DirectIOEvent Event
Remarks Fired by the service object to communicate information directly to the application.
DirectIOEvent provides a means for a service object to communicate information
in the form of an event to the application that would not otherwise be supported by
other events or properties defined for the device. Use of this event may restrict the
application from being used with other vendor’s devices which may not have any
knowledge of the service object’s need for this event.
ErrorEvent Event Updated in Release 1.12
Remarks Fired when an error is detected and the service object's State transitions into the
error state.
Input error events are not delivered until the DataEventEnabled property is
TRUE, so that proper application sequencing occurs.
OutputCompleteEvent Event
Remarks Fired when a previously started asynchronous output request completes
successfully. The OutputID property indicates the ID number of the
asynchronous output request that is complete.
StatusUpdateEvent Event
Remarks Fired when the service object needs to alert the application of a device status
change.
Examples are a change in the cash drawer position (open vs. closed), a change in
a POS printer sensor (form present vs. absent), or a change in the power state of
the device.
When a device is enabled, the service object may fire initial StatusUpdateEvents
to inform the application of the device state. This behavior, however, is not
required.

POS for .NET vs. UnifiedPOS Members C-75
POS for .NET vs. UnifiedPOS Members

POS for .NET class member names sometimes vary from those in the
UnifiedPOS specification. In many cases, the variance is only in case (.NET uses
the Pascal naming convention for methods, properties, and events). For example,
the common property OutputID in the UnifiedPOS specification is OutputId in
POS for .NET.
For some devices, POS for .NET introduces several properties and methods not
found in the UnifiedPOS specification.
The table below has examples of some of the property names that vary from the
UnifiedPOS specification:
UnifiedPOS Property Corresponding POS for .NET Property
CapMACCalculation CapMacCalculation
DeviceServiceDescription ServiceObjectDescription
DeviceServiceVersion ServiceObjectVersion
OutputID OutputId
POSKeyData PosKeyData
POSKeyEventType PosKeyEventType
PhysicalDeviceDescription DeviceDescription
PhysicalDeviceName DeviceName
N/A Compatibility
N/A DevicePath
N/A SynchronizingObject
The table below includes some of the method names that vary from the
UnifiedPOS specification:
UnifiedPOS Method Corresponding POS for .NET Method
beginEFTTransaction BeginEftTransaction
checkHealth CheckHealth
claim Claim
computeMAC ComputeMac
DeviceServiceVersion ServiceObjectVersion
directIO DirectIO
enablePINEntry EnablePinEntry
endEFTTransaction EndEftTransaction
read Read
resetStatistics ResetStatistics
verifyMAC VerifyMac
N/A ResetStatistic
N/A RetrieveStatistic
N/A UpdateStatistic
The table below includes event names that vary from the UnifiedPOS
specification:
Corresponding POS for .NET EventArg
UnifiedPOS Event Attribute
Class Property
OutputID OutputId
N/A public DateTime TimeStamp {get; }

Interim Procedure Available For Legacy OPOS Services...

Shim Code Usage
Updated in Release 1.11
The .NET architecture allows for new features and functions that can be invoked
using current and future Windows operating systems. In order to benefit from all
the .NET architecture has to offer, new service objects should be written.
However, in order to more quickly leverage existing OPOS service object source
code in the .NET environment, OPOS-Japan (OPOS-J) has created a translation
middle layer of software, referred to as the “Shim”. The “Shim” is a module to
develop (or implement) a .NET Service Object by utilizing existing OPOS based
service object naming methodologies. It is freely available for service object
providers to use when porting their existing OPOS service objects to POS for
.NET. Some of the reasons behind the strategy in using the Shim are as follows:
• POS for .NET extends the definitions for the UnifiedPOS methods and
requires modifications in the OPOS service objects to handle these extensions.
The Shim handles these extensions and masks any changes that would
otherwise be required to be made to an existing OPOS service object.
• POS for .NET requires enumeration types in its usage, a feature that was not
specified in an OPOS service object implementation. The Shim provides a
mechanism to map constants of the parameters to an enumeration type without
changing the name from the existing OPOS service object source code.
• It is important to note that the usage of the Shim does not require any changes
to the .NET application; the Shim hides any OPOS and POS for .NET service
object differences from the application. When a POS for .NET service object
is available, it should be able to replace the Shim/OPOS service object with
no required changes to the application.
• The development of the POS Application should be in accordance with the
reference material outlined earlier in this appendix. The only difference is in
the development of the service object used to support a UnifiedPOS, POS for
.NET environment. Potentially, usage of the Shim allows for faster generation
of POS for .NET service objects by allowing for greater re-usability of
existing OPOS service object source code.

Architecture Structures C-77
Architecture Structures Added in Release 1.11

The following diagram shows the structures of the OPOS, POS for .NET, and
Shim-POS for .NET architectures.
WePOS (WindowsXP Embedded for POS) Operational Environment

Current
OPOS
Win32 Application .NET Application Structure
a b c d
WePOS Subsystem POSExplorer

will be used
.NET Framework instead of
CO & SO
OPOS CCL I/F Class (24)

CO/CCO
Basic Class (24)
InterOp Layer Base Class (8)
Shim
a b c d
OLE OPOS SO POS for .NET SO POS for .NET SO
Notes:
Route a: Current OLE POS path between Win32 application and OLE OPOS SO
Route b: .NET application and current OLE OPOS SO
Route c: .NET application and POS for .NET SO (Microsoft’s Implementation)
Route d: .NET application and POS for .NET SO (OPOS-J’s SOs w/Shim)

Method of Implementation
Shim Code Naming rules
The Shim code extends the POS for .NET Basic class as described below:
Microsoft.PointOfService.BasicServiceObjects NameSpace.
The names of the Shim classes comply with the following rule:
<DeviceCategoryName>+ShimBasic
For example:
PosPrinterShimBasic
LineDisplayShimBasic
The file name that defines the Shim class complies with the following rule:
<Class Name>.cs
For example:
PosPrinterShimBasic.cs
LineDisplayShimBasic.cs
The shim class is defined in the following NameSpace:
Opos.PointOfService.BasicShimServiceObjects.
The file that defines the specific enumeration type is specified in a separate file
associated with its device category. The file name that defines this takes the same
name as the header file of the OPOS Common Control Object (CCO).
For example:
Constants definition for POS Printer,
OposPtr.cs
Constants definition for LineDisplay
OposDisp.cs
The enumeration type name is derived from the name associated with the
function parameter that uses the constants.
For example, the alignment parameter that is used with the PrintBarCode
function supported by a POS Printer would map as follows:
OposPtr.cs
Enum BarCodeAlignment
{
Left = -1,
Center = -2,
Right = -3
}
The enumeration type is defined in the following NameSpace:
Opos.PointOfService

Method of Implementation C-79
Shim Method Redefinition Rules

As noted earlier in this appendix, POS for .NET method calls are handled
differently than UnifiedPOS OPOS implementations. For instance, under POS for
.NET return values are used instead of OPOS requiring a separate method call to
obtain the information. The Shim provides the translation code to allow for the
mapping of these operational differences.
The functions of the UnifiedPOS specification that are implemented differently
between POS for .NET and OPOS are redefined using an abstract attribute at the
protected level.
For example, the DirectIO method would map as follows:
public override DirectIOData DirectIO (int command, int data, object obj)
{
;
}
protected abstract void DirectIO (int command, ref int data, ref object obj);
Note that the abstract function that UnifiedPOS defined, DirectIO, is called in a
way that is consistent with the POS for .NET Application implementation
requirements. However, the Shim code performs the necessary functions to
process the OPOS DirectIO method and any other method calls to obtain the
method functionality and data exchange. The Shim code then responds back to
the POS for .NET Application with the functionality and result codes that are
consistent with what it is expecting to see. Continuing with the example:
public override DirectIOData DirectIO (int command, int data, object obj)
{
this.DirectIO (command, ref data, ref obj);
return new DirectIOData (data, obj);
}
/** The abstract function implements it with Service Object that extends
the Shim class.**/
It is possible that the implementation of the function regarded as the object of the
translation could be implemented by the Shim class. In order to prevent that from
happening, the sealed attribute is added to prevent the override in Service Object.
For example:
public sealed override DirectIOData DirectIO (int command, int data, object obj)
Shim Code Rules For In/Out Parameters

Any OPOS parameter that is defined with an In/Out attribute in the UnifiedPOS
specification is handled differently under a POS for .NET implementation. POS
for .NET is expecting the data to be provided as return values. The Shim code
facilitates this mapping by using the “ref” attribute to the In/Out parameter. This
translation is handled automatically by the Shim code and is transparent to the
calling application.

Method of Administration
The source for the Shim components is managed by the OPOS-J Committee. The
Shim source code is currently available to the public from the following web site:
http://www.monroecs.com/posfordotnet/shim.htm.
Shim Code File Names

The following is a list of the files that are currently available with the Shim Code.
The naming convention has been chosen to provide as much intuitive device
usage as possible. As new devices are released, the Shim Code will be updated to
reflect the new devices. In addition, bug fixes and other support issues will be
handled by OPOS-J.

Shim Code File Names C-81
Shim file list

Shim class files Description
CashChangerShimBasic.cs Shim class of CashChanger
CashDrawerShimBasic.cs Shim class of CashDrawer
CatShimBasic.cs Shim class of Cat
CheckScannerShimBasic.cs Shim class of CheckScanner
CoinDispenserShimBasic.cs Shim class of CoinDispenser
HardTotalsShimBasic.cs Shim class of HardTotals
KeylockShimBasic.cs Shim class of Keylock
LineDisplayShimBasic.cs Shim class of LineDisplay
MicrShimBasic.cs Shim class of Micr
MsrShimBasic.cs Shim class of Msr
PinPadShimBasic.cs Shim class of PinPad
PointCardRWShimBasic.cs Shim class of PointCardRW
PosKeyboardShimBasic.cs Shim class of PosKeyboard
PosPowerShimBasic.cs Shim class of PosPower
PosPrinterShimBasic.cs Shim class of PosPrinter
ScaleShimBasic.cs Shim class of Scale
ScannerShimBasic.cs Shim class of Scanner
SmartCardRWShimBasic.cs Shim class of SmartCardRW
ToneIndicatorShimBasic.cs Shim class of ToneIndicator
Enumeration type definition files Description
OposCash.cs Enumeration type for CashDrawer
OposCat.cs Enumeration type for Cat
OposChan.cs Enumeration type for CashChanger
OposChk.cs Enumeration type for CheckScanner
OposCoin.cs Enumeration type for CoinDispenser
OposDisp.cs Enumeration type for LineDisplay
OposKbd.cs Enumeration type for PosKeyBoard
OposLock.cs Enumeration type for Keylock
OposMicr.cs Enumeration type for Micr
OposMsr.cs Enumeration type for Msr
OposPcrw.cs Enumeration type for PointCardRW
OposPpad.cs Enumeration type for PinPad
OposPtr.cs Enumeration type for PosPrinter
OposPwr.cs Enumeration type for PosPower
OposScal.cs Enumeration type for Scale
OposScan.cs Enumeration type for Scanner
OposScrw.cs Enumeration type for SmartCardRW
OposTone.cs Enumeration type for ToneIndicator
OposTot.cs Enumeration type for HardTotals
Project files Description
AssemblyInfo.cs Assembly information file
Opos.PointOfService.BasicShimServiceObjects.csproj Project file

Class Diagrams
Interface Class
public abstract DirectIOData DirectIO(int command, int data, object obj)

public abstract void ResetStatistic(string statistic)
public abstract void ResetStatistics()
public abstract void ResetStatistics(StatisticCategories statistics)
public abstract void ResetStatistics(string[] statistics)
public abstract string RetrieveStatistic(string statistic)
public abstract string RetrieveStatistics()
public abstract string RetrieveStatistics(StatisticCategories statistics)
public abstract string RetrieveStatistics(string[] statistics)
public abstract void UpdateStatistic(string name, object value)
public abstract void UpdateStatistics(Statistic[] statistics)
public abstract void UpdateStatistics(StatisticCategories statistics, object value)
:
:
Basic Class
public override void ResetStatistic(string statistic)

public override void ResetStatistics()
public override void ResetStatistics(StatisticCategories statistics)
public override void ResetStatistics(string[] statistics)
public override string RetrieveStatistic(string statistic)
public override string RetrieveStatistics()
public override string RetrieveStatistics(StatisticCategories statistics)
public override string RetrieveStatistics(string[] statistics)
public override void UpdateStatistic(string name, object value)
public override void UpdateStatistics(Statistic[] statistics)
public override void UpdateStatistics(StatisticCategories statistics, object value)
:
:

Class Diagrams C-83
Shim Class
public sealed override DirectIOData DirectIO(int command, int data, object obj)
public sealed override void ResetStatistic(string statistic)
public sealed override void ResetStatistics()
public sealed override void ResetStatistics(StatisticCategories statistics)
public sealed override void ResetStatistics(string[] statistics)
public sealed override string RetrieveStatistic(string statistic)
public sealed override string RetrieveStatistics()
public sealed override string RetrieveStatistics(StatisticCategories statistics)
public sealed override string RetrieveStatistics(string[] statistics)
public sealed override void UpdateStatistic(string name, object value)
public sealed override void UpdateStatistics(Statistic[] statistics)
public sealed override void UpdateStatistics(StatisticCategories statistics, object value)
protected abstract void DirectIO(int command, ref int data, ref object obj)
protected abstract void ResetStatistics(string statistics)
protected abstract void RetrieveStatistics(ref string statistics)
protected abstract void UpdateStatistics(string statistics)
:
:
Service Class
protected override void DirectIO(int command, ref int data, ref object obj)
protected override void ResetStatistics(string statistics)
protected override void RetrieveStatistics(ref string statistics)
protected override void UpdateStatistics(string statistics)
:
:


A P P E N D I X D
XMLPOS — XML POS Mapping Reference
This appendix was added in Release 1.12 of this specification.
Overview
UnifiedPOS is providing a component of the architecture to include Web
technologies based on XML. This XML mapping is called XMLPOS.
XMLPOS essentially extends UnifiedPOS to enable Enterprise Applications
access to remote peripherals by mapping (as much as possible) the UML
Property/Method/Event parameters of UnifiedPOS directly into XML elements,
inside XML documents. There are two pieces to XMLPOS, first the mapping of
the UnifiedPOS Property/Method/Events into equivalent XML Tag Names, then
grouping these tag names into appropriate W3C XML Schemas following ARTS,
ARTS-XML Best Practices.
XMLPOS requirements
• Application support for remote input devices (e.g., Scanner)
• Application support for remote output devices (e.g., Printer)
• Share output peripherals between multiple applications.
• Minimize changes to existing UnifiedPOS-compliant Applications
• <*Optionally*> Minimize changes to existing UnifiedPOS-compliant
Device Services
• Heterogeneous Platform Connectivity
• Interoperability between Enterprise Applications and devices
• Must be (relatively) transparent to existing applications, device services
• Must provide adequate performance despite device remoteness
• No “per device type” translation required
• Efficiently operate in the web services arena
• Efficiently operate in a browser.
• Needs to work in both the single command and aggregated command
environments. That is, to issue a single command in one message or issue a
set of commands with one message.
Out of Scope
• Non-universal extensions.
UnifiedPOS Retail Peripheral Architecture Appendix D
D-2 XMLPOS - XML POS Mapping Reference
Referenced Documents
• ARTS-XML Data Dictionary
• UnifiedPOS, Retail Peripheral Architecture V1.12
• ARTS, ARTS-XML Best Practices V2.0.0
• [ISO 2382]ISO/IEC 2382-14:1997 Information technology - Vocabulary -
Part 14 Reliability, Maintainability and Availability
Taxonomy for Conversion from UnifiedPOS to XML

This section describes the rules for converting a Property, Method or Event Name
to an XML Tag Name.
• Convert all Property, Methods and Event Names to Upper Camel Case
following ARTS, “ARTS-XML Best Practices”.
• To keep consistent, enumerations will follow the existing upper case pattern
identified in the UnifiedPOS Specification.
• Following the pattern set in WAMPOS, buffers are passed as repeatable
XML elements in XMLPOS.
• Following the pattern set in WAMPOS, UnifiedPOS objects are passed as
repeatable XML elements in XMLPOS.
XMLPOS Architecture Overview

UnifiedPOS XML Requirements
To be consistent across ARTS standards, UnifiedPOS has chosen to follow the
ARTS-XML Best Practices in developing XMLPOS. The ARTS-XML Best
Practices document identifies the Venetian Blind Design Methodology for
creation of ARTS-XML schemas. Basically, this is a node based methodology
where individual nodes are aggregated as building blocks in the creation of the
schema.
For example:
<DirectIO>
<Command>0</Command>
<Data>0</Data>
<Object>String</Object>
</DirectIO>
Converting UnifiedPOS Methods and Events

The method to convert UnifiedPOS Methods and Events to XMLPOS Embedded
is to:
• Convert the UnifiedPOS Method/Event Name to an XML Tag name
following the Upper Camel Case best practice. The ARTS-XML Data
Dictionary is the definition source for these tag names.

XMLPOS Architecture Overview D-3
UnifiedPOS Synchronous XML Communications
<?xml version ="1.0" encoding="UTF-8"?>

Application <DirectIO xmlns="http://www.nrf-arts.org/
Driver
UnifiedPOS/namespace /" xmlns:xsi="http://
www.w3.org/2001 /XMLSchema -instance "
xsi:schemaLocation ="http://www.nrf-arts.org/
UnifiedPOS/namespace / \DirectIOV 1.0.0.xsd">
<Data>0</Data>
<Object >String</Object>
</DirectIO>
Figure 1: Synchronous Communications
A synchronous environment is characterized by both ends of the connection

having knowledge of each others’ communication requirements. By establishing
a session, only commands (representing UnifiedPOS Properties and Methods)
and responses need traverse the connection. In the XML world, each individual
command and response is a message.
To create these XML messages, the tags as defined in the ARTS XML Data
Dictionary, and the schemas, as derived from the UnifiedPOS specification, are
brought together in conjunction with the necessary tools to convert them to well
formed XML messages. This conversion of UnifiedPOS Properties, Methods, and
Events to XMLPOS Messages involves wrapping the XMLPOS Embedded Tags
in a well formed XML header.
<?xml version=”1.0” encoding=”UTF-8”?>
<DirectIO xmlns=”http://www.nrf-arts.org/UnifiedPOS/namespace/”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/namespace/
\DirectIOV1.0.0.xsd”>
<Data>0</Data>
<Object>String</Object>
</DirectIO>
UnifiedPOS Asynchronous XML Communications

Asynchronous communications are characterized by messages arriving from an
application without prior knowledge of the source and timing requirements of the
message, i.e. a direct connection. Figures 2 and 3 show examples of how the
UnifiedPOS Common Properties, Methods, and Events translate into XML
messages using XMLPOS.

XMLPOS Common Properties Schema Architecture
@Action
@CapPowerReportingProperty XMLPOSCommonProperties - Get
- PR_NONE - Set
-@AutoDisable[0..1]
- PR_STANDARD - Return
- PR_ADVANCED-@CapCompareFirmwareVersion[0..1]
-@CapPowerReporting[0..1] @PowerStateProperty
@PowerNotifyProperty -@CapStatisticsReporting[0..1] - PS_UNKNOWN
- PN_DISABLED -@CapUpdateFirmware[0..1] - PS_ONLINE
- PN_ENABLED -@CapUpdateStatistics[0..1] - PS_OFF
-@Claimed[0..1] - PS_OFFLINE
-@DataEventEnabled[0..1] - PS_OFF_OFFLINE
-@DeviceEnabled[0..1]
-@FreezeEvents[0..1] @StateProperty
-@PowerNotify[0..1] - S_CLOSED
- S_IDLE
-@PowerState[0..1]
- S_BUSY
-@State[0..1]
-CheckHealthText[0..1] - S_ERROR
-DeviceControlDescription[0..1]
-DeviceControlVersion[0..1]
-DeviceServiceDescription[0..1]
-DeviceServiceVersion[0..1]
-OutputID[0..1]
-PhysicalDeviceDescription [0..1]
-PhysicalDeviceName[0..1]
Figure 2: XML Common Properties Schema Architecture Sample
XMLPOS Common Methods Schema Architecture

@Result
- CFV_FIRMWARE_OLDER
- CFV_FIRMWARE_SAME
- CFV_FIRMWARE_NEWER
- CFV_FIRMWARE_DIFFERENT
- CFV_FIRMWARE_UNKNOWN
DirectIOMethodCommonData
CompareFirmwareVersionCommonData
-Command[1]
-@FirmwareFileName[1] XMLPOSCommonMethods UpdateFirmwareCommonData
-Data[1..*]
-@Result[1] -Object[1..*] -@FirmwareFileName[1]
-@MessageType[0..1]
-@ActionCode[0..1]
@Level -+MessageID[0..1]
- CH_INTERNAL -+DateTime[0..1]
- CH_EXTERNAL -+Response[0..1] ResetStatisticsCommonData OpenCommonData
- CH_INTERACTIVE -+SensorID[0..*] -Statistic[1..*] -@LogicalDeviceName[1]
-LogicalDeviceName[0..1]
CheckHealthCommonData ClaimCommonData -+OrganizationalHierarchy[0..*]
-@Level[1] -@Timeout[1] -+CheckHealth[0..1]
-+Claim[0..1]
-ClearInput[0..1]
-ClearInputProperties[0..1]
-ClearOutput[0..1]
-Close[0..1] RetrieveStatisticsCommonData
-+CompareFirmwareVersion[0..1] -Statistic[1..*]
-+DirectIO[0..1]
ErrorCommonData UpdateStatisticsCommonData -+Error[0..1]
-@TypeCode[1] -Statistic[1..*] -+Open[0..1]
-Release[0..1]
-+ResetStatistics[0..1]
-+RetrieveStatistics[0..1]
@TypeCode - E_OFFLINE -+UpdateFirmware[0..1]
- E_CLOSED - E_NOEXIST -+UpdateStatistics[0..1]
- E_CLAIMED - E_EXISTS
- E_NOTCLAIMED - E_FAILURE
- E_NOSERVICE - E_TIMEOUT
- E_DISABLED - E_BUSY
- E_ILLEGAL - E_DEPRECATED
- E_NOHARDWARE - E_EXTENDED
Figure 3: XML Common Methods Schema Architecture Sample

NOTE: @ - represents XPath nomenclature for an attribute

XMLPOS Architecture Overview D-5
This Domain View represents the UnifiedPOS common methods. It is

implemented in each device specific XML schema by the XML Schema
methodology of derivation by extension. Conceptually this is very similar to an
abstract base class.
• Create a common data complex type schema which contains the elements
from the common Property, Methods, and Events XML Tag Names.
• Create a node for each UnifiedPOS API for each device that is derived by
extension from the common data complex type schema,
XMLPOSCommonData.
Single Commands
Application
Middleware Driver
Application
Figure 4: Asynchronous Example
In the first example of sending an asynchronous command, the application

transmits multiple individual XML messages. This is an extension of the
synchronous model but requires additional support information identifying the
source of the message with each message transmitted.
Command Sets
Application Driver
Intelligent
Controller
Application Driver
Figure 5: Asynchronous with Intelligent Controller Example
In order to more efficiently utilize the available bandwidth, transmission of a

series of aggregated messages can be utilized. This more complex methodology
requires an Intelligent Controller to be located between the application and the
peripheral device driver. It incorporates either using a single more complex
UnifiedPOS command or a collection of simple and/or more complex
UnifiedPOS commands in a single XML message. The Intelligent Controller
parses out the message into its individual UnifiedPOS commands and applies
them in the proper order to the appropriate Peripheral Device Driver.

The following is an example of creating a single XMLPOS Message Command

Set to incorporate multiple UnifiedPOS commands.
<CashDrawerDevice xmlns=”http://www.nrf-arts.org/UnifiedPOS/namespace/”
\CashDrawerDeviceV1.0.0.xsd” MessageType=”Request”>
<MessageID>12412341234</MessageID>
<DateTime TypeCode=”Message”>2001-12-17T09:30:47.0Z</DateTime>
<RequestID Name=”String” Timestamp=”2001-12-17T09:30:47.0Z”>String</
RequestID>
<LogicalDeviceName>String</LogicalDeviceName>
<CheckHealth Level=”CH_INTERNAL”/>
<ClaimType Timeout=”0”/>
<ClearInput/>
<ClearOutput/>
<Close/>
<CompareFirmwareVersion Result=”Text” FirmwareFileName=”Text”/>
<DirectIO Command=”0” Object=”String” Data=”0”/>
<Open LogicalDeviceName=”String”/>
<Release/>
<ResetStatistics StatisticsBuffer=”String”/>
<RetrieveStatistics StatisticsBuffer=”String”/>
<UpdateFirmware FirmwareFileName=”String”/>
<UpdateStatistics StatisticsBuffer=”String”/>
<CashDrawerID>String</CashDrawerID>
<OpenDrawer/>
<WaitForDrawerClose BeepFrequency=”0” BeepTimeout=”0”
BeepDuration=”0” BeepDelay=”0”/>
<ClearInputProperties/>
</CashDrawerDevice>

UnifiedPOS XML Errors D-7
UnifiedPOS XML Errors

Device Error Codes and Message Severity Codes
It is not a requirement to have a direct mapping between Device Error Codes and
Message Severity Codes. Device Error Codes originate from the Peripheral
device or the service to communicate an accessing or operation problem.
Message Severity Codes are assigned to each individual XML Message and
describe how the message should be handled by creating an implicit handling
priority. For example, a printer cover open can generate a Device Error Code. The
XML Message which originally delivers this error can have a Message Severity
Code of “Information”. This is just to inform the receiver of the printer condition.
After some period of time the Message can escalate the Device Error to be a
Message Severity of “Error” saying the equipment has failed and needs
immediate attention.
Following this logic, most messages transmitting a Device Error Code will start
out with one Message Severity Code then over time escalate to indicate attention
is needed if not handled in a timely manner. There is one class of codes, the
Device Failure Codes, which will always start out at a higher Message Severity
Code level. Some examples are shown in the table below.
Message Severity Codes

The key ISO standard for maintenance activity definitions is section 14 of
Information Technology - Vocabulary - Reliability, Maintainability, and
Availability [ISO2382-14]. The following definitions come from that
specification.
Severity Codes identify the priority of the message. Basically there are three
types of Severity Codes. They characterize the effect of normal operation of a
piece of equipment. It either has an effect … that is; it results in a change of state
of the equipment, or it can stay in the same state but predict imminent problems
that result in reduced functionality. The final category is simple information, that
is neither an error nor a warning but information about the state of equipment.
• A fatal error that forces a change in state of a piece of equipment. This is
often a major or fatal error that results in the equipment or part of the
equipment being inoperative.
• A fault that produces a warning of imminent failure or a breakdown of some
functional component that is not essential to the functionality of the device.
• And finally there is simple information, e.g., chiller temperature, freezer
temperature.
These three types can be categorized as a severity, i.e., Error, Warning or
Information.
A generic “Severity Code” identifies faults. Each Generic Severity Code can have
zero or more manufacturer specific fault codes, each with their own (optional)
description. Although the common name is “Error of Fault code” in fact this
should be the error identification information.

Standard Error Codes to Severity Codes
Value Severity Meaning

E_CLOSED Warning An attempt was made to access a closed Device
An attempt was made to access a Physical Device that is
claimed by another Control instance. The other Control
E_CLAIMED Information must release the Physical Device before this access may be
made. For exclusive-use devices, the application will also
need to claim the Physical Device before the access is legal
An attempt was made to access an exclusive-use device that
must be claimed before the method or property set action
E_NOTCLAIMED Information can be used. If the Physical Device is already claimed by
another Control instance, then the status E_CLAIMED is
returned instead.
The Control cannot communicate with the Service,
E_NOSERVICE Warning
E_DISABLED Information Cannot perform this operation while the Device is disabled.
An attempt was made to perform an illegal or unsupported
E_ILLEGAL Error operation with the Device, or an invalid parameter value
was used.
The Physical Device is not connected to the system or is not
E_NOHARDWARE Error
powered on.
E_OFFLINE Warning The Physical Device is off-line.
E_NOEXIST Error The file name (or other specified value) does not exist.
E_EXISTS Error The file name (or other specified value) already exists.
The Device cannot perform the requested procedure, even
E_FAILURE Warning though the Physical Device is connected to the system,
powered on, and on-line.
The Service timed out waiting for a response from the
E_TIMEOUT Error Physical Device, or the Control timed out waiting for a
The current Service state does not allow this request. For
E_BUSY Warning example, if asynchronous output is in progress, certain
methods may not be allowed.
The requested operation can not be performed since it has
E_DEPRECATED Error
been deprecated.
E_CLOSED Information The device must be opened.
The device is opened but not claimed. Another application
E_CLAIMED Warning
has the device claimed, so it cannot be claimed at this time.
The device is opened but not claimed. No other application
E_NOTCLAIMED Information
has the device claimed, so it can and must be claimed.
The device is opened and claimed (if this is an exclusive
E_DISABLED Information
use device), but not enabled.

UnifiedPOS XML Errors D-9
Standard Status Codes to Severity Codes

SUE_POWER_ONLINE Information The device is powered on and ready for use.
SUE_POWER_OFF Information The device is off or detached from the terminal.
The device is powered on but is either not ready or
SUE_POWER_OFFLINE Warning
not able to respond to requests.
SUE_POWER_OFF_OFFLINE Warning The device is either off or offline.
SUE_UF_PROGRESS + 1 to The update firmware process has successfully
Information
100 completed 1 to 100 percent of the total operation.
The update firmware process has completed
SUE_UF_COMPLETE Information successfully. The value of this constant is identical
to SUE_UF_PROGRESS + 100.
The update firmware process succeeded, however
the Service and/or the physical device cannot be
returned to the state they were in before the update
firmware process started. The Service has restored
SUE_UF_COMPLETE_
Warning all properties to their default initialization values.
DEV_NOT_RESTORED
To ensure consistent Service and physical device
states, the application needs to close the Service,
then open, claim, and enable again, and also
restore all custom application settings.
The update firmware process failed but the device
SUE_UF_FAILED_DEV_OK Error
is still operational.
The update firmware process failed and the device
SUE_UF_FAILED_DEV_ is neither usable nor recoverable through software.
Error
UNRECOVERABLE The device requires service to be returned to an
operational state.
The update firmware process failed and the device
SUE_UF_FAILED_DEV_
Error will not be operational until another attempt to
NEEDS_FIRMWARE
update the firmware is successful.
SUE_UF_FAILED_DEV_ The update firmware process failed and the device
Error
UNKNOWN is in an indeterminate state.

UnifiedPOS Synchronous XML Errors

..\CashDrawerDeviceV1.0.0.xsd”>
<Error TypeCode=”E_CLOSED”/>
</CashDrawerDevice>
UnifiedPOS Asynchronous XML Errors

..\CashDrawerDeviceV1.0.0.xsd” MessageType=”Response”>
<RequestID Name=”String” Timestamp=”2001-12-17T09:30:47.0Z”>String</
RequestID>
<Response ResponseCode=”OK”>
<RequestID>String</RequestID>
<ResponseTimestamp>2001-12-17T09:30:47.0Z</
ResponseTimestamp>
<ResponseDescription Language=”eng”>String</
ResponseDescription>
<BusinessError Severity=”Information”>
<ErrorID>String</ErrorID>
<Code>String</Code>
<Description Language=”eng”>String</Description>
<RelatedErrorID>String</RelatedErrorID>
</BusinessError>
<ResponderID/>
</Response>
<LogicalDeviceName>String</LogicalDeviceName>
<Error TypeCode=”E_CLOSED”/>
</CashDrawerDevice>

XMLPOS Common Events D-11
XMLPOS Common Events

DateTimeCommonData
-@TypeCode[1] SourceURIType
EventCommonData -@TypeCode[1]
-@Severity[0..1]
BusinessUnitCommonData -@Priority[0..1]
-@Mode[0..1]
-@Name[1] -SequenceNumber[1] SensorID
-@TypeCode[1] -+EventDateTime[1] -@Name[0..1]
"Device Specific" Event -EventDescription[0..1] -@REM[0..1]
-@MajorVersion[1] -SourceName[0..1] -@UnifiedPOS[0..1]
-@MinorVersion[0..1] OrganizationHierarchyCommonData -<choice>[1] -@IFSF[0..1]
-@FixVersion[0..1] -+SourceURI[1] -@IETF[0..1]
-@Level[0..1] -+SensorID[1]
-@ActionCode[0..1] -@ID[0..1] -@NAFEM[0..1]
-+DataEvent[0..*] -</choice>[1] -@LonMark[0..1]
-+DirectIOEvent[0..*] -Instance[0..1]
-+ErrorEvent[0..*] -+BusinessUnit[0..1]
-+StatusUpdateEvent[0..*] -+OrganizationalHierarchy[0..1]
-+OutputCompleteEvent[0..*]
DataEventType DirectIOEventType ErrorEventType StatusUpdateEventType OutputCompleteEventType
-Status[1] -EventNumber[1] -ErrorCode[1] -Status[1] -OutputID[1]

-+Properties[0..1] -Data[1..*] -ErrorCodeExtended[1] -+Properties[0..1] -+Properties[0..1]
-Obj[1..*] -ErrorLocus[1]
-+Properties[0..1] -ErrorResponse[1]
-+Properties[0..1]
XMLPOSCommonProperties
-@AutoDisable[0..1]
-@CapCompareFirmwareVersion[0..1]
-@CapPowerReporting[0..1]
-@CapStatisticsReporting[0..1]
-@CapUpdateFirmware[0..1]
-@CapUpdateStatistics[0..1]
-@Claimed[0..1]
-@DataEventEnabled[0..1]
-@DeviceEnabled[0..1] "Device Unique" Properties Type
-@FreezeEvents[0..1]
-@PowerNotify[0..1]
-@PowerState[0..1]
-@State[0..1]
-CheckHealthText[0..1]
-OutputID[0..1]
-PhysicalDeviceName [0..1]
Figure 6: UnifiedPOS XML Events

The process for getting UnifiedPOS Events involves an application first receiving
the event and then querying for which property(s) caused the event.
In order to reduce the time to respond to an event, WAMPOS introduced an
alternative way to get the properties. WAMPOS introduced the idea of having the
properties, which changed as a result of the event, be sent with the event. This
results in the reduction of the number of steps to retrieve and respond to an event.
Depending on the needs of the system, XMLPOS is designed to support either
alternative.

UnifiedPOS Synchronous XML Events

<”DeviceSpecific” Event xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:noNamespaceSchemaLocation=”..\XMLPOSEventV1.0.0.xsd”
Severity=”Information” Mode=”Production” Priority=”-0”>
<SequenceNumber>4294967295</SequenceNumber>
<EventDateTime TypeCode=”Message”>2001-12-17T09:30:47.0Z</
EventDateTime>
<SensorID UnifiedPOS=”Scanner”>0</SensorID>
<DirectIOEvent EventNumber=”0” Obj=”String” Data=”0”/>
</”DeviceSpecific”Event>
UnifiedPOS Asynchronous XML Events
Single Events
<”DeviceSpecific”Event xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
EventDateTime>
<EventDescription>String</EventDescription>
<SourceName>String</SourceName>
<SourceURI>String</SourceURI>
<Instance>String</Instance>
<BusinessUnit TypeCode=”RetailStore” Name=”String”>String</
BusinessUnit>
<OrganizationalHierarchy ID=”String” Level=”Corporation”>String</
OrganizationalHierarchy>
Event Sets
<”DeviceSpecific”Event xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
EventDateTime>
<SourceName>String</SourceName>
<SourceURI>String</SourceURI>
<Instance>String</Instance>
<BusinessUnit TypeCode=”RetailStore” Name=”String”>String</
BusinessUnit>
<OrganizationalHierarchy ID=”String” Level=”Corporation”>String</
OrganizationalHierarchy>
<DataEvent Status=”0”/>
<ErrorEvent ErrorLocus=”EL_INPUT” ErrorResponse=”ER_RETRY”
ErrorCode=”0” ErrorCodeExtended=”0”/>
<StatusUpdateEvent Status=”0”/>

XMLPOS Common Events D-13
<OutputCompleteEvent OutputID=”0”/>

XMLPOS Common Properties
@Action
@CapPowerReportingProperty XMLPOSCommonProperties - Get
- PR_NONE - Set
-@AutoDisable[0..1]
- PR_STANDARD - Return
- PR_ADVANCED-@CapCompareFirmwareVersion[0..1]
-@CapPowerReporting[0..1] @PowerStateProperty
@PowerNotifyProperty -@CapStatisticsReporting[0..1] - PS_UNKNOWN
- PN_DISABLED -@CapUpdateFirmware[0..1] - PS_ONLINE
- PN_ENABLED -@CapUpdateStatistics[0..1] - PS_OFF
-@Claimed[0..1] - PS_OFFLINE
-@DataEventEnabled[0..1] - PS_OFF_OFFLINE
-@FreezeEvents[0..1] @StateProperty
-@PowerNotify[0..1] - S_CLOSED
- S_IDLE
-@PowerState[0..1]
- S_BUSY
-@State[0..1]
-CheckHealthText[0..1] - S_ERROR
-OutputID[0..1]
Figure 7: UnifiedPOS XMLPOS Common Properties
XMLPOS Common Properties complex type encapsulates the set of UnifiedPOS

properties used by all device categories. It can then be instantiated by each
individual device category using the standard XML schema extension
mechanism. Because of its common nature and to reduce complexity, this
complex type is represented by a box in each individual device domain drawings.

XMLPOS Common Data D-15
XMLPOS Common Data
Figure 8: UnifiedPOS XMLPOS Common Data
XMLPOS Common Data brings together the XMLPOS Common Properties and
ARTS Common Data while adding in UnifiedPOS Common Methods. Because
of its common nature this complex type is also represented by a box in each
individual device domain drawings.

ARTS Common Data
DateTimeCommonData
XMLPOS -@TypeCode[1]
OrganizationHierarchyCommonData Common
-@Level[0..1] Properties
-@ID[0..1] BusinessUnitCommonData
-@Name[1]
-@TypeCode[1]
RequestIDCommonData
SensorID -@Name[0..1]
XMLPOS -@Timestamp[0..1]
-@Name[0..1]
Common
-@REM[0..1]
Data
-@UnifiedPOS[0..1]
-@IFSF[0..1]
-@IETF[0..1] BusinessErrorCommonData
-@NAFEM[0..1] -@Severity[0..1]
-@LonMark[0..1] -ErrorID[0..1]
-Code[0..1]
-Description[0..1]
-RelatedErrorID[0..*]
ResponseCommonData
ResponseType -@ResponseCode[1]
-ResponderID[1] -RequestID[1]
-ResponseTimeStamp[1]
-ResponseDescription[1]
-+BusinessError[1]
Figure 9: ARTS Common Data
ARTS XML has identified a common set of elements and attributes used across
all ARTS XML schemas. This common header is comprised of a set of complex
types and handles situations like a standard request/response and business error
reporting mechanisms. Because of its common nature this complex type is
represented by a box in each individual device domain drawings.

UnifiedPOS Devices D-17
UnifiedPOS Devices
Each Device Category’s domain view is represented in the following diagram. The
“Device Category” is replaced by a specific device schema containing the device
specific properties and methods.
In the sections that follow describing the details of the Domain View of each Device
Category, only the Properties, Methods, and Events Domain Views specific to each
device are depicted.
XMLPOS
Common
Properties
ARTS
Common
Data
XMLPOS
Common
Data
"Device Category"
Specific Properties
Specific Methods
Figure 10: “Device Category” Domain View
Belt
Belt Example
<Belt xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/Belt/ ../
BeltV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/Belt/”
MajorVersion=”1” MessageType=”Publish” FixVersion=”0”
MinorVersion=”0” ActionCode=”Request”>
<DateTime>2001-12-17T09:30:47.0Z</DateTime>
<SensorID UnifiedPOS=”Belt”>POS1belt</SensorID>
<MoveForward>
<Speed>10</Speed>
</MoveForward>
</Belt>

Belt Properties
XMLPOS
Common
Propertie
ARTS
XMLPOS
Common
Common
Dat
Dat
Belt (Properties Domain View

-@MajorVersion[1]
-@MinorVersion[0..1]
-@FixVersion[0..1]
---- Properties ---[1]
-@AutoStopBackward[0..1]
-@AutoStopForward[0..1]
-@CapAutoStopBackward[0..1]
-@CapAutoStopBackwardItemCount[0..1]
-@CapAutoStopForward[0..1]
-@CapAutoStopForwardItemCount[0..1]
-@CapLightBarrierBackward[0..1]
-@CapLightBarrierForward[0..1]
-@CapMoveBackward[0..1]
-@CapSecurityFlapBackward[0..1]
-@CapSecurityFlapForward[0..1]
-@CapSpeedStepsBackward[0..1]
-@CapSpeedStepsForward[0..1]
-@LightBarrierBackwardInterrupted[0..1]
-@LightBarrierForwardInterrupted[0..1]
-@SecurityFlapBackwardOpened[0..1]
-@SecurityFlapForwardOpened[0..1]
-AutoStopBackwardDelayTime[0..1]
-AutoStopBackwardItemCount[0..1]
-AutoStopForwardDelayTime[0..1]
-AutoStopForwardItemCount[0..1]
-MotionStatus[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 11: Belt Properties Domain View

Belt Methods
XMLPOS
Common
Propertie
ARTS
XMLPOS
Common
Common
Dat
Dat
Belt (Methods Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-+MoveBackward[0..1]
-+MoveForward[0..1]
-StopBelt[0..1]
-ResetBelt[0..1]
MoveBackwardType MoveForwardType
-Speed[1] -Speed[1]
Figure 12: Belt Methods Domain View

Belt Events
DateTimeCommonDat SourceURITyp
EventCommonDat
-@TypeCode[1] -@TypeCode[1]
-@Severity[0..1]
-@Priority[0..1]
-@Mode[0..1]
-SequenceNumber[1]
BusinessUnitCommonDat -+EventDateTime[1] SensorI
-@Name[1] -EventDescription[0..1] -@Name[0..1]
-@TypeCode[1] -SourceName[0..1]
BeltEven -@REM[0..1]
-<choice>[1] -@UnifiedPOS[0..1]
-@MajorVersion[1] -+SourceURI[1] -@IFSF[0..1]
-@MinorVersion[0..1] OrganizationHierarchyCommonDat -+SensorID[1] -@IETF[0..1]
-@FixVersion[0..1] -@Level[0..1] -</choice>[1] -@NAFEM[0..1]
-+DirectIOEvent[0..*] -@ID[0..1] -Instance[0..1] -@LonMark[0..1]
-+StatusUpdateEvent[0..*] -+BusinessUnit[0..1]
-+OrganizationalHierarchy[0..1]
DirectIOEventType StatusUpdateEventType
-EventNumber[1] -Status[1]
XMLPOSCommonPropertie -Data[1..*] -+Properties[0..1]
-Obj[1..*]
-@AutoDisable[0..1]
-+Properties[0..1]
-@Claimed[0..1] BeltPropertiesTyp
-@AutoStopBackward[0..1]
-@AutoStopForward[0..1]
-@FreezeEvents[0..1] -@CapAutoStopBackward[0..1]
-@PowerNotify[0..1] -@CapAutoStopBackwardItemCount[0..1]
-@PowerState[0..1]
-@CapAutoStopForward[0..1]
-@State[0..1]
-@CapAutoStopForwardItemCount[0..1]
-@CapLightBarrierBackward[0..1]
-DeviceControlDescription[0..1] -@CapLightBarrierForward[0..1]
-DeviceControlVersion[0..1] -@CapMoveBackward[0..1]
-DeviceServiceDescription [0..1]
-@CapSecurityFlapBackward[0..1]
-DeviceServiceVersion [0..1]
-@CapSecurityFlapForward[0..1]
-OutputID[0..1]
-@CapSpeedStepsBackward[0..1]
-PhysicalDeviceDescription [0..1] -@CapSpeedStepsForward[0..1]
-PhysicalDeviceName [0..1] -@LightBarrierBackwardInterrupted[0..1]
-@LightBarrierForwardInterrupted[0..1]
-@SecurityFlapBackwardOpened[0..1]
-@SecurityFlapForwardOpened[0..1]
-AutoStopBackwardDelayTime[0..1]
-AutoStopBackwardItemCount[0..1]
-AutoStopForwardDelayTime[0..1]
-AutoStopForwardItemCount[0..1]
-MotionStatus[0..1]
Figure 13: Belt Events Domain View
Device Error Codes to Message Severity Codes

This device only has common errors as defined in “Device Error Codes and
Message Severity Codes” on page 7.
Method Value Severity Meaning
N/A
Status Codes to Message Severity Codes

This table is for device specific status codes. The common status codes are

defined in “Standard Status Codes to Severity Codes” on page 9.
Device Specific Status Messages
Bill Acceptor
Bill Acceptor Example
Æ SetRealTimeDataEvents to true
<BillAcceptor xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/BillAcceptor/ ../
BillAcceptorV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
BillAcceptor/” RealTimeDataEnabled=”true” FixVersion=”0”
MajorVersion=”1” MessageType=”Request” MinorVersion=”0”
ActionCode=”Update”>
<SensorID UnifiedPOS=”BillAcceptor”>1</SensorID>
</BillAcceptor>
Æ:BeginDeposit()
BillAcceptor/” FixVersion=”0” MajorVersion=”1”
MessageType=”Request” MinorVersion=”0”>
<MessageID>asdf2345sdfg</MessageID>
<BeginDeposit/>
</BillAcceptor>
Cash is accepted
Å DataEvent is fired
<BillAcceptorEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/

BillAcceptorEvents/ ../BillAcceptorEventV1.0.0.xsd” xmlns=”http://

www.nrf-arts.org/UnifiedPOS/BillAcceptorEvents/” FixVersion=”0”
MajorVersion=”1” MinorVersion=”0”>
<DataEvent Severity=”Information”>
<EventDateTime>2001-12-17T09:30:47.0Z</EventDateTime>
<Status>0</Status>
</DataEvent>
</BillAcceptorEvent>
Æ EndDeposit()
BillAcceptor/” FixVersion=”0” MajorVersion=”1”
<MessageID>asdf2345sdfg</MessageID>
<EndDeposit>
<Success>BACC_DEPOSIT_COMPLETE</Success>
</EndDeposit>
</BillAcceptor>

Bill Acceptor Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
BillAcceptor (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@CapDiscrepancy[0..1]
-@CapFullSensor[0..1]
-@CapJamSensor[0..1]
-@CapNearFullSensor[0..1]
-@CapPauseDeposit[0..1]
-@CaprRealTimeData[0..1]
-@RealTimeDataEnabled[0..1]
-AdjustCashCounts[0..1]
-CurrencyCode[0..1]
-DepositAmount[0..1]
-DepositCashList[0..*]
-DepositCodeList[0..*]
-DepositCounts[0..1]
-FullStatus[0..1]
---- Methods ---[1]
-......[0..1]
Figure 14: Bill Acceptor Properties Domain View

Bill Acceptor Methods
XMLPOS
Common
Properties
XMLPOS ARTS
Common Common
Data Data
Bill Acceptor(Methods Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-..... [0..1]
---- Methods ---[1]
-+AdjustCashCounts[0..1]
-BeginDeposit[0..1]
-+EndDeposit[0..1]
-FixDeposit[0..1]
-+PauseDeposit[0..1]
-+ReadCashCounts[0..1]
AdjustCashCountsType EndDepositType PauseDepositType ReadCashCountsType

-CashCounts[1..*] -Success[1] -Control[1] -@Discrepancy[1]
-CashCounts[1..*]
Figure 15: Bill Acceptor Methods Domain View

Bill Acceptor Events
EventCommonData
-@Severity[0..1]
BillAcceptorEvent
DateTimeCommonData -@Priority[0..1] SourceURIType
-@MajorVersion[1] -@Mode[0..1]
-@MinorVersion[0..1] -@TypeCode[1] -@TypeCode[1]
-SequenceNumber[1]
-@FixVersion[0..1] -+EventDateTime[1]
-@ActionCode[0..1] BusinessUnitCommonData -EventDescription[0..1]
-+DataEvent[0..*] -@Name[1] -SourceName[0..1] SensorID
-+DirectIOEvent[0..*] -@TypeCode[1] -<choice>[1] -@Name[0..1]
-+StatusUpdateEvent[0..*] -+SourceURI[1]
OrganizationHierarchyCommonData -@REM[0..1]
-+SensorID[1] -@UnifiedPOS[0..1]
-@Level[0..1] -</choice>[1] -@IFSF[0..1]
-@ID[0..1] -Instance[0..1] -@IETF[0..1]
-+BusinessUnit[0..1] -@NAFEM[0..1]
-+OrganizationalHierarchy[0..1] -@LonMark[0..1]
DataEventType DirectIOEventType StatusUpdateEventType

-Status[1] -EventNumber[1] -Status[1]
-+Properties[0..1] -Data[1..*] -+Properties[0..1]
-Obj[1..*]
-@AutoDisable[0..1] -+Properties[0..1]
-@Claimed[0..1] BillAcceptorPropertiesType
-CapDiscrepancy[0..1]
-CapFullSensor[0..1]
-CapJamSensor[0..1]
-@PowerNotify[0..1]
-CapNearFullSensor[0..1]
-@PowerState[0..1]
-CapPauseDeposit[0..1]
-@State[0..1]
-CapRealTimeData[0..1]
-CurrencyCode[0..1]
-DepositCashList[0..1]
-DepositCodeList[0..1]
-OutputID[0..1]
-FullStatus[0..1]
-RealTimeDataEnabled[0..1]
Figure 16: Bill Acceptor Events Domain View


N/A


BACC_STATUS_FULL Warning Some cash slots are full
BACC_STATUS_NEARFULL Warning Some cash slots are nearly full
BACC_STATUS_FULLOK Information No cash slots are either full or nearly full.
BACC_STATUS_JAM Error A mechanical fault has occurred.
BACC_STATUS_JAMOK Information A mechanical fault has recovered.
Bill Dispenser
Bill Dispenser Example
ÆDispenseCash(“;100:4”)Dispense 4 $1.00 bills
<BillDispenser xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/BillDispenser/ ../
BillDispenserV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
BillDispenser/” FixVersion=”0” MajorVersion=”1”
MessageType=”Publish” MinorVersion=”0”>
<SensorID UnifiedPOS=”BillDispenser”>100</SensorID>
<DispenseCash>
<CashCounts Denomination=”100”>4</CashCounts>
</DispenseCash>
</BillDispenser>

Bill Dispenser Properties
XMLPOS
Common
Properties
ARTS
XMLPOS Common
Common Data
Data
BillDispenser (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@AsyncMode[0..1]
-@CapEmptySensor[0..1]
-@CapNearEmptySensor[0..1]
-AsyncResultCode[0..1]
-AsyncResultCodeExtended[0..1]
-CurrencyCashList[0..*]
-CurrencyCode[0..1]
-CurrencyCodeList[0..*]
-CurrentExit[0..1]
-DeviceExit [0..1]
-DeviceStatus[0..1]
-ExitCashList [0..*]
---- Methods ---[1]
-......[0..1]
Figure 17: Bill Dispenser Properties Domain View

Bill Dispenser Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
BillDispenser (Methods Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-DispenseCash[0..1]
-ReadCashCounts[0..1]
AdjustCashCountsType DispenseCashType ReadCashCountsType

-CashCounts[1..*] -CashCounts[1..*] -@Discrepancy[1]
-CashCounts[1..*]
Figure 18: Bill Dispenser Methods Domain View

Bill Dispenser Events
EventCommonData
-@Severity[0..1]
-@Mode[0..1]
-SequenceNumber[1]
-+EventDateTime[1]
BusinessUnitCommonData -EventDescription[0..1] SensorID
-@Name[1] -SourceName[0..1]
BillDispenserEvent -@TypeCode[1] -<choice>[1] -@Name[0..1]
-+SourceURI[1] -@REM[0..1]
-@MajorVersion[1] -@UnifiedPOS[0..1]
-@MinorVersion[0..1] -+SensorID[1]
OrganizationHierarchyCommonData -@IFSF[0..1]
-@FixVersion[0..1] -</choice>[1]
-@Level[0..1] -Instance[0..1] -@IETF[0..1]
-@ActionCode[0..1] -@ID[0..1] -@NAFEM[0..1]
-+BusinessUnit[0..1]
-+DirectIOEvent[0..*] -@LonMark[0..1]
-+StatusUpdateEvent[0..*]
-Data[1..*] -+Properties[0..1]
-@AutoDisable[0..1] -Obj[1..*]
-@CapCompareFirmwareVersion[0..1] -+Properties[0..1]
-@Claimed[0..1]
-@FreezeEvents[0..1] BillDispenserPropertiesType
-@PowerNotify[0..1] -@AsyncMode[0..1]
-@PowerState[0..1]
-@State[0..1] -@CapEmptySensor[0..1]
-CheckHealthText[0..1] -@CamJamSensor[0..1]
-DeviceControlDescription[0..1] -@CapNearEmptySensor[0..1]
-DeviceControlVersion[0..1] -AsyncResultCode[0..1]
-DeviceServiceVersion[0..1] -CurrencyCashList[0..*]
-OutputID[0..1] -CurrencyCode[0..1]
-PhysicalDeviceDescription [0..1] -CurrencyCodeList[0..*]
-PhysicalDeviceName [0..1] -CurrentExit[0..1]
-DeviceExit [0..1]
-DeviceStatus[0..1]
Figure 19: Bill Dispenser Events Domain View


This table is for device specific error codes. The common errors are defined in
“Device Error Codes and Message Severity Codes” on page 7.

The specified cash cannot be
dispenseCash EBDSP_OVERDISPENSE Warning dispensed because of a cash
shortage.

Device Specific Stati

BDSP_STATUS_EMPTY Warning Some cash slots are empty.
BDSP_STATUS_NEAREMPTY Warning Some cash slots are nearly empty
No cash slots are either empty or
BDSP_STATUS_EMPTYOK Information
nearly empty
BDSP_STATUS_JAM Error A mechanical fault has occurred.
BDSP_STATUS_JAMOK Information A mechanical fault has recovered
Asynchronously performed method
BDSP_STATUS_ASYNC Information
has completed.
Biometrics
Biometrics Example
Æ SetDataEventEnabled to true
<Biometrics xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/Biometrics/ ../
BiometricsV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
Biometrics/” DataEventEnabled=”true” FixVersion=”0” MajorVersion=”1”
MessageType=”Request” MinorVersion=”0” ActionCode=”Update”>
<SensorID UnifiedPOS=”Biometrics”>001</SensorID>
</Biometrics>
Æ:BeginEnrollCapture()
Biometrics/” FixVersion=”0” MajorVersion=”1” MessageType=”Request”
MinorVersion=”0”>

<BeginEnrollCapture>
<ReferenceBIR/>
<Payload/>
</BeginEnrollCapture>
</Biometrics>
Capture Biometric Data
Å Data Event is fired
<BiometricsEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
BiometricsEvents/ ../BiometricsEventV1.0.0.xsd” xmlns=”http://www.nrf-
arts.org/UnifiedPOS/BiometricsEvents/” FixVersion=”0”
<Status>BIO_DATA_VERIFY</Status>
</DataEvent>
</BiometricsEvent>
Æ GetBIR()
Biometrics/” FixVersion=”0” MajorVersion=”1” MessageType=”Request”
MinorVersion=”0” ActionCode=”Read”>
<BIR/>
</Biometrics>
Å BIR property returned
Biometrics/” FixVersion=”0” MajorVersion=”1”
MessageType=”Response” MinorVersion=”0” ActionCode=”Read”>
<MessageID>asdfasfString</MessageID>
<Response>
<RequestID>45674567</RequestID>
<ResponderID>500</ResponderID>
</Response>
<BIR>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</BIR>
</Biometrics>

Biometrics Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
Biometrics (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@CapPrematchData[0..1]
-@CapRawSensorData[0..1]
-@CapRealTimeData[0..1]
-@CapTemplateAdaptation[0..1]
-@RawSensorData[0..1]
-Algorithm[0..1]
-AlgorithmList[0..*]
-BIR[0..1]
-CapSensorColor[0..1]
-CapSensorOrientation[0..1]
-CapSensorType[0..1]
-SensorBPP[0..1]
-SensorColor[0..1]
-SensorHeight[0..1]
-SensorOrientation[0..1]
-SensorType[0..1]
-SensorWidth[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 20: Biometrics Properties Domain View

Biometrics Methods
ARTS
Common
Data
XMLPOS
XMLPOS
Common
Common
Properties
Data
Biometrics (Methods Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1] BeginEnrollCaptureType
-+BeginEnrollCapture[0..1] -ReferenceBIR[1]
-BeginVerifyCapture[0..1] -Payload[1]
-EndCapture[0..1]
-+Identify[0..1]
-+IdentifyMatch[0..1]
-+ProcessPrematchData[0..1]
-+Verify[0..1]
-+VerifyMatch[0..1]
VerifyMatchType VerifyType ProcessPrematchDataType IdentifyMatchType IdentifyType

-@FARPrecendence[1] -@FARPrecedence[1] -SampleBIR[1] -@FARPrecedence[1] -@FARPrecedence[1]
-@Result[1] -@Result[1] -PrematchDataBIR[1] -MaxFARRequested[1] -MaxFARRequested[1]
-@Payload[1] -@Payload[1] -ProcessedBIR [1] -MaxFRRRequested[1] -MaxFRRRequested[1]
-MaxFARRequested[1] -MaxFARRequested[1] -SampleBIR[1] -ReferenceBIRPopulation[1]
-MaxFRRRequested[1] -MaxFRRRequested[1] -ReferenceBIRPopulation[1] -CandidateRanking[1]
-SampleBIR[1] -ReferenceBIR[1] -CandidateRanking[1] -Timeout[1]
-ReferenceBIR[1] -AdaptedBIR[1]
-AdaptedBIR[1] -FARAchieved[1]
-FARAchieved[1] -FRRAchieved[1]
-FRRAchieved[1] -Timeout[1]
Figure 21: Biometric Methods Domain View

Biometrics Events
EventCommonData
-@Severity[0..1]
-@Mode[0..1] -@TypeCode[1]
-@TypeCode[1]
-SequenceNumber[1]
-+EventDateTime[1]
BusinessUnitCommonData -EventDescription[0..1]
BiometricsEvent -@Name[1] -SourceName[0..1] SensorID
-@MajorVersion[1] -@TypeCode[1] -<choice>[1] -@Name[0..1]
-@MinorVersion[0..1] -+SourceURI[1] -@REM[0..1]
-@FixVersion[0..1] -+SensorID[1] -@UnifiedPOS[0..1]
OrganizationHierarchyCommonData
-@ActionCode[0..1] -</choice>[1] -@IFSF[0..1]
-+DataEvent[0..*] -@Level[0..1] -Instance[0..1] -@IETF[0..1]
-+DirectIOEvent[0..*] -@ID[0..1] -+BusinessUnit[0..1] -@NAFEM[0..1]
-+ErrorEvent[0..*] -+OrganizationalHierarchy[0..1] -@LonMark[0..1]
DataEventType DirectIOEventType ErrorEventType StatusUpdateEventType

-Status[1] -EventNumber[1] -ErrorCode[1] -Status[1]
-+Properties[0..1] -Data[1..*] -ErrorCodeExtended[1] -+Properties[0..1]
-+Properties[0..1]
-@AutoDisable[0..1] BiometricsPropertiesType
-@CapPrematchData[0..1]
-@CapRawSensorData[0..1]
-@CapUpdateFirmware[0..1] -@CapRealTimeData[0..1]
-@CapTemplateAdaptation[0..1]
-@RawSensorData[0..1]
-@Claimed[0..1]
-Algorithm[0..1]
-@FreezeEvents[0..1] -AlgorithmList[0..*]
-BIR[0..1]
-@PowerNotify[0..1]
-CapSensorColor[0..1]
-@PowerState[0..1]
-CapSensorOrientation[0..1]
-@State[0..1]
-CapSensorType[0..1]
-DeviceControlDescription[0..1] -SensorBPP[0..1]
-SensorColor[0..1]
-SensorHeight[0..1]
-SensorOrientation[0..1]
-SensorType[0..1]
-OutputID[0..1]
-PhysicalDeviceDescription [0..1] -SensorWidth[0..1]
Figure 22: Biometrics Events Domain View

beginEnrollCapture E_FAILURE Warning referenceBIR could not be adapted.
endCapture E_ILLEGAL Warning Biometrics capture was not in progress.
identify E_FAILURE Error referenceBIRPopulation was not valid.
identifyMatch E_FAILURE Error referenceBIRPopulation was not valid.
processPrematchData E_FAILURE Error sampleBIR was not valid.
verify E_FAILURE Error referenceBIRPopulation was not valid.
verifyMatch E_FAILURE Error referenceBIRPopulation was not valid.



BIO_SUE_RAW_DATA Information Raw image data is available
BIO_SUE_MOVE_LEFT Warning The position was too far to the right.
BIO_SUE_MOVE_RIGHT Warning The position was too far to the left
BIO_SUE_MOVE_DOWN Warning The position was too high
BIO_SUE_MOVE_UP Warning The position was too low
BIO_SUE_MOVE_CLOSER Warning The position was too far away
BIO_SUE_MOVE_AWAY Warning The position was too near (close)
BIO_SUE_MOVE_BACKWARD Warning The position was too far forward
BIO_SUE_MOVE_FORWARD Warning The position was too far backward
BIO_SUE_MOVE_SLOWER Warning The motion was too fast, move slower.
BIO_SUE_MOVE_FASTER Warning The motion was too slow, move faster.
BIO_SUE_SENSOR_DIRTY Information The sensor is dirty and requires cleaning
Bump Bar
Bump Bar Example
Æ Set AutoToneDuration to 3000 milliseconds
<BumpBar xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/BumpBar/ ../
BumpBarV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
BumpBar/” FixVersion=”0” MajorVersion=”1” MessageType=”Publish”
MinorVersion=”0” ActionCode=”Update”>
<SensorID UnifiedPOS=”BumpBar”>1</SensorID>
<AutoToneDuration>3000</AutoToneDuration>
</BumpBar>

Bump Bar Properties
XMLPOS
Common
Properties
XMLPOS ARTS
Common Common
Data Data
BumpBar (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@AsyncMode[0..1]
-@CapTone[0..1]
-AutoToneDuration[0..1]
-AutoToneFrequency[0..1]
-BumpBarDataCount[0..1]
-CurrentUnitID[0..1]
-ErrorString[0..1]
-ErrorUnits[0..1]
-EventString[0..1]
-EventUnitID[0..1]
-EventUnits[0..1]
-Keys[0..1]
-Timeout[0..1]
-UnitsOnline[0..1]
---- Methods ---[1]
-....[*]
Figure 23: Bump Bar Properties Domain View

Bump Bar Methods
XMLPOS
Common
Properties
XMLPOS ARTS
Common Common
Data Data
BumpBar (Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-+BumpBarSound[0..1]
-+SetKeyTranslation[0..1]
SetKeyTranslationType BumpBarSoundType
-Units[1] -Units[1]
-ScanCode[1] -Frequency[1]
-LogicalKey [1] -Duration[1]
-NumberOfCycles[1]
-InterSoundWait[1]
Figure 24: Bump Bar Methods Domain View

Bump Bar Events
EventCommonData
-@Severity[0..1]
-@Mode[0..1]
-SequenceNumber[1]
-+EventDateTime[1]
BumpBarEvent -@Name[1] -SourceName[0..1] SensorID
-@MajorVersion[1] -@TypeCode[1] -<choice>[1] -@Name[0..1]
-@MinorVersion[0..1] -+SourceURI[1] -@REM[0..1]
-@FixVersion[0..1] -+SensorID[1] -@UnifiedPOS[0..1]
-@ActionCode[0..1] -</choice>[1] -@IFSF[0..1]
-+DataEvent[0..*] -@Level[0..1] -Instance[0..1] -@IETF[0..1]
-+DirectIOEvent[0..*] -@ID[0..1] -+BusinessUnit[0..1] -@NAFEM[0..1]
-+ErrorEvent[0..*] -+OrganizationalHierarchy[0..1] -@LonMark[0..1]
DataEventType DirectIOEventType ErrorEventType OutputCompleteEventType StatusUpdateEventType

-Status[1] -EventNumber[1] -ErrorCode[1] -OutputID[1] -Status[1]
-+Properties[0..1]
-@AutoDisable[0..1]
-@CapPowerReporting[0..1] BumpBarPropertiesType
-@CapStatisticsReporting[0..1] -@AsyncMode[0..1]
-@CapUpdateFirmware[0..1] -@CapTone[0..1]
-@CapUpdateStatistics[0..1] -AutoToneDuration[0..1]
-@Claimed[0..1] -AutoToneFrequency[0..1]
-@DataEventEnabled[0..1] -BumpBarDataCount[0..1]
-@DeviceEnabled[0..1] -CurrentUnitID[0..1]
-@FreezeEvents[0..1] -ErrorString[0..1]
-@PowerNotify[0..1] -ErrorUnits[0..1]
-@PowerState[0..1] -EventString[0..1]
-@State[0..1] -EventUnitID[0..1]
-CheckHealthText[0..1] -EventUnits[0..1]
-DeviceControlDescription[0..1] -Keys[0..1]
-DeviceControlVersion[0..1] -Timeout[0..1]
-DeviceServiceDescription[0..1] -UnitsOnline[0..1]
-OutputID[0..1]
Figure 25: Bump Bar Events Domain View


bumpBarSound
One of the following errors occurred:
numberOfCycles is neither a positive,
non-zero value nor FOREVER.
numberOfCycles is FOREVER when
AsyncMode is false.
E_ILLEGAL Error A negative interSoundWait was
specified.
units is zero or a non-existent unit was
specified.
A unit in units does not support the
CapTone capability.
setKeyTranslatio
n
scanCode or logicalKey are out of range.
E_ILLEGAL Error
units is zero or a non-existent unit was
specified.


N/A
Cash Changer
Cash Changer Example
Æ SetDataEventEnabled to true
<CashChanger xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/CashChanger/ ../
CashChangerV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
CashChanger/” DataEventEnabled=”true” FixVersion=”0”
<MessageID Name=”String” Timestamp=”2001-12-
17T09:30:47.0Z”>String</MessageID>

<SensorID UnifiedPOS=”CashChanger”>1</SensorID>
</CashChanger>
Æ:BeginDeposit()
CashChanger/” FixVersion=”0” MajorVersion=”1”
<BeginDeposit/>
</CashChanger>
Cash is accepted
<CashChangerEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
CashChangerEvents/ ../CashChangerEventV1.0.0.xsd” xmlns=”http://
www.nrf-arts.org/UnifiedPOS/CashChangerEvents/” FixVersion=”0”
<DataEvent Severity=”Information” Mode=”Production” Priority=”-0”>
<Status>0</Status>
</DataEvent>
</CashChangerEvent>
Æ EndDeposit(Change)
CashChanger/” FixVersion=”0” MajorVersion=”1”
<EndDeposit>
<Success>CHAN_DEPOSIT_CHANGE</Success>
</EndDeposit>
</CashChanger>

Cash Changer Properties
XMLPOS
Common
Properties
XMLPOS ARTS
Common Common
Data Data
CashChanger(Properties Domain View)

-@MajorVersion[1]
-@MinorVersion[1]
-@FixVersion[1]
-@AsyncMode[0..1]
-@CapDeposit[0..1]
-@CapDepositDataEvent[0..1]
-@CapRepayDeposit[0..1]
-AsyncResultCode[0..1]
-CurrencyCashList[0..*]
-CurrencyCode[0..1]
-CurrentExit[0..1]
-CurretService[0..1]
-DepositStatus[0..1]
-DeviceExits [0..1]
-DeviceStatus[0..1]
-FullStatus[0..1]
-ServiceCount[0..1]
-ServiceIndex[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 26: Cash Changer Properties Domain View

Cash Changer Methods
ARTS
Common
Data
XMLPOS XMLPOS
Common
Common
Properties
Data
CashChanger (Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-+AdjustCashCount[0..1]
-BeginDeposit[0..1]
-+DispenseCash[0..1]
-+DispenseChange[0..1]
-+EndDeposit[0..1]
-FixDeposit[0..1]
-+PauseDeposit[0..1]
AdjustCashCountType DispenseCashType DispenseChangeType EndDepositType ReadCashCountsType PauseDepositType

-+CashCount[1..*] -CashCount[1] -Amount[1] -Success[1] -@Discrepancy[1] -Control[1]
-CashCounts[1]
@Control
@Success - CHAN_DEPOSIT_PAUSE
- CHAN_DEPOSIT_CHANGE - CHAN_DEPOSIT_RESTART
- CHAN_DEPOSIT_NOCHANGE
- CHAN_DEPOSIT_REPAY
Figure 27: Cash Changer Methods Domain View

Cash Changer Events
EventCommonData
-@Severity[0..1]
-@Mode[0..1]
-SequenceNumber[1]
-+EventDateTime[1]
-@Name[1] -SourceName[0..1] SensorID
CashChangerEvent -@TypeCode[1] -<choice>[1] -@Name[0..1]
-@MajorVersion[1] -+SourceURI[1] -@REM[0..1]
-@MinorVersion[0..1] -+SensorID[1] -@UnifiedPOS[0..1]
-@FixVersion[0..1] -</choice>[1] -@IFSF[0..1]
-@ActionCode[0..1] -@Level[0..1] -Instance[0..1] -@IETF[0..1]
-+DataEvent[0..*] -@ID[0..1] -+BusinessUnit[0..1] -@NAFEM[0..1]
-+DirectIOEvent[0..*] -+OrganizationalHierarchy[0..1] -@LonMark[0..1]
DataEventType
-Status[1] -+Properties[0..1]
-Data[1..*]
XMLPOSCommonProperties -+Properties[0..1]
-Obj[1..*]
-@CapUpdateFirmware[0..1] CashChangerPropertiesType
-@CapUpdateStatistics[0..1] -@AsyncMode[0..1]
-@Claimed[0..1] -@CapDeposit[0..1]
-@DataEventEnabled[0..1] -@CapDepositDataEvent[0..1]
-@DeviceEnabled[0..1] -@CapDiscrepancy[0..1]
-@FreezeEvents[0..1] -@CapEmptySensor[0..1]
-@PowerNotify[0..1] -@CapFullSensor[0..1]
-@PowerState[0..1] -@CapJamSensor[0..1]
-@State[0..1] -@CapNearEmptySensor[0..1]
-CheckHealthText[0..1] -@CapNearFullSensor[0..1]
-DeviceControlDescription[0..1] -@CapPauseDeposit[0..1]
-DeviceControlVersion[0..1] -@CapRealTimeData[0..1]
-DeviceServiceDescription[0..1] -@CapRepayDeposit[0..1]
-DeviceServiceVersion[0..1] -@RealTimeDataEnabled[0..1]
-OutputID[0..1] -AsyncResultCode[0..1]
-PhysicalDeviceDescription [0..1] -AsyncResultCodeExtended[0..1]
-PhysicalDeviceName[0..1] -CurrencyCashList[0..*]
-CurrencyCode[0..1]
-CurrentExit[0..1]
-CurretService[0..1]
-DeviceExits [0..1]
-DeviceStatus[0..1]
-FullStatus[0..1]
-ServiceCount[0..1]
-ServiceIndex[0..1]
Figure 28: Cash Changer Events Domain View


beginDeposit
Either the Cash Changer does not
E_ILLEGAL Error support cash acceptance, or the call
sequence is not correct.
dispenseCash
Cash cannot be dispensed because an
E_BUSY Warning
asynchronous method is in progress.
• The cashCounts parameter value was
E_ILLEGAL Error illegal for the current exit.
• Cash could not be dispensed because
cash acceptance was in progress.
ECHAN_OVERDISPENSE:
E_EXTENDED Error The specified cash cannot be dispensed
because of a cash shortage.
dispenseChange
The specified change cannot be
E_BUSY Warning dispensed because an asynchronous
• A negative or zero amount was
specified.
• The amount could not be dispensed
E_ILLEGAL Error based on the values specified in
ExitCashList for the current exit.
• Change could not be dispensed
because cash acceptance was in
progress.
ECHAN_OVERDISPENSE:
E_EXTENDED Error The specified change cannot be
dispensed because of a cash shortage.
endDeposit
• The call sequence is invalid.
E_ILLEGAL Error
beginDeposit and fixDeposit must be
called in sequence before calling this
method.
fixDeposit


E_ILLEGAL Error • The call sequence is invalid.
beginDeposit must be called before
pauseDeposit
beginDeposit must be called before
E_ILLEGAL Error
• The deposit process is already paused
and control is set to
CHAN_DEPOSIT_PAUSE, or the
deposit process is not paused and control
is set to CHAN_DEPOSIT_RESTART.
readCashCounts
Cash units and counts cannot be read
E_BUSY Information because an asynchronous method is in
process.


CHAN_STATUS_EMPTY Error Some cash slots are empty
CHAN_STATUS_NEAREMPTY Warning Some cash slots are nearly empty.
No cash slots are either empty or nearly
CHAN_STATUS_EMPTYOK Information empty.
CHAN_STATUS_FULL Information Some cash slots are full
CHAN_STATUS_NEARFULL Information Some cash slots are nearly full.
CHAN_STATUS_FULLOK Warning No cash slots are either full or nearly full.
CHAN_STATUS_JAM Error A mechanical fault has occurred
CHAN_STATUS_JAMOK Information A mechanical fault has recovered.
Asynchronously performed method has
CHAN_STATUS_ASYNC Information completed.

Cash Drawer
Cash Drawer Example
ÆopenDrawer()
<CashDrawer xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/CashDrawer/ ../
CashDrawerV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
CashDrawer/” FixVersion=”0” MajorVersion=”1”
<SensorID UnifiedPOS=”CashDrawer”>1</SensorID>
<OpenDrawer/>
</CashDrawer>
Å StatusUpdateEvent fired
<CashDrawerEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
CashDrawerEvents/ ../CashDrawerEventV1.0.0.xsd” xmlns=”http://
www.nrf-arts.org/UnifiedPOS/CashDrawerEvents/” FixVersion=”0”
<StatusUpdateEvent Severity=”Information”>
<SensorID UnifiedPOS=”CashDrawer”>1</SensorID>
<Status>CASH_SUE_DRAWEROPEN</Status>
</StatusUpdateEvent>
</CashDrawerEvent>

Cash Drawer Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CashDrawer (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@CapStatus[0..1]
-@CapStatusMultiDrawerDetect[0..1]
-@DrawerOpened[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 29: Cash Drawer Properties Domain View

Cash Drawer Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CashDrawer (Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-OpenDrawer[0..1]
-+WaitForDrawerClose[0..1]
WaitForDrawerCloseType
-BeepTimeout[1]
-BeepFrequency[1]
-BeepDuration[1]
-BeepDelay[1]
Figure 30: Cash Drawer Methods Domain View

Cash Drawer Events
EventCommonData
DateTimeCommonData -@Severity[0..1]
-@Priority[0..1] SourceURIType
-@TypeCode[1] -@Mode[0..1]
-@TypeCode[1]
-SequenceNumber[1]
BusinessUnitCommonData -+EventDateTime[1] SensorID
CashDrawerEvent -@Name[1] -EventDescription[0..1]
-@Name[0..1]
-@TypeCode[1] -SourceName[0..1]
-@MajorVersion[1] -<choice>[1] -@REM[0..1]
-@MinorVersion[0..1] -+SourceURI[1] -@UnifiedPOS[0..1]
-@FixVersion[0..1] OrganizationHierarchyCommonData -@IFSF[0..1]
-+SensorID[1]
-@ActionCode[0..1] -@Level[0..1] -@IETF[0..1]
-</choice>[1]
-+DirectIOEvent[0..*] -@ID[0..1] -@NAFEM[0..1]
-Instance[0..1]
-+StatusUpdateEvent[0..*] -+BusinessUnit[0..1] -@LonMark[0..1]
XMLPOSCommonProperties -EventNumber[1] -Status[1]
-@AutoDisable[0..1] -Obj[1..*]
-@Claimed[0..1]
-@DataEventEnabled[0..1] CashDrawerPropertiesType
-@CapStatus[0..1]
-@CapStatusMultiDrawerDetect[0..1]
-@PowerNotify[0..1]
-@DrawerOpened[0..1]
-@PowerState[0..1]
-@State[0..1]
-OutputID[0..1]
Figure 31: Cash Drawer Events Domain View

This device only has common errors and they are defined in “Device Error Codes
and Message Severity Codes” on page 7.

N/A


CASH_SUE_DRAWERCLOSED Information The drawer is closed.
CASH_SUE_DRAWEROPEN Information The drawer is open.

CAT
CAT Example
Æset PaymentMedia
<CAT xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/CAT/ ../
CATV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/CAT/”
FixVersion=”0” MajorVersion=”1” MessageType=”Request”
MinorVersion=”0” ActionCode=”Update”>
<SensorID UnifiedPOS=”CAT”>2</SensorID>
<PaymentMedia>CAT_MEDIA_CREDIT</PaymentMedia>
</CAT>
ÆAuthorizeSales
<CAT xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/CAT/ ../
CATV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/CAT/”
FixVersion=”0” MajorVersion=”1” MessageType=”Publish”
<SensorID UnifiedPOS=”CAT”>100</SensorID>
<AuthorizeSales>
<Amount>100</Amount>
<TaxOthers>4</TaxOthers>
<Timeout>10</Timeout>
</AuthorizeSales>
</CAT>

CAT Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CAT (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@AsyncMode[0..1]
-@CapAdditionalSecurityInformation[0..1]
-@CapAuthorizeCompletion[0..1]
-@CapAuthorizePreSales[0..1]
-@CapAuthorizeRefund[0..1]
-@CapAuthorizeVoid[0..1]
-@CapAuthorizeVoidPreSales[0..1]
-@CapCashDeposit[0..1]
-@CapCenterResultCode[0..1]
-@CapCheckCard[0..1]
-@CapInstallments[0..1]
-@CapLockTerminal[0..1]
-@CapLogStatus[0..1]
-@CapPaymentDetail[0..1]
-@CapTaxOthers[0..1]
-@CapTransactionNumber[0..1]
-@CapTrainingMode[0..1]
-@CapUnlockTerminal[0..1]
-@TrainingMode[0..1]
-AccountNumber[0..1]
-AdditionalSecurityInformation[0..1]
-ApprovalCode[0..1]
-Balance[0..1]
-CapDailyLog[0..1]
-CardCompanyID[0..1]
-CenterResultCode[0..1]
-DailyLog[0..*]
-LogStatus[0..1]
-PaymentCondition[0..1]
-PaymentDetail[0..*]
-PaymentMedia[0..1]
-SequenceNumber[0..1]
-SettledAmount[0..1]
-SlipNumber[0..1]
-TransactionNumber[0..1]
-TransactionType[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 32: CAT Properties Domain View

CAT Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CAT (Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-+AccessDailyLog [0..1]
-AuthorizeCompletion[0..1]
-AuthorizePreSales[0..1]
-AuthorizeRefund[0..1]
-AuthorizeSales[0..1]
-AuthorizeVoid[0..1]
-AuthorizeVoidPreSales[0..1]
-+CashDeposit[0..1]
-+CheckCard[0..1]
-LockTerminal[0..1]
-UnlockTerminal[0..1]
AccessDailyLogType CATCommonType CashDepositType CheckCardType

-SequenceNumber[1] -SequenceNumber[1] -@SequenceNumber[1] -@SequenceNumber[1]
-Timeout[1] -Amount[1] -@Amount[1] -@Timeout[1]
-TaxOthers[1] -@Timeout[1]
-Timeout[1]
Figure 33: CAT Methods Domain View

CAT Events
EventCommonData
-@Severity[0..1]
-@TypeCode[1]
-SequenceNumber[1]
-+EventDateTime[1]
CATEvent -@TypeCode[1] -<choice>[1] -@Name[0..1]
-@MajorVersion[1] OrganizationHierarchyCommonData -+SensorID[1] -@UnifiedPOS[0..1]
-@FixVersion[0..1]
-@ID[0..1] -Instance[0..1] -@IETF[0..1]
-@ActionCode[0..1]
-+DirectIOEvent[0..*]
-+ErrorEvent[0..*]
-+OutputComplete[0..*]
-+StatusUpdate[0..*]
DirectIOEventType ErrorEventType OutputCompleteEventType StatusUpdateEventType

-EventNumber[1] -ErrorCode[1] -OutputID[1] -Status[1]
-Data[1..*] -ErrorCodeExtended[1] -+Properties[0..1] -+Properties[0..1]
-+Properties[0..1]
CATPropertiesType
-@AutoDisable[0..1]
-@AsyncMode[1]
-@CapAdditionalSecurityInformation[1]
-@CapAuthorizeCompletion[1]
-@CapAuthorizePreSales[1]
-@CapAuthorizeRefund[1]
-@CapAuthorizeVoid[1]
-@Claimed[0..1]
-@CapAuthorizeVoidPreSales[1]
-@CapCashDeposit[1]
-@CapCenterResultCode[0..1]
-@CapCheckCard[0..1]
-@PowerNotify[0..1]
-@CapInstallments[0..1]
-@PowerState[0..1]
-@State[0..1]
-@CapPaymentDetail[0..1]
-@CapTaxOthers[0..1]
-@CapTransactionNumber[0..1]
-OutputID[0..1]
-@TrainingMode[0..1]
-ApprovalCode[0..1]
-Balance[0..1]
-CapDailyLog[0..1]
-CardCompanyID[0..1]
-CenterResultCode[0..1]
-DailyLog[0..*]
-LogStatus[0..1]
-PaymentCondition[0..1]
-PaymentDetail[0..*]
-PaymentMedia[0..1]
-SlipNumber[0..1]
-TransactionNumber[0..1]
-TransactionType[0..1]
Figure 34: CAT Events Domain View


accessDailyLog
Invalid or unsupported type or timeout
E_ILLEGAL Error parameter was specified, or
CapDailyLog is false.
No response was received from CAT
E_TIMEOUT Error during the specified timeout time in
milliseconds.
The CAT device cannot accept any
E_BUSY Warning
commands now.
authorizeCompletion
Invalid timeout parameter was specified,
E_ILLEGAL Error
or CapAuthorizeCompletion is false.
E_TIMEOUT Warning during the specified timeout time in
milliseconds.
E_BUSY Information
commands now.
authorizePreSales
E_ILLEGAL Error
or CapAuthorizePreSales is false.
milliseconds.
E_BUSY Information
commands now.
authorizeRefund
E_ILLEGAL Error
or CapAuthorizeRefund is false.
milliseconds.
E_BUSY Information
commands now.
authorizeSales
E_ILLEGAL Error Invalid timeout parameter was specified.
milliseconds.
E_BUSY Information
commands now.

authorizeVoid
E_ILLEGAL Error
or CapAuthorizeVoid is false.
milliseconds.
E_BUSY Information
commands now.
authorizeVoidPreSale
s
E_ILLEGAL Error
or CapAuthorizeVoidPreSales is false.
milliseconds.
E_BUSY Information
commands now.
cashDeposit
E_ILLEGAL Error
or CapCashDeposit is false.
milliseconds.
E_BUSY Information
commands now.
cashCheck
E_ILLEGAL Error
or CapCheckCard is false.
milliseconds.
E_BUSY Information
commands now.
lockTerminal
The Electronic Money Device does not
E_ILLEGAL Information
have a security lock function.
E_BUSY Information
commands now.
unlockTerminal
The Electronic Money Device does not
E_ILLEGAL Information
have a security lock function.
E_BUSY Information
commands now.



CAT_LOGSTATUS_OK Information DealingLog is enough capacity
CAT_LOGSTATUS_NEARFULL Warning DealingLog is nearly full.
CAT_LOGSTATUS_FULL Error DealingLog is full
Check Scanner
Check Scanner Example
ÆbeginInsertion
<CheckScanner xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/CheckScanner/
../CheckScannerV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
CheckScanner/” FixVersion=”0” MajorVersion=”1”
<SensorID UnifiedPOS=”CheckScanner”>1</SensorID>
<BeginInsertion>
</BeginInsertion>
</CheckScanner>
ÆendInsertion
<SensorID UnifiedPOS=”CheckScanner”>Front Counter</SensorID>
<EndInsertion/>
</CheckScanner>
Å fire StatusUpdateEvent (check detected)
<CheckScannerEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
CheckScannerEvents/ ../CheckScannerEventV1.0.0.xsd” xmlns=”http://

www.nrf-arts.org/UnifiedPOS/CheckScannerEvents/” FixVersion=”0”
<StatusUpdateEvent>
<Status>CHK_SUE_SCANCOMPLETE</Status>
</StatusUpdateEvent>
</CheckScannerEvent>
ÆretrieveImage(2)
<RetrieveImage>
<CropAreaID>2</CropAreaID>
</RetrieveImage>
</CheckScanner>
Åfire DataEvent
<CheckScannerEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
CheckScannerEvents/ ../CheckScannerEventV1.0.0.xsd” xmlns=”http://
www.nrf-arts.org/UnifiedPOS/CheckScannerEvents/” FixVersion=”0”
<DataEvent Severity=”Information” Mode=”Production” Priority=”-0”>
EventDateTime>
<Status>0</Status>
</DataEvent>
</CheckScannerEvent>
ÆRetrieve Image
<Response>
<ResponderID>1</ResponderID>
</Response>

<ImageData>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</
ImageData>
</CheckScanner>
ÆbeginRemoval
<BeginRemoval>
</BeginRemoval>
</CheckScanner>
ÆendRemoval
<EndRemoval/>
</CheckScanner>

Check Scanner Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CheckScanner (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@CapAutoContrast[0..1]
-@CapAutoGenerateFileID[0..1]
-@CapAutoGenerateImageTagData[0..1]
-@CapAutoSize[0..1]
-@CapConcurrentMICR[0..1]
-@CapContrast[0..1]
-@CapDefineCropArea[0..1]
-@CapImageTagData[0..1]
-@CapMICRDevice[0..1]
-@CapStoreImageFiles[0..1]
-@CapValidationDevice[0..1]
-@ConcurrentMICR[0..1]
-CapColor[0..1]
-CapImageFormat[0..1]
-Color[0..1]
-Contrast[0..1]
-CropAreaCount[0..1]
-DocumentHeight[0..1]
-DocumentWidth[0..1]
-FileID[0..1]
-FileIndex[0..1]
-ImageData[0..1]
-ImageFormat[0..1]
-ImageMemoryStatus[0..1]
-ImageTagData[0..1]
-MapMode[0..1]
-MaxCropAreas[0..1]
-Quality [0..1]
-QualityList [0..*]
-RemainingImagesEstimate[0..1]
---- Methods ---[1]
-......[0..1]
Figure 35: Check Scanner Properties Domain View

Check Scanner Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CheckScanner (Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
BeginInsertionType -.....[0..1] StoreImageType
-@Timeout[1] ---- Methods ---[1] -@CropAreaID[1]
-BeginInsertion[0..1]
-BeginRemoval[0..1]
BeginRemovalType -ClearImage[0..1] RetrieveImageType
-DefineCropArea[0..1]
-@Timeout[1] -@CropAreaID[1]
-EndInsertion[0..1]
-EndRemoval[0..1]
-RetrieveImage[0..1]
-RetrieveMemory[0..1]
-StoreImage[0..1]
@By
ClearImageType DefineCropAreaType RetrieveMemoryType
- CHK_CLR_ALL
CHK_CLR_BY_FILEID -@By[1] -@CropAreaID[1] -@By[1]
- CHK_CLR_BY_FILEINDEX -@X[1] @By
- CHK_CLR_BY_IMAGETAGDATA -@Y[1] - CHK_LOCATE_BY_FILEID
-@CX[1] - CHK_LOCATE_BY_FILEINDEX
-@CY[1] - CHK_LOCATE_BY_IMAGETAGDATA
Figure 36: Check Scanner Methods Domain View

Check Scanner Events
EventCommonData SourceURIType
-@Severity[0..1] -@TypeCode[1]
DateTimeCommonData
-@Priority[0..1]
CheckScannerEvent -SequenceNumber[1]
-@MajorVersion[1] -+EventDateTime[1]
-@MinorVersion[0..1] SensorID
-@FixVersion[0..1] -@Name[1] -SourceName[0..1]
-<choice>[1] -@Name[0..1]
-@ActionCode[0..1] -@TypeCode[1]
-@REM[0..1]
-+SourceURI[1]
-+DataEvent[0..*] OrganizationHierarchyCommonData -@UnifiedPOS[0..1]
-+DirectIOEvent[0..*] -+SensorID[1]
-@IFSF[0..1]
-+ErrorEvent[0..*] -@Level[0..1] -</choice>[1]
-@IETF[0..1]
-+StatusUpdateEvent[0..*] -@ID[0..1] -Instance[0..1]
-@LonMark[0..1]
DirectIOEventType DirectIOEventType ErrorEventType StatusUpdateEventType

-EventNumber[1] -EventNumber[1] -ErrorCode[1] -Status[1]
-Data[1..*] -Data[1..*] -ErrorCodeExtended[1] -+Properties[0..1]
-Obj[1..*] -Obj[1..*] -ErrorLocus[1]
-+Properties[0..1] -+Properties[0..1] -ErrorResponse[1]
-+Properties[0..1]
CheckScannerPropertiesType
-@CapAutoContrast[0..1]
-@CapAutoGenerateFileID[0..1]
-@CapAutoGenerateImageTagData[0..1]
XMLPOSCommonProperties -@CapAutoSize[0..1]
-@CapConcurrentMICR[0..1]
-@AutoDisable[0..1]
-@CapContrast[0..1]
-@CapDefineCropArea[0..1]
-@CapImageTagData[0..1]
-@CapMICRDevice[0..1]
-@CapStoreImageFiles[0..1]
-@CapValidationDevice[0..1]
-@Claimed[0..1]
-@ConcurrentMICR[0..1]
-CapColor[0..1]
-CapImageFormat[0..1]
-Color[0..1]
-@PowerNotify[0..1]
-Contrast[0..1]
-@PowerState[0..1]
-CropAreaCount[0..1]
-@State[0..1]
-DocumentHeight[0..1]
-DocumentWidth[0..1]
-FileID[0..1]
-FileIndex[0..1]
-ImageData[0..1]
-ImageFormat[0..1]
-OutputID[0..1]
-ImageMemoryStatus[0..1]
-ImageTagData[0..1]
-MapMode[0..1]
-MaxCropAreas[0..1]
-Quality[0..1]
-QualityList [0..*]
-RemainingImagesEstimate[0..1]
Figure 37: Check Scanner Events Domain View


beginInsertion
If the Check Scanner is a
E_BUSY Information combination device, the peer
device may be busy.
An invalid timeout parameter was
E_ILLEGAL Error
specified.
The specified time has elapsed
E_TIMEOUT Warning without the check being properly
inserted.
beginRemoval
If the Check Scanner is a
E_BUSY Information combination device, the peer
device may be busy.
An invalid timeout parameter was
E_ILLEGAL Error
specified.
The specified time has elapsed
E_TIMEOUT Warning without the check being properly
removed.
clearImage
One of the following errors
occurred:
• Device does not support stored
E_ILLEGAL Error
images
• Device does not support clearing
one image
E_NOEXIST Error Image was not found.
endInsertion
The device is not in check
E_ILLEGAL Warning
insertion mode.
The device was taken out of
ECHK_NOCHECK Warning insertion mode without a check
being inserted.
endRemoval
The device is not in check
E_ILLEGAL Warning
removal mode.
The device was taken out of
ECHK_CHECK Warning removal mode while a check is
still present.
retrieveImage
The following error has occurred:
E_ILLEGAL Error • Cropped area that is specified by
cropAreaID parameter is invalid.

retrieveMemory
occurred:
• by parameter is invalid.
• The image data file could not be
E_ILLEGAL Error located due to an invalid value
stored in either the FileID,
FileIndex, or ImageTagData
properties that was being used
with the by value.
storeImage
Image already exists in the store
E_EXIST Warning location specified by the
FileIndex property.
occurred:
• Device does not support storing
E_ILLEGAL Error
images
• Cropped area that is specified by
cropAreaID parameter is invalid.
E_FAILURE Error Internal error storing image.
There is no more room for the
ECHK_NOROOM Error
image in memory.


The process of scanning a document image
CHK_SUE_SCANCOMPLETE Information
has been successfully completed

Coin Acceptor
Coin Acceptor Example
Æ SetRealTimeDataEvents to true
<CoinAcceptor xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/CoinAcceptor/
../CoinAcceptorV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
CoinAcceptor/” RealTimeDataEnabled=”true” FixVersion=”0”
<MessageID>asf1234</MessageID>
<SensorID UnifiedPOS=”CoinAcceptor”>1</SensorID>
</CoinAcceptor>
Æ:BeginDeposit()
CoinAcceptor/” FixVersion=”0” MajorVersion=”1”
<BeginDeposit/>
</CoinAcceptor>
Cash is accepted
<CoinAcceptorEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
CoinAcceptorEvents/ ../CoinAcceptorEventV1.0.0.xsd” xmlns=”http://
www.nrf-arts.org/UnifiedPOS/CoinAcceptorEvents/” FixVersion=”0”
<Status>0</Status>
</DataEvent>
</CoinAcceptorEvent>
Æ EndDeposit()
CoinAcceptor/” FixVersion=”0” MajorVersion=”1”

<EndDeposit>
<Success>CACC_DEPOSIT_COMPLETE</Success>
</EndDeposit>
</CoinAcceptor>
Coin Acceptor Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
Coin Acceptor(Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@DepositStatus[0..1]
-CurrencyCode[0..1]
-FullStatus[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 38: Coin Acceptor Properties Domain View

Coin Acceptor Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CoinAcceptor(Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-BeginDeposit[0..1]
-EndDeposit[0..1]
-FixDeposit[0..1]
-PauseDeposit[0..1]
-ReadCashCounts[0..1]
---- Methods ----[1]
-.....[0..1]
AdjustCashCountsType EndDepositType ReadCashCountsType PauseDepositType

-CashCounts[1..*] -Success[1] -@Discrepancy[1] -Control[1]
-CashCounts[1..*]
Figure 39: Coin Acceptor Methods Domain View

Coin Acceptor Events
EventCommonData
-@Severity[0..1]
-@Mode[0..1]
-SequenceNumber[1]
-+EventDateTime[1]
CoinAcceptorEvents -@TypeCode[1] -<choice>[1]
-+SourceURI[1] SensorID
-@MajorVersion[1] OrganizationHierarchyCommonData -+SensorID[1] -@Name[0..1]
-@Level[0..1] -</choice>[1] -@REM[0..1]
-@FixVersion[0..1]
-@ID[0..1] -Instance[0..1] -@UnifiedPOS[0..1]
-@ActionCode[0..1]
-+BusinessUnit [0..1]
-+DataEvent[0..*] -@IFSF[0..1]
-+OrganizationalHierarchy[0..1] -@IETF[0..1]
-+StatusUpdateEvent[0..*] -@NAFEM[0..1]
-@LonMark[0..1]
DataEventType DirectIOEventType StatusUpdateEventType

-Status[1] -EventNumber[1] -Status[1]
-+Properties[0..1] -Data[1..*] -+Properties[0..1]
-Obj[1..*]
-+Properties[0..1]
-@AutoDisable[0..1]
-@CapCompareFirmwareVersion[0..1] CoinAcceptorPropertiesType
-@Claimed[0..1]
-CurrencyCode[0..1]
-@PowerNotify[0..1]
-@PowerState[0..1]
-@State[0..1]
-FullStatus[0..1]
-OutputID[0..1]
Figure 40: Coin Acceptor Events Domain View


beginDeposit
The call sequence is not
E_ILLEGAL Error
correct.
endDeposit
occurred:
E_ILLEGAL Error
beginDeposit and fixDeposit
must be called in sequence
before calling this method.
fixDeposit
occurred:
E_ILLEGAL Error • The call sequence is invalid.
beginDeposit must be called
pauseDeposit
occurred:
beginDeposit must be called
E_ILLEGAL Error • The deposit process is already
paused and control is set to
CACC_DEPOSIT_PAUSE, or
the deposit process is not
paused and control is set to
CACC_DEPOSIT_RESTART.


CACC_STATUS_FULL Error Some cash slots are full.
CACC_STATUS_NEARFULL Warning Some cash slots are nearly full
CACC_STATUS_FULLOK Information No cash slots are either full or nearly full
CACC_STATUS_JAM Error A mechanical fault has occurred.
CACC_STATUS_JAMOK Error A mechanical fault has recovered

Coin Dispenser
Coin Dispenser Example
ÆDispenseChange(“92”)
<CoinDispenser xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/CoinDispenser/
../CoinDispenserV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
CoinDispenser/” FixVersion=”0” MajorVersion=”1”
<SensorID UnifiedPOS=”CoinDispenser”>1</SensorID>
<DispenseChange>
<Amount>92</Amount>
</DispenseChange>
</CoinDispenser>
Coin Dispenser Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CoinAcceptor(Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-DispenserStatus[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 41: Coin Dispenser Properties Domain View

Coin Dispenser Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
CoinDispenser(Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-+AdjustCashCounts[0..1]
-+DispenseChange[0..1]
AdjustCashCountsType DispenseChangeType ReadCashCountsType

-CashCounts[1] -Amount[1] -@Discrepancy[1]
-CashCounts[1]
Figure 42: Coin Dispenser Methods Domain View

Coin Dispenser Events
EventCommonData
-@Severity[0..1] SourceURIType
DateTimeCommonData -@Priority[0..1]
-@TypeCode[1]
-@Mode[0..1]
-@TypeCode[1] -SequenceNumber[1]
-+EventDateTime[1]
-@Name[1] -SourceName[0..1] -@Name[0..1]
-@TypeCode[1] -<choice>[1]
-@REM[0..1]
CoinDispenserEvent -+SourceURI[1]
-@UnifiedPOS[0..1]
-@MajorVersion[1] -+SensorID[1]
OrganizationHierarchyCommonData -@IFSF[0..1]
-@MinorVersion[0..1] -</choice>[1] -@IETF[0..1]
-@FixVersion[0..1] -@Level[0..1] -Instance[0..1] -@NAFEM[0..1]
-@ActionCode[0..1] -@ID[0..1] -+BusinessUnit[0..1]
-@LonMark[0..1]
-+DirectIOEvent[0..*] -+OrganizationalHierarchy[0..1]
-Obj[1..*]
-@AutoDisable[0..1]
-+Properties[0..1]
-@CapUpdateStatistics[0..1] CoinDispenserPropertiesType
-@Claimed[0..1]
-@DataEventEnabled[0..1] -@CapEmptySensor[0..1]
-@DeviceEnabled[0..1] -@CapJamSensor[0..1]
-@PowerNotify[0..1]
-@PowerState[0..1]
-@State[0..1]
-OutputID[0..1]
Figure 43: Coin Dispenser Events Domain View


dispenseChange
An amount parameter value
of zero was specified, or the
amount parameter
E_ILLEGAL Error
contained a negative value
or a value greater than the
device can dispense.


Ready to dispense coinage.
This value is also set when
COIN_STATUS_OK Information
the dispenser is unable to
detect an error condition
Cannot dispense coinage
COIN_STATUS_EMPTY Error because the dispenser is
empty.
Can still dispense coinage,
COIN_STATUS_NEAREMPTY Warning but the dispenser is nearly
empty.
A mechanical fault has
COIN_STATUS_JAM Error
occurred.

Electronic Journal
Electronic Journal Example
ÆqueryContent(“data.bin”, 1, 2)
<ElectronicJournal xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
ElectronicJournal/ ../ElectronicJournalV1.0.0.xsd” xmlns=”http://www.nrf-
arts.org/UnifiedPOS/ElectronicJournal/” FixVersion=”0”
MajorVersion=”1” MessageType=”Publish” MinorVersion=”0”>
<SensorID UnifiedPOS=”ElectronicJournal”>EJ1</SensorID>
<QueryContent>
<FileName>data.bin</FileName>
<FromMarker>1</FromMarker>
<ToMarker>2</ToMarker>
</QueryContent>
</ElectronicJournal>
Å DataEvent fired
<ElectronicJournalEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-
instance” xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/
ElectronicJournalEvents/ ../ElectronicJournalEventV1.0.0.xsd”
xmlns=”http://www.nrf-arts.org/UnifiedPOS/ElectronicJournalEvents/”
FixVersion=”0” MajorVersion=”1” MinorVersion=”0”>
<SensorID UnifiedPOS=”ElectronicJournal”>EJ1</SensorID>
<Status>0</Status>
</DataEvent>
</ElectronicJournalEvent>

Electronic Journal Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
ElectronicJournal(Properties Domain View)
-@MajorVersion[1]
-@FixVersion[0..1]
-@AsyncMode[0..1]
-@CapAddMarker[0..1]
-@CapErasableMedium[0..1]
-@CapInitializeMedium[0..1]
-@CapMediumIsAvailable[0..1]
-@CapPrintContent[0..1]
-@CapPrintContentFile[0..1]
-@CapRetrieveCurrentMarker[0..1]
-@CapRetrieveMarker[0..1]
-@CapRetrieveMarkerByDateTime[0..1]
-@CapRetrieveMarkersDateTime[0..1]
-@CapStorageEnabled[0..1]
-@CapSuspendPrintContent[0..1]
-@CapSuspendQueryContent[0..1]
-@CapWaterMark[0..1]
-@FlagWhenIdle[0..1]
-@MediumIsAvailable [0..1]
-@StorageEnabled[0..1]
-@Suspended[0..1]
-@WaterMark[0..1]
-CapStation[0..1]
-MediumFreeSpace[0..1]
-MediumID[0..1]
-MediumSize[0..1]
-Station[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 44: Electronic Journal Properties Domain View

Electronic Journal Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
ElectronicJournal(Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-+AddMarker[0..1] RetrieveMarkersDateTimeType
AddMarkerType
-CancelPrintContent[0..1] -Marker[1]
-Marker[1] -CancelQueryContent[0..1] -DateTime[1]
-EraseMedium[0..1]
-+InitializeMedium[0..1]
-+PrintContent[0..1]
-+PrintContentFile[0..1] RetrieveMarkerByDateTimeType
InitializeMediumType
-+QueryContent[0..1] -MarkerType[1]
-MediumID[1]
-ResumePrintContent[0..1] -DateTime[1]
-ResumeQueryContent[0..1]
-+RetrieveCurrentMarker[0..1]
-+RetrieveMarker[0..1]
-+RetrieveMarkerByDateTime[0..1]
-+RetrieveMarkersDateTime[0..1]
-SuspendPrintContent[0..1]
-SuspendQueryContent[0..1]
PrintContentType PrintContentFileType QueryContentType RetrieveCurrentMarkerType RetrieveMarkerType

-FromMarker[1] -FileName[1] -FileName[1] -MarkerType[1] -MarkerType[1]
-ToMarker[1] -FromMarker[1] -Marker[1] -SessionNumber[1]
-ToMarker[1]
Figure 45: Electronic Journal Methods Domain View

Electronic Journal Events
EventCommonData
DateTimeCommonData -@Severity[0..1]
-@Priority[0..1] SourceURIType
-SequenceNumber[1] -@TypeCode[1]
BusinessUnitCommonData -+EventDateTime[1]
-@Name[1] -EventDescription[0..1]
ElectronicJournalEvent -@TypeCode[1] -SourceName[0..1] SensorID
-<choice>[1] -@Name[0..1]
-@MajorVersion[1]
-@MinorVersion[0..1] OrganizationHierarchyCommonData
-+SensorID[1] -@UnifiedPOS[0..1]
-@FixVersion[0..1]
-@ActionCode[0..1]
-@ID[0..1] -Instance[0..1] -@IETF[0..1]
-+DataEvent[0..*]
-+ErrorEvent[0..*]
DataEventType DirectIOEventType ErrorEventType OutputCompleteEventType StatusUpdateEventType

-Status[1] -EventNumber[1] -ErrorCode[1] -OutputID[1] -Status[1]
-+Properties[0..1]
ElectronicJournalPropertiesType
XMLPOSCommonProperties -@AsyncMode[0..1]
-@AutoDisable[0..1] -@CapAddMarker[0..1]
-@CapCompareFirmwareVersion[0..1] -@CapErasableMedium[0..1]
-@CapPowerReporting[0..1] -@CapInitializeMedium[0..1]
-@CapStatisticsReporting[0..1] -@CapMediumIsAvailable[0..1]
-@CapUpdateFirmware[0..1] -@CapPrintContent[0..1]
-@CapUpdateStatistics[0..1] -@CapPrintContentFile[0..1]
-@Claimed[0..1] -@CapRetrieveCurrentMarker[0..1]
-@DataEventEnabled[0..1] -@CapRetrieveMarker[0..1]
-@DeviceEnabled[0..1] -@CapRetrieveMarkerByDateTime[0..1]
-@FreezeEvents[0..1] -@CapRetrieveMarkersDateTime[0..1]
-@PowerNotify[0..1] -@CapStorageEnabled[0..1]
-@PowerState[0..1] -@CapSuspendPrintContent[0..1]
-@State[0..1] -@CapSuspendQueryContent[0..1]
-CheckHealthText[0..1] -@CapWaterMark[0..1]
-DeviceControlDescription[0..1] -@FlagWhenIdle[0..1]
-DeviceControlVersion[0..1] -@MediumIsAvailable [0..1]
-DeviceServiceDescription[0..1] -@StorageEnabled[0..1]
-DeviceServiceVersion[0..1] -@Suspended[0..1]
-OutputID[0..1] -@WaterMark[0..1]
-PhysicalDeviceDescription [0..1] -CapStation[0..1]
-PhysicalDeviceName[0..1] -MediumFreeSpace[0..1]
-MediumID[0..1]
-MediumSize[0..1]
-Station[0..1]
Figure 46: Electronic Journal Events Domain View



addMarker
E_ILLEGAL Error Characters that cannot be used
as marker are included, or the
character string is too long to
be used as the marker.
E_BUSY Warning Request cannot be performed
while output is in progress.
(This includes when the
POSPrinter or FiscalPrinter is
busy printing.)
EEJ_EXISTING Error The marker name is already
specified in current medium.
EEJ_MEDIUM_F Error There is not enough free space
ULL to add a marker in current
medium.
eraseMedium
E_FAILURE Error Failed to erase data.
initializeMedium
E_BUSY Warning Cannot perform while output is
in progress. (This includes
when the POSPrinter or
printContentFile
E_BUSY Warning Cannot perform while output is
in progress. (This includes
when the POSPrinter or
E_ILLEGAL Error fileName contains invalid
characters.
E_EXISTS Error The file defined in fileName
already exists.
retrieveCurrentMarker
E_ILLEGAL Error The parameter markerType
contains an invalid value.
E_NOEXIST Error A marker does not exist for the
specified marker type.
retrieveMarker
E_ILLEGAL Error One of the parameters is
invalid. Either the value in
markerType does not exist.


specified parameter values.
retrieveMarkerByDateTime
E_ILLEGAL Error One of the parameters is
invalid. The value in
markerType does not exist,
dateTime is invalid, or the
markerNumber does not exist
for the specified time period.
specified time period.
EEJ_MULTIPLE_ Error More than one marker exists
MARKER for the specified time period.


The medium is nearly full (i.e., its free space is
EJ_SUE_MEDIUM_NEAR_FULL Warning
low
EJ_SUE_MEDIUM_FULL Error Storage medium is full.
EJ_SUE_MEDIUM_REMOVED Information Medium was removed from the device.
EJ_SUE_MEDIUM_INSERTED Information Medium was inserted into the device.
EJ_SUE_SUSPENDED Warning Data printing or transfer was suspended
Electronic Value Reader / Writer

Electronic Value Reader / Writer Example
ÆbeginDetection
<ElectronicValueRW xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
ElectronicValueRW/ ../ElectronicValueRWV1.0.0.xsd” xmlns=”http://
www.nrf-arts.org/UnifiedPOS/ElectronicValueRW/” FixVersion=”0”
<SensorID UnifiedPOS=”ElectronicValueRW”>EVR1</SensorID>
<BeginDetection Type=”EVRW_BD_ANY”>
</BeginDetection>
</ElectronicValueRW>

ÆendDetection
<EndDetection/>
Æset DataEventEnabled to true
www.nrf-arts.org/UnifiedPOS/ElectronicValueRW/”
DataEventEnabled=”true” FixVersion=”0” MajorVersion=”1”
MessageType=”Request” MinorVersion=”0” ActionCode=”Begin”>
<MessageID Timestamp=”2001-12-17T09:30:47.0Z”>1234</MessageID>
ÆbeginRemoval
<BeginRemoval>
</BeginRemoval>
ÆendRemoval
<EndRemoval />

Electronic Value Reader / Writer Properties
XMLPOS
Common
ElectronicValueRW (Properties Domain View) Properties
-@MajorVersion[1]
-@FixVersion[0..1]
----- Properties ----[1]
-@AsyncMode[0..1]
-@CapActivateService[0..1] ARTS
-@CapAddValue[0..1] Common
XMLPOS Data
-@CapCancelValue[0..1]
-@CapElectronicMoney[0..1] Common
-@CapEnumerateCardServices[0..1] Data
-@CapIndirectTransactionLog[0..1]
-@CapMediumID[0..1]
-@CapPoint[0..1]
-@CapSubtractValue[0..1]
-@CapTransaction[0..1]
-@CapTransactionLog[0..1]
-@CapUpdateKey[0..1]
-@CapVoucher[0..1]
-@CapWriteValue[0..1]
-@DetectionControl[0..1]
-@DetectionStatus[0..1]
-@LogStatus[0..1]
-Amount[0..1]
-ApprovalCode[0..1] VoucherIDListType
-Balance[0..1] -TicketID[1]
-BalanceOfPoint[0..1] -Count[1]
-CapCardSensor[0..1]
-CapDetectionControl[0..1]
-CardServiceList[0..*]
-CurrentService[0..1]
-ExpirationDate[0..1]
-LastUsingDate[0..1]
-MediumID[0..1]
-Point[0..1]
-ReaderWriterServiceList[0..1]
-SettledPoint[0..1]
-TransactionLog[0..1]
-VoucherID[0..1]
-VoucnerIDList[0..*]
----- Methods ----[1]
-....[1]
Figure 47: Electronic Value Reader / Writer Properties Domain View

Electronic Value Reader / Writer Methods
XMLPOS
Common
Properties
XMLPOS ARTS
Common Common
Data Data
ElectronicValueRW(Methods Domain View)

-@MajorVersion[1]
@Type AccessLogType -@FixVersion[0..1]
-----Properties ----[1] WriteValueType
- EVRW_AL_REPORTING
-@Type[1] -.....[0..1] -SequenceNumber[1]
- EVRW_AL_SETTLEMENT
-SequenceNumber[1] -----Methods ----[1] -Timeout[1]
-Timeout[1] -+AccessLog [0..1]
-+ActivateService [0..1]
ActivateService -+AddValue[0..1] UpdateKeyType
-Data[1] -+BeginDetection[0..1]
-+BeginRemoval[0..1] -Data[1]
-Obj[1] -Object[1]
-+CancelValue[0..1]
-CaptureCard[0..1]
AddValue TransactionAccessType
-EndDetection[0..1]
-SequenceNumber[1] -EndRemoval[0..1] -@Control[1]
-Timeout[1] -EnumerateCardServices[0..1]
-LockTerminal[0..1] SubtractValueType
-+ReadValue[0..1]
@Type BeginDetectionType -SequenceNumber[1]
-+SubtractValue[0..1]
- EVRW_BD_ANY -@Type[1] -Timeout[1]
EVRW_BD_SPECIFIC -Timeout[1] -+TransactionAccess[0..1]
-UnlockTerminal[0..1]
-+UpdateKey[0..1]
-+WriteValue[0..1]
BeginRemovalType CancelValueType ReadValueType

-Timeout[1] -SequenceNumber[1] -SequenceNumber[1]
-Timeout[1] -Timeout[1]
Figure 48: Electronic Value Reader / Writer Methods Domain View

Electronic Value Reader / Writer Events
SensorID
-@Name[0..1]
-@REM[0..1]
EventCommonData -@UnifiedPOS[0..1]
-@Severity[0..1] -@IFSF[0..1]
ElectronicValueRWEvent
DateTimeCommonData -@Priority[0..1] -@IETF[0..1]
-@MajorVersion[1] -@Mode[0..1] -@NAFEM[0..1]
-@MinorVersion[0..1] -@TypeCode[1] SourceURIType
-SequenceNumber[1] -@LonMark[0..1]
-@FixVersion[0..1] -+EventDateTime[1] -@TypeCode[1]
-@ActionCode[0..1] OrganizationHierarchyCommonData -EventDescription[0..1]
-+DataEvent[0..1] -@Level[0..1] -SourceName[0..1]
-+DirectIOEvent[0..1] -@ID[0..1] -<choice>[1]
-+ErrorEvent[0..1] -+SourceURI[1]
-+OutputCompleteEvent[0..1] BusinessUnitCommonData -+SensorID[1]
-+StatusUpdateEvent[0..1] -@Name[1] -</choice>[1]
-@TypeCode[1] -Instance[0..1]
-+BusinessUnit[0..1]
-@AutoDisable[0..1]
DataEventType DirectIOEventType ErrorEventType OutputCompleteEventType StatusUpdateEventType -@CapCompareFirmwareVersion[0..1]
-Status[1] -EventNumber[1] -ErrorCode[1] -OutputID[1] -Status[1] -@CapStatisticsReporting[0..1]
-@Claimed[0..1]
-+Properties[0..1]
-@PowerNotify[0..1]
-@PowerState[0..1]
ElectronicValueRWPropertiesType -@State[0..1]
-@AsyncMode[0..1] -DeviceControlDescription[0..1]
-@CapActivateService[0..1] -DeviceControlVersion[0..1]
-@CapAddValue[0..1] -DeviceServiceDescription [0..1]
-@CapCancelValue[0..1] -DeviceServiceVersion [0..1]
-@CapElectronicMoney[0..1] -OutputID[0..1]
-@CapEnumerationCardServices[0..1] -PhysicalDeviceDescription [0..1]
-@CaIndirectTransactionLog[0..1] -PhysicalDeviceName [0..1]
-@CapMediumID[0..1]
-@CapPoint[0..1]
-@CapSubtractValue[0..1]
-@CapTransaction[0..1]
-@CapTransactionLog[0..1]
-@CapUpdateKey[0..1]
-@CapVoucher[0..1]
-@CapWriteValue[0..1]
-@DetectionControl[0..1]
-@DetectionStatus[0..1]
-@LogStatus[0..1]
-Amount[0..1]
-ApprovalCode[0..1]
-Balance[0..1]
-BalanceOfPoint[0..1]
-CapCardSensor[0..1]
-CapDetectionControl[0..1]
-CardServiceList[0..*]
-CurrentService[0..1]
-ExpirationDate[0..1]
-LastUsingDate[0..1]
-MediumID[0..1]
-Point[0..1]
-ReaderWriterServiceList[0..1]
-SettledPoint[0..1]
-TransactionLog[0..1]
-VoucherID[0..1]
-VoucherIDList[0..*]
Figure 49: Electronic Value Reader / Writer Events Domain View



Fiscal Printer
Fiscal Printer Example
ÆOpen Request
<FiscalPrinter xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/FiscalPrinter/ ../
FiscalPrinterV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
FiscalPrinter/” FixVersion=”0” MajorVersion=”1”
MessageType=”Request” DeviceEnabled=”true” DayOpened=”true”>
<RequestID Name=”FiscalPrinterOpen” Timestamp=”2001-12-
17T09:30:45.0Z”>String</RequestID>
<LogicalDeviceName>WN_FPTR_THF_COM</LogicalDeviceName>
<Claim Timeout=”3000” />
<Open LogicalDeviceName=”WN_FPTR_THF_COM” />
<PrinterState xsi:nil=”true” />
</FiscalPrinter>
ÆResponse to Open Request
FiscalPrinter/” FixVersion=”0” MajorVersion=”1” MessageType=”Response”>
<RequestID Name=”FiscalPrinterOpen” Timestamp=”2001-12-

<Open LogicalDeviceName=”WN_FPTR_THF_COM” />
<State>S_IDLE</State>
<PrinterState>FPTR_PS_MONITOR</PrinterState>
<DayOpened>true</DayOpened>
</FiscalPrinter>
ÆPrint Receipt Header Request
FiscalPrinter/” FixVersion=”0” MajorVersion=”1” MessageType=”Request”>
<RequestID Name=”FiscalReceiptHeader” Timestamp=”2001-12-
<BeginFiscalReceipt printHeader=”false” />
<GetPrinterState xsi:nil=”true” />
</FiscalPrinter>
ÆResponse to Print Receipt Header Request
FiscalPrinter/” FixVersion=”0” MajorVersion=”1” MessageType=”Response”>
<RequestID Name=”FiscalReceiptHeader” Timestamp=”2001-12-
<PrinterState>FPTR_PS_FISCAL_RECEIPT</PrinterState>

</FiscalPrinter>
ÆPrint Receipt Body Request
<RequestID Name=”FiscalReceiptBody” Timestamp=”2001-12-
<PrintRecItem>
<Description>item1</Description>
<Price>100000</Price>

<Quantity>1000</Quantity>

<VatInfo>1</VatInfo>
<UnitPrice>100000</UnitPrice>
<UnitName>pcs</UnitName>

</PrintRecItem>
<PrintRecItem>
<Description>item2</Description>
<Price>200000</Price>

<Quantity>2000</Quantity>

<VatInfo>1</VatInfo>
<UnitPrice>100000</UnitPrice>
<UnitName>pcs</UnitName>
</PrintRecItem>
<PrintRecTotal total=”300000” payment=”300000” description=”cash” />
<PrinterState />
</FiscalPrinter>
ÆResponse to Print Receipt Body Request
MessageType=”Response” MinorVersion=”0”>
<Response>
<ResponderID>WN_FPTR_THF_COM</ResponderID>
</Response>
<PrinterState>FPTR_PS_FISCAL_RECEIPT_TOTAL</PrinterState>
</FiscalPrinter>
ÆPrint Receipt Footer Request

<PrinterState xsi:nil=”true” />

<EndFiscalReceipt PrintHeader=”false” />
<PrintRecMessage>
<Message>Thank you for your visit</Message>
</PrintRecMessage>
</FiscalPrinter>
ÆResponse to Print Receipt Footer Request
MessageType=”Response” MinorVersion=”0”>

<Response>
<ResponderID>Printer #7</ResponderID>
</Response>
<PrinterState>FPTR_PS_MONITOR</PrinterState>
</FiscalPrinter>
ÆPrint Normal on station 1 “Hello World”
<SensorID UnifiedPOS=”FiscalPrinter”>Station1</SensorID>
<PrintNormal>
<Station>FPTR_S_JOURNAL</Station>
<Data>Hello World</Data>
</PrintNormal>
</FiscalPrinter>
ÆClose Request
<RequestID Name=”FiscalPrinterClose” Timestamp=”2001-12-
<Close />
</FiscalPrinter>

Fiscal Printer Properties

FiscalPrinter (Properties Domain View)
-@MajorVersion[1]
-@MinorVersion[0..1] XMLPOS
-@FixVersion[0..1] Common
-@AsyncMode[0..1] Properties
-@CapAdditionalHeader[0..1]
-@CapAdditionalLines[0..1]
-@CapAdditionalTrailer[0..1]
-@CapAmountAdjustment[0..1]
-@CapChangeDue[0..1]
-@CapCheckTotal[0..1]
XMLPOS ARTS
-@CapCoverSensor[0..1]
Common Common
-@CapDoubleWidth[0..1]
Data Data
-@CapDuplicateReceipt[0..1]
-@CapEmptyReceiptIsVoidable[0..1]
-@CapFiscalReceiptStation[0..1]
-@CapFiscalReceiptType[0..1]
-@CapFixedOutput[0..1]
-@CapHasVatTable[0..1]
-@CapIndependentHeader[0..1]
-@CapItemList[0..1]
-@CapMultiContractor[0..1]
-@CapNonFiscalMode[0..1]
-@CapOnlyVoidLastItem[0..1]
-@CapOrderAdjustmentFirst[0..1]
-@CapPackageAdjustment[0..1]
-@CapPercentAdjustment[0..1]
-@CapPositiveAdjustment[0..1]
-@CapPositiveSubtotalAdjustment [0..1]
-@CapPostPreLine[0..1]
-@CapPowerLossReport[0..1]
-@CapPredefinedPaymentLines[0..1]
-@CapReceiptNotPaid[0..1]
-@CapRemainingFiscalMemory[0..1]
-@CapReservedWord[0..1]
-@CapSetCurrency[0..1]
-@CapSetHeader[0..1]
-@CapSetPOSID[0..1]
-@CapSetStoreFiscalID[0..1]
-@CapSetTrailer[0..1] PrinterStationType
-@CapSetVatTable[0..1]
-@CapSubAmountAdjustment[0..1]
-@CapSubPercentAdjustment[0..1] -@CapNearEndSensor[0..1]
-@CapSubtotal[0..1] -@CapPresent[0..1]
-@CapTotalizerType[0..1] -@Empty[0..1]
-@CapTrainingMode[0..1] -@NearEnd[0..1]
-@CapValidateJournal[0..1]
-@CapXReport[0..1]
-@CheckTotal[0..1]
-@CoverOpen[0..1]
-@DayOpened[0..1]
-@DuplicateReceipt[0..1]
-@TrainingModeActive[0..1]
-ActualCurrency[0..1]
-AdditionalHeader[0..1]
-AdditionalTrailer[0..1]
-AmountDecimalPlaces [0..1]
-ChangeDue[0..1]
-ContractorID[0..1]
-CountryCode[0..1]
-DateType[0..1] SlipStationType
-DescriptionLength[0..1] -@CapSlpFiscalDocument[0..1]
-ErrorLevel[0..1] -@CapSlpFullSlip[0..1]
-ErrorOutID[0..1] -@CapSlpValidation[0..1]
-ErrorState[0..1] -SlipSelection [0..1]
-ErrorStation[0..1]
-ErrorString[0..1]
-FiscalReceiptStation [0..1]
-FiscalReceiptType[0..1]
-MessageLength[0..1]
-NumHeaderLines[0..1]
-NumTrailerLines[0..1]
-NumVatRates[0..1]
-PostLine[0..1]
-PredefinedPaymentLines[0..1]
-PreLine[0..1]
-PrinterState[0..1]
-PrintingMessageType[0..1]
-QuantityDecimalPlaces [0..1]
-QuantityLength[0..1]
-RemainingFiscalMemory[0..1]
-ReservedWord[0..1]
-TotalizerType[0..1]
-+ReceiptStation[0..1]
-+JournalStation[0..1]
-+SlipStation[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 50: Fiscal Printer Properties Domain View

Fiscal Printer Methods
XMLPOS
Common
Properties
FiscalPrinterMethod
-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
BeginFiscalDocumentType
XMLPOS ---- Methods ---[1]
ARTS -+BeginFiscalDocument[0..1] -DocumentAmount[1]
Common
Common -+BeginFiscalReceipt [0..1]
Data
Data -+BeginFixedOUtput[0..1]
-+BeginInsertion[0..1] BeginFiscalReceiptType
-+BeginItemList[0..1] -@PrintHeader[1]
-BeginNonFiscal[0..1]
-+BeginRemoval[0..1]
BeginFixedOutputType
-BeginTraining[0..1]
-ClearError[0..1] -Station[1]
-EndFiscalDocument[0..1] -DocumentType[1]
-+EndFiscalReceipt[0..1]
-EndFixedOUtput[0..1] BeginInsertionType
-EndInsertion[0..1] -Timeout[1]
-EndItemList[0..1]
-EndNonFiscal[0..1]
-EndRemoval[0..1]
PrintRecNotPaidType -EndTraining[0..1]
-+GetData[0..1] BeginItemListType
-Description[1]
-+GetDate[0..1]
-Amount[1] -VatID[1]
-+GetTotalizer [0..1]
PrintRecMessageType -+GetVatEntry[0..1]
-PrintDuplicateReceipt[0..1]
-Message[1] -+PrintFiscalDocumentLIne[0..1] BeginRemovalType
-+PrintFixedOutput[0..1] -Timeout[1]
PrintRecItemFuelVoidType -+PrintNormal[0..1]
-Description[1] -+PrintPeriodicTotaslReport[0..1]
-Price[1] -PrintPowerLossReport[0..1] EndFiscalReceiptType
-VatInfo[1] -+PrintRecCash[0..1] -@PrintHeader[1]
-SpecialTax[1] -+PrintRecItem[0..1]
-+PrintRecItemAdjustment[0..1]
PrintRecItemFuelType GetDataType
-+PrintRecItemAdjustmentVoid[0..1]
-Description[1] -+PrintRecItemFuel[0..1] -DataItem[1]
-Price[1] -+PrintRecItemFuelVoid[0..1] -OptArgs[1]
-Quantity[1] -+PrintRecItemVoid[0..1] -Data[1]
-VatInfo[1] -+PrintRecMessage[0..1]
-UnitPrice[1] -+PrintRecNotPaid[0..1] GetDateType
-UnitName[1] -+PrintRecPackageAdjustment[0..1] -Date[1]
-SpecialTax[1] -+PrintRecPackageAdjustVoid [0..1]
-SpecialTaxName[1] -+PrintRecRefund[0..1]
-+PrintRecRefundVoid[0..1] GetTotalizerType
PrintRecItemAdjustmentType -+PrintRecSubtotal[0..1] -VatID[1]
-+PrintRecSubtotalAdjustment[0..1] -OptArgs[1]
-AdjustmentType[1]
-+PrintRecSubtotalAdjustVoid [0..1] -Data[1]
-Description[1]
-Amount[1] -+PrintRecTaxID[0..1]
-+PrintRecTotal[0..1]
-VatInfo[1] GetVatEntryType
-+PrintRecVoidItem[0..1]
PrintRecItemType -+PrintReport[0..1] -VatID[1]
-PrintXReport[0..1] -OptARgs[1]
-Description[1] -PrintZReport[0..1] -VatRate[1]
-Price[1] -ResetPrinter[0..1]
-Quantity[1] -+SetCurrency[0..1] SetHeaderTrailerLineType
-VatInfo[1] -+SetDate[0..1] -@DoubleWidth[1]
-UnitPrice[1] -+SetHeaderLine[0..1] -LineNumber[1]
-UnitName[1] -+SetPOSID[0..1] -Text[1]
-+SetStoreFiscalID[0..1]
PrintRecPackageAdjustVoidType -+SetTrailerLine[0..1] PrintRecPackageAdjustmentType
-AdjustmentType[1] -SetVatTable[0..1] -AdjustmentType[1]
-VatAdjustment[1] -+SetVatValue[0..1] -Description[1]
-+VerifyItem[0..1] -VatAdjustment[1]
PrintRecCashType PrintPeriodicTotalsReportType PrintNormalType PrintFixedOutputType PrintFiscalDocumentLineType

-Amount[1] -Date1[1] -Station[1] -DocumentType[1] -DocumentLine[1]
-Date2[1] -Data[1] -LineNumber[1]
-Data[1]
Figure 51: Fiscal Printer Methods Domain View

Fiscal Printer Events
FiscalPrinterPropertiesType
-@AsyncMode[0..1]
-@CapAdditionalHeader[0..1]
FiscalPrinterEvents -@CapAdditionalLines[0..1]
-@CapAdditionalTrailer[0..1]
-@MajorVersion[1] -@CapAmountAdjustment[0..1]
-@CapChangeDue[0..1]
-@FixVersion[0..1]
-@CapCheckTotal[0..1]
-@ActionCode[0..1]
-@CapCoverSensor[0..1]
-@CapDoubleWidth[0..1]
-+ErrorEvent[0..*] -@CapDuplicateReceipt[0..1]
-@CapEmptyReceiptIsVoidable[0..1]
-@CapFiscalReceiptStation[0..1]
EventCommonData
-@CapFiscalReceiptType[0..1]
-@Severity[0..1] -@CapFixedOutput[0..1]
DateTimeCommonData
-@Priority[0..1] SourceURIType -@CapHasVatTable[0..1]
-@TypeCode[1] -@Mode[0..1] -@CapIndependentHeader[0..1]
-@TypeCode[1]
-SequenceNumber[1] -@CapItemList[0..1]
BusinessUnitCommonData -+EventDateTime[1] -@CapMultiContractor[0..1]
-@Name[1] -EventDescription[0..1] -@CapNonFiscalMode[0..1]
SensorID
-@TypeCode[1] -SourceName[0..1] -@CapOnlyVoidLastItem[0..1]
-<choice>[1] -@Name[0..1] -@CapOrderAdjustmentFirst[0..1]
OrganizationHierarchyCommonData -+SourceURI[1] -@REM[0..1] -@CapPackageAdjustment[0..1]
-+SensorID[1] -@UnifiedPOS[0..1] -@CapPercentAdjustment[0..1]
-@ID[0..1] -@CapPositiveAdjustment[0..1]
-Instance[0..1] -@IETF[0..1] -@CapPositiveSubtotalAdjustment[0..1]
-+BusinessUnit [0..1] -@NAFEM[0..1] -@CapPostPreLine[0..1]
-+OrganizationalHierarchy[0..1] -@LonMark[0..1] -@CapPowerLossReport[0..1]
-@CapPredefinedPaymentLines[0..1]
-@CapReceiptNotPaid[0..1]
-@CapRemainingFiscalMemory[0..1]
-@CapReservedWord[0..1]
-@CapSetCurrency[0..1]
-@CapSetHeader[0..1]
-@CapSetPOSID[0..1]
DirectIOEventType ErrorEventType OutputCompleteEventType StatusUpdateEventType -@CapSetStoreFiscalID[0..1]
-EventNumber[1] -ErrorCode[1] -OutputID[1] -Status[1] -@CapSetTrailer[0..1]
-Data[1..*] -ErrorCodeExtended[1] -+Properties[0..1] -+Properties[0..1] -@CapSetVatTable[0..1]
-Obj[1..*] -ErrorLocus[1] -@CapSubAmountAdjustment[0..1]
-+Properties[0..1] -ErrorResponse[1] -@CapSubPercentAdjustment[0..1]
-+Properties[0..1] -@CapSubtotal[0..1]
-@CapTotalizerType[0..1]
-@CapValidateJournal[0..1]
-@CapXReport[0..1]
-@CheckTotal[0..1]
-@CoverOpen[0..1]
-@DayOpened[0..1]
-@DuplicateReceipt[0..1]
XMLPOSCommonProperties -@TrainingModeActive[0..1]
-ActualCurrency[0..1]
-@AutoDisable[0..1] -AdditionalHeader[0..1]
-@CapCompareFirmwareVersion[0..1] -AdditionalTrailer[0..1]
-@CapPowerReporting[0..1] -AmountDecimalPlaces[0..1]
-@CapStatisticsReporting[0..1] -ChangeDue[0..1]
-@CapUpdateFirmware[0..1] -ContractorID[0..1]
-@CapUpdateStatistics[0..1] -CountryCode[0..1]
-@Claimed[0..1] -DateType[0..1]
-@DataEventEnabled[0..1] -DescriptionLength[0..1]
-@DeviceEnabled[0..1] -ErrorLevel[0..1]
-@FreezeEvents[0..1] -ErrorOutID[0..1]
-@PowerNotify[0..1] -ErrorState[0..1]
-@PowerState[0..1] -ErrorStation[0..1]
-@State[0..1] -ErrorString[0..1]
-CheckHealthText[0..1] -FiscalReceiptStation[0..1]
-DeviceControlDescription[0..1] -FiscalReceiptType[0..1]
-DeviceControlVersion[0..1] -MessageLength[0..1]
-DeviceServiceDescription[0..1] -NumHeaderLines[0..1]
-DeviceServiceVersion[0..1] -NumTrailerLines[0..1]
-OutputID[0..1] -NumVatRates[0..1]
-PhysicalDeviceDescription [0..1] -PostLine[0..1]
-PhysicalDeviceName [0..1] -PredefinedPaymentLines[0..1]
-PreLine[0..1]
-PrinterState[0..1]
-PrintingMessageType[0..1]
-QuantityDecimalPlaces [0..1]
-QuantityLength[0..1]
-RemainingFiscalMemory[0..1]
-ReservedWord[0..1]
-TotalizerType[0..1]
-+ReceiptStation[0..1]
-+JournalStation[0..1]
-+SlipStation[0..1]
Figure 52: Fiscal Printer Events Domain View


beginFiscalDocument
The slip station does not exist or the printer
E_ILLEGAL Error does not support fiscal output to the slip
station
The printer’s current state does not allow this
EFPTR_WRONG_STATE Error
state transition.
EFPTR_SLP_EMPTY Error There is no paper in the slip station
EFPTR_BAD_ITEM_AM
Error The documentAmount parameter is invalid.
OUNT
EFPTR_MISSING_SET_ The new receipt cannot be opened. the Fiscal
Error Printer is expecting the current currency to be
CURRENCY
changed by calling setCurrency method.
The completion of the fiscal day is required
EFPTR_DAY_END_REQ by calling printZReport. No further fiscal
Error
UIRED receipts or documents can be started before
this is done.
beginFiscalReceipt
E_ILLEGAL Error An invalid receipt type was specified.
The Fiscal Printer’s current state does not
allow this state transition.
The new receipt cannot be opened, the Fiscal
EFPTR_MISSING_SET_
Error Printer is expecting the current currency to be
CURRENCY changed by calling setCurrency method.
The completion of the fiscal day is required
EFPTR_DAY_END_REQ by calling printZReport. No further fiscal
Error
UIRED receipts or documents can be started before
this is done.
beginFixedOutput
• Station does not exist
E_ILLEGAL Error • Fiscal Printer does not support fixed output.
• station parameter is invalid.
• documentType is invalid.
EFPTR_SLP_EMPTY Error There is no paper in the slip station
beginInsertion
The slip station does not exist or an invalid
E_ILLEGAL Error
timeout parameter was specified.
The specified time has elapsed without the
E_TIMEOUT Warning
form being properly inserted
beginItemList

The Fiscal Printer does not support an item

E_ILLEGAL Error list report or the Fiscal Printer does not
support VAT tables
allow this state transition
EFPTR_BAD_VAT Error The vatID parameter is invalid
beginNonFiscal
The Fiscal Printer does not support non-fiscal
E_ILLEGAL Error
output
beginRemoval
The Fiscal Printer does not have a slip station
E_ILLEGAL Error or an invalid timeout parameter was
specified.
The specified time has elapsed without the
E_TIMEOUT Warning
form being properly removed.
beginTraining
The Fiscal Printer does not support training
E_ILLEGAL Error
mode
clearError
E_FAILURE Error Error recovery failed.
endFiscalDocument
The Fiscal Printer does not support fiscal
E_ILLEGAL Error
output to the slip station
The Fiscal Printer is not currently in the
Fiscal Document state
endFiscalReceipt
Fiscal Receipt Ending state
endFixedOutput
The Fiscal Printer does not support fixed
E_ILLEGAL Error
output
endInsertion
The Fiscal Printer is not in slip insertion
E_ILLEGAL Error
mode.
The device was taken out of insertion mode
EFPTR_COVER_OPEN Error
while the Fiscal Printer cover was open.
The device was taken out of insertion mode
EFPTR_SLP_EMPTY Error
without a form being inserted.
endItemList


E_ILLEGAL Error output or the Fiscal Printer does not support
VAT tables
endNonFiscal
The Fiscal Printer does not support non-fiscal
E_ILLEGAL Error
output
The Fiscal Printer is not currently in the Non-
endRemoval
The Fiscal Printer is not in slip removal
E_ILLEGAL Error
mode.
The device was taken out of removal mode
EFPTR_SLP_FORM Error
while a form was still present.
endTraining
The Fiscal Printer does not support training
E_ILLEGAL Error
mode
Training state.
getData
E_BUSY Warning Cannot perform while output is in progress.
The dataItem, optArgs or ContractorId
E_ILLEGAL Error
specified is invalid.
getDate
Retrieval of the date and time is not valid at
E_ILLEGAL Warning
this time.
getTotalizer
• The vatID parameter is invalid, or
E_ILLEGAL Error
• The ContractorId property is invalid, or
• The specified totalizer is not available.
getVatEntry
The vatID parameter is invalid, or
E_ILLEGAL Error
CapHasVatTable is false.
printDuplicateReceipt
The Fiscal Printer does not support duplicate
E_ILLEGAL Error receipts or there is no buffered transaction to
print
Monitor state
EFPTR_JRN_EMPTY Error The journal station is out of paper.
EFPTR_REC_EMPTY Error The receipt station is out of paper
printFiscalDocumentLine


The Fiscal Printer does not support fiscal
E_ILLEGAL Error
documents
Fiscal Document state.
EFPTR_COVER_OPEN Error The Fiscal Printer cover is open.
The slip station was specified, but a form is
EFPTR_SLP_EMPTY Warning
not inserted
printFixedOutput
E_ILLEGAL Error
output or the lineNumber is invalid.
The Fiscal Printer is not in the Fixed Output
state
The receipt station was specified but is out of
EFPTR_REC_EMPTY Error
paper.
not inserted
printNormal
E_ILLEGAL Error The specified station does not exist.
The Fiscal Printer is not currently in the Non-
Fiscal state.
EFPTR_COVER_OPEN Error The Fiscal Printer cover is open
The journal station was specified but is out of
EFPTR_JRN_EMPTY Error
paper
The receipt station was specified but is out of
EFPTR_REC_EMPTY Error
paper
not inserted
printPeriodicTotalsReport
EFPTR_JRN_EMPTY Error The journal station is out of paper
EFPTR_BAD_DATE Error One of the date parameters is invalid.
printPowerLossReport
The Fiscal Printer does not support power
E_ILLEGAL Error
loss reports


printRecCash
E_BUSY Error Cannot perform while output is in progress.
The Fiscal Printer does not support this
E_ILLEGAL Error
method.
Fiscal Receipt state
not inserted
printRecItem
not inserted
EFPTR_BAD_ITEM_QU
Error The quantity is invalid.
ANTITY
EFPTR_BAD_PRICE Error The unit price is invalid.
EFPTR_BAD_ITEM_DES The discount description is too long or
Error
CRIPTION contains a reserved word.
EFPTR_BAD_VAT Error The VAT parameter is invalid
EFPTR_RECEIPT_TOTA
Error The receipt total has overflowed
L_OVERFLOW
• The Fiscal Printer does not support fixed
amount adjustments
E_ILLEGAL Error
• The Fiscal Printer does not support
percentage discounts
Fiscal Receipt state.
not inserted.

FPTR_BAD_ITEM_AMO
Error The discount amount is invalid.
UNT
Error
CRIPTION contains a reserved word
• The Fiscal Printer does not support fixed
amount adjustments
E_ILLEGAL Error
percentage discounts
not inserted.
FPTR_BAD_ITEM_AMO
Error The discount amount is invalid.
UNT
Error
printRecItemFuel
E_ILLEGAL Error This method is not supported.
not inserted
EFPTR_BAD_ITEM_QU
Error The quantity is invalid
ANTITY
EFPTR_BAD_PRICE Error The unit price is invalid
Error
EFPTR_RECEIPT_TOTA
Error The receipt total has overflowed
L_OVERFLOW

E_ILLEGAL Error This method is not supported.

not inserted
EFPTR_BAD_PRICE Error The price is invalid
Error
CRIPTION contains a reserved word.
printRecItemVoid
Cancelling is not allowed at this ticket state.
E_ILLEGAL Error May be because no item has been sold
previously.
EFPTR_REC_EMPTY Error The receipt station is out of paper.
not inserted
EFPTR_BAD_ITEM_AM
Error The price is invalid.
OUNT
EFPTR_BAD_ITEM_QU
Error The quantity is invalid.
ANTITY
EFPTR_BAD_VAT Error The VAT information is invalid.
EFPTR_BAD_ITEM_DES The description is too long or contains a
Error
CRIPTION reserved word
EFPTR_NEGATIVE_TO
Error The computed total is less than zero
TAL
printRecMessage
The Fiscal Printer is not in the Fiscal Receipt
Ending state.
not inserted
EFPTR_BAD_ITEM_DES The message is too long or contains a
Error
CRIPTION reserved word.

printRecNotPaid
The Fiscal Printer is not currently in either
EFPTR_WRONG_STATE Error the Fiscal Receipt or Fiscal Receipt Total
state.
not inserted.
Error
EFPTR_BAD_ITEM_AM
Error The amount is invalid.
OUNT
E_BUSY Warning Cannot perform while output is in progress
The Fiscal Printer does not support package
E_ILLEGAL Error adjustments or the adjustmentType
parameter is invalid
not inserted
Error
The Fiscal Printer does not support package
E_ILLEGAL Error adjustments, or the adjustmentType
EFPTR_REC_EMPTY Error The receipt station is out of paper.
not inserted
Error
printRecRefund


not inserted.
Error
EFPTR_BAD_ITEM_AM
Error The amount is invalid.
OUNT
EFPTR_BAD_VAT Error The VAT information is invalid
printRecRefundVoid
not inserted.
Error
EFPTR_BAD_ITEM_AM
Error The VAT information is invalid
OUNT
printRecSubtotal
not inserted
The subtotal from the application does not
EFPTR_BAD_ITEM_AM
Error match the subtotal computed by the Fiscal
OUNT
Printer.
EFPTR_NEGATIVE_TO The total computed by the Fiscal Printer is
Error
TAL less than zero.


• Fixed amount discounts are not supported.
E_ILLEGAL Error • Percentage discounts are not supported
• Surcharges are not supported
not inserted.
EFPTR_BAD_ITEM_AM
Error The discount amount is invalid
OUNT
Error
• Fixed amount discounts are not supported.
E_ILLEGAL Error
• Percentage discounts are not supported.
not inserted.
EFPTR_BAD_ITEM_AM
Error The discount amount is invalid
OUNT
printRecTaxID
The Fiscal Printer does not support printing
E_ILLEGAL Error
tax identifications.
not inserted
printRecTotal


not inserted
• The application computed total does not
EFPTR_BAD_ITEM_AM match the Fiscal Printer computed total, or
Error
OUNT • the total parameter is invalid, or
• the payment parameter is invalid
Error
EFPTR_NEGATIVE_TO
TAL
EFPTR_WORD_NOT_AL
Error The description contains the reserved word.
LOWED
printRecVoid
not inserted
Error
printRecVoidItem
E_BUSY Warning Cannot perform while output is in progress
• Fixed amount adjustments are not
E_ILLEGAL Error supported, or
• Percentage discounts are not supported, or
not inserted
EFPTR_BAD_ITEM_AM
Error The amount is invalid
OUNT

EFPTR_BAD_ITEM_QU
Error The quantity is invalid
ANTITY
EFPTR_BAD_VAT Error The VAT information is invalid
Error
EFPTR_NEGATIVE_TO
TAL
printReport
• The reportType parameter is invalid, or
E_ILLEGAL Error • One or both of startNum and endNum are
invalid, or
• startNum > endNum
The Fiscal Printer's current state does not
printXReport
E_ILLEGAL Error The Fiscal Printer does not support X reports
printZReport
setCurrency
• The Fiscal Printer does not support this
method, or
E_ILLEGAL Error • The Fiscal Printer has already begun the
fiscal day, or
• the specified newCurrency value is not
valid.
setDate
The Fiscal Printer has already begun the
E_ILLEGAL Warning
fiscal day
One of the entries of the date parameters is
EFPTR_BAD_DATE Error
invalid.

setHeaderLine
• The Fiscal Printer does not support setting
header lines, or
E_ILLEGAL Error
• The Fiscal Printer has already begun the
fiscal day, or
• the lineNumber parameter was invalid
EFPTR_BAD_ITEM_DES The text parameter is too long or contains a
Error
setPOSID
the POS Identifier, or
E_ILLEGAL Error • The printer has already begun the fiscal day,
or
• Either the POSID or cashierID parameter
is invalid.
setStoreFiscalID
the store fiscal identifier, or
E_ILLEGAL Error
fiscal day, or
• The ID parameter was invalid.
setTrailerLine
the receipt trailer lines, or
E_ILLEGAL Error
fiscal day, or
EFPTR_BAD_ITEM_DES The text parameter is too long or contains a
Error
setVatTable
• The Fiscal Printer does not support VAT
E_ILLEGAL Error tables or their setting, or
fiscal day
setVatValue
• The Fiscal Printer does not support VAT
tables, or
E_ILLEGAL Error • The Fiscal Printer has already begun the
fiscal day, or
changing an existing VAT value
verifyItem

The Fiscal Printer does not support VAT

E_ILLEGAL Error
tables
The Fiscal Printer is not currently in the Item
List state.
EFPTR_BAD_ITEM_DES The item name is too long or contains a
Error
EFPTR_BAD_VAT Error The VAT parameter is invalid.


FPTR_SUE_COVER_OPEN Error Fiscal Printer cover is open
FPTR_SUE_COVER_OK Information Fiscal Printer cover is closed
FPTR_SUE_JRN_EMPTY Error No journal paper.
FPTR_SUE_JRN_NEAREMPTY Warning Journal paper is low
FPTR_SUE_JRN_PAPEROK Information Journal paper is ready
FPTR_SUE_REC_EMPTY Error No receipt paper
FPTR_SUE_REC_NEAREMPTY Warning Receipt paper is low
FPTR_SUE_REC_PAPEROK Information Receipt paper is ready
No slip form is inserted, and no slip form has
FPTR_SUE_SLP_EMPTY Warning
FPTR_SUE_SLP_NEAREMPTY Warning Almost at the bottom of the slip form
FPTR_SUE_SLP_PAPEROK Information Slip form is inserted
All asynchronous output has finished, either
FPTR_SUE_IDLE Information successfully or because output has been
cleared.
FPTR_SUE_JRN_COVER_OPEN Error Journal station cover is open
FPTR_SUE_JRN_COVER_OK Information Journal station cover is closed.
FPTR_SUE_REC_COVER_OPEN Error Receipt station cover is open.
FPTR_SUE_REC_COVER_OK Information Receipt station cover is closed.
FPTR_SUE_SLP_COVER_OPEN Error Slip station cover is open.
FPTR_SUE_SLP_COVER_OK Information Slip station cover is closed

Gate
Gate Example
<Gate xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/Gate/ ../
GateV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/Gate/”
FixVersion=”0” MajorVersion=”1” MessageType=”Publish”
<MessageID />
<SensorID UnifiedPOS=”Gate”>Front Gate</SensorID>
<OpenGate />
</Gate>
Gate Properties
XMLPOS
Common
Properties
XMLPOS ARTS
Common
Common
Data
Data
Gate (Properties Domain View)

-@MajorVersion[1]
-@MinorVersion[1]
-@FixVersion[1]
-@CapGateStatus[0..1]
-GateStatus[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 53: Gate Properties Domain View

Gate Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
Gate (Methods Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-OpenGate[0..1]
-+WaitForGateClose[0..1]
Figure 54: Gate Methods Domain View

Gate Events
EventCommonData
-@Severity[0..1] SourceURIType
DateTimeCommonData -@Priority[0..1]
-@TypeCode[1]
-SequenceNumber[1]
-+EventDateTime[1]
BusinessUnitCommonData
-EventDescription[0..1]
-@Name[0..1]
-+SourceURI[1]
GateEvent OrganizationHierarchyCommonData -@REM[0..1]
-+SensorID[1]
-@UnifiedPOS[0..1]
-@MajorVersion[1] -@Level[0..1] -</choice>[1]
-@IFSF[0..1]
-@MinorVersion[0..1] -@ID[0..1] -Instance[0..1]
-@IETF[0..1]
-@FixVersion[0..1] -+BusinessUnit[0..1]
-@NAFEM[0..1]
-+DirectIOEvent[0..*] -+OrganizationalHierarchy[0..1]
-@LonMark[0..1]
XMLPOSCommonProperties StatusUpdateEventType
DirectIOEventType
-@AutoDisable[0..1] -Status[1]
-EventNumber[1]
-Data[1..*]
-Obj[1..*]
-+Properties[0..1]
-@Claimed[0..1]
-@PowerNotify[0..1]
-@PowerState[0..1]
GatePropertiesType
-@State[0..1]
-CheckHealthText[0..1] -@CapGateStatus[0..1]
-DeviceControlDescription[0..1] -GateStatus[0..1]
-OutputID[0..1]
Figure 55: Gate Events Domain View

N/A


Hard Totals
Hard Totals Example
Æ write(1, data, 100, 256)
<HardTotals xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/HardTotals/ ../
HardTotalsV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
HardTotals/” FixVersion=”0” MajorVersion=”1” MessageType=”Publish”
<SensorID UnifiedPOS=”HardTotals”>HT1</SensorID>
<Write>
<HTotalsFile>1</HTotalsFile>
<Data>data</Data>
<Offset>100</Offset>
<Count>256</Count>
</Write>
</HardTotals>
Hard Totals Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
HardTotals(Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@CapErrorDetection[0..1]
-@CapSingleFile[0..1]
-@CapTransactions[0..1]
-@TransactionInProgress[0..1]
-FreeData[0..1]
-NumberOfFiles[0..1]
-TotalsSize[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 56: Hard Totals Properties Domain View

Hard Totals Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
HardTotalsMethod
-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-BeginTrans[0..1]
-ClaimFile[0..1]
-CommitTrans[0..1] ReleaseFileType
ClaimFileType -Create[0..1]
-Delete[0..1] -HTotalsFile[1]
-HTotalsFile[1] -Find[0..1]
-Timeout[1] -FindByIndex[0..1]
-Read[0..1]
-RecalculateValidationData[0..1] WriteType
CreateType -ReleaseFile[0..1]
-Rename[0..1] -HTotalsFile[1]
-FileName[1]
-HTotalsFile[1] -Rollback[0..1] -Data[1]
-ErrorDetection[1] -SetAll[0..1] -Offset[1]
-ValidateData[0..1] -Count[1]
-Write[0..1]
ValidateDataType RecalculateValidationDataType
DeleteType
-HTotalsFile[1] -HTotalsFile[1]
-FileName[1]
FindType RenameType SetAllType ReadType FindByIndexType

-FileName[1] -HTotalsFile[1] -HTotalsFile[1] -HTotalsFile[1] -Index[1]
-hTotalsFile[1] -FileName[1] -Value[1] -Data[1] -FileName[1]
-Size[1] -Offset[1]
-Count[1]
Figure 57: Hard Totals Methods Domain View

Hard Totals Events
EventCommonData
-@Severity[0..1]
-@TypeCode[1]
-SequenceNumber[1]
-+EventDateTime[1]
-EventDescription[0..1]
HardTotalsEvents -@TypeCode[1] -<choice>[1] -@Name[0..1]
-@MajorVersion[1] OrganizationHierarchyCommonData -+SensorID[1] -@UnifiedPOS[0..1]
-@FixVersion[0..1] -@Level[0..1] -</choice>[1] -@IFSF[0..1]
-@ActionCode[0..1] -@ID[0..1] -Instance[0..1] -@IETF[0..1]
-@AutoDisable[0..1] -Data[1..*] -+Properties[0..1]
-@CapCompareFirmwareVersion[0..1] -Obj[1..*]
-@CapPowerReporting[0..1] -+Properties[0..1]
-@Claimed[0..1]
-@DataEventEnabled[0..1] HardTotalsPropertiesType
-@DeviceEnabled[0..1] -@CapErrorDetection[0..1]
-@FreezeEvents[0..1] -@CapSingleFile[0..1]
-@PowerNotify[0..1] -@CapTransactions[0..1]
-@PowerState[0..1] -@TransactionInProgress[0..1]
-@State[0..1] -FreeData[0..1]
-CheckHealthText[0..1] -NumberOfFiles[0..1]
-DeviceControlDescription[0..1] -TotalsSize[0..1]
-OutputID[0..1]
Figure 58: Hard Totals Events Domain View


beginTrans
Transactions are not supported by this
E_ILLEGAL Error
device.
claim
E_ILLEGAL Error An invalid timeout parameter was specified.
Another application has exclusive access to
the device or one or more of its files and did
E_TIMEOUT Warning
not relinquish control before timeout
claimFile
The handle is invalid, or an invalid timeout
E_ILLEGAL Error
The timeout value expired before another
application released exclusive access of
E_TIMEOUT Warning
either the requested totals file or the entire
totals area.
commitTrans
E_ILLEGAL Error
device, or no transaction is in progress.
create
Cannot create because the entire totals file
E_CLAIMED Warning
area is claimed by another application.
The fileName is too long or contains invalid
E_ILLEGAL Error
characters
E_EXISTS Error fileName already exists.
There is insufficient room in the totals area
ETOT_NOROOM Error
to create the file.
delete
Cannot delete because either the totals file
E_CLAIMED Warning or the entire totals area is claimed by another
application.
The fileName is too long or contains invalid
E_ILLEGAL Error
characters.
E_NOEXIST Error fileName was not found.
find
Cannot find because the entire totals file
E_CLAIMED Warning
E_ILLEGAL Error The fileName contains invalid characters.
E_NOEXIST Error fileName was not found.
findByIndex

Cannot find because the entire totals file

E_CLAIMED Warning
The index is greater than the largest file
E_ILLEGAL Error
index that is currently defined
read
Cannot read because either the totals file or
E_CLAIMED Warning the entire totals area is claimed by another
application.
The handle is invalid, part of the data range
E_ILLEGAL Error is outside the bounds of the totals file, or
data array length is less than count
ETOT_VALIDATIO A validation error has occurred while
Error
N reading data.
recalculateValidationData
Cannot recalculate because either the totals
E_CLAIMED Warning file or the entire totals area is claimed by
another application.
The handle is invalid, or advanced error
E_ILLEGAL Error detection is either not supported by the
Service or by this file
release
The application does not have exclusive
E_ILLEGAL Warning
access to the device.
releaseFile
The handle is invalid, or the specified file is
E_ILLEGAL Error
not claimed by this application.
rename
Cannot rename because either the totals file
E_CLAIMED Error or the entire totals area is claimed by another
application.
The handle is invalid, the fileName contains
E_ILLEGAL Error invalid characters, or the CapSingleFile
property is true.
E_EXISTS Error fileName already exists.
rollback
E_ILLEGAL Error
device, or no transaction is in progress.
setAll
Cannot set because either the totals file or
application.
E_ILLEGAL Error The handle is invalid.
validateData
Cannot validate because either the totals file
E_CLAIMED Warning or the entire totals area is claimed by another
application.

The handle is invalid, or advanced error

E_ILLEGAL Error detection is either not supported by the
Service or by this file.
write
Cannot write because either the totals file or
application.
The handle is invalid, or part of or all of the
E_ILLEGAL Error data range is outside the bounds of the totals
file.
Cannot write because a transaction is in
ETOT_NOROOM Error progress, and there is not enough free space
to prepare for the transaction commit.
ETOT_VALIDATIO A validation error has occurred while
Error
N reading data.


N/A

Image Scanner
Image Scanner Example
Æ set ImageMode to IMG_STILL_ONLY
<ImageScanner xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/ImageScanner/
../ImageScannerV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
ImageScanner/” FixVersion=”0” MajorVersion=”1”
MessageType=”Publish” MinorVersion=”0” ActionCode=”Update”>
<MessageID>asdfasfsdf</MessageID>
<SensorID UnifiedPOS=”ImageScanner”>IS1</SensorID>
<ImageMode>IMG_STILL_ONLY</ImageMode>
</ImageScanner>
Æ set DeviceEnabled to true

ImageScanner/” DeviceEnabled=”true” FixVersion=”0” MajorVersion=”1”
MessageType=”Publish” MinorVersion=”0” ActionCode=”Update”>
<MessageID>sdhgdfg</MessageID>
</ImageScanner>
(acquire image)
Å fire DataEvent
<ImageScannerEvent xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
ImageScannerEvents/ ../ImageScannerEventV1.0.0.xsd” xmlns=”http://
www.nrf-arts.org/UnifiedPOS/ImageScannerEvents/” FixVersion=”0”
<DataEvent>
<Status>0</Status>
</DataEvent>
</ImageScannerEvent>
Application services event

Request:

MessageType=”Request” MinorVersion=”0” ActionCode=”Read”>
<FrameData xsi:nil=”true”/>
<FrameType xsi:nil=”true”/>
<ImageHeight xsi:nil=”true”/>
<ImageType xsi:nil=”true”/>
<ImageWidth xsi:nil=”true”/>
</ImageScanner>
Response:
<FrameData>
R0lGODlhEwAIAPcAAAQCBGwaHBwaHFQeHAwODCQmJHwuLBQWHDQaHCQSFKQuNBQWFCQiJHQ2NIwq
LBQOFAwKDCQeJEQuLDQuLJQyNDwiJAwGDIQqLBweHCwqLIQuNCwWHDQeHCQWFBQSFAQGBHweHEwm
JBQODCQqJBwWHLwyNBwWFCwiJIw6PKQmJBwOFFwqLCQeHIQyNDweHCwWFG4gVAAA8gAAgAAAfKiA
QOIP5BIIEgAAABgBa+4A8pAAgHwCfHAAOAUAAJEAAHwAAP+eWP8C8P8AAv8AAG1FAAUJAJGRAHx8
AIVOpOcJAIGRAHx8AAC4/QDmZRYSUQAABGAkAAMAAAACAAAAAFCkWKbk8BkSAgAAAAACAGYAABYA
AAAAAACQ/wBB/wCR/wB8/34A/wDw/wD9/8B/fwAFAQAQAACQAAB8AP9MAP/jAP8SAP8AAP8A9P8A
Af8AAP8AAAAcmADkAQASAAAAAAAYJQDuAACQAAB8AABwFAAJABaRAAB8AGDAYJjkngCXgAB8fLhv
COI+0BKRFgB8AJ9iAOs+AIGRAHx8AEoIB+MCAIEAAHwAACA4AJvnAFASAAAAAAAAAGYA0AEAFgAA
AGxOAAAAAAAAAAAAAPRgAOGYABIAAAAAADTQAADjAAASAMAAAPiFAPcrABKDAAB8ABgAaO4AnpAA
gHwAfHAA/wUA/5EA/3wA//8AYP8Anv8AgP8AfG0AIwUBAJEAAHwAAErpI/QrAICDAHx8AAD0XADj
8BYSEgAAAADE/wAr/wCD/wB8/wAAAGYAABYAAAAAAAAI/AHQ5AAWEgAAAAA01gBkWACDTAB8AFf/
3PT/5ID/Enz/AOD4d+PkMBISTwAAAABtEGZk5RaDEgB8AOM0NOpMZJBPg3wAfOQgq+JV5RJPEgAA
AEAA2wAB/wAA/wAAf0D0iADj5QASEgAAAAQACAAB0AAAFgAAAAGINABkZACDgwB8fNABCFUA0J0A
FrEAADAAYAAwmAAAAAAAAACcAADxAAASAABDAPAAndYA/4oARwAAACH5BAEAAAAALAAAAAATAAgA
BwiTAAEAeEAAwAIPCwhYWEBigYkFDzAIsCAQIQARHhAuYIDBAwMBDD4IWCAwQwIAEBJAQEiCgAcL
IzxAIAiAQIEFEES8QODixIeVHwAIcCmQQ4sUJRSAMBBAwwUUA04uJPAAAAUHLkh88OCSpIgOKxps
AEBCZgaDOLlmrCnTQwgJHT1ggGDCw9AIKz0SYABhwQQBAAICADs=
</FrameData>
<FrameType>IMG_FRAME_STILL</FrameType>
<ImageHeight>8</ImageHeight>
<ImageType>IMG_TYP_GIF</ImageType>
<ImageWidth>19</ImageWidth>
</ImageScanner>

Image Scanner Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
ImageScanner (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@AimMode[0..1]
-@CapAim[0..1]
-@CapDecodeData[0..1]
-@CapHostTriggered[0..1]
-@CapIlluminate[0..1]
-@CapImageData[0..1]
-@CapImageQuality[0..1]
-@CapVideoData[0..1]
-@FrameData[0..1]
-@IlluminateMode[0..1]
-BitsPerPixel [0..1]
-FrameType[0..1]
-ImageHeight[0..1]
-ImageLength[0..1]
-ImageMode[0..1]
-ImageType[0..1]
-ImageWidth[0..1]
-VideoCount[0..1]
-VideoRate[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 59: Image Scanner Properties Domain View

Image Scanner Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
ImageScanner (Method Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-StartSession[0..1]
-StopSession[0..1]
Figure 60: Image Scanner Methods Domain View

Image Scanner Events
EventCommonData
-@Severity[0..1]
-@TypeCode[1]
-SequenceNumber[1]
-+EventDateTime[1]
ImageScannerEvents -EventDescription[0..1]
-@MajorVersion[1]
-@TypeCode[1] -<choice>[1] -@Name[0..1]
-@FixVersion[0..1]
OrganizationHierarchyCommonData -+SensorID[1] -@UnifiedPOS[0..1]
-@ActionCode[0..1]
-+DataEvent[0..*] -@Level[0..1] -</choice>[1] -@IFSF[0..1]
-+DirectIOEvent[0..*] -@ID[0..1] -Instance[0..1] -@IETF[0..1]
-+ErrorEvent[0..*]
DataEventType DirectIOEventType ErrorEventType StatusUpdateEventType

-Status[1] -EventNumber[1] -ErrorCode[1] -Status[1]
-+Properties[0..1] -Data[1..*] -ErrorCodeExtended[1] -+Properties[0..1]
-+Properties[0..1]
ImageScannerPropertiesType
XMLPOSCommonProperties -@AimMode[0..1]
-@CapAim[0..1]
-@AutoDisable[0..1]
-@CapDecodeData[0..1]
-@CapHostTriggered[0..1]
-@CapIlluminate[0..1]
-@CapImageData[0..1]
-@CapImageQuality[0..1]
-@CapVideoData[0..1]
-@Claimed[0..1]
-@FrameData[0..1]
-@IlluminateMode[0..1]
-BitsPerPixel [0..1]
-FrameType[0..1]
-@PowerNotify[0..1]
-ImageHeight[0..1]
-@PowerState[0..1]
-ImageLength[0..1]
-@State[0..1]
-ImageMode[0..1]
-ImageType[0..1]
-ImageWidth[0..1]
-VideoCount[0..1]
-VideoRate[0..1]
-OutputID[0..1]
Figure 61: Image Scanner Events Domain View


startSession
An attempt was made to call
the startSession method when
E_ILLEGAL Error
the CapHostTriggered
property is false.
stopSession
An attempt was made to call
the stopSession method when
E_ILLEGAL Error
the CapHostTriggered
property is false.


N/A
Item Dispenser
Item Dispenser Example
<ItemDispenser xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/ItemDispenser/
../ItemDispenserV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/
ItemDispenser/” FixVersion=”0” MajorVersion=”1”
<MessageID />
<SensorID UnifiedPOS=”ItemDispenser”>100</SensorID>
<DispenseItem>
<NumItem>4</NumItem>
<SlotNumber>2</SlotNumber>
</DispenseItem>
</KeylockMethod>

Item Dispenser Properties
XMLPOS
Common
Properties
XMLPOS ARTS
Common Common
Data
Data
ItemDispenser (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-@CapIndividualSlotStatus[0..1]
-@CapNEarEmptySensor[0..1]
-MaxSlots[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 62: Item Dispenser Properties Domain View

Item Dispenser Methods
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data Data
ItemDispenser (Methods Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-.....[0..1]
---- Methods ---[1]
-+AdjustItemCount[0..1]
-+DispenseItem[0..1]
-+ReadItemCount[0..1]
AdjustItemCountType DispenseItemType ReadItemCountType

-ItemCount[1] -NumItem[1] -ItemCount[1]
-SlotNumber[1] -SlotNumber[1] -SlotNumber[1]
Figure 63: Item Dispenser Methods Domain View

Item Dispenser Events

EventCommonData
-@Severity[0..1]
-SequenceNumber[1] -@TypeCode[1]
-+EventDateTime[1]
ItemDispenserEvent BusinessUnitCommonData -EventDescription[0..1]
SensorID
-@MajorVersion[1] -@Name[0..1]
-@MinorVersion[0..1] -@REM[0..1]
-+SourceURI[1]
-@FixVersion[0..1] -@UnifiedPOS[0..1]
OrganizationHierarchyCommonData -+SensorID[1]
-+DirectIOEvent[0..1] -@IFSF[0..1]
-@Level[0..1] -</choice>[1]
-+StatusUpdateEvent[0..1] -@IETF[0..1]
-@ID[0..1] -Instance[0..1]
DirectIOEventType
StatusUpdateEventType
-EventNumber[1]
-Data[1..*] -Status[1]
XMLPOSCommonProperties -+Properties[0..1]
-Obj[1..*]
-@Claimed[0..1] ItemDispenserPropertiesType
-@CapIndividualSlotStatus[0..1]
-@PowerNotify[0..1]
-@PowerState[0..1]
-@State[0..1]
-MaxSlots[0..1]
-OutputID[0..1]
Figure 64: Item Dispenser Events Domain View

N/A


Keylock
Keylock Example
Æ waitForKeylockChange(LOCK_KP_LOCK, 30000)
<Keylock xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://www.nrf-arts.org/UnifiedPOS/Keylock/ ../
KeylockV1.0.0.xsd” xmlns=”http://www.nrf-arts.org/UnifiedPOS/Keylock/
” FixVersion=”0” MajorVersion=”1” MessageType=”Publish”
<SensorID UnifiedPOS=”Keylock”>1</SensorID>
<WaitForKeylockChange>
<KeyPosition>LOCK_KP_LOCK</KeyPosition>
</WaitForKeylockChange>
</Keylock>

Keylock Properties
XMLPOS
Common
Properties
ARTS
XMLPOS
Common
Common
Data
Data
Keylock (Properties Domain View)

-@MajorVersion[1]
-@FixVersion[0..1]
-CapKeylockType[0..1]
-ElectronicKeyValue [0..1]
-KeyPosition [0..1]
-PositionCount[0..1]
---- Methods ---[1]
-.....[0..1]
Figure 65: Keylock Properties Domain View

D-1

UnifiedPOS Version 1.12 01142008

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

UnifiedPOS Version 1.12 01142008

Transféré par

Droits d'auteur :

Formats disponibles

UnifiedPOS

For Implementation of Point Of Service Peripherals

Copyright © National Retail Federation, 2004-2008. All Rights Reserved.

THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS PROVIDED

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Technical Committee Members:

UnifiedPOS Technical Committee Contributors:

Information regarding the activities of the UnifiedPOS Committee can

JavaPOS is a trademark of Sun Microsystems, Inc.

UnifiedPOS Version 1.12 -- Released January 14, 2008

This page intentionally left blank.

UnifiedPOS Version 1.12 -- Released January 14, 2008

Initial Connectivity Model ............................................................................................70

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

METHODS (UML OPERATIONS) .........................................................................................529

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

GENERAL INFORMATION ....................................................................................................782

UnifiedPOS Version 1.12 -- Released January 14, 2008

Initialization of Magnetic Stripe Data ........................................................................876

UnifiedPOS Version 1.12 -- Released January 14, 2008

POS Printer State Diagrams (Low Level) ..................................................................981

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

Device Name Keys and Values .....................................................................................74

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

VERSION HANDLING ............................................................................................................30

UnifiedPOS Version 1.12 -- Released January 14, 2008

Java Command Examples .............................................................................................91

UnifiedPOS Version 1.12 -- Released January 14, 2008

KEY PARAMETER DIFFERENCES ..........................................................................................31

UnifiedPOS Version 1.12 -- Released January 14, 2008

Interface Class ..............................................................................................................82

UnifiedPOS Version 1.12 -- Released January 14, 2008

Bill Dispenser Methods ..........................................................................................28

UnifiedPOS Version 1.12 -- Released January 14, 2008

Coin Acceptor Properties........................................................................................65

UnifiedPOS Version 1.12 -- Released January 14, 2008

Image Scanner Example .......................................................................................113

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

Device Specific Stati ............................................................................................191

UnifiedPOS Version 1.12 -- Released January 14, 2008

Maintenance Enterprise Group ..................................................................................230

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

Methods (UML operations) ....................................................................................92

UnifiedPOS Version 1.12 -- Released January 14, 2008

Item Dispenser Methods Domain View ...........................................................................120

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Architecture for Retail

UnifiedPOS is the acronym for Unified Point of Service. It is an architectural

The UnifiedPOS standard will include:

The UnifiedPOS standard will not include:

About This Documentation Updated in Release 1.12

UnifiedPOS Version 1.12 -- Released January 14, 2008

UnifiedPOS Version 1.12 -- Released January 14, 2008

“Appendix H” provides information on functionality and changes that are

UnifiedPOS Version 1.12 -- Released January 14, 2008